The simple interface

prop_capillary(radius, flength, gas, pressure; λ0, λlims, trange, kwargs...)

Simulate pulse propagation in a hollow fibre using the capillary model.

Mandatory arguments

• radius: Core radius of the fibre. Can be a Number for constant radius, or a function a(z) which returns the z-dependent radius.
• flength::Number: Length of the fibre.
• gas::Symbol: Filling gas species.
• pressure: Gas pressure. Can be a Number for constant pressure, a 2-Tuple of Numbers for a simple pressure gradient, or a Tuple of (Z, P) where Z and P contain z positions and the pressures at those positions.
• λ0: (keyword argument) the reference wavelength for the simulation. For simple single-pulse inputs, this is also the central wavelength of the input pulse.
• λlims::Tuple{<:Number, <:Number}: The wavelength limits for the simulation grid.
• trange::Number: The total width of the time grid. To make the number of samples a power of 2, the actual grid used is usually bigger.

Grid options

• envelope::Bool: Whether to use envelope fields for the simulation. Defaults to false. By default, envelope simulations ignore third-harmonic generation. Plasma has not yet been implemented for envelope fields.
• δt::Number: Time step on the fine grid used for the nonlinear interaction. By default, this is determined by the wavelength grid. If δt is given and smaller than the required value, it is used instead.

Input pulse options

A single pulse in the lowest-order mode can be specified by the keyword arguments below. More complex inputs can be defined by a single AbstractPulse or a Vector{AbstractPulse}. In this case, all keyword arguments except for λ0 are ignored.

• λ0: Central wavelength
• τfwhm: The pulse duration as defined by the full width at half maximum.
• τw: The "natural" pulse duration. Only available if pulseshape is sech.
• ϕ: Spectral phases to be applied to the transform-limited pulse. Elements are the usual polynomial phases ϕ₀ (CEP), ϕ₁ (group delay), ϕ₂ (GDD), ϕ₃ (TOD), etc.
• energy: Pulse energy.
• power: Peak power after any spectral phases are added.
• pulseshape: Shape of the transform-limited pulse. Can be :gauss for a Gaussian pulse or :sech for a sech² pulse.
• polarisation: Polarisation of the input pulse. Can be :linear (default), :x, :y, :circular, or an ellipticity number -1 ≤ ε ≤ 1, where ε=-1 corresponds to left-hand circular, ε=1 to right-hand circular, and ε=0 to linear polarisation. The major axis for elliptical polarisation is always the y-axis.
• propagator: A function propagator!(Eω, grid) which mutates its first argument to apply an arbitrary propagation to the pulse before the simulation starts.
• shotnoise: If true (default), one-photon-per-mode quantum noise is included.

Modes options

• modes: Defines which modes are included in the propagation. Can be any of:
  • a single mode signifier (default: :HE11), which leads to mode-averaged propagation (as long as all inputs are linearly polarised).
  • a Dict mode signifier with keys :kind, :n, and :m, e.g. Dict(:kind=>:HE, :n=>1, :m=>1)
  • a Tuple of mode signifiers (Symbols or Dicts), which leads to multi-mode propagation in those modes.
  • a Number N of modes, which simply creates the first N HE modes.
  Note that when elliptical or circular polarisation is included, each mode is present twice in the output, once for x and once for y polarisation.
• model::Symbol: Can be :full, which includes the full complex refractive index of the cladding in the effective index of the mode, or :reduced, which uses the simpler model more commonly seen in the literature. See Luna.Capillary for more details. Defaults to :full.
• loss::Bool: Whether to include propagation loss. Defaults to true.
• temperature::Number: Temperature of the gas in Kelvin. Defaults to room temperature.

Nonlinear interaction options

• kerr: Whether to include the Kerr effect. Defaults to true.
• raman: Whether to include the Raman effect. Defaults to false.
• plasma: Can be one of
  • :ADK – include plasma using the ADK ionisation rate.
  • :PPT – include plasma using the PPT ionisation rate.
  • true (default) – same as :PPT.
  • false – ignore plasma.
  Note that plasma is only available for full-field simulations.
