Using the GUI#

The graphical interface takes you from a loaded trace to a retrieved pulse, dispersion analysis and uncertainty estimates in one window. Its controls use the same calculations as the Python interface. If this is your first visit, follow installing the GUI, then try a synthetic trace whose pulse is known.

A session runs through five stages — Data → Check → Prepare → Retrieve → Analyse — which you reach from Home. The top bar always shows where you are, which stages you can open and the one action that moves the session on.

Launching#

For a standalone tool installation:

croak-gui

Within a uv project or source checkout, use uv run croak-gui or uv run python -m croak.gui. From Python, call croak.gui.run_gui():

import croak.gui

croak.gui.run_gui()

croak.gui.main() is the console-script entry point; run_gui() creates the QApplication and shows the window (croak.gui.MainWindow) maximised, because the plots need the room. Un-maximising gives the window the size you last left it (remembered between launches and clamped to the screen it opens on), or on a first run a window filling 90 % of the screen.

The GUI is built on PySide6. Every plot on screen is an interactive pyqtgraph view; figures you export or save are drawn by matplotlib (croak.plotting), so they look the same as the figures a script makes.

Small screens#

The window is laid out for displays of 1366×768 logical pixels and up (a 1920×1080 monitor at Windows’ 125 % scaling is 1536×864 logical pixels). Each stage puts its settings in a narrow column on the left (340 pixels) and gives the rest of the window to its plots; when the window is narrower than 1000 pixels the plots move below the settings instead. The settings are grouped in sections that fold, and Retrieve’s advanced sections start folded, so a laptop screen shows the settings you use most without scrolling. Beneath Retrieve’s plots, the run’s numbers and its convergence share one short strip.

Plot text stays at the same size whatever the window size. Exported figures (see Figures for publication) and the files a Save writes are drawn afresh at their own design size, so they do not depend on the window either.

Desktop integration#

The GUI carries its own icon (croak/gui/resources/croak.svg) and identifies itself as croak rather than as the Python interpreter running it: that is the icon in the macOS Dock, the Windows taskbar and the Linux dock, and the name in the macOS menu bar. Two platform details remain:

On macOS the Cmd-Tab switcher and the Dock tooltip still say python3. Those come from an application bundle, which a plain croak-gui process does not have.
On Windows croak-gui is a gui-scripts entry point, so it opens no console window, but a crash before the window appears is then silent. Run uv run python -m croak.gui from a terminal to see the traceback.

Home#

Home is where a session starts. Its first three tiles each start a session from one kind of data:

Measured trace — load a FROG measurement from HDF5 or NPZ, with its independent spectrum, backgrounds and calibration curves.
Simulated scan — load a numerically simulated scan (a scansave file), with its known input pulse and instrument geometry.
Synthetic trace — generate a trace from a pulse you specify, with dispersion and noise, and test a retrieval against the known answer.

The fourth tile, Open a session, reopens a saved session from its options.toml (see Sessions). Beneath the tiles, About croak opens the About page: the version, links to this manual, the source on GitHub, the package on PyPI and the issue tracker, the authors, and the copyright and licences. The Recent sessions list on the right holds the last six sessions you saved or opened, named by their folder, with the folder’s location and the time the session was last saved; a session whose file has gone is left out. Click one to reopen it.

Starting a new session, or opening one, replaces the session in the window. If that session holds a trace or a retrieval, the GUI asks first, with Discard or Cancel; Save session… in the ⋯ menu keeps it.

The top bar#

The top bar carries, from left to right:

the croak brand and a context label: what the session is (Measured trace, Simulated scan or Synthetic trace) and, once it has been saved or opened, its folder’s name;
Home, which returns to Home (so does the brand). The session stays open: its stage buttons are still there, so you can go back to it;
the five stage buttons Data · Check · Prepare · Retrieve · Analyse. A stage that cannot be opened yet is greyed out, and its tooltip says why;
the primary action, the button that moves the session on, and on Retrieve, once a retrieval is done, Retrieve again beside it;
the ⋯ menu: Save session…, Open a session…, Export this page as a figure…, Show the settings (options.toml), Show as a Python script, Help for this stage and About croak.

