API reference

Reference to croak’s physics, retrieval and workflow interfaces, generated from NumPy-style docstrings. The pages group the package by role; the quickstart and user guide show these APIs in context. The examples provide runnable calculations, and the developer’s guide explains how to contribute to the package.

The headline API is importable from the top-level croak namespace (e.g. croak.Grid, croak.retrieve, croak.load_and_clean); the submodules (croak.maths, croak.materials, croak.metrics, …) are also exposed directly. The individual solver classes are normally selected by name through croak.retrieve() rather than imported — the registry croak.retrieve.ALGORITHMS maps each algorithm string to its class.

Terms used throughout the manual are defined in the glossary, and the papers and published methods behind croak are listed in the references. Units, sign conventions and the FFT convention are collected under conventions.

• Core physics
  • Grid and transforms
  • Pulses
  • Interactions
  • Forward model
  • Geometric smearing
  • Chromatic focal mixture
  • Collection aperture
  • Materials
  • Gases
  • Maths utilities
  • Constants
• Retrieval
  • The retrieve wrapper
  • Solver base
  • COPRA
  • COPRA (JAX)
  • L-BFGS (analytic gradients)
  • L-BFGS (hand-gradient JAX)
  • L-BFGS (autodiff)
  • L-BFGS (Optimistix)
  • Levenberg–Marquardt
  • Levenberg–Marquardt (Optimistix)
  • CMA-ES (global)
  • Warm-started L-BFGS
  • Result
  • Progress reporting
  • Metrics
  • Delay-origin convention
• Workflow
  • I/O
  • Preprocessing
  • Pipeline
  • Processing
  • Known-truth errors
  • Marginal consistency checks
  • Dispersion tuning
  • Mirrors
  • Saving and loading
  • Uncertainty analysis
  • Sessions (headless replay)
  • Command line and script generation
• Plotting
  • PlotScale
  • FULL_SCALE
  • FONT_SCALE_MIN
  • FONT_SCALE_STEP
  • COMPACT_BELOW
  • plot_scale()
  • scaled_rc()
  • cmap_white()
  • cmap_negwhite()
  • signed_pcolormesh()
  • si_power()
  • sig3()
  • plot_residual()
  • plot_temporal()
  • plot_spectral()
  • SPECTRAL_AXES
  • EDGE_ENERGY_WARN
  • plot_convergence()
  • plot_marginal()
  • plot_spectrogram()
  • plot_retrieval()
  • RetrievalPlotData
  • retrieval_plot_data()
  • TraceArtists
  • ResidualArtists
  • TemporalArtists
  • SpectralArtists
  • ConvergenceArtists
  • LineArtists
  • MarginalArtists
  • SpectrogramArtists
  • PanelSpec
  • PageSpec
  • ColorbarSpec
  • RETRIEVAL_PANELS
  • RETRIEVAL_COLORBARS
  • RETRIEVAL_PAGES
  • RETRIEVAL_OVERVIEW
  • plot_retrieval_page()
  • draw_measured_log()
  • draw_retrieved_log()
  • draw_measured_lin()
  • draw_retrieved_lin()
  • draw_temporal()
  • draw_spectral()
  • draw_convergence()
  • draw_residual()
  • draw_spectral_filter()
  • draw_freq_marginal()
  • draw_delay_marginal()
  • draw_spectrogram()
  • update_measured_log()
  • update_retrieved_log()
  • update_measured_lin()
  • update_retrieved_lin()
  • update_temporal()
  • update_spectral()
  • update_convergence()
  • update_convergence_curve()
  • update_residual()
  • update_spectral_filter()
  • update_freq_marginal()
  • update_delay_marginal()
  • update_spectrogram()
  • RetrievalPageView
  • plot_frog_filter()
  • filter_view_vmax()
  • FrogFilterView
  • plot_simulated_trace()
  • plot_fwhm_distribution()
  • plot_intensity_band()
  • plot_uncertainty()
• JAX backend
  • JAX forward model
  • JAX metrics
  • JAX pulse parameterisation

Map of the package

Area	Modules
Core physics	grid, pulses, interactions, forward, smearing, focal, collection, materials, gases, maths, constants
Retrieval	retrieve, solver, copra, copra_jax, lbfgs, lbfgs_hand, lbfgs_ad, optimistix_lbfgs, lm, optimistix_lm, cmaes, warm_lbfgs, result, progress, metrics, delay_origin
Workflow	io, preprocess, pipeline, processing, truth_metrics, marginal_checks, dispersion, mirrors, save, uncertainty, covariance, engine, cli, scripting
Plotting	plotting
JAX backend	forward_jax, metrics_jax, _jax_pulse