Mode-locked lasers are modelled by the oscillator element. It produces the steady-state output of a laser and replaces
the incoming beam with it, so place it first in the system. The run's pulse sets the grid (centre wavelength,
window). With "start": "pulse" it also seeds the laser.
| model | what it is | use it for |
|---|---|---|
parametric |
"output": { pulse }: you give the output pulse (as in the run spec) and the repetition rate |
a known seed laser in front of an amplifier |
haus |
lumped master equation iterated round trip by round trip: saturated gain with a spectral shape, loss, GDD/TOD, SPM δ·P(t), saturable absorber, output coupler | soliton and fast-absorber mode-locking, parameter studies (fast: thousands of round trips per second) |
cavity |
a real gain medium ("gain": {"medium": ...} with a cw pump) plus any engine elements in "elements", run in order every round trip |
a specific laser design: crystals, chirped mirrors, prisms, SESAMs, Kerr media, filters |
Gain (lumped). The gain is a ln power gain per round trip, g(E) = g0 / (1 + E/E_sat) (or with P_sat on the
average power). It has a lorentzian (default), gaussian or parabolic spectral shape of FWHM bandwidthM
around centerWavelengthM. Give fluenceSaturationEnergyJ to get the Q-switching diagnostic.
Gain (medium, cavity model). The gain medium is described like the gain elements (gain.md):
medium, lengthM, pump (cw), modeRadiusM, passesPerRoundTrip (2), slices. The inversion follows the
cw rate equations with the pump and the average intracavity power. The upper-state lifetime is much longer
than a round trip, so the inversion is relaxed towards that quasi-steady state by relaxation (0.2) per round
trip. Every pass applies the spectral gain, the dispersion and SPM of the host, and gain narrowing.
Cavity elements. Cavity elements are ordinary elements, compiled with ids oscillatorId.elementId. Any type
works except another oscillator:
chirpedMirror,dispersion,bulk(with n2: SPM, Kerr lensing on atransversegrid);saturableAbsorber,aperture(soft or hard, acting on a carried profile),filter,lens.
The output coupler sits at the end of the list.
Window. The oscillator iterates on at most gridPoints (4096) samples of the run's grid, with the same time
step and carrier. The result is embedded back into the full window, so a long stretcher downstream does not
slow the oscillator down.
Start-up. "start": "noise" starts from one photon per mode (quantum noise, seeded by seed). It is the
default for haus and shows the real build-up. "start": "pulse" starts from the run's pulse (scaled to
seedEnergyJ); it is the default for cavity and is faster.
Convergence. Convergence is checked every checkEvery (25) round trips. Steady state means that the output
energy and FWHM change by less than tolerance per round trip and the spectral centroid stays put, three
checks in a row. The pulse is re-centred every round trip; the drift is reported as roundTripTimingOffsetS,
the correction to the round-trip time.
"type": "saturableAbsorber" (alias sesam) works anywhere in a system. In the Haus model it is the oscillator's
absorber.
| kind | loss q(t) | parameters |
|---|---|---|
slow (SESAM) |
dq/dt = −(q − q0)/τ_A − q P/E_sat,A | modulationDepth q0, nonsaturableLoss, recoveryTimeS, saturationFluenceJPerM2 + spotRadiusM (or areaM2, beam) or saturationEnergyJ |
fast |
q0 / (1 + P/P_sat) | modulationDepth, saturationPowerW (or saturationIntensityWPerM2 + spot) |
kerrLens |
max(0, q0 − κP) | modulationDepth, kappaPerW: the lumped self-amplitude modulation of Kerr-lens mode-locking |
The field is multiplied by exp(−(q(t) + q_ns)/2). The element reports pulseLoss, saturationParameter
(E/E_sat) and the arrays timeS and loss (q(t)). For short pulses on a slow absorber the absorbed fraction is
q0(1 − e^−S)/S (tested).
Spatial cavities and Kerr-lens mode-locking. Cavity elements may carry a transverse profile (a Kerr medium
on a radial grid, gaps, lenses or curved mirrors, a soft or hard aperture). The profile goes round the cavity and
settles on the resonator's eigenmode: LaserTests checks a lens-guide cavity whose mode reproduces the
Gaussian-beam eigenmode, w0 = sqrt(λ z_R/π). Kerr-lens mode-locking from first principles needs a resonator that
focuses tightly into the crystal and runs near its stability edge, as real KLM lasers do. It then needs
thousands of spatial round trips (≈ 0.1 s each on a 32-point radial grid), so treat it as experimental. The
lumped kerrLens absorber is the practical model.
Values (summary.json → elements[i].values):
| value | meaning |
|---|---|
outputEnergyJ, averagePowerW, repRateHz |
output |
intracavityEnergyJ, intracavityAveragePowerW |
at the output coupler |
roundTrips, converged |
|
netGainPerRoundTrip, bIntegralPerRoundTripRad, gddPerRoundTripS2 |
per round trip |
outputFwhmS, outputSpectralFwhmM, timeBandwidthProduct |
the output pulse |
solitonFwhmS, fwhmOverSoliton |
soliton area theorem τ = 3.53·|GDD|/(δE), δ = B / P_peak (negative GDD only) |
pulsesInCavity |
> 1 means multi-pulsing, and a warning is issued |
backgroundFraction |
energy more than 5 FWHM from the pulse: cw breakthrough or an unsettled state (warning above 5 %) |
qmlParameter |
E_p² / (E_sat,L E_sat,A ΔR) (Hönninger et al., JOSA B 16, 46 (1999)); below 1, Q-switched mode-locking is expected (warning) |
inversionFraction, smallSignalGainPerPass, absorbedPumpPowerW, opticalEfficiency |
cavity model |
The gain dynamics are relaxed rather than resolved, so the simulation itself does not show Q-switching;
qmlParameter tells you whether a real laser would.
Arrays (el_<id>_*):
roundTrip,outputEnergyPerRoundTrip,netGainPerRoundTrip;- snapshots
evolutionRoundTrip×evolutionTimeS→evolutionPower; - snapshots
evolutionRoundTrip×evolutionWavelengthM→evolutionSpectrum.
ultrafast-plot draws them in oscillator.png.
A resonator is a passive cavity around nested elements, for its modes rather than for a laser pulse:
{ "id": "cavity", "type": "resonator", "geometry": "ring", // "ring": once per round trip; "linear": forward and back, end elements once
"transverse": { "model": "radial", "points": 256, "radiusM": 3.5e-3, "spectralSamples": 1 }, // optional: the Fox-Li iteration
"roundTrips": { "max": 800, "tolerance": 1e-7 },
"elements": [ { "id": "half1", "type": "gap", "lengthM": 0.3 }, { "id": "lens", "type": "lens", "focalLengthM": 0.5 },
{ "id": "stop", "type": "aperture", "radiusM": 1.1e-3 }, { "id": "half2", "type": "gap", "lengthM": 0.3 } ] }- The tracker gives the round-trip matrix, and the element reports
stabilityX,stabilityY((A + D) / 2),stable,modeRadiusXM,modeRadiusYM,modeCurvatureXPerMat the reference plane (the start of the first element),roundTripOpticalLengthMandfreeSpectralRangeHz. An unstable cavity gives a warning. A curved end mirror of a linear cavity is an element that acts once per round trip, like a lens of f = R / 2. - With a
transversegrid (given to nested gaps and bulks without one) the Fox-Li iteration (Bell Syst. Tech. J. 40, 453 (1961)) starts from a Gaussian and runs the round trip until the loss settles:roundTripLoss,foxLiRadiusXM,foxLiRoundTrips,converged. A cw source ("shape": "cw") makes this one frequency. - The output beam takes the mode: the tracked beam becomes the eigenmode, and the pulse carries the Fox-Li profile. Its energy is unchanged: this is a mode calculation, not a cavity ring-down.
The
oscillatorelement is the one for pulses building up in a cavity.
Checks (CavityAndCoherenceTests): a lens guide's eigenmode (Kogelnik & Li), a two-mirror cavity, Fox-Li against the ABCD mode (3 %), and the diffraction loss of plane circular mirrors, near 20 %
at N = 1 and falling as N^(−3/2).
It is a nested sequence, not a graph: elements inside cannot be reached by a second beam. A graph loop is the alternative: see Branched systems.
from ultrafast.laser import Oscillator
osc = (Oscillator("laser", model="haus", rep_rate_hz=80e6, output_coupler=0.05)
.simple_gain(1.5, saturation_energy_j=5e-9, bandwidth_m=100e-9, shape="gaussian")
.loss(0.02).dispersion(gdd_fs2=-500).spm(1.5e-6)
.absorber("kerrLens", modulation_depth=0.03, kappa_per_w=3e-8))
res = uf.run(osc.system(), b.run_spec(b.pulse(800e-9, 30e-15, energy=1e-12), grid={"auto": False, "n": 4096, "windowS": 8e-12}))
Oscillator.soliton_fwhm_s(-500e-30, 1.5e-6, 16.5e-9) # area theoremA cavity model in Python uses .gain_medium(...) and .add(b.chirped_mirror(...), b.saturable_absorber(...)).
LaserTests checks:
- the soliton area theorem in the Haus model and in a real Yb:YAG + SESAM cavity (both within 10–15 %);
- cw gain clamping, E = E_sat(g0/L − 1);
- slow-absorber saturation q0(1 − e^−S)/S;
- fast-absorber saturation;
- the multi-pulse and background detectors;
- the QML criterion is reported.
Examples: 19 (Ti:sapphire KLM, Haus, from noise), 20 (Yb:YAG SESAM oscillator → stretcher → amplifier → compressor).
{ "id": "laser", "type": "oscillator", "model": "haus", // "parametric" | "haus" | "cavity" "repRateHz": 80e6, // or "cavityLengthM" (linear: c / 2L; "ring": true: c / L) "outputCoupler": 0.05, // power transmission "gain": { "smallSignalGain": 1.5, "saturationEnergyJ": 5e-9, "bandwidthM": 100e-9, "shape": "gaussian" }, "lossPerRoundTrip": 0.02, "gddFs2": -500, "spmRadPerW": 1.5e-6, "absorber": { "kind": "kerrLens", "modulationDepth": 0.03, "kappaPerW": 3e-8 }, "start": "noise", "roundTrips": { "max": 8000, "tolerance": 1e-5 } }