Functionality and capabilities

croak — Complete Retrieval by Optimisation and Adjoint Kernels — retrieves the complex field of an ultrashort pulse from a frequency-resolved optical gating (FROG) trace. A spectrometer records intensity; croak estimates the spectral amplitude and phase by comparing a predicted nonlinear measurement with the data. From that field you can calculate a temporal profile, duration and spectral phase, and explore propagation through materials or mirrors.

The usual workflow is to inspect and calibrate the data, choose the measurement model, retrieve from suitable starting fields, and assess the result. The experimental-workflow tutorial introduces those steps. The user guide explains their assumptions, and the gallery provides worked applications.

What a retrieval can tell you

A retrieval returns the field as defined by the forward model, at the reference plane that model sets. A small trace error shows agreement with the model, not that the model describes the instrument: on simulated deep-UV TG-FROG scans the thin-medium model fits to below 0.54 % yet returns a pulse up to 2.3 times too long (validation). Absolute phase and time origin are not determined, and SHG also cannot tell the direction of time. An energy measurement is needed to assign absolute power. See conventions and interpreting results.

croak implements SHG, SD and PG FROG, with transient-grating (TG) FROG retrieved through the PG interaction. The PNPS formalism also describes d-scan and related methods; their measurement operators are not implemented.

Retrieval

Ten solvers sit behind one croak.retrieve() call and all return a RetrievalResult. They are four algorithm families plus on-device reimplementations:

algorithm	Class	Gradient	Notes
"warm-lbfgs"	WarmLBFGS	JAX autodiff	the default; lbfgs-ad seeded from a COPRA local sweep
"copra"	COPRA	analytic adjoint	robust from poor guesses
"copra-jax"	COPRAJax	analytic adjoint	COPRA on-device
"lbfgs"	LBFGS	analytic adjoint	most flexible objective in pure NumPy
"lbfgs-hand"	LBFGSHand	analytic adjoint	jitted and vectorised; typically the fastest L-BFGS
"lbfgs-ad"	LBFGSAD	JAX autodiff	widest model coverage — see below
"lbfgs-optx"	OptxLBFGS	JAX autodiff	whole loop on-device
"lm"	LM	JAX Jacobian	polishes to the lowest error
"lm-optx"	OptxLM	JAX Jacobian	on-device Levenberg–Marquardt
"cma-es"	CMAES	none (global)	population search; needs croak[evo]

Options common to most solvers: amplitude-and-phase or phase_only retrieval, per-frequency R_omega intensity scaling, second-difference smoothness penalties on spectral amplitude (reg_amp) and phase (reg_phase), a spectral-match penalty against an independent measurement (reg_spectrum), and a temporal energy penalty outside a window (reg_time, on lbfgs-ad and cma-es). The amplitude and spectral penalties default to 0.03 and 0.01 for the gradient solvers (3e-5 and 1e-5 for LM); pass 0 to disable. The papers’ validation retrievals use 0.03 for both. See Regularisation.

A cubic B-spline phase basis (phase_basis="bspline") acts as a structural regulariser and is what makes the global search tractable. Warm starts, random restarts and a two-stage COPRA → LM polish are described in Solver selection; croak.retrieve.algorithm_params() reports which options a given solver accepts.

Further reading: Retrieval algorithms, Retrieval as least squares.

Gradients

The forward model is written in JAX and is differentiable end to end, so automatic differentiation is the general route. It supplies the gradients for everything the closed-form adjoint does not cover:

• geometric time smearing,

• fitted medium thickness, delay-zero and smearing width,

• the B-spline phase basis and the temporal penalty,

• the residual Jacobian that Levenberg–Marquardt and the Laplace covariance need,

• implemented interaction kernels expressed in the JAX model.