The menu bar repeats these under File (Home, Open a session…, Save session… and Export this page as a figure…, with the platform’s Open and Save shortcuts and Ctrl+E, ⌘E on macOS), View (the settings and the script) and Help (Help for this stage, F1 on Windows and Linux, ⌘? on macOS, and About croak, which macOS moves to the application menu). Passing notices, such as “Saved …” or why a stage cannot open, appear at the foot of the window, which also holds the display settings while a session is open, and hides on Home when there is nothing to say.

The route#

Which stages can be opened depends only on what the session holds:

Stage	Opens once
Data	a session has started
Check	a trace has been loaded
Prepare	a trace has been loaded
Retrieve	the trace has been prepared
Analyse	a retrieval has run

A simulated scan loaded with Skip filtering & regrid is retrieved on its own grid, so it goes from Data straight to Retrieve and Prepare stays disabled (Check stays open, to look at the scan, and its Continue also goes to Retrieve). Changing a setting upstream clears what was derived from it — a new trace clears the prepared trace and the retrieval — so the GUI never shows a pulse retrieved from superseded settings, and the later stages close again until they are recomputed.

The primary action follows the stage:

Where	Primary action
Data	Continue: load or generate the trace and go on to Check
Check	Continue to Prepare
Prepare	Continue to Retrieve
Retrieve	Retrieve, Stop while it runs, then Analyse, with Retrieve again beside it
Analyse	Save (the session); on the Uncertainty page Estimate, or Stop while it runs

The action is greyed out until it can be done: Continue on Data, for example, until there is a trace to hand on.

The stage pages#

Every stage page has the same layout. On the left is a form of sections, each headed by a title you click to fold or unfold it. Hover over a control for its help; when a control has the keyboard focus, the same help is shown as one line under the form. Help for this stage (⋯ menu or F1) opens a summary of every setting on the page. The Retrieve form also has a Find a setting box, which shows only the rows whose label or help contains what you type; typing part of a section’s title shows that whole section.

At the foot of the form a ready line says whether the stage can go on: green when it can, amber with a warning, red when something has to be fixed first. Retrieve has none: the numbers beneath its plots say how a run goes, anything else it has to say appears at the foot of the window, and a failed retrieval shows in an amber box over the plots until the next run. On the right are the stage’s plots.

A setting with a slider has its value in a box just wide enough for the numbers it takes, so the slider has the rest of the row; a range has its two ends either side of one slider.

Plots#

Every plot shares the same handling:

Hover to show a crosshair and a read-out: the position, and the value of the map or of each curve under the pointer.
Scroll to zoom about the pointer, and drag to pan.
Double-click to return to the view the data were first shown with, and a map to its colour scale.
Drag a colour bar’s ends (or the bar itself) to change that map’s colour scale on its own, for example to look further down a logarithmic trace. A signed map keeps its white at zero wherever the scale is dragged.

Plots that share an axis are linked, so zooming one zooms its partners: the trace maps on Prepare, and the measured and retrieved traces on Retrieve and Analyse. Images are shown on evenly spaced axes at their finest sample spacing, so no detail is lost where the samples are densest. A logarithmic (dB) trace shows the positive part of the signal; negative samples, left by background subtraction, show on the linear maps, which run from white to viridis for positive values and from white to red for negative ones.

Display: spectral axis and log range#

Two settings at the foot of the window hold for every plot on every page. They are remembered between launches and stay until you change them or click Reset:

Spectral axis: As computed keeps each plot on the axis its data were computed on — wavelength for a loaded trace and the generator’s previews, frequency for the prepared trace and the retrieval. Wavelength or Frequency draws every spectral plot, maps and curves alike, against that axis, with ν = c/λ. An intensity is a density per unit of its axis, so it takes the Jacobian too, \(I_\nu = I_\lambda\,\lambda^2/c\) and \(I_\lambda = I_\nu\,\nu^2/c\): a broad spectrum changes shape, not only position. Phases and filter factors only move. Each plot keeps its peak, and a map is resampled onto an even grid on the new axis, for drawing only (croak.plotting.display).
Log range: how far below its peak every logarithmic (dB) map reaches, from 5 to 120 dB (30 dB by default). A dragged colour bar overrides it for one map until that map is next drawn.

