options.md

Option reference (generated)

Every key the engine reads, with its JSON type, SI unit, default and meaning. The same registry produces the JSON Schemas (schemas/, Schemas) and the unknown-key warnings, so this page is complete by construction. Units: the key suffix names the unit (lengthM metres, durationFwhmS seconds, gddFs2 fs²).

System file

Top-level keys of a .ufs system file.

An optical system: a chain of elements. More: system-file.md

key	type	unit	default	meaning
format	string			"ultrafast-system"
version	integer		2	Format version
name	string			Name of the system
description	string			Free text
source	object			Provenance of the file (written by exporters, e.g. the zemax plugin); free-form
sampling	object (samplingWavelengths)			Wavelengths of all per-wavelength arrays in the file
environment	object (environment)			Air of the laboratory and the index reference of quoted data
materials	object			Materials defined in this file, by name (docs/reference/materials.md)
coatings	object			Coatings defined in this file, by name (docs/reference/coatings.md)
substrates	object			Mirror substrates defined in this file, by name: material, thicknessM, backCoating / backReflectance, wedgeDeg (docs/reference/coatings.md#substrate-echoes)
inputBeam	model (beam)			Default beam for nonlinear elements without one
elements	array of element			The beam path, in order Required.
overrides	array of override			Changes to models or values (docs/reference/models.md#overrides)

Run spec

Top-level keys of a run spec (run.json). Plugins add keys (see Plugin keys).

A run: the pulse, the instruments and numerical settings. More: run-spec.md

key	type	unit	default	meaning
format	string			"ultrafast-run"
version	integer		2	Format version
name	string			Name of the run
pulse	object (pulse)			The input pulse Required.
grid	object (grid)			Time/frequency grid
physics	object (physics)			Physics switches
stepper	object (stepper)			Nonlinear solver settings
probes	any		"end"	Snapshots of the pulse: "all", "end" or a list of element ids
instruments	array of instrument			Instruments
detectors	object			Detector presets by name: {instrument: {keys for an instrument that does not set them}, detector: {read-out}}; an instrument says "detector": "name" (docs/reference/instruments.md#detector-presets)
overrides	array of override			Overrides (highest priority)
inputBeam	model (beam)			Default beam for nonlinear elements without one
outputs	object (outputs)			Which files to write
compute	object (compute)			Compute back-end and threads
coherence	object (coherence)			Partially coherent beam: a run over coherent modes (docs/reference/transverse.md#partial-coherence)

Pulse

run.pulse.

The input pulse (docs/reference/run-spec.md#pulse).

key	type	unit	default	meaning
shape	"gaussian" | "sech2" | "superGaussian" | "spectrum" | "cw"		gaussian	Pulse shape; cw: one spectral bin at centerWavelengthM, with powerW
centerWavelengthM	number	m		Carrier wavelength (for spectrum: default = intensity-weighted mean)
centerWavelengthNm	number	nm		Carrier wavelength in nm (alternative)
durationFwhmS	number	s		Transform-limited intensity FWHM
durationFwhmFs	number	fs		Transform-limited FWHM in fs (alternative)
bandwidthFwhmM	number	m		Spectral FWHM (alternative to the duration)
bandwidthFwhmNm	number	nm		Spectral FWHM in nm
order	integer		2	superGaussian order
energyJ	number	J		Pulse energy
averagePowerW	number	W		Average power (with repRateHz)
peakPowerW	number	W		Peak power (alternative)
powerW	number	W		Power of a cw source (shape cw)
repRateHz	number	Hz		Repetition rate
chirp	object (chirp)			Spectral phase about the carrier: gddS2/todS3/fodS4 or gddFs2/todFs3/fodFs4
cepRad	number	rad	0	Carrier-envelope phase
polarization	any		"x"	"x", "y", "45", "-45", "rcp", "lcp", {angleDeg, ellipticity} or [exRe, exIm, eyRe, eyIm]
spectrum	object (pulseSpectrum)			Measured spectrum (shape: spectrum): wavelengthsM + intensity (+ phaseRad), or csv
delayS	number	s	0	Time offset
pedestal	any			Pedestal / contrast components: one object or a list (replica, prePulse, postPulse, ase, phaseNoise, exponential, measured)
noise	object (pulseNoise)			Quantum noise on the input: one photon per frequency mode with random phase (supercontinuum coherence, parametric seeding)

Grid

run.grid.

The time/frequency grid (docs/reference/run-spec.md#grid).

key	type	unit	default	meaning
auto	boolean		true	Size the grid from pulse and system
n	integer		4096	Number of samples (with auto: a minimum)
windowS	number	s	30 x the transform limit	Time window
windowPs	number	ps		Time window in ps
maxN	integer		4194304	Largest allowed n
snapCarrier	boolean		true	Put the carrier on the frequency grid. A cw source is not snapped (its line sits on centerWavelengthM) unless this is written
spectralMargin	number		auto	Spectral span factor
minSpanFraction	number		0.1	Nonlinear runs: minimum half-span / carrier
minPointsPerFwhm	number		12	Samples across the transform-limited FWHM
satelliteLevel	number		1e-8	Weakest combination of ghost / replica satellites the window makes room for (relative intensity); weaker multi-satellite combinations may wrap around the window
extendForSatellites	boolean		false	Manual window (auto false): grow the window, keeping dt, so that ghosts, echoes and pedestal replicas above satelliteLevel fit
strict	boolean		false	A ghost, echo or pedestal that wraps around the window is an error instead of a warning
tail	any		false	Delayed-light ledger: true, or {windowS, warnEnergyFraction, exactSteps (every linear element takes the exact long-grid step; default false), crossPhase (first-order cross-phase of the tail by the main pulse in nonlinear elements; default true)}. A second, long, linear grid with the same time step carries ghosts, echoes and gas-line tails next to the main nonlinear grid (docs/reference/delayed-light.md)

Physics

run.physics.

Physics switches (docs/reference/run-spec.md#physics).

key	type	unit	default	meaning
nonlinear	boolean		true	Master switch for nonlinear propagation
selfSteepening	boolean		true	Self-steepening
raman	boolean		true	Delayed (Raman) response of materials that have one
fieldMode	"auto" | "envelope" | "carrier"		auto	Envelope or carrier-resolved (real field) propagation
fieldHarmonic	number		3	Highest harmonic the carrier-resolved grid holds
absoluteIndex	boolean		true	Add air dispersion to air paths quoted relative to air
strictMaterialsAllow	array			Catalogue quantities that strictMaterials accepts although they are not verified, by catalogue path (e.g. "CS2.n2") as listed in the error and in summary.json unverifiedInputs; matching is case-insensitive and an entry name such as "CS2" accepts all its quantities
strictMaterials	boolean		false	Refuse a run that uses approximate or unverified material-catalogue values (the compile error lists them; override each, or give a verified value in your own catalogue file). The environment variable ULTRAFAST_STRICT_MATERIALS=1 does the same
polarization	"jones" | "scalar"		jones	Jones (two polarisations) or scalar
losses	boolean		true	false removes flat loss terms
beamTracking	any		"auto"	Gaussian beam (q) tracking: "auto" (on with a Gaussian inputBeam), "on", "off"
spatioTemporal	any		"auto"	Spatio-temporal couplings (angular / spatial dispersion, pulse-front tilt) with the tracked beam: "auto" (tracked, and their group-delay dispersion applied unless an element has traced groupDelayS), "on", "track" (reported only), "profile" (gratings and tilted surfaces tilt each frequency of a carried cartesian profile; the field holds the coupling), "off" (docs/reference/components.md#spatio-temporal-couplings)
transverse	object (transverse)			Default spatial model for every bulk/gap/crystal without one
ionization	any		false	Photo-ionisation and plasma in every nonlinear bulk element: true or an ionization object

Stepper

run.stepper.

Nonlinear solver (docs/reference/solvers.md).

key	type	unit	default	meaning
method	"adaptive" | "rk4ip"		adaptive	Adaptive ERK4(3)-IP or fixed-step RK4IP
tolerance	number		1e-6	Adaptive: local relative error per step
maxPhasePerStepRad	number	rad	0.01	Fixed: max nonlinear phase per step; adaptive: initial step
maxAreaChangePerStep	number		0.05	Limit on |d ln A_eff| per step (focusing beams)
minStepM	number	m		Smallest step
maxStepM	number	m		Largest step
maxSteps	integer			Step limit per element
steps	integer			Fixed number of steps (rk4ip)

Outputs

run.outputs.

Files written by the CLI / WriteAll.

key	type	unit	default	meaning
json	boolean		true	summary.json and provenance.json
npz	boolean		true	result.npz
csv	boolean		true	CSV files
maxPoints	integer		0	Cap exported traces (0 = full grid incl. complex fields)
keepProfiles	"all" | "used"		all	Transverse profiles kept in the result: all (after every element) or used (only where an instrument or the end reads one, and before such an element); used saves memory on large grids

Elements

system.elements[], by type. Every element also accepts the common element keys.

amplifier

Multipass or regenerative amplifier around one gain medium (1-D). More: gain.md#the-amplifier-element

Also accepts: gainCommon (see Common key groups).

key	type	unit	default	meaning
ghosts	any		false	Ghost replicas of the end faces: true / false or a ghosts object (components.md#ghost-reflections)
geometry	"multipass" | "regenerative"		multipass	Amplifier type
passes	integer		4	Passes (multipass)
betweenPasses	object (betweenPasses)			loss, gddFs2, todFs3, materials
roundTrips	any		"auto"	Round trips (regenerative) or "auto" (eject at the maximum)
passesPerRoundTrip	integer		2	Crystal passes per round trip
maxRoundTrips	integer		300	Limit for auto
cavity	object (betweenPasses)			lossPerRoundTrip, gddFs2, todFs3, materials

aopdf — plugin: ao

An acousto-optic programmable dispersive filter: programmed spectral phase (delay, GDD, TOD, FOD or a table), finite acoustic window, diffraction efficiency, amplitude table and a spurious replica. More: plugins/ao.md#aopdf

key	type	unit	default	meaning
centerWavelengthM	number	m	the carrier	Wavelength at which the polynomial phase is expanded
delayFs	number	fs	0	Group delay at the centre
gddFs2	number	fs^2	0	Group-delay dispersion
todFs3	number	fs^3	0	Third-order dispersion
fodFs4	number	fs^4	0	Fourth-order dispersion
spectralPhaseRad	number or array	rad		Extra spectral phase table over tableWavelengthsM
amplitudeTable	number or array			Amplitude transmission table over tableWavelengthsM
tableWavelengthsM	number or array	m		Wavelengths of the tables
windowS	number	s	0	Acoustic window: components whose programmed group delay is outside +-window/2 are not diffracted (0 = unlimited)
efficiency	number		1	Diffraction efficiency (power)
replicaAmplitude	number		0	Spurious replica split off the main pulse: H x (1 + a exp(i omega tau)) / sqrt(1 + a^2)
replicaDelayS	number	s	0	Delay of the spurious replica

aperture

A hard or soft aperture (clips; acts on a carried transverse profile). More: system-file.md

Also accepts: beamSize (see Common key groups).

key	type	unit	default	meaning
radiusM	number	m		Circular radius
halfWidthXM	number	m		Rectangular half-width x
halfWidthYM	number	m		Rectangular half-width y
softRadiusM	number	m		Soft (Gaussian / super-Gaussian) aperture radius
order	integer		1	Super-Gaussian order of the soft aperture
aperture	model (aperture)			Aperture model

beamSplitter

Lossless 2x2 splitter: c = t a - r b, d = r a + t b. More: branches.md#beam-splitters

Also accepts: elementCommon (see Common key groups).

key	type	unit	default	meaning
reflectivity	number		0.5	Power reflectivity R
output	string		c	Port that continues in a Sequential system (c, d; also transmitted, reflected)
side	integer		1	Side the light meets: 2 reverses the sign of r (Michelson return)

bulk (also medium)

Propagation in a material, nonlinear when it has a beam and n2. More: system-file.md

Also accepts: nonlinearMedium (see Common key groups).

key	type	unit	default	meaning
material	string			Material name (the file's materials or a built-in) Required.
lengthM	number	m		Length Required.
groupDelayS	number or array	s		Traced group delay (used instead of the material index unless overridden)
groupDelayYS	number or array	s		Traced group delay of y
transmission	number or array			Per-wavelength internal transmission (else the material's attenuation)
dispersionSource	"data" | "material"		data	Use traced data or the material index
airPathM	number	m		Air path whose data are relative to air
air	any			gap only: this gap's air (temperatureC, pressurePa, humidity, co2ppm, and the keys of environment.air), overriding the system's environment.air (docs/reference/gases.md#air-in-the-gaps)
ghosts	any		false	Ghost replicas of the end faces: true / false or a ghosts object (components.md#ghost-reflections)

chirpedMirror

Chirped (dispersive) mirror: GDD/TOD/FOD per bounce. More: system-file.md

key	type	unit	default	meaning
gddS2	number	s^2		GDD per bounce
todS3	number	s^3		TOD per bounce
fodS4	number	s^4		FOD per bounce
gddFs2	number	fs^2		GDD per bounce in fs^2
todFs3	number	fs^3		TOD per bounce in fs^3
fodFs4	number	fs^4		FOD per bounce in fs^4
bounces	integer		1	Number of bounces
reflectance	number		1	Reflectance per bounce
rippleGddFs2	number	fs^2		GDD ripple amplitude per bounce
rippleGddS2	number	s^2		GDD ripple amplitude per bounce
ripplePeriodNm	number	nm		Ripple period in wavelength at the carrier
ripplePeriodThz	number	THz		Ripple period in frequency
ripplePeriodRadPerS	number	rad/s		Ripple period in angular frequency
ripplePhaseRad	number	rad	0	Ripple phase at the carrier
complementaryPairs	boolean		false	Bounces come in complementary pairs (ripples cancel per pair)
referenceWavelengthM	number	m	the carrier	Expansion wavelength

crystal

Chi(2) frequency conversion and parametric amplification (SHG, SFG, OPA, DFG). More: crystals.md

key	type	unit	default	meaning
ghosts	any		false	Ghost replicas of the end faces: true / false or a ghosts object (components.md#ghost-reflections)
crystal	model (crystal)			Built-in crystal name (BBO, LBO, KTP, KDP, LiNbO3, MgO:LiNbO3, BiBO, AgGaSe2), a materials entry, or an object Required.
lengthM	number	m		Length Required.
interaction	object (interaction)			process, type, plane, polarizations, noncollinearDeg, qpm Required.
cut	any		"auto"	"auto" or {thetaDeg, phiDeg, detuneDeg}
detuneDeg	number	deg		Tilt from the phase-matching angle
beam	model (beam)			Main beam model
aux	array of auxBeam			Auxiliary beams (pump, signal, b)
mainRole	string			Role of the main beam (signal, idler, pump, a)
output	string			Field that continues as the main beam
record	array			Names of fields kept as by-products
overlap	any		"gaussian"	"gaussian", "planeWave", {model, radiusM} or {areaM2}
deffPmPerV	number	pm/V		Effective nonlinearity (overrides the tensor)
temperatureC	number	degC		Crystal temperature
chi3	boolean		true	Include the crystal's chi(3) (SPM/XPM)
n2	number	m^2/W		n2 of the crystal
seedNoise	boolean		true	Seed generated fields with vacuum noise
noiseSeed	integer			Noise random seed
spectralMargin	number			Spectral span factor
polarizationAxisDeg	number	deg		Angle of the crystal's slow axis in the lab x-y plane
transverse	object (transverse)			Spatial model

custom

A spectral filter: any filter model (transmission and phase). More: system-file.md

key	type	unit	default	meaning
filter	model (filter)			Filter model
model	model (filter)			Filter model (alternative key)
mechanism	string		filter	Name of the loss in the budget

deformableMirror — plugin: ao

A parametric deformable mirror on the carried transverse profile: actuator layout, Gaussian influence function, stroke limit, drive quantisation. Compiles to a modulator with an optical-path (achromatic) map. Generic: no vendor data. More: plugins/ao.md#deformablemirror

key	type	unit	default	meaning
layout	"square" | "hex" | "ring" | "explicit"		square	Actuator layout
actuatorsX	integer			Actuators along x (square), per row (hex)
actuatorsY	integer		actuatorsX	Actuators along y (square), rows (hex)
ringCounts	number or array			ring layout: actuators on ring k (radius k pitch); the first entry is the centre actuator count
positionsXM	number or array	m		explicit layout: actuator x positions
positionsYM	number or array	m		explicit layout: actuator y positions
pitchM	number	m		Actuator pitch Required.
commandsM	any	m	0	Drive coefficient per actuator (the surface is the sum of the influence functions: a uniform drive gives about 1.7 x the drive in the interior at coupling 0.15, not a uniform piston), positive away from the incoming beam (lengthens the path): a list in layout order, or [actuatorsX][actuatorsY] for the square layout
influenceCoupling	number		0.15	Surface value at a neighbouring actuator when one actuator is driven (Gaussian influence function exp(ln(c) (r/pitch)^2))
strokeM	number	m	unlimited	Mechanical stroke limit (commands are clipped to +-strokeM)
driveBits	integer		0	Drive resolution in bits over +-strokeM (needs strokeM); 0 = continuous
incidenceAngleRad	number	rad	0	Angle of incidence; the wavefront changes by 2 cos(aoi) times the surface
clearApertureRadiusM	number	m	0	Radius of the circular clear aperture (0 = the actuator footprint)
marginPitches	number		0.5	Border around the outermost actuators, in pitches
reflectivity	number		1	Power reflectivity
samplesPerActuator	integer		4	Surface cells per actuator pitch along x and y
designWavelengthM	number	m	the carrier	Wavelength at which the optical path becomes a phase

delay

A pure delay on a stage: a path in vacuum, or a time. More: branches.md#delays

Also accepts: elementCommon (see Common key groups).

key	type	unit	default	meaning
delayS	number	s		Delay
lengthM	number	m		... or the vacuum path giving it
tiltXRad	number	rad	0	Tilt of the beam against the axis
tiltYRad	number	rad	0	Tilt in y
offsetXM	number	m	0	Offset of the beam from the axis
offsetYM	number	m	0	Offset in y

dichroic

A spectral splitter: reflects one side of an edge, transmits the other. More: branches.md#beam-splitters

Also accepts: elementCommon (see Common key groups).

key	type	unit	default	meaning
edgeWavelengthM	number	m		Wavelength of R = 1/2 Required.
edgeWidthM	number	m	10e-9	10-90 % width of the edge
reflectLong	boolean		true	Reflect wavelengths above the edge (else below)
output	string		c	Port that continues in a Sequential system (c, d)

dispersion

Linear dispersion: sampled group delay, spectral phase or Taylor coefficients. More: system-file.md

key	type	unit	default	meaning
groupDelayS	number or array	s		Per-wavelength absolute group delay (e.g. traced group path / c)
groupDelayYS	number or array	s		Group delay of the y polarisation (if different)
phaseRad	number or array	rad		Per-wavelength spectral phase (alternative)
gddS2	number	s^2		GDD
todS3	number	s^3		TOD
fodS4	number	s^4		FOD
gddFs2	number	fs^2		GDD in fs^2
todFs3	number	fs^3		TOD in fs^3
fodFs4	number	fs^4		FOD in fs^4
groupDelayAtCarrierS	number	s		Absolute group delay at the carrier
referenceWavelengthM	number	m	the carrier	Expansion wavelength
transmission	number or array			Per-wavelength power transmission
lossMechanism	string		transmission	Name of the transmission loss in the budget
airPathM	number	m		Length of air whose data are relative to air (absolute-index correction)
lengthM	number	m		Geometric length (informational)

faradayRotator (also faraday)

Faraday rotator: non-reciprocal rotation with Verdet dispersion, optional crystal (dispersion, B-integral). More: components.md#faraday-rotators

Also accepts: nonlinearMedium (see Common key groups).

key	type	unit	default	meaning
rotationDeg	number	deg	45	Rotation at the design wavelength
designWavelengthM	number	m	the carrier	Design wavelength
verdetRadPerTM	number	rad/(T m)		Verdet constant (with fieldT and lengthM)
fieldT	number	T		Magnetic field
lengthM	number	m		Crystal length
material	string			Crystal (e.g. TGG)
verdetDispersion	"inverseSquare" | "none"		inverseSquare	V ~ 1/(lambda^2 - lambda0^2)
verdetPoleWavelengthM	number	m	258e-9	lambda0
direction	number		1	+1 forward, -1 backward (non-reciprocal)
transmission	number		1	Power transmission

fiber (also fibre, waveguide)

A single-mode fibre or waveguide: Taylor betas, a dispersion curve or a material; gamma or n2 + effective area; loss; gain; Raman; soliton and dispersive-wave diagnostics. More: fibers.md

key	type	unit	default	meaning
lengthM	number	m		Fibre length Required.
betas	number or array	s^k/m		Taylor coefficients [beta2, beta3, ...] at referenceWavelengthM (SI)
betasPsKm	number or array	ps^k/km		Taylor coefficients [beta2, beta3, ...] in ps^k/km (pyNLO / fibre-datasheet units)
referenceWavelengthM	number	m	the carrier	Wavelength of the Taylor expansion
dispersion	object (fiberDispersion)			Dispersion curve {wavelengthsM, dPsNmKm | beta2S2PerM} (alternative to betas)
material	string			Bulk material for the dispersion (alternative to betas)
effectiveIndex	number		1.45	Mode index at the reference (sets only the absolute phase / group delay)
gamma	any	1/(W m)		Nonlinear coefficient: a number, or an expression in z (m) for a tapered fibre
n2	number	m^2/W	2.6e-20	Nonlinear index (with effectiveAreaM2 or modeFieldDiameterM, instead of gamma)
effectiveAreaM2	number	m^2	1e-11 with gamma	Effective mode area
modeFieldDiameterM	number	m		Mode-field diameter (A_eff = pi MFD^2 / 4)
lossDbPerKm	number	dB/km	0	Propagation loss
loss	object (fiberLossTable)			Loss vs wavelength {wavelengthsM, dbPerKm} (alternative)
gainDbPerM	number	dB/m	0	Flat (small-signal) gain
gain	object (fiberGain)			Gain spectrum {wavelengthsM, dbPerM, outputEnergyJ | outputPowerW}
raman	any		"silica"	Raman model: "silica" (Blow-Wood), "linAgrawal", "hollenbeck", "none" / false, or a delayed-response model
ramanFraction	number		the model's (0.18; Lin-Agrawal 0.245)	Raman fraction
nonlinear	boolean		true	false forces linear propagation
selfSteepening	boolean		run setting	Self-steepening (optical shock)
timeResponse	model (timeResponse)			An extra time-domain response n(t, I)
replaceKerr	boolean		false	true switches off the built-in Kerr/Raman
ionization	any		false	Photo-ionisation (hollow-core gas fibres): true or an ionization object

filter

A spectral filter: any filter model (transmission and phase). More: system-file.md

key	type	unit	default	meaning
filter	model (filter)			Filter model
model	model (filter)			Filter model (alternative key)
mechanism	string		filter	Name of the loss in the budget

gain

A pumped gain medium crossed once (1-D or spatial). More: gain.md

Also accepts: gainCommon (see Common key groups).

key	type	unit	default	meaning
ghosts	any		false	Ghost replicas of the end faces: true / false or a ghosts object (components.md#ghost-reflections)

gap

Free space (air by default); linear unless nonlinear: true. More: system-file.md

Also accepts: nonlinearMedium (see Common key groups).

key	type	unit	default	meaning
material	string		Air	Material name (the file's materials or a built-in)
lengthM	number	m		Length Required.
groupDelayS	number or array	s		Traced group delay (used instead of the material index unless overridden)
groupDelayYS	number or array	s		Traced group delay of y
transmission	number or array			Per-wavelength internal transmission (else the material's attenuation)
dispersionSource	"data" | "material"		data	Use traced data or the material index
airPathM	number	m		Air path whose data are relative to air
air	any			gap only: this gap's air (temperatureC, pressurePa, humidity, co2ppm, and the keys of environment.air), overriding the system's environment.air (docs/reference/gases.md#air-in-the-gaps)
ghosts	any		false	Ghost replicas of the end faces: true / false or a ghosts object (components.md#ghost-reflections)

grating

A diffracting surface (one grating). More: system-file.md

Also accepts: beamSize (see Common key groups).

key	type	unit	default	meaning
mode	"refract" | "reflect" | "diffract"		diffract	Surface action
before	string		Air	Medium before the surface
after	string			Medium after (mirror: substrate/metal; omitted = ideal)
aoiRad	number or array	rad		Angle of incidence (per wavelength or scalar)
aoiDeg	number or array	deg		Angle of incidence in degrees
coating	model (coating)			Coating name (from coatings) or inline coating; none = bare Fresnel
ripple	any			Phase / amplitude ripple of the coating: {phaseRmsRad, amplitudeRms, maxDelayS (5e-12), seed, components (64)} -- a random ripple whose pedestal lies within +-maxDelayS (docs/reference/coatings.md#coating-ripple). Measured ripple: a table coating
delayedScatter	any			Scatter returned as delayed light: {fraction, delay: {kind: uniform|exponential|table, minS, maxS, tauS, delaysS, weights}, spectralExponent, seed}, or the analytic surface model {model: "surface", roughnessRmsM, correlationLengthM, beamRadiusM, surfaces, delay} (docs/reference/coatings.md#delayed-scatter)
substrate	any			mirror: the substrate behind the coating -- a name (from the file's substrates or the built-in catalogue, e.g. "FS-12.7mm") or {material, thicknessM, backCoating | backReflectance, wedgeDeg, orders}. Light leaking through the coating reflects from the back face and returns as a delayed echo (docs/reference/coatings.md#substrate-echoes)
linesPerMm	number	1/mm		grating: groove density -- angular dispersion, anamorphic magnification and spatio-temporal couplings on the tracked beam
linesPerM	number	1/m		grating: groove density (alternative)
order	integer		-1	grating: diffraction order m, sin(theta_out) = sin(theta_in) + m lambda / period with signed angles in the unfolded beam
efficiency	number or array			Diffraction efficiency (grating, no coating)
efficiencyS	number or array			s efficiency
efficiencyP	number or array			p efficiency
kIn	number or array			Incoming ray direction (global) for exact s/p basis transport
kOut	number or array			Outgoing ray direction
normal	number or array			Surface normal
planeOfIncidenceDeg	number	deg	90	s-direction angle from local x when no vectors are given Also: planeOfIncidence.
semiDiameterM	number	m		Hard circular aperture
clearApertureM	number	m		Clear aperture (alternative)
aperture	model (aperture)			Aperture model
beam	model (beam)			Beam at the surface (instead of beamRadiusM)
roughnessRmsM	number	m		Rms roughness -> total integrated scatter
lidt	object (lidt)			Damage threshold (else the coating's, else the material's)
radiusOfCurvatureM	number	m		Curved mirror: f = R/2 (off-axis: f_t = R cos(aoi)/2, f_s = R/(2 cos(aoi))) on the tracked beam and a carried profile
focalLengthM	number	m		Focal length (mirror, alternative to the radius)
aberration	object (aberration)			Wavefront error / surface figure (Zernike, random figure)

gratingPair

Treacy grating pair (exact dispersion; negative separation = stretcher). More: system-file.md

key	type	unit	default	meaning
linesPerMm	number	1/mm		Groove density
linesPerM	number	1/m		Groove density (alternative)
aoiDeg	number	deg		Angle of incidence Required.
aoiRad	number	rad		Angle of incidence
separationM	number	m		Perpendicular separation (negative for a stretcher) Required.
order	integer		-1	Diffraction order
passes	integer		2	Passes through the pair
efficiency	number		1	Efficiency per diffraction

interface (also surface)

A refracting surface: Fresnel or coating, clipping, polarisation basis. More: system-file.md

Also accepts: beamSize (see Common key groups).

key	type	unit	default	meaning
mode	"refract" | "reflect" | "diffract"		refract	Surface action
before	string		Air	Medium before the surface
after	string			Medium after (mirror: substrate/metal; omitted = ideal)
aoiRad	number or array	rad		Angle of incidence (per wavelength or scalar)
aoiDeg	number or array	deg		Angle of incidence in degrees
coating	model (coating)			Coating name (from coatings) or inline coating; none = bare Fresnel
ripple	any			Phase / amplitude ripple of the coating: {phaseRmsRad, amplitudeRms, maxDelayS (5e-12), seed, components (64)} -- a random ripple whose pedestal lies within +-maxDelayS (docs/reference/coatings.md#coating-ripple). Measured ripple: a table coating
delayedScatter	any			Scatter returned as delayed light: {fraction, delay: {kind: uniform|exponential|table, minS, maxS, tauS, delaysS, weights}, spectralExponent, seed}, or the analytic surface model {model: "surface", roughnessRmsM, correlationLengthM, beamRadiusM, surfaces, delay} (docs/reference/coatings.md#delayed-scatter)
substrate	any			mirror: the substrate behind the coating -- a name (from the file's substrates or the built-in catalogue, e.g. "FS-12.7mm") or {material, thicknessM, backCoating | backReflectance, wedgeDeg, orders}. Light leaking through the coating reflects from the back face and returns as a delayed echo (docs/reference/coatings.md#substrate-echoes)
linesPerMm	number	1/mm		grating: groove density -- angular dispersion, anamorphic magnification and spatio-temporal couplings on the tracked beam
linesPerM	number	1/m		grating: groove density (alternative)
order	integer		-1	grating: diffraction order m, sin(theta_out) = sin(theta_in) + m lambda / period with signed angles in the unfolded beam
efficiency	number or array			Diffraction efficiency (grating, no coating)
efficiencyS	number or array			s efficiency
efficiencyP	number or array			p efficiency
kIn	number or array			Incoming ray direction (global) for exact s/p basis transport
kOut	number or array			Outgoing ray direction
normal	number or array			Surface normal
planeOfIncidenceDeg	number	deg	90	s-direction angle from local x when no vectors are given Also: planeOfIncidence.
semiDiameterM	number	m		Hard circular aperture
clearApertureM	number	m		Clear aperture (alternative)
aperture	model (aperture)			Aperture model
beam	model (beam)			Beam at the surface (instead of beamRadiusM)
roughnessRmsM	number	m		Rms roughness -> total integrated scatter
lidt	object (lidt)			Damage threshold (else the coating's, else the material's)
radiusOfCurvatureM	number	m		Curved mirror: f = R/2 (off-axis: f_t = R cos(aoi)/2, f_s = R/(2 cos(aoi))) on the tracked beam and a carried profile
focalLengthM	number	m		Focal length (mirror, alternative to the radius)
aberration	object (aberration)			Wavefront error / surface figure (Zernike, random figure)

leakMirror

A mirror that leaks: reflected light continues, the leak is a port. More: branches.md#beam-splitters

Also accepts: elementCommon (see Common key groups).

key	type	unit	default	meaning
transmission	number		0.01	Power transmission
wavelengthsM	number or array	m		Wavelengths of transmissionSpectrum
transmissionSpectrum	number or array			Power transmission at each wavelength (instead of transmission)
gddFs2	number	fs^2	0	GDD of the reflected beam
leakGddFs2	number	fs^2	0	GDD of the leak (substrate)
output	string		out	Port that continues in a Sequential system (out, leak)

lens

Thin lens on a carried transverse profile (chromatic with a material). More: system-file.md

key	type	unit	default	meaning
ghosts	any		false	Ghost replicas of the end faces: true / false or a ghosts object (components.md#ghost-reflections)
focalLengthM	number	m		Focal length at the carrier Required.
material	string			Lens glass (chromatic focal length)
medium	string		Air	Surrounding medium
thicknessM	number	m	0	Glass thickness (adds its dispersion)
focalLengthXM	number	m		Focal length in x (cylindrical / astigmatic)
focalLengthYM	number	m		Focal length in y
aberration	object (aberration)			Wavefront error

mask

A thin mask on the carried transverse profile: axicon, Fresnel zone plate, vortex phase plate, slits, or an amplitude / phase map from a file. More: transverse.md#masks

key	type	unit	default	meaning
kind	"axicon" | "zonePlate" | "vortex" | "slits" | "file"			Mask Required.
coneAngleRad	number	rad		axicon: deflection angle (phase -k r sin(angle))
focalLengthM	number	m		zonePlate: first-order focal length at the design wavelength
binaryPhase	boolean		false	zonePlate: closed zones shift by pi instead of blocking
designWavelengthM	number	m	the carrier	zonePlate: design wavelength; file: wavelength of phase_rad
charge	integer		1	vortex: topological charge l (phase l phi)
count	integer		2	slits: number of slits
widthM	number	m		slits: slit width
separationM	number	m		slits: centre-to-centre distance
heightM	number	m	unlimited	slits: height in y
file	string			file: NPZ with x_m, y_m (or r_m), amplitude, and optionally phase_rad; relative to the system file
decenterXM	number	m		Decentre in x
decenterYM	number	m		Decentre in y

mirror

A reflecting surface: coating, AOI, s/p phases, curvature. More: system-file.md

Also accepts: beamSize (see Common key groups).

key	type	unit	default	meaning
mode	"refract" | "reflect" | "diffract"		reflect	Surface action
before	string		Air	Medium before the surface
after	string			Medium after (mirror: substrate/metal; omitted = ideal)
aoiRad	number or array	rad		Angle of incidence (per wavelength or scalar)
aoiDeg	number or array	deg		Angle of incidence in degrees
coating	model (coating)			Coating name (from coatings) or inline coating; none = bare Fresnel
ripple	any			Phase / amplitude ripple of the coating: {phaseRmsRad, amplitudeRms, maxDelayS (5e-12), seed, components (64)} -- a random ripple whose pedestal lies within +-maxDelayS (docs/reference/coatings.md#coating-ripple). Measured ripple: a table coating
delayedScatter	any			Scatter returned as delayed light: {fraction, delay: {kind: uniform|exponential|table, minS, maxS, tauS, delaysS, weights}, spectralExponent, seed}, or the analytic surface model {model: "surface", roughnessRmsM, correlationLengthM, beamRadiusM, surfaces, delay} (docs/reference/coatings.md#delayed-scatter)
substrate	any			mirror: the substrate behind the coating -- a name (from the file's substrates or the built-in catalogue, e.g. "FS-12.7mm") or {material, thicknessM, backCoating | backReflectance, wedgeDeg, orders}. Light leaking through the coating reflects from the back face and returns as a delayed echo (docs/reference/coatings.md#substrate-echoes)
linesPerMm	number	1/mm		grating: groove density -- angular dispersion, anamorphic magnification and spatio-temporal couplings on the tracked beam
linesPerM	number	1/m		grating: groove density (alternative)
order	integer		-1	grating: diffraction order m, sin(theta_out) = sin(theta_in) + m lambda / period with signed angles in the unfolded beam
efficiency	number or array			Diffraction efficiency (grating, no coating)
efficiencyS	number or array			s efficiency
efficiencyP	number or array			p efficiency
kIn	number or array			Incoming ray direction (global) for exact s/p basis transport
kOut	number or array			Outgoing ray direction
normal	number or array			Surface normal
planeOfIncidenceDeg	number	deg	90	s-direction angle from local x when no vectors are given Also: planeOfIncidence.
semiDiameterM	number	m		Hard circular aperture
clearApertureM	number	m		Clear aperture (alternative)
aperture	model (aperture)			Aperture model
beam	model (beam)			Beam at the surface (instead of beamRadiusM)
roughnessRmsM	number	m		Rms roughness -> total integrated scatter
lidt	object (lidt)			Damage threshold (else the coating's, else the material's)
radiusOfCurvatureM	number	m		Curved mirror: f = R/2 (off-axis: f_t = R cos(aoi)/2, f_s = R/(2 cos(aoi))) on the tracked beam and a carried profile
focalLengthM	number	m		Focal length (mirror, alternative to the radius)
aberration	object (aberration)			Wavefront error / surface figure (Zernike, random figure)

modulator

A pixelated thin phase / amplitude modulator (spatial light modulator, deformable-mirror surface, tile mask) on the carried transverse profile: a cell grid with a fill factor, gaps, quantisation, phase wrapping, cross-talk and a stated chromatic rule. More: modulator.md

key	type	unit	default	meaning
cellsX	integer		from the map	Cells along x
cellsY	integer		from the map	Cells along y
pitchXM	number	m		Cell pitch along x Required.
pitchYM	number	m	pitchXM	Cell pitch along y
offsetXM	number	m	0	Centre of the array in x
offsetYM	number	m	0	Centre of the array in y
rotationRad	number	rad	0	Rotation of the array about its centre
phaseRad	any	rad		Commanded phase at designWavelengthM: an array [cellsX][cellsY] or a callback "@name" f(x, y, z) (cell centres, z = 0)
opdM	any	m		Commanded optical path instead of phaseRad (same forms)
amplitude	any		1	Amplitude transmission per cell (same forms)
file	string			NPZ with phase_rad or opd_m, and amplitude, shaped [cellsX][cellsY]; relative to the system file
designWavelengthM	number	m	the carrier	Wavelength at which phaseRad holds
chromatic	"opd" | "phaseAtDesign" | "fixedPhase" | "index"		opd	opd (also phaseAtDesign): the written phase is an optical path, phase = phaseRad * omega / omega_design (a wrapped map is a grating); fixedPhase: the phase does not change with frequency; index: phase = phaseRad * omega dn(omega) / (omega_design dn(omega_design)), a liquid-crystal cell with a dispersive index modulation dn
deltaIndexCauchy	number or array			chromatic index: dn = A + B / lambda^2 + C / lambda^4 as [A, B (m^2), C (m^4)]; only the ratio dn(lambda) / dn(design) matters
deltaIndex	number or array			chromatic index: a table of dn (linear in lambda between points), with deltaIndexWavelengthsM
deltaIndexWavelengthsM	number or array	m		Wavelengths of the deltaIndex table
fillFactor	number		1	Active fraction of the pitch in x and y (0-1]
gapTransmission	number		0	Amplitude transmission of the gaps
outsideTransmission	number		0	Amplitude transmission outside the array
zeroOrderLeak	number		0	Amplitude fraction eta that passes unmodulated (phase 0) inside active cells: t = a [(1 - eta) e^(i phi) + eta]; a flat map stays lossless
crosstalkSigmaCells	number		0	Gaussian fringing-field cross-talk, standard deviation in cells (applied to the written phase and amplitude)
crosstalkKernel	number or array			Explicit cross-talk kernel in cells (odd length, centre weight in the middle, normalised to unit sum), applied along x and along y to the written phase and amplitude; overrides crosstalkSigmaCells; weights must be >= 0
quantisationLevels	integer		0	Phase levels over phaseWrapRad (2 pi if that is 0); 0 = continuous
phaseWrapRad	number	rad	0	Wrap the commanded phase to [0, phaseWrapRad); 0 = no wrapping

ndFilter

A neutral-density filter (absorptive or reflective): OD or OD(lambda), substrate, ghosts. More: components.md#ndfilter

Also accepts: nonlinearMedium, beamSize (see Common key groups).

key	type	unit	default	meaning
material	string		N-BK7 (absorptive) / FusedSilica (reflective)	Substrate
thicknessM	number	m	2e-3 / 1e-3	Thickness
aoiDeg	number	deg	0	Angle of incidence
aoiRad	number	rad		Angle of incidence
planeOfIncidenceDeg	number	deg	90	s-direction angle from x
medium	string		Air	Surrounding medium
coating	model (coating)			Coating of both surfaces
coatingFront	model (coating)			Front coating
coatingBack	model (coating)			Back coating
wedgeDeg	number	deg	0	Wedge angle (tilts the ghosts)
ghosts	any		false	true / false or a ghosts object
delayedScatter	any			Bulk back-scatter returned as delayed light: {fraction, delay: {kind: uniform, maxS (default 2 n_g d cos(theta)/c)}, spectralExponent, seed}, or the analytic surface model {model: "surface", roughnessRmsM, correlationLengthM, beamRadiusM, surfaces (default 2), delay} (docs/reference/coatings.md#delayed-scatter)
od	number or array			Optical density (number, or per wavelength)
kind	"absorptive" | "reflective"		absorptive	ND type (ndFilter)

oscillator

A mode-locked laser that replaces the incoming beam (parametric, Haus or cavity model). More: oscillators.md

key	type	unit	default	meaning
model	"parametric" | "haus" | "cavity"			Model Required.
repRateHz	number	Hz		Repetition rate
cavityLengthM	number	m		Cavity length (alternative)
ring	boolean		false	Ring cavity
outputCoupler	number			Output-coupler transmission
output	object (pulse)			parametric: the output pulse (run-spec pulse keys)
gain	object			haus: lumped gain {smallSignalGain|smallSignalLnGain, saturationEnergyJ|saturationPowerW, shape, centerWavelengthM, bandwidthM, fluenceSaturationEnergyJ}; cavity: a gain medium (gain-element keys)
absorber	object			haus: saturable absorber (absorber parameters)
lossPerRoundTrip	number			Lumped loss
gddFs2	number	fs^2		Round-trip GDD
todFs3	number	fs^3		Round-trip TOD
gddS2	number	s^2		Round-trip GDD
todS3	number	s^3		Round-trip TOD
spmRadPerW	number	rad/W		Lumped SPM delta
elements	array of element			cavity: elements run every round trip
start	"noise" | "pulse"			Start from quantum noise or from the run's pulse
seed	integer			Noise seed
seedEnergyJ	number	J		Energy of the starting pulse
roundTrips	any			Maximum round trips, or {max}
checkEvery	integer		25	Convergence check interval
tolerance	number			Convergence tolerance
gridPoints	integer		4096	Samples the oscillator iterates on
relaxation	number		0.2	cavity: inversion relaxation per round trip
passesPerRoundTrip	integer		2	cavity: crystal passes per round trip
snapshots	integer			Evolution snapshots kept

plate (also window)

A plane-parallel plate or window: two surfaces, bulk dispersion, absorption and nonlinearity, ghost replicas. More: components.md#plate

Also accepts: nonlinearMedium, beamSize (see Common key groups).

key	type	unit	default	meaning
material	string			Plate material Required.
thicknessM	number	m		Thickness Required.
aoiDeg	number	deg	0	Angle of incidence
aoiRad	number	rad		Angle of incidence
planeOfIncidenceDeg	number	deg	90	s-direction angle from x
medium	string		Air	Surrounding medium
coating	model (coating)			Coating of both surfaces
coatingFront	model (coating)			Front coating
coatingBack	model (coating)			Back coating
wedgeDeg	number	deg	0	Wedge angle (tilts the ghosts)
ghosts	any		false	true / false or a ghosts object
delayedScatter	any			Bulk back-scatter returned as delayed light: {fraction, delay: {kind: uniform, maxS (default 2 n_g d cos(theta)/c)}, spectralExponent, seed}, or the analytic surface model {model: "surface", roughnessRmsM, correlationLengthM, beamRadiusM, surfaces (default 2), delay} (docs/reference/coatings.md#delayed-scatter)
od	number or array			(ndFilter only)
kind	"absorptive" | "reflective"		absorptive	ND type (ndFilter)

polarizer

A linear polariser. More: system-file.md

key	type	unit	default	meaning
axisDeg	number	deg	0	Transmission axis from x
axisRad	number	rad		Transmission axis
extinctionRatio	number		1e5	Extinction ratio
transmission	number		1	Transmission along the axis

polarizingSplitter

A polarising splitter: p (x) mostly transmitted, s (y) mostly reflected. More: branches.md#beam-splitters

Also accepts: elementCommon (see Common key groups).

key	type	unit	default	meaning
transmissionP	number		1	Power transmission of x
reflectivityS	number		1	Power reflectivity of y
output	string		c	Port that continues in a Sequential system (c, d)
side	integer		1	2 reverses the sign of r

prism

A prism in air: two refracting faces and the glass on the chief ray; disperses the tracked beam. More: components.md#spatio-temporal-couplings

key	type	unit	default	meaning
material	string			Prism glass Required.
apexDeg	number	deg		Apex angle Required.
aoiDeg	number	deg		Signed angle of incidence on the first face Required.
pathM	number	m	0	Glass path of the carrier's ray
medium	string		Air	Surrounding medium
planeOfIncidenceDeg	number	deg	90	s-direction angle from local x Also: planeOfIncidence.
fresnel	boolean		true	Fresnel losses of the two faces

probe (also marker)

A named place in the beam (does nothing; snapshots and instruments). More: system-file.md

No parameters of its own.

resonator

A passive resonator around nested elements: round-trip matrix, stability, eigenmode on the tracked beam; with a transverse grid, the Fox-Li mode and diffraction loss. More: oscillators.md#resonators

key	type	unit	default	meaning
elements	any			The elements of one pass (gaps, lenses, mirrors, apertures ...) Required.
geometry	"ring" | "linear"		ring	ring: once per round trip; linear: forward and back, end elements once
transverse	object (transverse)			Grid of the Fox-Li iteration (given to nested gaps and bulks without one)
roundTrips	any			{max (400), tolerance (1e-6)}

rotator

Rotates the polarisation (and the image). More: system-file.md

key	type	unit	default	meaning
angleDeg	number	deg	0	Rotation angle
angleRad	number	rad		Rotation angle

saturableAbsorber (also sesam)

Saturable absorber: slow (SESAM), fast or Kerr-lens loss modulation. More: oscillators.md#saturable-absorbers

Also accepts: absorberParams (see Common key groups).

key	type	unit	default	meaning
absorber	model (absorber)			Absorber model (kind slow / fast / kerrLens and its parameters), or the parameters directly on the element

slm — plugin: ao

A parametric phase-only liquid-crystal spatial light modulator: pixels, fill factor, grey levels through a voltage-to-phase curve, dispersive birefringence, fringing cross-talk. Compiles to a modulator. Generic: no vendor data. More: plugins/ao.md#slm

key	type	unit	default	meaning
pixelsX	integer		from the map	Pixels along x
pixelsY	integer		from the map	Pixels along y
pitchM	number	m		Pixel pitch Required.
pitchYM	number	m	pitchM	Pixel pitch along y
offsetXM	number	m	0	Centre of the panel in x
offsetYM	number	m	0	Centre of the panel in y
rotationRad	number	rad	0	Rotation of the panel
fillFactor	number		1	Active fraction of the pitch (0-1]
gapTransmission	number		0	Amplitude transmission of the gaps
outsideTransmission	number		0	Amplitude transmission outside the panel
greyLevels	integer		256	Number of grey levels
lutKind	"linear" | "tanh" | "table"		linear	Voltage-to-phase curve: linear (maxPhaseRad k / levels), tanh (S-shaped, lutSteepness) or table (lutPhaseRad)
maxPhaseRad	number	rad	2 pi	Phase range of the curve at the design wavelength
lutSteepness	number		2	tanh curve steepness
lutPhaseRad	number or array	rad		table curve: phase of each grey level (non-decreasing)
greyLevel	any			Grey level of each pixel [pixelsX][pixelsY]
phaseTargetRad	any	rad		Wanted phase [pixelsX][pixelsY]: wrapped to 2 pi and mapped to the nearest grey level of the curve
file	string			NPZ with grey_level or phase_target_rad [pixelsX][pixelsY]; relative to the system file
designWavelengthM	number	m	the carrier	Wavelength at which the curve holds
dispersion	"liquidCrystal" | "none"		liquidCrystal	liquidCrystal: phase scales with omega dn(omega) (the written 2 pi reset is only 2 pi at the design wavelength); none: an achromatic optical path
deltaIndexCauchy	number or array			Birefringence dn = A + B/lambda^2 + C/lambda^4 as [A, B (m^2), C (m^4)]; default a GENERIC nematic preset (unverified)
crosstalkSigmaCells	number		0	Gaussian fringing-field cross-talk, standard deviation in pixels
crosstalkKernel	number or array			Explicit cross-talk kernel (odd length, non-negative)
zeroOrderLeak	number		0	Amplitude fraction that passes unmodulated

spectralShaper — plugin: ao

A pixelated spectral phase / amplitude mask in the Fourier plane of a 4f line (1-D SLM pulse shaper), as a linear spectral transfer function. The programmed group delay is kept in the transfer (the pulse moves inside the time window). More: plugins/ao.md#spectralshaper

key	type	unit	default	meaning
pixels	integer			Number of pixels Required.
pixelPitchM	number	m		Pixel pitch Required.
fillFactor	number		1	Active fraction of the pitch (0-1]
gapTransmission	number		0	Amplitude transmission of the gaps
outsideTransmission	number		0	Amplitude transmission beyond the array
centerWavelengthM	number	m	the carrier	Wavelength at the centre of the array
offsetM	number	m	0	Position of the array centre relative to the centre wavelength's focus
dispersionMPerM	number		from the grating	Focal-plane position per wavelength (m of position per m of wavelength; 1e6 = 1 mm/nm)
gratingLinesPerMm	number	1/mm		Grating line density
incidenceAngleRad	number	rad	0	Angle of incidence on the grating
order	number		1	Diffraction order
focalLengthM	number	m		Focal length of the 4f lens
spotRadiusM	number	m	lambda f / (pi inputBeamRadiusM)	1/e^2 field radius of the focused monochromatic spot
inputBeamRadiusM	number	m		Beam radius at the grating (sets the spot size)
phaseRad	any	rad	0	Phase per pixel
amplitude	any		1	Amplitude transmission per pixel
phaseWrapRad	number	rad	2 pi	Wrap the phase to [0, phaseWrapRad); 0 = no wrapping
greyLevels	integer		0	Phase levels over 2 pi; 0 = continuous

thinFilmPolarizer (also tfp)

Thin-film polariser at its design angle: physical quarter-wave stack (TMM) or ideal, transmitted (p) or reflected (s) port. More: components.md#thin-film-polarisers

Also accepts: nonlinearMedium, beamSize (see Common key groups).

key	type	unit	default	meaning
model	"stack" | "ideal"		stack	Coating model
output	"transmitted" | "reflected"		transmitted	Port that continues
aoiDeg	number	deg	56	Angle of incidence
aoiRad	number	rad		Angle of incidence
axisDeg	number	deg	0	Transmission (p) axis from x
axisRad	number	rad		Transmission axis
substrate	string		FusedSilica	Substrate
thicknessM	number	m	3e-3	Substrate thickness
medium	string		Air	Surrounding medium
designWavelengthM	number	m	the carrier	Stack design wavelength
pairs	integer		12	HL pairs
high	string		HfO2	High-index film
low	string		SiO2_film	Low-index film
coatingBack	model (coating)			Back-surface coating
transmissionP	number		0.98	ideal: Tp
transmissionS	number		1e-3	ideal: Ts
reflectanceS	number		0.998	ideal: Rs
reflectanceP	number		1 - Tp	ideal: Rp

transform — plugin: fitting

Fittable physical changes to the beam: spectral phase / amplitude, energy, polarisation, contrast (replicas, phase noise, pedestals), wavefront. More: plugins/fitting.md#transform-elements

key	type	unit	default	meaning
operators	array of fitting:operator			The operators, applied in order Required.
regularization	number		the run's backward.regularization	Backward propagation: relative Tikhonov level for inverting this element

user

Your own function of the main beam's spectrum (Python, C#, C). More: system-file.md

key	type	unit	default	meaning
callback	model (callback)			"@name" of a registered element callback Required.
params	any			Any JSON passed to the function
lengthM	number	m		Length (informational)

wavefront (also aberration)

A wavefront error (Zernike, random figure) and optional focal power at one plane. More: components.md#aberrations

key	type	unit	default	meaning
aberration	object (aberration)			The wavefront error
zernikeNollWaves	number or array	waves		Zernike coefficients (flat form)
radiusM	number	m		Normalisation radius (flat form)
referenceWavelengthM	number	m		Wavelength of the coefficients
terms	object			Zernike terms by name
randomRmsM	number	m		Random figure rms
correlationLengthM	number	m		Correlation length
seed	integer			Random seed
focalLengthM	number	m		Focal power
focalLengthXM	number	m		Focal length in x
focalLengthYM	number	m		Focal length in y
beamRadiusM	number	m		Beam radius for the 1-D Strehl estimate

waveplate

A waveplate: dispersionless design model, or a thick birefringent plate (multi-order, zero-order, compound) with "material". More: components.md#waveplates

key	type	unit	default	meaning
plate	"half" | "quarter"		half	Plate type
retardanceWaves	number	waves		Retardance at the design wavelength
axisDeg	number	deg	0	Fast-axis angle from x
axisRad	number	rad		Fast-axis angle
designWavelengthM	number	m	the carrier	Design wavelength
material	string			Birefringent crystal: Quartz, MgF2, Sapphire, Calcite, YVO4, aBBO (enables the thick-plate model)
indexOrdinary	model (index)			Ordinary index (user crystal)
indexExtraordinary	model (index)			Extraordinary index (user crystal)
construction	"single" | "compound"		single	One plate, or a compound zero-order pair with crossed axes
thicknessM	number	m		Plate thickness (single)
order	integer		0	Order m: retardance = m + retardanceWaves (single, when no thickness)
plateThicknessM	number	m	1e-3	Thickness of the thicker plate (compound)

Instruments

run.instruments[], by kind. Every instrument also accepts the common instrument keys.

autocorrelator

Intensity or interferometric autocorrelation. More: instruments.md#autocorrelator

key	type	unit	default	meaning
type	"intensity" | "interferometric"		intensity	AC type
rangeS	number	s	3 x FWHM	Delay range (interferometric)
points	integer		4001	Output points (interferometric)
resolutionS	number	s	0	Delay resolution of the scan (Gaussian FWHM, intensity AC)
shgAcceptanceFwhmM	number	m	0	Phase-matching acceptance of the SHG crystal (FWHM of the SH wavelength window); 0: unlimited
acceptancePoints	integer		512	Grid of the finite-acceptance computation
maxN	integer		65536	Grid cap for the computation

beamProfile

Fluence vs radius (or x/y cuts), radius, M^2, true peak fluence. More: instruments.md#beamprofile

No parameters of its own.

camera (also nearFieldCamera, farFieldCamera)

A camera: imaging plane (near / far / relay) + sensor. More: instruments.md#camera

Also accepts: sensorFlat (see Common key groups).

key	type	unit	default	meaning
imaging	object (imaging)			What the sensor sees
sensor	object (sensor)			The detector
plane	string			Shortcut for imaging.plane
bandM	number or array	m		[min, max] band-pass filter

compressor

Ideal compressor: GDD/TOD that maximise peak power. More: instruments.md#compressor

key	type	unit	default	meaning
optimizeTod	boolean		true	Also optimise TOD
maxN	integer		131072	Grid cap
points	integer		4096	Output points

contrast

Intensity in dB, pre/post-pulse contrast, pedestal fraction (ideal). More: instruments.md#contrast

key	type	unit	default	meaning
resolutionS	number	s		Temporal resolution
windowS	number	s	5 x FWHM	Pre/post window
dynamicRangeDb	number	dB	120	Noise floor
points	integer		8192	Output points

conversion

Energies and photon numbers of every field leaving an active element. More: instruments.md#conversion

No parameters of its own.

crossCorrelator (also thirdOrderCorrelator)

Third-order (SHG-gated) cross-correlator: high-dynamic-range contrast with noise floor, resolution, scan grid, polarisation. More: instruments.md#crosscorrelator

key	type	unit	default	meaning
rangeS	number or array	s	the simulated window	[min, max] delay scan (relative to the peak)
stepS	number	s		Coarse step
points	integer		2001	Coarse points (when no step)
fineStepS	number	s		Fine step near zero delay
fineRangeS	number	s		Half-range of the fine steps
dynamicRangeDb	number	dB	110	Noise floor below the peak
noiseFloor	number			Noise floor (relative to the peak; alternative to dynamicRangeDb)
noise	boolean		true	Fluctuating detector background (else a flat floor)
seed	integer		1	Noise seed
saturationLevel	number		0	Detector saturation: the reading (signal x attenuation + floor) is clipped at this level, relative to the unattenuated peak (0 or omitted: none)
segments	any			Attenuation-range stitching: a list of {fromS, toS, attenuation (or gain), noiseFloor} -- the signal in that delay range is measured through the attenuation (power factor) and divided by it afterwards, so the floor rises as 1/attenuation and saturation moves up accordingly
resolutionS	number	s	0	Extra temporal resolution (Gaussian FWHM)
shgAcceptanceFwhmM	number	m		SHG crystal acceptance (SH wavelength FWHM)
polarization	any		"total"	"total", "x", "y" or an analyser angle in degrees
gateArm	any			Elements in the gate arm only: {elements: [...], materials: {...}}. The second-harmonic gate (at lambda0/2) passes them before the sum-frequency step; the probe channel does not. Window: the instrument's (grid.windowS or grid.tail) must hold the replicas
probeDelaysS	number or array	s		Delays at which to report the contrast in dB
windowS	number	s	5 x FWHM	Pre/post window around the peak

delayScan

Re-runs a crystal for aux delays: output energy vs delay. More: instruments.md#delayscan

key	type	unit	default	meaning
fromS	number	s	-1e-12	First delay
toS	number	s	1e-12	Last delay
points	integer		21	Points

dscan

Dispersion scan: SHG spectrum vs glass insertion or GDD. More: instruments.md#dscan

key	type	unit	default	meaning
material	string			Wedge material (with insertionM)
insertionM	number or array	m		[min, max] insertion
gddRangeS2	number or array	s^2		[min, max] GDD (alternative)
steps	integer		101	Scan steps
spectralResolutionM	number	m	0	Spectrometer resolution (Gaussian FWHM at the SH wavelength)
shgAcceptanceFwhmM	number	m	0	Phase-matching acceptance of the SHG crystal (FWHM of the SH wavelength window); 0: unlimited

energyMeter (also powerMeter)

Pulse energy and average power (optionally behind a polariser / band). More: instruments.md#energymeter

key	type	unit	default	meaning
rangeM	number or array	m		[min, max] wavelength band
polarizerDeg	number	deg		Analyser angle
repRateHz	number	Hz	the pulse's repetition rate	Repetition rate for average power

fieldProbe

Temporal phase, instantaneous wavelength, group delay, CEP (virtual). More: instruments.md#virtual-instruments

key	type	unit	default	meaning
threshold	number		1e-3	Relative intensity threshold
realField	boolean		false	Also the real field on the optical cycle
maxN	integer		8192	Grid cap

frog

SHG, PG or self-diffraction (SD) FROG trace. More: instruments.md#frog

key	type	unit	default	meaning
type	"shg" | "pg" | "sd"		shg	FROG geometry: shg (E E), pg (E |E|^2), sd (E^2 E*)
points	integer		256	Delay and frequency points
spectralResolutionM	number	m	0	Spectrometer resolution (Gaussian FWHM at the signal wavelength)
shgAcceptanceFwhmM	number	m	0	Phase-matching acceptance of the SHG crystal (FWHM of the SH wavelength window); 0: unlimited

phaseMatchingCurve

Low-conversion phase-matching curve of a crystal vs angle, wavelength, temperature or period. More: instruments.md#phasematchingcurve

key	type	unit	default	meaning
scan	"angle" | "wavelength" | "temperature" | "period"		angle	Scan variable
rangeDeg	number	deg	1	Angle range
rangeM	number	m		Wavelength or period range
rangeK	number	K	20	Temperature range
points	integer		201	Points

polarimeter

Stokes parameters, integrated and vs wavelength. More: instruments.md#polarimeter

key	type	unit	default	meaning
points	integer		1024	Output points
extinctionRatio	number		0	Power extinction ratio of the analysers (0: perfect); Stokes readings scale by (1 - e) / (1 + e)

pulseSummary

Every scalar pulse metric. More: instruments.md#pulsesummary

No parameters of its own.

scope (also photodiode)

Detected power vs time with a rise time / bandwidth. More: instruments.md#scope

key	type	unit	default	meaning
riseTimeS	number	s	0	10-90 % rise time of the detection
bandwidthHz	number	Hz		Bandwidth (alternative: rise time = 0.35 / bandwidth)
points	integer		4096	Output points

singleShotCorrelator

Single-shot time-to-space cross-correlator: two beams cross in a nonlinear crystal and the signal across the overlap is a delay trace (window and resolution from the geometry). More: instruments.md#singleshotcorrelator

key	type	unit	default	meaning
crossingAngleDeg	number	deg		Full angle between the pulse under test and the sampling beam INSIDE the crystal (or give externalCrossingAngleDeg)
externalCrossingAngleDeg	number	deg		Full angle between the beams in air; both hit a face normal to their bisector, each refracts with its own index (alternative to crossingAngleDeg)
beamWidthM	number	m		Width W of the beam overlap across the signal (sets the delay window T = W x slope) Required.
crystalLengthM	number	m	0	Crystal length L along the signal (sets the geometric resolution L |n_T cos a - n_S cos b| / c)
crystal	string		"BBO"	Crystal of the library whose ordinary (x) index gives the angles and the delay slope
indexPt	number			Refractive index at the pulse under test instead of the crystal's (also the group index unless groupIndexPt)
indexSampling	number			Index at the sampling pulse
groupIndexPt	number			Group index at the pulse under test (with indexPt)
groupIndexSampling	number			Group index at the sampling pulse (with indexSampling)
delayIndex	"group" | "phase"		group	Index in the depth term of the resolution: group (the crystal's dispersion through dk_z/d omega; default) or phase (the form of Ma et al.'s eq. (2)); the window uses the phase indices either way
samplingPulse	"secondHarmonic" | "fundamental"		secondHarmonic	secondHarmonic: the sampling pulse is the second harmonic of the pulse (third-order contrast correlator); fundamental: the pulse itself (single-shot autocorrelator)
points	integer		256	Camera pixels across the overlap
delayOffsetS	number	s	0	Delay at the centre of the overlap
dynamicRangeDb	number	dB	60	Camera floor below the peak
noiseFloor	number			Floor relative to the peak (alternative to dynamicRangeDb)
noise	boolean		true	Fluctuating floor (else flat)
seed	integer		1	Noise seed
windowAroundPeakS	number	s	5 x FWHM	Pre / post-pulse contrast is read outside this distance from the peak

spaceTime

I(r, t) and S(r, lambda) across the beam (virtual). More: instruments.md#virtual-instruments

key	type	unit	default	meaning
points	integer		512	Time samples
maxRadiusM	number	m	2.5 w	Largest radius
axis	"x" | "y"		x	Cartesian cut axis

spectrometer

Spectrum vs wavelength with resolution. More: instruments.md#spectrometer

key	type	unit	default	meaning
resolutionM	number	m	0	Gaussian resolution FWHM
rangeM	number or array	m	the spectrum's support	[min, max] wavelength range
points	integer		2048	Output points
wavelengthOffsetM	number	m	0	Wavelength calibration error: added to the reported axis
polarizerDeg	number	deg		Analyser angle
normalize	"peak" | "area" | "none" | true | false		peak	Normalisation of the output spectrum: peak = 1, area = 1 (per metre), none = spectral energy density in J/m; true = peak, false = none
db	boolean		false	Also report the spectrum in dB (relative to its peak)

wavefrontSensor

Shack-Hartmann-like wavefront sensor: map, Zernike terms, curvature. More: instruments.md#wavefrontsensor

key	type	unit	default	meaning
pixels	any		64	Lenslets
wavelengthM	number	m	spectral centroid	Reconstruction wavelength
threshold	number		0.01	Fluence threshold relative to the peak
apertureRadiusM	number	m	1/e^2 radius	Pupil radius
halfWidthM	number	m		Map half-width
zernikeTerms	integer		15	Zernike terms (max 36)
propagateM	number	m		Propagation before the sensor
bandM	number or array	m		[min, max] band

wigner

Wigner distribution or spectrogram (virtual). More: instruments.md#virtual-instruments

key	type	unit	default	meaning
points	integer		256	Time rows
gateFwhmS	number	s	0	> 0: spectrogram gate
maxN	integer		65536	Grid cap

xfrog (also sfgFrog)

Cross-correlation FROG (sum-frequency, SFG-FROG): the pulse gated by a known reference pulse. More: instruments.md#frog

key	type	unit	default	meaning
reference	any			The known gate pulse, as a run-spec pulse object (shape, centerWavelengthM, durationFwhmS, gddS2, ...); any carrier. Required
points	integer		256	Delay and frequency points
spectralResolutionM	number	m	0	Spectrometer resolution (Gaussian FWHM at the signal wavelength)

Common key groups

Keys shared by several components.

absorberParams

Saturable-absorber parameters.

key	type	unit	default	meaning
kind	"slow" | "fast" | "kerrLens"		slow	Absorber type
modulationDepth	number			Saturable loss q0
nonsaturableLoss	number			Non-saturable loss
recoveryTimeS	number	s		Recovery time (slow)
saturationFluenceJPerM2	number	J/m^2		Saturation fluence (slow)
saturationEnergyJ	number	J		Saturation energy (slow, alternative)
saturationPowerW	number	W		Saturation power (fast)
saturationIntensityWPerM2	number	W/m^2		Saturation intensity (fast)
kappaPerW	number	1/W		Kerr-lens loss slope
spotRadiusM	number	m		Spot radius on the absorber
areaM2	number	m^2		Spot area
beam	model (beam)			Beam on the absorber

beamSize

Beam size at a surface.

key	type	unit	default	meaning
beamRadiusM	number or array	m		1/e^2 beam radius (per wavelength)
beamRadiusXM	number or array	m		Beam radius in x
beamRadiusYM	number or array	m		Beam radius in y
decenterXM	number	m		Beam decentre in x
decenterYM	number	m		Beam decentre in y

elementCommon

Keys every element accepts.

key	type	unit	default	meaning
id	string			Unique id Required.
type	string			Element type (omit with sameAs) Required.
sameAs	string			Id of an element this one is a copy of: the same type and physical numbers (e.g. a transform used on several passes); it may set only id, label, enabled, wiring (next, inputs, loop, output) and geometry (aoiDeg, aoiRad, tiltXRad, side). Its input pulse and beam are its own (docs/reference/system-file.md#identical-elements)
label	string			Display name
enabled	boolean		true	false skips the element
next	any			Branched systems: where the light goes. A target ("bs:1", {"id": "bs", "port": 1}, "end", "virtual"), or an object of targets by output port (docs/reference/branches.md)
inputs	any			Virtual input beams by input port: the keys of an aux beam, with phaseRad and coherentWith, or {"virtual": true} for an input left empty on purpose (docs/reference/branches.md)
loop	any			Branched systems: on the element where light enters a loop: kind ("ringDown", "steadyState"), maxRoundTrips, tolerance (docs/reference/branches.md)
surfaces	number or array			[first, last] source surfaces (OpticStudio rows), informational
wavelengthsM	number or array	m		Wavelengths of this element's per-wavelength arrays (default: the file's sampling)
indexProfile	model (field)			Position-dependent index change dn(x, y, z) (docs/reference/spatial-properties.md)
absorptionProfile	model (field)			Position-dependent absorption alpha(x, y, z) [1/m]
n2Scale	model (field)			Position-dependent factor on n2
params	any			Free parameters (expressions, user elements)

gainCommon

Keys of gain and amplifier elements.

key	type	unit	default	meaning
medium	model (gainMedium)			Yb:YAG, Ti:sapphire, Nd:YAG, a materials entry, or an object Required.
lengthM	number	m		Crystal length Required.
pump	object (pump)			kind, powerW / energyJ, wavelengthM, radiusM, profile, order, passes, delayS
inversion	object (inversion)			fraction or smallSignalGain (instead of / before a pump)
beam	model (beam)			Signal beam
modeRadiusM	number	m		Signal 1/e^2 radius (mode area pi w^2 / 2)
transverse	object (transverse)			Spatial gain
thermalLens	any			true / false or {rodRadiusM, heatFraction, apply, track, focalLengthM, passGapM, stress}: track (default true; amplifier: only when given) puts the thermal lens on the tracked Gaussian beam as a graded-index duct (a regenerative amplifier also needs an integer roundTrips); passGapM is the free path between amplifier passes; focalLengthM is a measured thermal focal length used instead of the heat model; stress adds thermal birefringence: a lumped depolarisation, or the four-lobed pattern on a cartesian transverse grid (docs/reference/gain.md#thermal-lens)
slices	integer		24	Slices along z
segments	integer		auto	Time-ordered saturation groups
spm	boolean		true	SPM of the host
host	string			Host material (dispersion, n2)
repRateHz	number	Hz		Repetition rate (overrides the pulse's)
steadyState	any		true	true / false or {maxPulses, tolerance}
dopingProfile	model (field)			Position-dependent doping factor
ase	boolean		false	Seed amplified spontaneous emission (1-D)
aseSeed	integer			ASE random seed
aseModel	any		false	true / false or {solidAngleSr, polarizations, points, bandLowerM, bandUpperM}: inter-pulse ASE in both directions over the inversion lifetime; it depletes the inversion between pulses and reports the ASE power in the signal mode (docs/reference/gain.md#ase)
temperatureK	number	K		Crystal temperature
dopingDensityM3	number	1/m^3		Doping density (overrides the medium's)

nonlinearMedium

Keys of elements that propagate nonlinearly in a material.

key	type	unit	default	meaning
beam	model (beam)			Beam model along the element (z from the element start); needed for nonlinear propagation
nonlinear	boolean		true (gap: false)	false forces linear propagation
n2	number	m^2/W		Nonlinear index (overrides the material's)
kerrAnisotropy	number		the material's (BaF2 -1.2, others 0)	Cubic anisotropy sigma = (chi1111 - 3 chi1122) / chi1111 of the electronic Kerr response (overrides the material's); n2 is then the value for light along [100]
kerrCutAxis	number or array		[0, 0, 1]	Propagation direction in crystal coordinates [h, k, l] of a cubic crystal with kerrAnisotropy != 0 ([001] cut, [011] holographic cut, ...)
kerrAzimuthDeg	number	deg	0	Angle of the lab x axis from the in-plane reference axis (the projection of [100], or of [010] for a [100] cut) about the propagation direction
timeResponse	model (timeResponse)			An extra time-domain response n(t, I)
replaceKerr	boolean		false	true switches off the built-in Kerr/Raman (use with your own timeResponse)
raman	any			false, or a delayed-response model
fR	number			Raman fraction
selfSteepening	boolean		run setting	Per-element self-steepening switch
ionization	any		physics.ionization	Photo-ionisation and plasma: true or an ionization object
transverse	object (transverse)			Spatial model

sensorFlat

Sensor keys (inside sensor, or at the instrument's top level).

key	type	unit	default	meaning
pixels	any		256	n or [nx, ny]
pixelSizeM	number	m	auto: ~5 beam radii across	Pixel pitch on the sensor
qe	model (filter)			Quantum efficiency vs wavelength (a filter model: constant, table, gaussian, expression)
bitDepth	integer		0	ADC bits (0: ideal)
fullScaleJPerM2	number	J/m^2	1.1 x peak	Fluence at full scale
readNoiseCounts	number	counts	0	Read noise rms
backgroundCounts	number	counts	0	Dark / background offset
hotPixelFraction	number		0	Fraction of stuck pixels
noiseSeed	integer		1	Random seed
centerXM	number	m	0	Sensor centre x
centerYM	number	m	0	Sensor centre y
propagateM	number	m		Free-space propagation before imaging (v1 key)
magnification	number			Magnification (v1 key)
focalLengthM	number	m		Far-field focal length (v1 key)

Common instrument keys

Keys every instrument accepts (core and plugins).

core

Keys every instrument accepts.

key	type	unit	default	meaning
kind	string			Instrument kind Required.
name	string		kind_at	Name in the results (unique; repeated names get _2, _3)
at	string		"end"	"input", an element id (after that element) or "end"
sampling	object (sampling)			What part of the beam the instrument sees: near / far field, pinhole, fibre, slit (non-imaging instruments)
beam	model (beam)			Beam model for 1-D locations (cameras, sampling): the instrument images this ideal Gaussian
filter	model (filter)			Spectral transmission in front of the instrument (optics, detector spectral response): applied to the field before it is measured
detector	any			Read-out of the recorded trace / readings: an object (calibration, noise, noise floor, bit depth, saturation, spectral response) or the name of a preset from the run spec's detectors, or {preset: name | file, ...overrides}
axis	object (instrumentAxis)			Where a curve instrument takes its readings: explicit points or from / to / step, bin (pixel) width, Gaussian resolution
measured	object (measured)			Recorded data to compare this instrument with: a file name (CSV, NPZ, JSON), or an object (file, columns, normalize, sigma, background, rangeX, units, values, weight, resolutionM / resolutionS). docs/reference/measured-data.md

Plugin keys (run spec)

Top-level run-spec keys provided by plugins.

fitting — plugin: fitting

key	type	unit	default	meaning
fit	object (fitting:fit)			Fit transform parameters (and any listed number) to every instrument with measured data (fitting plugin).
backward	object (fitting:backward)			Backward propagation: the pulse is the field measured downstream; find the field at every plane upstream (fitting plugin).

Nested objects

aberration

Wavefront error of a surface (docs/reference/components.md#aberrations).

key	type	unit	default	meaning
zernikeNollWaves	number or array	waves		Zernike coefficients in Noll order from Z1, waves rms at referenceWavelengthM
terms	object			Zernike terms by name: {"Z4": 0.1, "Z11": -0.05}
radiusM	number	m		Normalisation radius of the Zernike terms
referenceWavelengthM	number	m	the carrier	Wavelength of the coefficients
surface	boolean		false	true: the numbers are surface height (x 2 cos(aoi) for a mirror, x (n2 - n1) refracting)
randomRmsM	number	m		Random figure rms (cartesian grids)
correlationLengthM	number	m	0.1 x grid	Correlation length of the random figure
seed	integer		1	Random seed

air

Laboratory air (Ciddor).

key	type	unit	default	meaning
temperatureC	number	degC	20	Temperature
pressurePa	number	Pa	101325	Pressure
humidity	number		0	Relative humidity 0..1
co2ppm	number	ppm	450	CO2
kind	string			An index model kind instead (e.g. "ciddor", or "hitran" with the hitran plugin)
applyToGaps	boolean		false	Use this air (humidity, temperature, pressure, gas lines) as the "Air" of every gap; a gap's own "air" overrides it. Off by default: existing results do not change

auxBeam

An auxiliary beam entering an active element (docs/reference/active-elements.md#auxiliary-beams).

key	type	unit	default	meaning
role	string		pump	pump, signal, idler, b
pulse	object (pulse)			The aux pulse (same keys as the run's pulse)
from	string			Results folder of a previous run (its output field)
energyJ	number	J		Rescale a 'from' field to this energy
beam	object (auxBeamShape)			Transverse shape of the aux beam
fromPort	boolean			Take this beam from a link to the port named by role (Branched systems; docs/reference/branches.md)
delayS	any	s	0	Delay relative to the main beam, or "auto" (centroids coincide)

auxBeamShape

Transverse shape of an auxiliary beam.

key	type	unit	default	meaning
kind	"gaussian" | "superGaussian" | "flatTop"		gaussian	Shape
radiusM	number	m		1/e^2 radius (edge radius for flatTop)
radiusXM	number	m		x radius
radiusYM	number	m		y radius
w0M	number	m		Radius (alternative key)
order	integer		6	superGaussian order
radiusOfCurvatureM	number	m		Wavefront radius of curvature
decenterXM	number	m		Decentre x
decenterYM	number	m		Decentre y

betweenPasses

Losses and dispersion between passes / per round trip.

key	type	unit	default	meaning
loss	number			Power loss
lossPerRoundTrip	number			Power loss per round trip
gddFs2	number	fs^2		GDD
todFs3	number	fs^3		TOD
gddS2	number	s^2		GDD
todS3	number	s^3		TOD
materials	array of materialPath			Material paths {name, lengthM}

chirp

Spectral phase coefficients about the carrier.

key	type	unit	default	meaning
gddS2	number	s^2		Group-delay dispersion
todS3	number	s^3		Third-order dispersion
fodS4	number	s^4		Fourth-order dispersion
gddFs2	number	fs^2		GDD in fs^2
todFs3	number	fs^3		TOD in fs^3
fodFs4	number	fs^4		FOD in fs^4

coherence

A Gaussian-Schell beam as an incoherent sum of Hermite-Gauss modes (docs/reference/transverse.md#partial-coherence).

key	type	unit	default	meaning
model	"gaussianSchell"		gaussianSchell	Coherence model
m2	number			Beam quality M^2 >= 1 Required.
modes	integer		12	Modes kept per axis
dimensions	integer		2; 1 for a grid with ny = 1	1 (x only) or 2
element	string		the first with a transverse object	Element whose transverse.initialProfile the modes replace

compute

Compute back-end (docs/reference/speed.md).

key	type	unit	default	meaning
backend	string		cpu	Back-end: cpu, auto (the fastest available that supports each element), or one a plugin registers (cuda, opencl)
threads	integer		0	Worker threads (0 = all cores)
fft	"auto" | "managed" | "fftw" | "accelerate"		ULTRAFAST_FFT or auto	CPU FFT provider (process-wide): auto = Accelerate on macOS, FFTW when installed, else managed
device	integer		-1 (first suitable)	GPU device index (ultrafast devices lists them)
gpuMinPoints	integer		8192 (1-D), 32768 (spatial); 0 for an explicit GPU back-end	backend auto: smallest problem (complex samples) sent to a GPU; smaller ones stay on the CPU
deviceSlots	integer		4	GPU back-ends: element propagations running on one device at the same time (parallel studies, fits); when all are busy, auto runs the element on the CPU and an explicit back-end waits

detector

Detector read-out applied to an instrument's recorded arrays and readings (spectrometer, scope, autocorrelator, FROG, d-scan, energy meter); width and peak readings are re-evaluated on the detected trace. More: instruments.md#detector-model

key	type	unit	default	meaning
calibration	number		1	Calibration factor (reading / true value)
noise	number		0	Multiplicative noise, relative rms
noiseFloor	number		0	Additive noise rms relative to the trace peak
dynamicRangeDb	number	dB		Noise floor as a dynamic range (alternative to noiseFloor)
response	any			Spectral response of the detector (spectral instruments): {wavelengthsM, values} -- the reading is multiplied by values(lambda) (e.g. the quantum efficiency), interpolated, held at the ends
counting	"energy" | "photons"		energy	photons: the spectrum is converted from energy to photon counts (x lambda / lambda_carrier) before the response
saturationLevel	number		0	Detector saturation: readings are clipped at this fraction of the trace peak (0 or omitted: none)
bitDepth	integer		0	ADC bits, full scale at the trace maximum (0: ideal)
seed	integer		1	Random seed

environment

Laboratory air.

key	type	unit	default	meaning
indexReference	"air" | "vacuum"		vacuum (air for zemax exports)	Quoted data are relative to air (OpticStudio) or vacuum
air	object (air)			Air: temperatureC, pressurePa, humidity, co2ppm, or an index model with kind

fiberDispersion

Tabulated fibre dispersion.

key	type	unit	default	meaning
wavelengthsM	number or array	m		Wavelengths
wavelengthsNm	number or array	nm		Wavelengths in nm
dPsNmKm	number or array	ps/(nm km)		Dispersion parameter D
beta2S2PerM	number or array	s^2/m		beta2 (alternative)

fiberGain

Fibre gain spectrum, optionally scaled at run time to reach an output.

key	type	unit	default	meaning
wavelengthsM	number or array	m		Wavelengths
wavelengthsNm	number or array	nm		Wavelengths in nm
dbPerM	number or array	dB/m		Gain (or a relative shape when an output target is given)
outputEnergyJ	number	J		Scale the gain so the output has this energy
outputPowerW	number	W		... or this average power (needs repRateHz)

fiberLossTable

Fibre loss vs wavelength.

key	type	unit	default	meaning
wavelengthsM	number or array	m		Wavelengths
wavelengthsNm	number or array	nm		Wavelengths in nm
dbPerKm	number or array	dB/km		Loss

fitting:backward

Backward propagation (fitting plugin). More: plugins/fitting.md#backward-propagation

key	type	unit	default	meaning
from	string		"end"	Plane where the run's pulse was measured: an element id (after it) or "end"
to	string		"input"	Plane to propagate back to: an element id (after it) or "input"
regularization	number		1e-3	Relative Tikhonov level for inverting linear terms (transmission below this x the peak is not recovered)
active	"error" | "linearized" | "identity"		error	Amplifiers, crystals and spatial elements: refuse, undo as the filter they were in a forward reference run, or pass through
referencePulse	object (pulse)			active = linearized: the input pulse of the forward reference run

fitting:condition

One operating condition of a multi-condition fit (fitting plugin). More: plugins/fitting.md#fitting-across-conditions

key	type	unit	default	meaning
name	string			Label (unique); used in the report as condition/instrument Required.
heldOut	boolean		false	Not in the cost: predicted from the fit and compared with its data afterwards
weight	number		1	Weight of this condition's residuals in the cost (chi^2 is multiplied by it)
variables	any			Named numbers describing the condition ({"energyJ": 2e-6}); the inputs of parametric and smooth dependence on the condition
set	any			Path -> value written into the files for this condition (a number, or a string such as instrument:spec/measured/file); same paths as fit.parameters

fitting:dependence

How a fitted number depends on the condition (fitting plugin). More: plugins/fitting.md#fitting-across-conditions

key	type	unit	default	meaning
kind	"constant" | "proportional" | "linear" | "polynomial" | "power" | "chebyshev" | "network"		linear	Form: c0 | c0 u | c0 + c1 u | sum ck u^k | c0 u^c1 | sum ck Tk(xi) | a small tanh network with built-in constraints; u = variable / reference
variable	string			Name of the condition variable (conditions[].variables) Required.
degree	integer		2	polynomial / chebyshev: highest order
reference	number		mean of the training values	u = variable / reference
range	array			chebyshev: [lo, hi] mapped to xi = -1..1 (outside it the series extrapolates)
smoothnessPaths	number		0	surface: weight on second differences across the paths
smoothnessVariable	number		0	surface (chebyshev): weight on second differences across the variable
coefficients	array			Per order: {initial, min, max, scale, prior, step} of that coefficient (network: one object {scale, min, max} for all weights)
hidden	integer		4	network: tanh units
output	"none" | "bounded" | "positive"		none	network: output constraint (bounded: lo + (hi - lo) sigmoid; positive: softplus), exact by construction
outputRange	array			network, output bounded: [lo, hi]
monotone	"none" | "increasing" | "decreasing"		none	network: output monotone in the variable (squared weights), exact by construction
weightDecay	number		1e-4	network: L2 penalty on the weights (a prior of sigma 1/sqrt(weightDecay))

fitting:fit

Fit (fitting plugin). More: plugins/fitting.md#fitting

key	type	unit	default	meaning
parameters	array of fitting:parameter			Numbers to fit by path (in addition to the transform parameters marked for fitting)
estimator	"levenbergMarquardt" | "cmaes" | "mcmc"		levenbergMarquardt	Fitting algorithm (plugins may register more)
maxIterations	integer		20 (LM), 60 (CMA-ES)	Iterations (LM) / generations (CMA-ES)
tolerance	number		1e-4 (LM), 1e-6 (CMA-ES)	Relative chi^2 change (LM) / cost spread (CMA-ES) that ends the fit
conditions	array of fitting:condition			Operating conditions fitted together with one set of shared parameters (energies, angles, ...); empty: one condition, the run itself
surfaces	array of fitting:surface			Smooth surfaces: several numbers (e.g. the knots of a spectral phase) as Chebyshev series of a condition variable, with smoothness penalties in both directions
freezeGrid	boolean		true	Fix the time/frequency grid (2x the planned bandwidth) for all evaluations
parallel	integer		1	Simulations run at the same time (Jacobian columns, CMA-ES population, MCMC walkers)
population	integer		4 + 3 ln n	CMA-ES population
sigma0	number		0.3	CMA-ES initial step (in units of each parameter's scale)
polish	boolean		true	CMA-ES: finish with Levenberg-Marquardt
walkers	integer		max(2n + 2, 8)	MCMC walkers
steps	integer		200	MCMC steps
burnIn	number		0.5	MCMC burn-in fraction
thin	integer		1	MCMC thinning
start	"optimum" | "initial"		optimum	MCMC start: a Levenberg-Marquardt optimum or the initial values
spread	number		0.1	MCMC starting ball (in units of each scale)
seed	integer		1	Random seed (CMA-ES, MCMC)

fitting:knots

Spline knots of a transform operator.

key	type	unit	default	meaning
wavelengthsM	number or array	m		Knot wavelengths
wavelengthsNm	number or array	nm		Knot wavelengths in nm
phaseRad	array			spectralPhase: phase at the knots (numbers or fit objects)
transmission	array			spectralAmplitude: power transmission at the knots
transmissionDb	array			spectralAmplitude: transmission in dB at the knots

fitting:operator

One transform operator (kind + parameters; numbers may be fit objects). More: plugins/fitting.md#operators

key	type	unit	default	meaning
kind	"spectralPhase" | "spectralAmplitude" | "energy" | "delay" | "jones" | "replica" | "phaseNoise" | "pedestal" | "wavefront" | "nonlinearPhase"			Operator kind (plugins may add more) Required.
enabled	boolean		true	false skips the operator
fit	array			Names of parameters to fit (dotted for nested: "knots.phaseRad" fits every knot), alternative to fit objects
bounds	object			Bounds for the names in "fit": {name: [min, max]}
priors	object			Gaussian priors for the names in "fit": {name: sigma | {mean, sigma}}
smoothness	number		0	Regularisation weight on the second differences of fitted knots
gddFs2	number or fit object	fs^2		spectralPhase: GDD
todFs3	number or fit object	fs^3		spectralPhase: TOD
fodFs4	number or fit object	fs^4		spectralPhase: FOD
fifthFs5	number or fit object	fs^5		spectralPhase: fifth order
gddS2	number or fit object	s^2		spectralPhase: GDD in s^2
todS3	number or fit object	s^3		spectralPhase: TOD in s^3
fodS4	number or fit object	s^4		spectralPhase: FOD in s^4
centerWavelengthM	number or fit object	m	the element's carrier	Reference / centre wavelength
centerWavelengthNm	number or fit object	nm		Reference / centre wavelength in nm
knots	object (fitting:knots)			Spline knots: wavelengthsM | wavelengthsNm with phaseRad (spectralPhase) or transmission | transmissionDb (spectralAmplitude)
shape	"gaussian" | "superGaussian" | "tilt" | "spline" | "model"		from the keys given	spectralAmplitude: shape
fwhmM	number or fit object	m		spectralAmplitude: band FWHM
fwhmNm	number or fit object	nm		spectralAmplitude: band FWHM in nm
order	number or fit object		2	superGaussian order
peak	number or fit object		1	Peak power transmission
tiltDbPerNm	number or fit object	dB/nm		spectralAmplitude: transmission slope
curvatureDbPerNm2	number or fit object	dB/nm^2		spectralAmplitude: curvature
model	model (filter)			spectralAmplitude: any filter model (shape: model)
passive	boolean		true	spectralAmplitude: clip the transmission to <= 1
causal	boolean		false	spectralAmplitude: add the minimum phase (Kramers-Kronig)
floor	number		1e-8	causal: smallest relative transmission used in the logarithm
bRad	number or fit object	rad		nonlinearPhase: peak nonlinear phase (B-integral of a thin Kerr plate), phi(t) = bRad I(t)/max I
transmission	number or fit object		1	energy: power transmission
gainDb	number or fit object	dB		energy: gain (alternative)
delayS	number or fit object	s		delay / replica: delay
delayFs	number or fit object	fs		delay / replica: delay in fs
delayPs	number or fit object	ps		replica: delay in ps
retardanceRad	number or fit object	rad		jones: retardance
axisDeg	number or fit object	deg		jones: retarder fast axis
diattenuation	number or fit object			jones: power loss of the weak axis (0..1)
diattenuationAxisDeg	number or fit object	deg	axisDeg	jones: weak axis
rotationDeg	number or fit object	deg		jones: rotation of the polarisation
relativeIntensity	number or fit object			replica / pedestal: intensity relative to the main peak
relativeIntensityDb	number or fit object	dB		replica / pedestal: the same in dB (better for fitting levels spanning decades)
phaseRad	number or fit object	rad		replica: relative phase
rmsRad	number or fit object	rad		phaseNoise: phase noise rms
amplitudeRms	number or fit object			phaseNoise: amplitude noise rms
correlationNm	number or fit object	nm		phaseNoise: correlation width
correlationRadPerS	number or fit object	rad/s		phaseNoise: correlation width
seed	integer		1	phaseNoise / pedestal: random seed
type	"ase" | "exponential"		ase	pedestal: incoherent background type
durationS	number or fit object	s	10e-9	pedestal (ase): duration
energyFraction	number or fit object			pedestal (ase): energy / main energy
level	number or fit object			pedestal (exponential): level at the peak
levelDb	number or fit object	dB		pedestal (exponential): level in dB
riseS	number or fit object	s		pedestal (exponential): rise
fallS	number or fit object	s		pedestal (exponential): fall
bandwidthFwhmNm	number or fit object	nm		pedestal: spectral FWHM (default: the pulse's spectrum)
zernike	object			wavefront: Noll index -> waves rms, e.g. {"4": 0.1, "11": 0.02}; values may be fit objects
radiusM	number or fit object	m	the beam's 1/e^2 radius	wavefront: normalisation radius
wavelengthM	number or fit object	m	the carrier	wavefront: wavelength of the waves
tiltXRad	number or fit object	rad		wavefront: pointing x
tiltYRad	number or fit object	rad		wavefront: pointing y
params	object			Parameters of operator kinds added by other plugins (free-form; numbers may be fit objects)

fitting:parameter

One fit parameter.

key	type	unit	default	meaning
path	string			pulse/..., element:ID/..., instrument:NAME/..., material:NAME/prop, run/..., system/... Required.
name	string		the path	Label
initial	number		the value in the files	Start value
min	number			Lower bound
max	number			Upper bound
scale	number		(max - min) / 4	Typical change
step	number		1e-3 x scale	Finite-difference step
unit	string			Unit label for reports
dependence	object (fitting:dependence)			The value follows the condition variable: its coefficients are fitted instead (fitting across conditions)
perCondition	boolean		false	Multi-condition fit: one value per training condition instead of one shared value
prior	any			Gaussian prior: sigma (mean = initial) or {mean, sigma}

fitting:surface

A smooth surface of several numbers over a condition variable (fitting plugin). More: plugins/fitting.md#fitting-across-conditions

key	type	unit	default	meaning
name	string			Label Required.
paths	array			The numbers (same paths as fit.parameters); or pathTemplate + count
pathTemplate	string			A path with {i} replaced by 0..count-1 (e.g. element:t/operators/0/knots/phaseRad/{i})
count	integer			Number of paths for pathTemplate
kind	"constant" | "proportional" | "linear" | "polynomial" | "chebyshev" | "network"		chebyshev	Basis over the variable
variable	string			Name of the condition variable Required.
degree	integer		2	Highest order
reference	number			u = variable / reference
range	array			[lo, hi] of the Chebyshev map
smoothnessPaths	number		0	Weight on second differences across the paths
smoothnessVariable	number		0	Weight on second differences across the variable
coefficients	array			Per order: {initial, min, max, scale, prior, step}
hidden	integer		4	network: tanh units
output	"none" | "bounded" | "positive"		none	network: output constraint (bounded: lo + (hi - lo) sigmoid; positive: softplus), exact by construction
outputRange	array			network, output bounded: [lo, hi]
monotone	"none" | "increasing" | "decreasing"		none	network: output monotone in the variable (squared weights), exact by construction
weightDecay	number		1e-4	network: L2 penalty on the weights (a prior of sigma 1/sqrt(weightDecay))

fitting:value

A fit parameter in place of a number: its value, and how to fit it. More: plugins/fitting.md#marking-parameters-for-fitting

key	type	unit	default	meaning
value	number			The value (used by plain runs; the start value of a fit) Required.
fit	boolean		false	Fit this number
min	number			Lower bound
max	number			Upper bound
scale	number		(max - min) / 4, else a per-quantity default	Typical size of a change
step	number		1e-3 x scale	Finite-difference step
prior	any			Gaussian prior: sigma (mean = value) or {mean, sigma}
name	string		element.operator.key	Label in reports
unit	string		from the key	Unit label

gas

A gas at pressure and temperature.

key	type	unit	default	meaning
species	string			Ar, Ne, He, Kr, Xe, N2, O2, air, CO2, H2, ... Required.
pressureBar	number	bar	1	Pressure
pressurePa	number	Pa		Pressure (alternative)
temperatureK	number	K	293.15	Temperature

ghosts

Ghost replicas of a plate (docs/reference/components.md#ghost-reflections).

key	type	unit	default	meaning
orders	integer		1	Number of replicas (round trips)
overlap	number			Field overlap with the main beam (default: from the offset, wedge and beam radius)
beamRadiusM	number	m	tracked beam	Beam radius for the overlap
frontReflectance	number			Internal reflectance of the front surface (default: its coating / Fresnel; 0.5 for a reflective ND)
backReflectance	number			Reflectance of the back surface (default: its coating / Fresnel)
material	string			Material of the inside, when the element does not say (crystals defined inline)
wedgeDeg	number	deg	0	Wedge between the end faces (bulk, crystal, gain, lens)

imaging

Camera imaging.

key	type	unit	default	meaning
plane	"near" | "far" | "relay"		near	near: the beam at the location (+ propagateM, relay); far: focal plane of focalLengthM
propagateM	number	m	0	Free-space propagation before imaging (negative: back to a waist)
focalLengthM	number	m	1	Far field: focal length
magnification	number		1	Imaging magnification onto the sensor
relay	array of relayStep			Thin lenses {focalLengthM} and gaps {gapM}, in order

initialProfile

Initial transverse field.

key	type	unit	default	meaning
kind	"gaussian" | "superGaussian" | "flatTop" | "tophat" | "hermiteGauss" | "laguerreGauss" | "besselGauss" | "airy" | "measured" | "tiles"		gaussian	Shape: Gaussian, super-Gaussian (order), flatTop (super-Gaussian of order 10), tophat (hard edge, uniform), Hermite-Gauss (modeX, modeY), Laguerre-Gauss (modeP, modeL), Bessel-Gauss (coneAngleRad), Airy (radiusM = scale, truncation), measured (file)
modeX	integer		0	hermiteGauss: order in x
modeY	integer		0	hermiteGauss: order in y
modeP	integer		0	laguerreGauss: radial index p
modeL	integer		0	laguerreGauss: azimuthal index l (helical phase, cartesian grids)
coneAngleRad	number	rad		besselGauss: cone angle of the plane waves, k_r = k sin(angle)
radialWavenumberPerM	number	rad/m		besselGauss: k_r (alternative)
truncation	number		0.1	airy: the exponential truncation a in Ai(x / x0) exp(a x / x0)
file	string			measured: NPZ with x_m, y_m (or r_m), fluence or amplitude, and optionally phase_rad; relative to the file that names it
background	any			measured: a number subtracted from the fluence, or "auto" (the median of the map's edge)
pixelSizeM	number	m		measured: pixel size of a PNG image
threshold	number		0	measured: fluence below this fraction of the peak is set to zero
center	boolean		false	measured: move the fluence centroid to the axis
geometry	"round" | "square"		round	round: a function of r (elliptical with radiusXM != radiusYM); square: separable in x and y (rectangular, cartesian grids)
order	integer		4	superGaussian order (also tiles with tileShape superGaussian)
layout	"square" | "hex" | "ring"		square	tiles: arrangement of the sub-beams (square: countX x countY; hex: rings around a centre tile; ring: count tiles on a circle)
pitchM	number	m		tiles: centre-to-centre distance
count	integer		2	tiles: tiles per side (square) or on the ring
countX	integer			tiles: square layout, tiles along x
countY	integer		1 if countX is given, else count	tiles: square layout, tiles along y
rings	integer		1	tiles: hex layout, rings around the centre tile (1: 7 tiles, 2: 19, 3: 37, 4: 61)
ringRadiusM	number	m		tiles: ring layout, circle radius
positionsM	any	m		tiles: explicit centres, a list of [x, y]
tileRadiusM	number	m		tiles: 1/e^2 radius of one tile (hard radius for tileShape tophat)
tileShape	"gaussian" | "tophat" | "superGaussian"		gaussian	tiles: transverse shape of one tile
amplitudes	any		1	tiles: amplitude per tile (a number or one per tile)
pistonRad	any	rad	0	tiles: piston phase at the carrier per tile
tileTiltXRad	any	rad	0	tiles: tilt about y per tile (a number or one per tile)
tileTiltYRad	any	rad	0	tiles: tilt about x per tile
delaysS	any	s	0	tiles: envelope delay per tile (adds (omega - omega_centre) tau to the phase; needs enough spectralSamples to resolve it)
pistonRmsRad	number	rad	0	tiles: random Gaussian piston error added to pistonRad (seed: seed)
decenterXM	number	m		Decentre in x
decenterYM	number	m		Decentre in y
tiltXRad	number	rad		Tilt about y
tiltYRad	number	rad		Tilt about x
radiusOfCurvatureM	number	m		Wavefront radius of curvature (negative: converging)
radiusM	number	m		1/e^2 radius; tophat: edge radius or half-width (default: from the element's beam)
radiusXM	number	m		Radius / half-width in x (default radiusM)
radiusYM	number	m		Radius / half-width in y (default radiusXM)
ripple	any			Seed ripple (cartesian): {periodM, relativeAmplitude, angleDeg, phaseRad}: amplitude x (1 + a cos(2 pi (x cos t + y sin t) / period + phase)). The Bespalov-Talanov seed (docs/reference/transverse.md#small-scale-self-focusing)
noise	any			Seeded random noise (cartesian): {relativeAmplitudeRms, phaseRmsRad, correlationLengthM, seed, components}

instrumentAxis

Sampling of a curve instrument's axis (spectrometer wavelengths, scope times, autocorrelator / cross-correlator delays, polarimeter wavelengths, delay scan, contrast, beam profile, phase-matching curve). Units: those of the axis (m, s). More: instruments.md#axis-where-readings-are-taken

key	type	unit	default	meaning
values	number or array	SI		Explicit reading positions (e.g. the pixel wavelengths of your spectrometer)
from	number	SI	the start of the simulated axis	First reading
to	number	SI	the end of the simulated axis	Last reading
step	number	SI		Spacing of the readings
points	integer		as simulated	Number of readings (with from / to, when no step)
binWidth	any	SI	0 (point readings)	Width each reading integrates over: a number, or "pixel" (the spacing between readings)
resolution	number	SI	0	Gaussian blur (FWHM) applied before binning

interaction

The chi(2) process.

key	type	unit	default	meaning
process	"shg" | "sfg" | "opa" | "dfg"			Process Required.
type	string		I (0 with qpm)	I, II (IIa), IIb or 0
plane	"XY" | "XZ" | "YZ"		auto	Biaxial plane
polarizations	object			Explicit polarisations per field, e.g. {signal: o, idler: o, pump: e}
noncollinearDeg	any	deg		Angle between the inputs inside the crystal (opa, dfg, sfg), or "magic" (opa, dfg)
externalAngleDeg	number	deg		Angle between the inputs outside the crystal (sfg; opa, dfg: the pump's angle to the signal, at a face normal to the signal); default: from the arms' tiltXRad
qpm	any			true or {periodM, model: averaged|domains, phaseDeg, periodExpr}

inversion

Initial inversion.

key	type	unit	default	meaning
fraction	number			N2 / N_t
smallSignalGain	number			Single-pass small-signal gain
wavelengthM	number	m		Wavelength of smallSignalGain

ionization

Photo-ionisation and plasma (docs/reference/ionization.md).

key	type	unit	default	meaning
model	"ppt" | "adk" | "mpi" | "keldysh"		ppt (gases) / keldysh (solids)	Rate model
ionizationEv	number	eV		Ionisation potential (gases)
zEff	number			Effective charge (molecules)
bandGapEv	number	eV		Band gap (solids)
effectiveMass	number			Reduced mass / m_e (solids)
neutralDensityM3	number	1/m^3		Density of ionisable atoms / valence electrons
sigmaK	number	(m^2/W)^K/s		MPI cross section
photons	integer			MPI order K
collisionTimeS	number	s		Electron collision time
recombinationTimeS	number	s		Recombination / trapping time
recombinationBetaM3PerS	number	m^3/s		Two-body recombination
electronDensityM3	number	1/m^3	0	Free-electron density present before the pulse (a prepared plasma)
frequencyResolved	boolean		true	Apply the Drude index at every frequency of the pulse (1/(omega (omega + i nu))); false: at the carrier only
avalanche	boolean		true for solids	Avalanche (impact) ionisation
absorption	boolean		true	Plasma and ionisation losses
species	string			Gas species (when the material does not say)

lidt

Laser-induced damage threshold.

key	type	unit	default	meaning
fluenceJPerCm2	number	J/cm^2		Threshold fluence Required.
pulseDurationS	number	s		Pulse duration the threshold was measured at
scalingExponent	number		0.5	tau^x scaling exponent
wavelengthM	number	m		Wavelength of the measurement

material

A material (docs/reference/materials.md).

key	type	unit	default	meaning
base	string			Start from a built-in material
index	model (index)			Refractive index model
indexReference	"air" | "vacuum"		vacuum	The index is relative to air or vacuum
n2	number	m^2/W		Nonlinear index
kerrAnisotropy	number		0	Cubic anisotropy sigma = (chi1111 - 3 chi1122) / chi1111 of the electronic Kerr response (docs/reference/nonlinear.md#cubic-anisotropy-xpw)
raman	model (delayedResponse)			Raman response
ramanFraction	number			Raman fraction fR
attenuation	model (attenuation)			Absorption model
lidt	object (lidt)			Damage threshold
gas	object (gas)			A gas: species, pressureBar, temperatureK
crystal	object			A user chi(2) crystal (docs/reference/crystals.md#user-crystals)
gain	object			A user gain medium (docs/reference/gain.md)
densityKgPerM3	number	kg/m^3		Density (informational)
name	string			Display name
rotationalRaman	any		on for N2, O2, CO2, H2, air	Molecular gases: false, or {species, pressureBar, temperatureK, dephasingTimeS}

materialPath

A length of material.

key	type	unit	default	meaning
name	string			Material Required.
lengthM	number	m		Length Required.

measured

Recorded data for one instrument, compared with its simulated reading on the measured axis (only where the simulated instrument has readings), after matching the recording's resolution. More: measured-data.md

key	type	unit	default	meaning
file	string			CSV, NPZ or JSON file, relative to the run file
columns	object			Column / array names: x, y, sigma (curves); rows, cols, trace (traces)
normalize	"peak" | "maximum" | "area" | "scale" | "none"		peak	How data and simulation are normalised before comparing
sigma	number		0.02	Uncertainty of each point relative to the data peak
background	any		none	A number to subtract, "auto" (median of the darker edge of the axis; for traces, the edges of the columns), "min" or "none"
rangeX	number or array	SI		Compare only this [min, max] of the measured axis
xUnit	string			Unit of the x column (overrides the name suffix)
yUnit	string			Unit of the y column ("dB" for logarithmic data)
rowUnit	string			Unit of the trace rows
colUnit	string			Unit of the trace columns
values	object			Scalar readings {name: value | [value, sigma]}
valueSigma	number		0.02	Relative uncertainty of values given without one
valueWeight	number		1	Extra weight of the scalar residuals
weight	number		1	Weight of this instrument in a fit's chi^2
simulated	object			Which arrays of the instrument to compare with: x, y | rows, cols, trace
scale	"linear" | "log"		linear	Compare in linear units, or in dB (high-dynamic-range data: contrast, cross-correlators)
sigmaDb	number	dB	1	scale log: uncertainty of each point in dB
floorDb	number	dB	the data's minimum	scale log: floor relative to the peak (values below are clipped to it)
resolutionM	number	m		Resolution (Gaussian FWHM) of the recording spectrometer / profiler, in the unit of the axis
resolutionS	number	s		Temporal / delay resolution (Gaussian FWHM) of the recording instrument
matchResolution	boolean		true	Curves: when the recording is coarser than the simulated instrument, blur the simulated reading by the missing width before comparing

override

One override (docs/reference/models.md#overrides).

key	type	unit	default	meaning
target	string			material:NAME, element:ID (trailing * wildcard), element:*, type:TYPE or global Required.
property	string			Property to change (lengthM, n2, index, beam, coating, timeResponse, filter, enabled, ...) Required.
value	any			New value (numbers may carry a unit string: "2.2E-20 m^2/W")
model	any			New model (an object with kind, an expression, or "@callback")
mode	"replace" | "add"		replace	replace, or add (time responses and filters)
source	string			Provenance label
origin	string			Provenance detail

pedestalComponent

A pedestal / contrast component of the input pulse (docs/reference/run-spec.md#pedestal).

key	type	unit	default	meaning
kind	"replica" | "prePulse" | "postPulse" | "ase" | "phaseNoise" | "exponential" | "measured"			Component Required.
delayS	number	s		Delay (replica; ASE envelope centre)
relativeIntensity	number			Intensity relative to the main peak
relativeEnergy	number			Energy relative to the main pulse (replica)
phaseRad	number	rad		Replica phase
gddFs2	number	fs^2		Extra GDD of a replica
gddS2	number	s^2		Extra GDD of a replica
durationS	number	s	10e-9	ASE duration
energyFraction	number			ASE energy / main energy
bandwidthFwhmM	number	m		Spectral FWHM of ASE / exponential pedestal
bandwidthFwhmNm	number	nm		Spectral FWHM in nm
centerWavelengthM	number	m		Centre of that spectrum
rmsRad	number	rad		Spectral phase noise rms
amplitudeRms	number			Spectral amplitude noise rms
correlationNm	number	nm		Noise correlation width
correlationRadPerS	number	rad/s		Noise correlation width
level	number			Exponential pedestal level at the peak
riseS	number	s		Exponential rise (before the peak)
fallS	number	s		Exponential fall (after the peak)
csv	string			measured: CSV file of a contrast trace (columns time_ or delay_, and relativeIntensity, intensity or contrast_dB)
timesS	any	s		measured: delays of the trace points (alternative to csv; use with relativeIntensity)
relativeIntensities	any			measured: intensity relative to the main peak at each delay (alternative to csv)
excludeWithinS	number	s	0	measured: trace points closer than this to t = 0 are ignored (the main pulse is already there)
outside	string		zero	measured: "zero" (no pedestal beyond the trace) or "hold" (the end values continue)
seed	integer		1	Random seed

pulseNoise

Quantum noise added to the input pulse (docs/reference/fibers.md#noise-and-coherence).

key	type	unit	default	meaning
kind	"onePhotonPerMode" | "none"		onePhotonPerMode	Noise model
seed	integer		1	Random seed (a coherence study varies it)
polarization	"same" | "both"		same	Noise in the pulse's polarisation only, or one photon in each of x and y

pulseSpectrum

A measured input spectrum.

key	type	unit	default	meaning
wavelengthsM	number or array	m		Wavelengths
wavelengthsNm	number or array	nm		Wavelengths in nm
intensity	number or array			Intensity per unit wavelength
phaseRad	number or array	rad		Spectral phase (optional)
csv	string			CSV file: wavelength, intensity, optional phase
wavelengthUnit	string		nm	Unit of the CSV wavelength column
resolutionM	number	m	0 (unknown)	Resolution (Gaussian FWHM) of the spectrometer that recorded it
resolutionNm	number	nm		Resolution in nm
deconvolve	boolean		false	Remove the recording resolution (Richardson-Lucy) before use
deconvolveIterations	integer		30	Richardson-Lucy iterations
extrapolate	"zero" | "gaussian"		zero	Outside the measured wavelengths: no light, or Gaussian tails fitted to the data
background	any		none	Background to subtract: a number (intensity units), "auto" (median of the darker edge, robust to a spectrum cut off on one side), "min" or "none"
threshold	number		0	After background subtraction, values below this fraction of the peak are set to zero

pump

A pump for gain media.

key	type	unit	default	meaning
kind	"cw" | "pulsed" | "none"		cw	Pump type
powerW	number	W		cw power
energyJ	number	J		Pump pulse energy
pumpDurationS	number	s		Pump pulse duration
wavelengthM	number	m		Pump wavelength
radiusM	number	m		1/e^2 or edge radius
profile	"tophat" | "gaussian" | "superGaussian"		tophat	Pump profile
order	integer			superGaussian order
passes	integer		1	1, or 2 (reflected back)
delayS	number	s		Pulsed pump: time before the seed

relayStep

A relay step: a thin lens or a free-space gap.

key	type	unit	default	meaning
focalLengthM	number	m		Thin lens
gapM	number	m		Free-space gap

sampling

Near / far field and apertures for non-imaging instruments. More: instruments.md#sampling

key	type	unit	default	meaning
plane	"near" | "far"		near	Near field, or the focal plane of a lens
focalLengthM	number	m	0.2	Far field: focal length
propagateM	number	m	0	Near field: free-space propagation before the aperture
aperture	object (samplingAperture)			The aperture

samplingAperture

Sampling aperture.

key	type	unit	default	meaning
kind	"integrated" | "pinhole" | "iris" | "fibre" | "fiber" | "slit" | "point"		pinhole	Aperture type
radiusM	number	m	50e-6 (fibre 25e-6)	Radius (pinhole, iris, fibre core)
widthM	number	m	2 x radius	Slit width
centerXM	number	m	0	Aperture centre x
centerYM	number	m	0	Aperture centre y
na	number		0.22	Fibre numerical aperture

samplingWavelengths

Sampling wavelengths of per-wavelength arrays.

key	type	unit	default	meaning
wavelengthsM	number or array	m		Wavelengths
wavelengthsNm	number or array	nm		Wavelengths in nm (alternative)

sensor

A camera sensor.

Also accepts: sensorFlat (see Common key groups).

No parameters of its own.

transverse

Spatial model of an element (docs/reference/spatial-models.md).

key	type	unit	default	meaning
model	"none" | "radial" | "cartesian"		none	Representation
points	integer		64	Radial samples (cartesian: nx = ny if omitted)
nx	integer			Cartesian samples in x
ny	integer			Cartesian samples in y
radiusM	number	m	extentFactor x expected radius	Radial grid extent
halfWidthM	number	m		Cartesian half-width
halfWidthXM	number	m		Cartesian half-width in x
halfWidthYM	number	m		Cartesian half-width in y
extentFactor	number		3.5	Grid extent / expected beam radius
paraxial	boolean		false	Paraxial diffraction operator instead of the exact one
transport	"auto" | "exact" | "rescale" | "beam"		auto	How a profile from before is brought in
initialProfile	object (initialProfile)			The field at the first spatial element
polarization	"auto" | "scalar" | "vector"		auto	Jones (vector) fields on the grid: auto = when the beam carries a y component
equation	"envelope" | "uppe"		envelope	Nonlinear coupling: paraxial envelope, or UPPE (n omega / c k_z per plane wave)
spectralSamples	integer		48	Frequencies at which the transverse profile is stored and (linear elements) propagated; fewer is faster for narrowband pulses
frequencyBlock	integer		0	Streaming: a linear spatial element propagates the stored frequencies in blocks of this many, so its propagator holds a block instead of all of them and a block-sized work buffer is added (saves memory for blocks under half the stored frequencies); the result does not depend on it. 0 = all at once
absorbingBoundary	any		false	Linear elements: absorb light leaving the grid instead of reflecting / wrapping it -- true (outer 15 %) or {widthFraction}; the absorbed energy is booked as 'grid boundary' (docs/reference/transverse.md#diffraction-and-apertures)

Model kinds

Models with declared parameters (other kinds are described in Models). Every model object also takes kind and optionally name, source, reference.

attenuation / refractiveindex

Absorption from the k data of a refractiveindex.info page.

key	type	unit	default	meaning
page	string			Page name or file
file	string			YAML file (alternative)
pressureBar	number	bar		Gas pressure
temperatureK	number	K		Temperature

beam / constant

Constant beam size.

key	type	unit	default	meaning
radiusM	number	m		1/e^2 radius
radiusXM	number	m		x radius
radiusYM	number	m		y radius
areaM2	number	m^2		Effective area

beam / gaussian

Gaussian beam w(z) = w0 sqrt(1 + ((z - zWaist)/zR)^2). More: models.md#beam

key	type	unit	default	meaning
w0M	number	m		Waist 1/e^2 radius
w0xM	number	m		Waist in x
w0yM	number	m		Waist in y
zWaistM	number	m	0	Waist position from the element start
zWaistXM	number	m		Waist position x
zWaistYM	number	m		Waist position y
m2	number		1	Beam quality
m2x	number			M^2 in x
m2y	number			M^2 in y
wavelengthM	number	m		Wavelength (filled in from the carrier)
n	number			Index of the medium (filled in from the material)
zRayleighM	number	m		Rayleigh range (instead of wavelength)
zRayleighXM	number	m		Rayleigh range x
zRayleighYM	number	m		Rayleigh range y

beam / sampled

Beam radii sampled along z (e.g. from OpticStudio).

key	type	unit	default	meaning
zM	number or array	m		Positions
radiusM	number or array	m		Radii
radiusXM	number or array	m		x radii
radiusYM	number or array	m		y radii

delayedResponse / callback

Delayed response h(t) from a registered callback, normalised to unit integral on the grid and forced causal. More: nonlinear.md#raman-models

key	type	unit	default	meaning
name	string			Registered callback name Required.
fR	number			Raman (delayed) fraction of n2
anisotropicFraction	number		0	Anisotropic share b of the response, h_b = b h and h_a = (1 - b) h (vector Raman: ellipse rotation, circular light). 0 isotropic, 1 purely anisotropic (h_a = 0), 1.5 purely orientational (h_a = -h_b/3, e.g. liquid CS2). Allowed 0 to 1.5

delayedResponse / dampedOscillator

Single damped oscillator h(t) ~ exp(-t/tau2) sin(t/tau1). More: nonlinear.md#raman-models

key	type	unit	default	meaning
tau1	number	s		Period parameter
tau2	number	s		Damping time
fR	number			Raman fraction
anisotropicFraction	number		0	Anisotropic share of the response (vector Raman: ellipse rotation, circular light)

delayedResponse / expression

Delayed response h(t) from an expression in t (s), normalised to unit integral on the grid and forced causal. More: nonlinear.md#raman-models

key	type	unit	default	meaning
expr	string			Expression in t (s) and the entries of params Required.
fR	number			Raman (delayed) fraction of n2
anisotropicFraction	number		0	Anisotropic share b of the response, h_b = b h and h_a = (1 - b) h (vector Raman: ellipse rotation, circular light). 0 isotropic, 1 purely anisotropic (h_a = 0), 1.5 purely orientational (h_a = -h_b/3, e.g. liquid CS2). Allowed 0 to 1.5

delayedResponse / hollenbeck

Hollenbeck & Cantrell 2002 silica Raman: 13 vibrational modes with intermediate broadening, fR = 0.18. More: nonlinear.md#raman-models

key	type	unit	default	meaning
fR	number		0.18	Raman fraction
anisotropicFraction	number		0.25	Anisotropic share of the response (vector Raman: ellipse rotation, circular light)

delayedResponse / linAgrawal

Lin & Agrawal 2006 silica Raman: damped oscillator + boson peak (pyNLO's full model), fR = 0.245. More: nonlinear.md#raman-models

key	type	unit	default	meaning
fR	number		0.245	Raman fraction
tau1	number	s	12.2e-15	Oscillator period parameter
tau2	number	s	32e-15	Oscillator damping time
taub	number	s	96e-15	Boson-peak time
fa	number		0.75	Weight a
fb	number		0.21	Weight b (boson peak)
fc	number		0.04	Weight c
anisotropicFraction	number		(fb + fc): h_b = fc h_a + fb h_b	Anisotropic share of the response (vector Raman: ellipse rotation, circular light)

delayedResponse / orientational

Molecular reorientation of a liquid (CS2): h(t) = (exp(-t/decayS) - exp(-t/riseS)) / (decayS - riseS), purely anisotropic Kerr tensor (h_a = -h_b/3). More: nonlinear.md#raman-models

key	type	unit	default	meaning
riseS	number	s	0.2e-12	Rise time (molecular inertia)
decayS	number	s	1.6e-12	Decay time (diffusive reorientation)
fR	number			Delayed fraction of n2
anisotropicFraction	number		1.5	Anisotropic share b of the response, h_b = b h and h_a = (1 - b) h (vector Raman: ellipse rotation, circular light). 0 isotropic, 1 purely anisotropic (h_a = 0), 1.5 purely orientational (h_a = -h_b/3, e.g. liquid CS2). Allowed 0 to 1.5

delayedResponse / silica

Fused-silica Raman response: Blow-Wood damped oscillator (12.2 / 32 fs), fR = 0.18. More: nonlinear.md#raman-models

key	type	unit	default	meaning
fR	number		0.18	Raman fraction
anisotropicFraction	number		0.25	Anisotropic share of the response (vector Raman: ellipse rotation, circular light)

filter / constant

Constant transmission.

key	type	unit	default	meaning
value	number			Power transmission
transmission	number			Power transmission
phaseRad	number	rad		Phase

filter / gaussian

Gaussian band-pass.

key	type	unit	default	meaning
centerWavelengthM	number	m		Centre
fwhmM	number	m		FWHM
peak	number		1	Peak transmission

filter / superGaussian

Super-Gaussian band-pass.

key	type	unit	default	meaning
centerWavelengthM	number	m		Centre
fwhmM	number	m		FWHM
peak	number		1	Peak transmission
order	integer		2	Order

filter / table

Tabulated transmission / phase vs wavelength.

key	type	unit	default	meaning
wavelengthsM	number or array	m		Wavelengths
wavelengthsNm	number or array	nm		Wavelengths in nm
wavelengthsUm	number or array	um		Wavelengths in um
transmission	number or array			Power transmission
phaseRad	number or array	rad		Phase
groupDelayS	number or array	s		Group delay (alternative to the phase)

index / constant

Constant index.

key	type	unit	default	meaning
value	number			Index

index / refractiveindex

A refractiveindex.info page (bundled, imported, a file, or ULTRAFAST_RII_PATH). More: materials.md#refractiveindexinfo-pages

key	type	unit	default	meaning
page	string			Page name ("main/SiO2/Malitson") or file
file	string			YAML file (alternative)
pressureBar	number	bar		Gas pressure (density scaling from the page's SPECS)
temperatureK	number	K		Temperature
dnDT	number	1/K	0	Thermo-optic coefficient (solids)
relativeToAir	boolean		false	The page's n are relative to air

index / sellmeier

Sellmeier: n^2 = A + sum B lambda^2 / (lambda^2 - C) (lambda in um, C in um^2). More: models.md#kinds-per-category

key	type	unit	default	meaning
B	number or array			B coefficients
C	number or array	um^2		C coefficients
A	number		1	Constant term