For the core model — all three thin-medium interactions, plus dispersive PG and SD, pointwise parameterisation, standard penalties — croak also carries a hand-derived Wirtinger adjoint, so COPRA and LBFGS run in pure NumPy with no JAX on the hot path. The two routes are tested against each other on every interaction and option they share, with complex-field perturbations and regularised objectives.

Further reading: Gradients.

Forward model

• Interactions — SHG, SD and PG (the transient-grating/TG-FROG kernel), each with analytic adjoints; see interaction physics.

• Dispersive propagation — a Gauss–Legendre depth integral through a material slab, propagating both the input replicas and the generated signal. Available on every solver, for PG and SD (the SHG signal is not at the fundamental frequency). The thin medium is the same code path with zero thickness and one quadrature node.

• Geometric time smearing — croak.smearing represents an achromatic, fully collected focal average using two timing coordinates: a gate-splitting parameter that changes the signal shape, and a delay offset that is a pure convolution along τ. square_boxcars_kernel() builds the kernel for a folded square BOXCARS mask, kernel_from_arms() for an arbitrary three-arm layout. fit_smearing=True fits its magnitude from the data on supported solvers.

• Chromatic focal fields and collection — an explicit focal mixture retains the frequency dependence of local beamlet fields. The collection model adds their complex signal fields through a finite aperture before squaring. Optional depth evolution accounts for beam profiles changing within the slab. These models take the instrument geometry (mask, focus, aperture) as input.

Further reading: The forward model, Interactions, Geometric smearing.

Materials, gases and mirrors

• Built-in materials — SiO₂, BK7, CaF₂, BaF₂, MgF₂, sapphire and silicon, each optmat’s recommended model, with its provenance from croak.materials.material_model().

• Gases — air and optmat’s fifteen gases (helium, argon, nitrogen, …) at the real-gas density for a pressure and temperature; registered as ordinary materials, so optical path length plays the role of thickness.

• Measured data — croak.materials.make_tabulated_material() turns noisy samples into a smoothing spline in log-λ, so its derivatives stay physical.

• Chirped mirrors and coatings — bundled mirror designs and beam-path coatings, applying both the per-bounce spectral phase and the measured reflectivity. A negative bounce count back-propagates, removing a mirror from the pulse.

• Your own — croak.materials.register_material() and croak.mirrors.mirror_from_arrays() make a custom index or measured mirror work everywhere a built-in does.

• Dispersion tuning — croak.dispersion.apply_dispersion() applies Taylor GDD/TOD/FOD, material thicknesses and a mirror stack in one call, with auto-tuners that maximise temporal peak power.

Further reading: Materials and mirrors, Dispersion tuning.

Loading and preprocessing

• Formats — traces from HDF5 and NumPy .npz files; independent spectra and calibration curves also from delimited text (CSV). Dataset auto-detection by name, unit handling and position→delay conversion (croak.io).

• Axis conventions — the trace orientation (transpose) and the delay sign (reverse_trace, mirroring the trace about τ = 0) are per-load switches on both the measured and the simulated loader.

• Simulated scans — traces written by a propagation code, including multi-thickness scans selectable by thickness or slice index.

• Corrections — background subtraction, calibration curves, χ⁽³⁾ efficiency scaling.

• Filtering — fringe band-stop, DC removal and delay low-pass, all on a non-uniform FFT, so a jittered or unevenly stepped delay axis stays correctly calibrated.

• De-fringing — defringe_carrier() removes interferometric fringes by a smooth low-pass below the optical carrier, which is computed from the wavelength axis rather than fitted, with a Nyquist guard.

• Baseline removal — arpls_baseline() fits a smooth asymmetric lower envelope per wavelength row, handling a background that is asymmetric about τ = 0, with a τ ≈ 0 hold-out that stops it bowing into the signal peak.

• Regridding — wavelength to a uniform angular-frequency grid with the correct Jacobian and anti-aliasing; the SHG carrier doubling is handled automatically, and τ = 0 is centred on the delay marginal to sub-sample precision.