Exported figures follow both: a plot or page exported from the screen is drawn as shown, and croak’s own figures of a result (Analyse’s Overview, Traces, Pulse and Diagnostics pages, and the retrieval.pdf a saved session holds) take the log range and draw their spectrum on the chosen axis. Their trace maps are always against frequency, so with the display on wavelength Analyse’s pages are exported as they are shown instead.

Right-click a plot for its own menu: Export this plot as a figure…, Save as an image… (a PNG of the plot as it is on screen) and Copy as an image.

The pages on Analyse also have Export ▾: Figure… saves that page as a figure (as Export this page as a figure… does), and Pop out opens it in a window of its own, which follows later results.

Figures for publication#

Any page, or any single plot, can be saved as a figure drawn by matplotlib: Export this page as a figure… (⋯ menu, File menu or Ctrl+E) for the page on screen, or Export this plot as a figure… from a plot’s right-click menu. Choose PDF or SVG for a vector figure, or PNG. In a vector figure the axes, curves and text stay sharp and the text stays editable text; the colour maps are embedded as images at 300 dpi (rasterized), so a trace map stays small and opens quickly. A PNG is written at 300 dpi.

The figure shows the same data as the screen, with the same colours, line styles and labels, sized for print: each plot is 3.4 × 2.6 inches (a journal’s single column) in 8-point type, and a page keeps its plots’ arrangement. Analyse’s Overview, Traces, Pulse and Diagnostics pages are saved as croak’s own figure of that page (plot_retrieval_page()), as a script makes it. From a script, croak.plotting.export draws the same screen views.

The stages#

Data#

Data holds the loader for the session’s kind of data. Continue loads (or generates) the trace and moves on to Check. Check opens as soon as a trace is loaded, so a measured trace loaded with Load & Preview can be checked from the top bar straight away.

Load the trace (measured)#

Pick an HDF5/NPZ file and the trace/wavelength/delay datasets, with unit and axis auto-detection (croak.io), then press Load & Preview; Continue is available once the trace has loaded. An optional independent spectrum can come from HDF5, NPZ or CSV, with background subtraction, and wavelength calibration curves from CSV. Transpose fixes a trace that loaded as (delay × wavelength), and Reverse delay axis flips the delay-sign convention — negating the scan axis, so the trace is mirrored about τ = 0. Which end of a stage scan is “gate late” is a wiring convention the file does not record. It matters for PG and SD, whose kernels fix the direction of time: a wrong setting time-reverses the retrieved pulse and flips the sign of every phase order. The error is invisible on a symmetric transform-limited pulse, so check the setting once against a pulse of known chirp (for example after adding a known glass thickness). An SHG trace is symmetric in delay even for a chirped pulse, so reversing it changes nothing and cannot settle SHG’s own direction-of-time ambiguity — that is resolved after retrieval instead (SHG: settle the direction of time first). It is the measured counterpart of the simulated loader’s switch of the same name.

Optionally enter the measured pulse energy (J) here to rescale the temporal plots to absolute power (see the Dispersion page under Analyse). The trace preview uses the same colour scheme as Prepare (white→viridis for positive, white→red for negative), with the display scaled to the in-trust-band signal so an aggressive efficiency tilt cannot wash the image out.

Load the scan (simulated)#

Load a numerically simulated scansave scan and preview it live. A thickness dropdown selects which saved propagation depth to retrieve from a multi-thickness scan (disabled for older single-thickness files). Continue loads the scan and moves to Check; with Skip filtering & regrid (raw → retrieval) ticked it builds the as-simulated trace on its native grid and goes straight to Retrieve. See Loading numerically simulated traces.

Generate the trace (synthetic)#