• PPT_options::Dict{Symbol, Any}: when using the PPT ionisation rate for the plasma nonlinearity, this allows for fine-tuning of the options in calculating the ionisation. See ionrate_fun_PPT for possible keyword arguments.
• preionfrac::Float64: fraction of the gas that is pre-ionised before the pulse. Defaults to 0.0. Note that this is a very simplistic model of pre-ionisation and should be used with caution.
• thg::Bool: Whether to include third-harmonic generation. Defaults to true for full-field simulations and to false for envelope simulations.

If raman is true, then the following options apply: - rotation::Bool = true: whether to include the rotational Raman contribution - vibration::Bool = true: whether to include the vibrational Raman contribution

Output options

• stats_kwargs::Dict{Symbol, Any}: a dictionary of keyword arguments to Stats.default
• saveN::Integer: Number of points along z at which to save the field.
• filepath: If nothing (default), create a MemoryOutput to store the simulation results only in the working memory. If not nothing, should be a file path as a String, and the results are saved in a file at this location. If scan is passed, filepath determines the output directory for the scan instead.
• scan: A Scan instance defining a parameter scan. If scan is given, aOutput.ScanHDF5Outputis used to automatically name and populate output files of the scan.scanidx` must also be given.
• scanidx: Current scan index within a scan being run. Only used when scan is passed.
• filename: Can be used to to overwrite the scan name when running a parameter scan. The running scanidx will be appended to this filename. Ignored if no scan is given.
• status_period::Number: Interval (in seconds) between printed status updates.

prop_capillary_args(radius, flength, gas, pressure; λ0, λlims, trange, kwargs...)

Prepare to simulate pulse propagation in a hollow fibre using the capillary model. This function takes the same arguments as prop_capillary but instead or running the simulation and returning the output, it returns the required arguments for Luna.run, which is useful for repeated simulations in an indentical fibre with different initial conditions.

prop_gnlse(γ, flength, βs; λ0, λlims, trange, kwargs...)

Simulate pulse propagation using the GNLSE.

Mandatory arguments

• γ::Number: The nonlinear coefficient.
• flength::Number: Length of the fibre.
• βs: The Taylor expansion of the propagation constant about λ0.
• λ0: (keyword argument) the reference wavelength for the simulation. For simple single-pulse inputs, this is also the central wavelength of the input pulse.
• λlims::Tuple{<:Number, <:Number}: The wavelength limits for the simulation grid.
• trange::Number: The total width of the time grid. To make the number of samples a power of 2, the actual grid used is usually bigger.

Grid options

• δt::Number: Time step on the fine grid used for the nonlinear interaction. By default, this is determined by the wavelength grid. If δt is given and smaller than the required value, it is used instead.

Input pulse options

A single pulse can be specified by the keyword arguments below. More complex inputs can be defined by a single AbstractPulse or a Vector{AbstractPulse}. In this case, all keyword arguments except for λ0 are ignored. Note that the current GNLSE model is single mode only.

• λ0: Central wavelength
• τfwhm: The pulse duration as defined by the full width at half maximum.
• τw: The "natural" pulse duration. Only available if pulseshape is sech.
• ϕ: Spectral phases to be applied to the transform-limited pulse. Elements are the usual polynomial phases ϕ₀ (CEP), ϕ₁ (group delay), ϕ₂ (GDD), ϕ₃ (TOD), etc.
• energy: Pulse energy.
• power: Peak power after any spectral phases are added.
• pulseshape: Shape of the transform-limited pulse. Can be :gauss for a Gaussian pulse or :sech for a sech² pulse.
• polarisation: Polarisation of the input pulse. Can be :linear (default), :circular, or an ellipticity number -1 ≤ ε ≤ 1, where ε=-1 corresponds to left-hand circular, ε=1 to right-hand circular, and ε=0 to linear polarisation. The major axis for elliptical polarisation is always the y-axis.
• propagator: A function propagator!(Eω, grid) which mutates its first argument to apply an arbitrary propagation to the pulse before the simulation starts.
• shotnoise: If true (default), one-photon-per-mode quantum noise is included.

GNLSE options

• shock::Bool: Whether to include the shock derivative term. Default is true.
• raman::Bool: Whether to include the Raman effect. Defaults to true.
• ramanmodel; which Raman model to use, defaults to :sdo which uses a simple damped oscillator model, defined τ1 and τ2 (which default to values commonly used for silica). ramanmodel can also be set to :SiO2 which uses the more advanced model of Hollenbeck and Cantrell.
• loss: the power loss [dB/m]. Defaults to 0.
• fr: fractional Raman contribution to γ. Defaults to fr = 0.18.
• τ1: the Raman oscillator period.
• τ2: the Raman damping time.

Output options

• saveN::Integer: Number of points along z at which to save the field.
• filepath: If nothing (default), create a MemoryOutput to store the simulation results only in the working memory. If not nothing, should be a file path as a String, and the results are saved in a file at this location. If scan is passed, filepath determines the output directory for the scan instead.
• scan: A Scan instance defining a parameter scan. If scan is given, aOutput.ScanHDF5Outputis used to automatically name and populate output files of the scan.scanidx` must also be given.
• scanidx: Current scan index within a scan being run. Only used when scan is passed.
• filename: Can be used to to overwrite the scan name when running a parameter scan. The running scanidx will be appended to this filename. Ignored if no scan is given.
• status_period::Number: Interval (in seconds) between printed status updates.