• Band diagnostics — the grid’s edge taper rolls the outermost frequency rows to zero, so a narrow lam_min/lam_max removes real signal. TraceData.taper_loss reports how much of the trace the taper removed, and the loader warns above 1 %.

Further reading: Preprocessing, Grids and filtering, Loading simulated traces.

Analysis and plotting

• Marginal checks — croak.marginal_checks tests the measured frequency marginal against the prediction before retrieval: centroid and width anchors per geometry, and automatic choice of the third-order efficiency exponent by centroid matching.

• Ambiguity resolution — an SHG trace cannot distinguish a pulse from its mirror image, and the flip also inverts the sign of the retrieved spectral phase. When the true pulse is known, croak.processing.resolve_time_direction() picks the matching branch from the temporal intensity (a time-symmetric intensity leaves it undecided).

• Post-processing — croak.processing.process_result() returns oversampled temporal intensity and phase with the linear ramp removed, the transform-limited reference, fitted GDD/TOD/FOD, marginals, weighted residuals, and absolute peak power when a pulse energy is supplied.

• Edge-energy quality flag — croak.processing.edge_energy_fraction() reports how much spectral energy sits in the unmeasured grid-edge bins: under 0.1 % is sound, a few percent means part of the spectrum and duration is an artefact, usually from R_omega without a spectral constraint.

• Plotting — a twelve-panel retrieval summary built from twelve independent panels (also laid out as three 2×2 pages), a six-panel filter before/after view, spectrograms, uncertainty and thickness-sensitivity plots. Every composite is built from single-axis functions, which the GUI embeds directly.

Further reading: Marginal checks, Post-processing.

Uncertainty

croak.uncertainty.estimate_fwhm_uncertainty() dispatches four resampling-based estimators by name:

method	Kind
"parametric"	Monte-Carlo over a detector noise model, re-retrieving each replicate
"delay" / "frequency"	resampling (block) bootstraps of delay columns or frequency rows
"thickness"	systematic — propagates a measured substrate-thickness prior

Two more estimators are their own functions rather than dispatcher methods:

• croak.covariance.covariance_uncertainty() — a local Gaussian covariance approximation from the JAX residual Jacobian. It needs no re-retrieval and also analyses NumPy-solver results whose model the JAX path implements. Its pseudo-inverse drops the unobservable gauge directions, and with them any equally weak physical direction.

• croak.uncertainty.combine_uncertainties() — convolves the centred sample distributions of independent contributions, preserving skew (and reducing to quadrature in the Gaussian limit).

Also: standard errors on fitted thickness, delay-zero and smearing width; coverage calibration against synthetic ground truth; and propagation of an interval to another point in the beamline through a known transfer function.

Further reading: Estimating FWHM uncertainty, Uncertainty of the retrieved duration.

Interfaces

• Library first — every stage is callable without the GUI.

• The wizard — a six-stage PyQt6 application (Load → Marginal check → Preprocess → Retrieve → Dispersion → Uncertainty) with live retrieval previews and a numeric read-out of retrieved, measured, transform-limited and (for synthetic sessions) true pulse parameters. Laid out for 1366×768 displays and up. Importing croak does not import Qt.

• Sessions — the session engine replays a saved TOML session end to end through the same stage operations the GUI uses.

• CLI — croak replay reruns a session headlessly, including batch retargeting across datasets; croak script generates a standalone, editable Python script from it.

Further reading: The wizard GUI, Saving and loading.

Conventions

SI units in the core numerical interfaces (session display units are named explicitly); a centred, baseband angular-frequency grid; the physics Fourier convention (\(+i\omega t\) forward, \(1/2\pi\) on the inverse); traces stored as (Nomega, Ndelay). The trace error is written \(R\). The known ambiguities — absolute phase, time origin, and for SHG the direction of time — are documented rather than hidden.

Further reading: Conventions, FFT convention, Glossary.