Package architecture#
The package separates the physical model, retrieval, and measurement workflow. The GUI calls the workflow layer; scripts and saved sessions can use that layer without opening a window.
Area |
Main responsibilities |
Reference |
|---|---|---|
Core physics |
Grids, transforms, pulse construction, interactions, propagation, focusing, and collection |
|
Retrieval |
Solver selection, objectives, optimisation, progress, and result assembly |
|
Workflow |
Loading, preprocessing, post-processing, uncertainty, persistence, and session replay |
|
Plotting |
Plot data, matplotlib figures, and the Qt-free screen views the GUI draws |
|
JAX calculations |
Differentiable forward models, residuals, and pulse parameterisation |
|
GUI |
The PySide6 window: Home, the stages, worker threads, and pyqtgraph views |
Keep physical calculations independent of GUI state and file I/O. Prefer the shared workflow operations when adding a command or GUI control so that the same settings retain the same meaning in scripts and saved sessions.
The GUI#
The GUI (croak.gui, the gui extra) sits on two Qt-free layers. The session
layer, croak.session, holds every setting as parameter dataclasses, maps each
stage onto the library, replays a saved session and writes a session’s files;
the GUI, croak replay and croak script all go through it. The screen layer,
croak.plotting.screen, turns the data behind a figure into the arrays an
interactive view draws, using the same helpers as the matplotlib panels, so
the screen and an exported figure agree; croak.plotting.export draws any
screen view as a matplotlib figure, for the GUI’s figure export.
On top of them, croak.gui.window.MainWindow takes a session from Home through
Data, Check, Prepare, Retrieve and Analyse. The route between the stages is a set of
pure rules (croak.gui.workflow); each stage is a page that binds its controls
to the session’s parameters and hands long computations to worker threads; and
every on-screen plot is a pyqtgraph view of screen data. Numerics belong in the
library and the two layers beneath, not in croak.gui. GUI and session integration describes the
modules and their contracts, and GUI design the look and layout
rules.
The forward-model chapter explains the physics; retrieval and numerical methods explains the objectives and derivatives.