Build a test trace (pulse shape, interaction, delays, optional dispersive slab and noise) using maketrace(), previewed live. Useful for trying the workflow without data. The duration is the intensity (power) FWHM of the temporal envelope — both Gaussian and sech² honour this convention (gaussian_pulse(), sech_pulse()). The delay and wavelength samplings each expose an interlocked count and step at fixed range (editing one updates the other), and a Spectrum (independent) section generates a fundamental spectrum that is passed downstream (range / step / # points); by default it mirrors the FROG-trace λ window, scaled to the fundamental (×2 for SHG). With it present, the marginal-check overlay and the SHG marginal correction work on synthetic traces too. Continue generates the trace and moves to Check. The known pulse (its temporal intensity envelope It) is carried through, shown beneath the retrieved pulse, and saved with the result.

Check#

Compare the trace’s frequency marginal with the marginal predicted from the independent spectrum (croak.marginal_checks): exact for SHG (the spectral autoconvolution) and transform-limited for PG/TG/SD, within the thin local model; the marginal guide states its assumptions. The page overlays the predicted marginal, marks the predicted vs measured centroid, reports the width-bracket check, and exposes the spectral trust region (defaults to 190–1000 nm for a measured trace, or the full loaded range for the noise-free simulated/synthetic traces), a log/linear marginal toggle (default linear, peak-normalised) and the 3rd-order (λ/µm)^exp efficiency correction. Its Auto button picks the exponent whose corrected-marginal centroid matches the prediction (auto_third_order_exponent()). The SHG marginal correction is available here: it scales the trace’s frequency rows onto the predicted SHG autoconvolution (apply_marginal_correction()), is enabled only for an SHG trace with an independent spectrum, and previews the snap onto the prediction live (the correction itself is applied in Prepare). All three kinds of session pass through this stage, except a raw simulated scan; see Marginal consistency checks.

The marginals are drawn against frequency, the space the retrieval works in, unless the display asks for wavelength. The wavelength view applies the \(1/\lambda^2\) density Jacobian to the predicted marginal, which shifts a broad marginal towards the blue even when its frequency centroid matches.

Prepare#

Fringe/DC/low-pass filtering, windowing and regridding (load_and_clean()), recomputed automatically as you change a setting. The plots show six maps in two rows of three — the measured, filtered and regridded trace, in dB above and linear below — with linked axes: all six share the delay axis, and the measured and filtered maps share the wavelength axis, so a zoom on one follows on the others. Above the maps, five numbers say what the grid gives: its size (delay × frequency samples), its time step Δt (the shortest feature it can show), its time window (the longest pulse it can hold), its λ span, and the taper loss, the share of the trace the grid’s edge taper removes, in amber above 1 %, when an advice box also says to widen the λ range.

The controls always show the settings that were actually applied: re-entering the stage re-seeds every widget from the current parameters, and those parameters survive a round trip back to the loader as long as the trace is unchanged (see Preprocessing). Reset defaults restores the data-seeded defaults. With Baseline (arPLS) on, the Auto button beside τ exclude (fs) sets the hold-out to twice the loaded trace’s delay-marginal FWHM. Use it on measured traces: without a hold-out the baseline bows into the τ ≈ 0 peak and removes signal, worst on the rows that constrain the fit least. The failure shows up as a thin stripe at one wavelength in the cleaned trace (see Peak suck-up).

Retrieve#

Choose the algorithm (any of the ten, including the global cma-es) and its parameters and run it with Retrieve in the top bar or Run on the form. Retrieval runs in a background thread, driven by the solver callback, so the interface stays responsive. The plots show a live overview: the measured and retrieved traces (log) above the retrieved pulse and its spectrum. The full pages of panels are on Analyse.

The form’s sections, in order, are the solver and its mode, the forward-model sections (Dispersive propagation, Geometrical smearing), the advanced sections and Post-filter (applied to result). The advanced sections — Chromatic focal mixture (advanced), Extra fit parameters, Regularisation and Global search (cma-es) — start folded, and whether each is open is remembered between launches. Below them are Reset (the default retrieval settings) and Retarget to new dataset… (see Sessions). A run starts and stops from the top bar’s Retrieve and Stop, and Save session… saves it.

By default Live full-plot preview redraws the overview as the run converges. Previews arrive at most four times a second, and less often on a machine where presenting one is slow: the GUI measures what each preview costs and stretches the interval so that presenting stays below about a quarter of the wall-clock time, so the preview never starves the solver. The convergence curve beside the numbers follows the run, redrawn at up to ten frames a second however fast the solver iterates. Later snapshots update the existing curves and images in place, so nothing shifts between frames. Pressing Stop halts the run at that point and leaves the latest result on screen as a (non-converged) result you can inspect, save or post-filter. Untick Live full-plot preview to leave the overview until the run finishes, with only the convergence curve moving. Every solver supports the preview, including copra/copra-jax and the COPRA warm-up of warm-lbfgs, which is 300 iterations by default. warm-lbfgs runs both stages on one convergence curve; the convergence panel on Analyse’s Diagnostics page marks the handover with a dashed rule. Read the two sides as different units of work (COPRA iterations, then L-BFGS function evaluations).

The Initial guess selector makes automatic, transform-limited, random, perfect-Gaussian, known truth, and reuse-previous starts mutually exclusive. Truth uses the complex field stored by ModelPNPS (and reports an explicit error for an older intensity-only file). Reuse previous result warm-starts one run from the last — handy for the global-then-local refine recipe. It seeds the previous spectrum as the initial guess and the extras that run fitted (thickness, τ₀, smearing width) as the starting values for fitting them again, naming them in a notice at the foot of the window; an extra you are no longer fitting keeps the value set in the controls. The numbers beneath the plots show the fitted extras — including the geometric-smearing width as a delay σ in fs with its multiplier on the nominal mask geometry (which is left untouched). When the trace came from a synthetic or simulated session, the known-truth temporal intensity is drawn as a thin black line beneath the retrieved and transform-limited pulses. When its complex field is available, dotted truth-phase lines appear in both time and spectrum panels and are named in their legends. The truth arrays are also written into the saved result.h5.

Beneath the plots, the run’s numbers sit beside its convergence, the error against iteration on a log scale (the whole history once the run ends, with the hand-overs between a solver’s stages marked). The first row tracks the run and its pulse: Iteration, Error R and Elapsed, then the retrieved spectrum’s peak wavelength λ peak and the pulse’s FWHM. The second row shows the forward model’s extra parameters, τ₀, Thickness and Smearing, each named fit or fixed so it is clear whether the retriever was free to move it (a smearing width also carries its factor on the nominal kernel). The run counters tick every iteration; the peak wavelength and FWHM refresh with the live full-plot preview, so with that preview turned off they stay blank until the run finishes. A number that is not defined shows an en dash. The transform-limited and known FWHMs, and the peak powers once a pulse energy is set, are in the retrieved pulse’s legend.

The last three, ε(Iₜ), ε(I𝜔) and ε(E𝜔), are filled when the trace came from a synthetic or simulated session and so has a known pulse: the temporal intensity, spectral intensity and complex-field errors against it (croak.truth_metrics). They answer a different question from the Error R above them — that scores the fit to the trace, these score the distance to the true pulse, and a FROG trace does not determine the pulse uniquely, so a small R can sit on a wrong answer. Read them together: a small ε(I𝜔) with a large ε(E𝜔) means the amplitude is right and the phase is not. The two spectral ones need the truth’s complex field, so an intensity-only file shows ε(Iₜ) alone rather than a number derived from something else.

Dispersive propagation models a slab (material, thickness, Δz/Npoints — see The forward model). Geometrical smearing models the tilted-pulse-front temporal blur of a non-collinear BOXCARS setup from the mask hole diameter and edge-to-edge spacing, with the resulting delay width shown — and editable, which back-computes the spacing. Both sections grey out for solvers that cannot use them; smearing needs one of the autodiff solvers. The chromatic focal and collection settings are described in collection aperture modelling. See also geometric smearing for the reduced model.

Analyse#

Analyse reads the retrieved result. A rail on the left lists its pages; click one, or step through them with the Up and Down arrow keys:

Overview — the live overview from Retrieve, without the form beside it;
Traces — the measured and retrieved trace, log and linear;
Pulse — the retrieved pulse over the delay marginal, and the spectrum over the frequency marginal;
Diagnostics — convergence, residuals, spectral filter and spectrogram;
Dispersion and Uncertainty, described below.

Overview, Traces, Pulse and Diagnostics are the panels of plot_retrieval(), two by two so that each has room even on a laptop display. A page is redrawn when it is shown, so the spectrogram, the costliest panel, is computed only when you open Diagnostics. Each has Export ▾ with Figure… and Pop out (see Plots). The primary action on these pages, and on Dispersion, is Save: it saves the session.

Dispersion#

Apply and auto-tune residual dispersion (croak.dispersion) to compress the retrieved pulse, including real glass (built-in or custom materials), gases and a mirror stack — add rows of (mirror, polarisation, bounces, remove/add) to back-propagate (remove) beam-path coating mirrors or add chirped-mirror bounces — with the temporal profile and spectrogram updating as you drag the sliders. Enter a pulse energy (J) (shared with the measured loader) to switch the temporal plot to absolute power and read off the current and transform-limited peak power; compressing the pulse raises the peak power towards the transform-limited maximum at fixed energy. When a dispersion is set, Save session… also writes the dispersed result as result_dispersion.h5, with dispersion.pdf (see Sessions).

Uncertainty#

Put an error bar on the retrieved FWHM (croak.uncertainty). Choose the estimator (parametric or resampling bootstrap, the substrate-thickness systematic, or the fast analytic covariance), set the replicate count and confidence level, and run it with Estimate in the top bar. It runs on a worker thread; the ready line counts the replicates, and Stop in the top bar cancels the run. The page reports the point estimate with its 68 % and 95 % intervals, draws the temporal confidence band over the retrieved profile. Each estimate is kept in a list; Combine ticked adds the ticked independent ones in quadrature. Save session… appends every estimate to result.h5 and writes the figure on screen as uncertainty.pdf. See Estimating FWHM uncertainty.

Sessions#

A session is the settings of every stage — the loader, preparation, retrieval, dispersion and uncertainty choices — kept as a TOML file (croak.save.save_options() / croak.save.load_options()), with the retrieval in HDF5 (croak.save.save_result()).

Save session… (⋯ menu, File menu, or the primary action on Analyse) asks for a folder and writes into it: result.h5 (the retrieval, with any uncertainty estimates appended), options.toml (the settings) and retrieval.pdf (the twelve-panel overview, drawn by matplotlib). It also writes what Analyse holds: with a dispersion set on the Dispersion page, result_dispersion.h5 (the dispersed pulse, with its peak power when a pulse energy is set) and dispersion.pdf; with an uncertainty estimate on screen, uncertainty.pdf. It is the one way to save: no page has a Save button of its own. The session is added to Recent sessions and its folder’s name appears in the top bar. Saving needs a retrieval: before one, the GUI says so.

Open a session… (Home, ⋯ menu or File menu) or a click on a recent session reopens a saved options.toml and replays it:

The trace is reloaded with the saved loader settings and prepared with the saved preparation settings.
If a result.h5 sits beside the options.toml, its retrieval is restored from the file (croak.save.result_from_saved()) without re-running the solver — but only when it was fitted to exactly the trace the replay produced. The saved measured trace and frequency axis are compared element by element (croak.session.files.result_mismatch()).
Otherwise the retrieval is re-run, and a notice at the foot of the window says why (no saved result, an unreadable file, or a trace that differs).

A synthetic session cannot be replayed this way: the generator’s settings are not part of the saved options, so the GUI loads the settings and asks you to regenerate the trace. If the trace cannot be reloaded (a file has moved, say), the loader says why. See Saving and loading.

Retarget to new dataset… on the Retrieve form, available once a retrieval has run, points a measured session at another dataset folder with the same file names, keeps the calibration files, and replays load → prepare → retrieve with the current settings (croak.session.retarget.retarget()). Only a measured session has such a folder; for the others the status bar gives the reason instead.

Show the settings (options.toml) and Show as a Python script open a drawer on the right of the window with the session’s settings as the options.toml it would save, or as a standalone script that replays it without the GUI (croak.scripting.generate_script()). Copy puts the text on the clipboard; Close hides the drawer.

Scripting the same workflow#

A saved session runs without the GUI: croak replay options.toml replays it headlessly, and croak script options.toml writes the same Python script that Show as a Python script shows (see saving, sessions, and reproducible workflows).

Everything in the GUI maps to a few library calls — load → clean → retrieve → process → plot → save:

import croak

fd = croak.io.list_datasets("frog.h5")
lam = fd.load("wavelength") * croak.io.unit_to_si("nm")
delays = fd.load("delay") * croak.io.unit_to_si("fs")
trace = fd.load("trace")

td = croak.load_and_clean(trace, lam, delays, "shg", lam_min=730e-9, lam_max=900e-9,
                         input_unit="delay")
result = croak.retrieve_from_tracedata(td, algorithm="lbfgs", maxiters=200)
pr = croak.process_result(result, measured=td.trace)
croak.plot_retrieval(result, measured=td.trace).savefig("retrieval.png")
croak.save_result(result, "retrieval.h5", processed=pr)

The experimental-workflow tutorial walks through exactly this, end to end.