Quickstart

Generate a synthetic FROG trace, retrieve a pulse from it, and inspect the result. This small calculation checks your installation; the first retrieval tutorial explains the physics and plots. All times, frequencies and lengths passed to croak use SI units.

Retrieve a pulse

import numpy as np
import croak

g = croak.Grid(128, dt=0.3e-15)
ew = croak.gaussian_pulse(g, 2.5e-15, phases=[4e-30])   # phases = [GDD, TOD, ...]
delays = np.linspace(-18e-15, 18e-15, 87)
trace = croak.maketrace(g.omega, delays, ew, "shg")
res = croak.retrieve(trace, g.omega, delays, "shg", algorithm="copra",
                     guess=croak.gaussian_pulse(g, 1.8e-15), maxiters=300,
                     rng=np.random.default_rng(0))
print(f"trace error R = {res.error:.3g}")

Grid defines matched time and angular-frequency axes. gaussian_pulse creates a pulse with a transform-limited intensity FWHM of 2.5 fs; the 4 fs² of spectral group-delay dispersion stretches it. maketrace predicts the intensity recorded at each frequency and delay in an SHG-FROG measurement. retrieve searches for a complex pulse that reproduces that trace. The seed makes this demonstration repeatable.

The trace is simulated, so its generating pulse is known. On measured data a small trace error shows that the model reproduces the trace, not that the model is the right one; the measurement modelling guide explains when that distinction matters.

Choose an algorithm

This example explicitly selects COPRA. Omitting algorithm selects "warm-lbfgs", a COPRA start followed by L-BFGS refinement. The same entry point supports all solvers, but their model support and options differ. Use the solver selection guide for practical choices and the executed algorithm comparison for a worked example.

retrieve displays progress by default. Set progress=False for quiet batch runs, or supply a callback for your own monitoring. You can also instantiate a solver, for example croak.COPRA(maxiters=100), and call its run method; the solver API documents this interface.

Dispersive retrieval

To include propagation through a nonlinear slab, specify the same material, thickness, depth quadrature and carrier in trace generation and retrieval:

omega0 = croak.maths.wlfreq(260e-9)
medium = dict(material="SiO2", thickness=10e-6, npoints=20, omega0=omega0)
trace = croak.maketrace(g.omega, delays, ew, "pg", **medium)
res = croak.retrieve(trace, g.omega, delays, "pg", algorithm="copra",
                     rng=np.random.default_rng(0), **medium)

The slab model supports PG and SD, whose signals remain near the fundamental carrier, but not SHG. The dispersive tutorial uses a suitable ultraviolet pulse and explains the recovered field’s reference plane. The measurement modelling guide explains when spatial geometry and collection must also be included.

Initial guesses

guess accepts None for a random Gaussian-spectrum start, a complex spectral array on the retrieval grid, or a croak.pulses.Pulse. Guesses are normalised internally. The objective is non-convex, so on measured data retrieve from several random starts and keep the lowest-error result. Agreement between starts is a convergence check, not a measurement uncertainty.

The result object

All solvers return a RetrievalResult:

res.error          # normalised trace error R
res.errors         # trace-error history
res.spectrum       # complex baseband spectrum, centred order
res.field          # complex temporal field envelope
res.intensity_t    # temporal intensity |E(t)|²
res.phase_omega    # unwrapped spectral phase
res.wavelength     # absolute wavelength axis (m), using omega0
res.trace          # predicted trace, already scaled by the fitted factor res.mu

res.trace can be compared directly with the supplied data. The absolute wavelength axis is correct only when omega0 is the true fundamental carrier. See interpreting results for plotting, ambiguity resolution, duration and spectral-phase interpretation.

Next steps

Continue with your first retrieval, then dispersive retrieval and the experimental workflow. The example gallery covers more specialised calculations.