Installation#

croak requires Python 3.14 or later. Use uv to manage Python and the package environment. If you want to use croak without writing Python, follow Installing the GUI first.

From PyPI (recommended)#

For a new analysis project, install uv using its installation instructions, then run:

uv init --python 3.14 pulse-retrieval
cd pulse-retrieval
uv add croak

In an existing uv project using Python 3.14 or later, run uv add croak. Save the Quickstart calculation in a file such as my_retrieval.py, then run it inside the project environment:

uv run python my_retrieval.py

To include the graphical interface in this project, use uv add "croak[gui]" and launch it with uv run croak-gui. The separate GUI installation uses a uv tool environment for a command available outside a particular project.

Into an existing environment, use uv pip install croak or plain pip install croak with a Python 3.14 interpreter (see the note below). uv tool upgrade croak updates a GUI tool installation later.

Python 3.14 is a hard requirement

croak’s source uses syntax introduced in Python 3.14 (for example unparenthesised except A, B: clauses), so it does not even parse on 3.13. A plain pip install with an older interpreter fails with an opaque dependency-resolution error rather than a clear message, so check python --version first, or let uv provide the interpreter (uv python install 3.14).

From a clone (development and examples)#

The repository includes the example scripts and the bundled reduced simulation datasets used in the gallery. They are not installed with the Python package. To run them:

git clone https://github.com/LupoLab/croak
cd croak
uv sync
uv run python examples/example_retrieval.py

uv sync creates the project environment and installs its declared dependencies. To use a plain virtual environment instead, run python3.14 -m venv .venv, activate it, then pip install -e .. For work on croak itself, continue with the development environment.

Supported platforms#

croak’s binary dependencies (jax, nlopt, finufft and, for the GUI, pyqt6) publish wheels for a limited set of platforms. Where a wheel is missing, the installer falls back to building from source, which needs CMake and a C++ toolchain.

Platform	Status
Linux x86_64, glibc ≥ 2.34 (Ubuntu 22.04+, RHEL 9+)	supported
macOS on Apple Silicon, macOS ≥ 14	supported
Windows x86_64	supported
macOS on Intel	not supported: there is no current `jaxlib` wheel
Linux aarch64	works; `nlopt` and `finufft` build from source

Linux: Qt system libraries#

The GUI needs Qt’s system libraries, which neither uv nor pip installs. On Debian/Ubuntu, this is the list the project’s CI installs:

sudo apt-get install -y libegl1 libgl1 libxkbcommon-x11-0 libdbus-1-3 \
  libxcb-icccm4 libxcb-image0 libxcb-keysyms1 libxcb-randr0 \
  libxcb-render-util0 libxcb-shape0 libxcb-xinerama0 libxcb-cursor0

Other distributions use different package names. On a headless machine, run under xvfb-run -a with Xvfb installed, or set QT_QPA_PLATFORM=offscreen. Scripting retrievals does not require Qt or a display server.

JAX and GPUs#

The default installation runs JAX on the CPU on every platform, which suits the standard and extended forward models. The full focal model is the one that benefits from a GPU: measured on an NVIDIA H200 it ran about 60× faster than an Intel Xeon Gold 6240 (all cores), with identical results. For small retrievals, compilation and transfer costs can make a GPU no faster than the CPU. croak needs no code changes to use a GPU; installing a CUDA-enabled JAX build is the whole job. On Linux x86_64 with an NVIDIA driver, the jax[cuda12] extra bundles the CUDA libraries, so no system CUDA toolkit is needed:

In a uv project that uses croak:
```
uv add "jax[cuda12]"
```
In a croak checkout, either add it to the project (uv add "jax[cuda12]", which edits pyproject.toml; keep that on a machine-local branch) or inject it into the synced environment with uv pip install "jax[cuda12]". The second form is undone by the next uv sync.
In the GUI tool installation, add it at install time (with --force to convert an existing CPU-only installation):
```
uv tool install --python 3.14 "croak[gui]" --with "jax[cuda12]"
```
With plain pip: pip install "jax[cuda12]" into the same environment.

Check the result with:

uv run python -c "import jax; print(jax.devices())"

The output should list a CUDA device. If it lists only a CPU, check that nvidia-smi works and that the command ran in the environment you installed into. Choose a CUDA extra compatible with your driver; JAX also provides a CUDA 13 extra, and its installation instructions list current driver and hardware requirements.

Dependencies#

Purpose	Packages
Numerics	`numpy`, `scipy`, `jax`, `nlopt`, `optimistix`, `lineax`
Delay filtering	`finufft`
Data and sessions	`h5py`, `tomli-w`
Plotting and progress	`matplotlib`, `tqdm`
GUI (`gui` extra)	`pyqt6`, `superqt`

Importing croak does not import Qt. The library and session replay work without the graphical interface.

Optional features#

In an analysis project, choose the extras you need:

uv add "croak[gui]"          # graphical interface
uv add "croak[evo]"          # CMA-ES retrieval

Extras can be combined, for example uv add "croak[gui,evo]". In a source checkout, use uv sync --extra gui --extra evo instead.

The evo extra installs evosax for CMA-ES retrieval; evosax brings in flax, optax and orbax, so it is not a small addition. Neither extra is required for the introductory tutorials.

Development and docs groups#

Development checks and documentation builds use dependency groups in a source checkout. Follow the developer’s guide and documentation build instructions.

Verifying the install#

uv run python -c "import croak; print(croak.__version__)"

Then follow the Quickstart, or run the bundled example above from a checkout. Continue with functionality and capabilities to decide which measurement model and interface fit your experiment.