prop_gnlse_args(γ, flength, βs; λ0, λlims, trange, kwargs...)

Prepare to simulate pulse propagation using the GNLSE. This function takes the same arguments as prop_gnlse but instead or running the simulation and returning the output, it returns the required arguments for Luna.run, which is useful for repeated simulations in an indentical fibre with different initial conditions.

CustomPulse(;λ0, energy=nothing, power=nothing, ϕ=Float64[],
            mode=:lowest, polarisation=:linear, propagator=nothing)

A custom pulse defined by a function for use with prop_capillary, with either energy or peak power specified.

Keyword arguments

• λ0::Number: the central wavelength
• Itshape::function: a function I(t)which defines the intensity/power envelope of the pulse as a function of timet. Note that the normalisation of this envelope is irrelevant as it will be re-scaled byenergyorpower`.
• energy::Number: the pulse energy.
• power::Number: the pulse peak power (after applying any spectral phases).
• ϕ::Vector{Number}: spectral phases (CEP, group delay, GDD, TOD, ...).
• mode::Symbol: Mode in which this input should be coupled. Can be :lowest for the lowest-order mode in the simulation, or a mode designation (e.g. :HE11, :HE12, :TM01, etc.). Defaults to :lowest.
• polarisation: Can be :linear, :x, :y, :circular, or an ellipticity number -1 ≤ ε ≤ 1, where ε=-1 corresponds to left-hand circular, ε=1 to right-hand circular, and ε=0 to linear polarisation.
• propagator: A function propagator!(Eω, grid) which mutates its first argument to apply an arbitrary propagation to the pulse before the simulation starts.

DataPulse(ω, Iω, ϕω; energy, λ0=NaN, mode=:lowest, polarisation=:linear, propagator=nothing)
DataPulse(ω, Eω; energy, λ0=NaN, mode=:lowest, polarisation=:linear, propagator=nothing)
DataPulse(fpath; energy, λ0=NaN, mode=:lowest, polarisation=:linear, propagator=nothing)

A custom pulse defined by tabulated data to be used with prop_capillary.

Data input options

• ω, Iω, ϕω: arrays of angular frequency ω (units rad/s), spectral energy density Iω and spectral phase ϕω. ϕω should be unwrapped.
• ω, Eω: arrays of angular frequency ω (units rad/s) and the complex frequency-domain field Eω.
• fpath: a string containing the path to a file which contains 3 columns: Column 1: frequency (units of Hertz) Column 2: spectral energy density Column 3: spectral phase (unwrapped)

Keyword arguments

• energy::Number: the pulse energy
• λ0::Number: the central wavelength (optional; defaults to the centre of mass of the given spectral energy density).
• ϕ::Vector{Number}: spectral phases (CEP, group delay, GDD, TOD, ...) to be applied to the pulse (in addition to any phase already present in the data).
• mode::Symbol: Mode in which this input should be coupled. Can be :lowest for the lowest-order mode in the simulation, or a mode designation (e.g. :HE11, :HE12, :TM01, etc.). Defaults to :lowest.
• polarisation: Can be :linear, :x, :y, :circular, or an ellipticity number -1 ≤ ε ≤ 1, where ε=-1 corresponds to left-hand circular, ε=1 to right-hand circular, and ε=0 to linear polarisation.
• propagator: A function propagator!(Eω, grid) which mutates its first argument to apply an arbitrary propagation to the pulse before the simulation starts.

GaussBeamPulse(waist, timepulse, Nmodes=:all)

A pulse whose shape in time is defined by the timepulse::AbstractPulse, and whose modal content is calculated by considering the overlap of an ideal Gaussian laser beam with 1/e² radius waist with the modes of the waveguide. Nmodes determines how many of the available modes to couple to. By default (Nmodes=:all) all modes are taken into account, but this can lead to numerical inaccuracies.

GaussPulse(;λ0, τfwhm, energy=nothing, power=nothing, ϕ=Float64[], m=1,
           mode=:lowest, polarisation=:linear, propagator=nothing)

A (super)Gaussian pulse for use with prop_capillary, with either energy or peak power specified.

Keyword arguments

• λ0::Number: the central wavelength.
• τfwhm::Number: the pulse duration (power/intensity FWHM).
• energy::Number: the pulse energy.
• power::Number: the pulse peak power (after applying any spectral phases).
• ϕ::Vector{Number}: spectral phases (CEP, group delay, GDD, TOD, ...).
• m::Int: super-Gaussian parameter (the power in the Gaussian exponent is 2m). Defaults to 1.
• mode::Symbol: Mode in which this input should be coupled. Can be :lowest for the lowest-order mode in the simulation, or a mode designation (e.g. :HE11, :HE12, :TM01, etc.). Defaults to :lowest.
• polarisation: Can be :linear, :x, :y, :circular, or an ellipticity number -1 ≤ ε ≤ 1, where ε=-1 corresponds to left-hand circular, ε=1 to right-hand circular, and ε=0 to linear polarisation.
• propagator: A function propagator!(Eω, grid) which mutates its first argument to apply an arbitrary propagation to the pulse before the simulation starts.

SechPulse(;λ0, τfwhm=nothing, τw=nothing, energy=nothing, power=nothing, ϕ=Float64[],
           mode=:lowest, polarisation=:linear, propagator=nothing)

A sech²(τ/τw) pulse for use with prop_capillary, with either energy or peak power specified, and duration given either as τfwhm or τw.

Keyword arguments

• λ0::Number: the central wavelength.
• τfwhm::Number: the pulse duration (power/intensity FWHM).
• τw::Number: "natural" pulse duration of a sech²(τ/τw) pulse.
• energy::Number: the pulse energy.
• power::Number: the pulse peak power (after applying any spectral phases).
• ϕ::Vector{Number}: spectral phases (CEP, group delay, GDD, TOD, ...)
• mode::Symbol: Mode in which this input should be coupled. Can be :lowest for the lowest-order mode in the simulation, or a mode designation (e.g. :HE11, :HE12, :TM01, etc.). Defaults to :lowest.
• polarisation: Can be :linear, :x, :y, :circular, or an ellipticity number -1 ≤ ε ≤ 1, where ε=-1 corresponds to left-hand circular, ε=1 to right-hand circular, and ε=0 to linear polarisation.
• propagator: A function propagator!(Eω, grid) which mutates its first argument to apply an arbitrary propagation to the pulse before the simulation starts.

LunaPulse(output; energy, λ0=NaN, mode=:lowest, polarisation=:linear, propagator=nothing)

A pulse defined to be used with prop_capillary which comes from a previous Luna propagation simulation.

For multi-mode simulations, only the lowest-order modes is transferred.

Arguments

• output::AbstractOutput: output from a previous Luna simulation.

Keyword arguments

• energy::Number: the pulse energy. When transferring multi-mode simulations this defines the total energy.
• scale_energy: if given instead of energy, scale the field from output by this number. Defaults to 1, so giving energy is not required. For multi-mode simulations, this can also be a Vector with the same number of elements as the number of modes, in which case the energy of each mode is scaled by the corresponding number.
• λ0::Number: the central wavelength (optional; defaults to the centre of mass of the given spectral energy density).
• ϕ::Vector{Number}: spectral phases (CEP, group delay, GDD, TOD, ...) to be applied to the pulse (in addition to any phase already present in the data).
• propagator: A function propagator!(Eω, grid) which mutates its first argument to apply an arbitrary propagation to the pulse before the simulation starts.