Installation¶

Requirements¶

Package	Version	Purpose
Python	>= 3.12	Runtime (tested with 3.12.x and 3.13.x)
JAX	>= 0.8.2	JIT-compiled numerical kernels (CPU-only)
NumPy	>= 2.3	Array operations
NLSQ	>= 0.6.10	Trust-region Levenberg–Marquardt solver
NumPyro	>= 0.19	Bayesian MCMC / NUTS inference
h5py	>= 3.15	HDF5 data I/O
evosax	>= 0.2.0	CMA-ES evolutionary optimization

Install with pip¶

pip install heterodyne

Install with uv (recommended)¶

uv add heterodyne

For an editable development install:

git clone https://github.com/imewei/heterodyne.git
cd heterodyne
uv sync

Development install¶

Install with all development and documentation dependencies:

uv pip install -e ".[dev,docs]"

Or use the Makefile:

make dev

Make Targets¶

The project Makefile provides common development workflows:

Target	Description
`make dev`	Install package with development and documentation dependencies
`make test`	Run all tests
`make test-all`	Run all tests with coverage report
`make quality`	Run all quality checks (format + lint + type-check)
`make docs`	Build Sphinx documentation

Verify Installation¶

After installation, verify that the package and its dependencies are correctly configured:

heterodyne-validate

This checks that JAX, NLSQ, NumPyro, and all required dependencies are importable and reports their versions.

You can also verify from Python:

import heterodyne
print(heterodyne.__version__)

import jax
print(jax.default_backend())  # Should print "cpu"

Shell Completion¶

Run the post-install script to set up shell completions and recommended aliases:

heterodyne-post-install

This installs tab completion for Bash, Zsh, and Fish shells.

Short aliases (installed as console scripts via pip/uv):

Alias	Equivalent	Purpose
`ht`	`heterodyne`	Main CLI
`ht-config`	`heterodyne-config`	Config generator
`ht-config-xla`	`heterodyne-config-xla`	XLA flag configurator
`ht-post-install`	`heterodyne-post-install`	Post-install setup
`ht-cleanup`	`heterodyne-cleanup`	Cleanup utility
`ht-validate`	`heterodyne-validate`	System validation
`hexp`	`heterodyne --plot-experimental-data`	Plot experimental data
`hsim`	`heterodyne --plot-simulated-data`	Plot simulated C2 heatmaps

Shell aliases (added to your profile by heterodyne-post-install):

Alias	Expands to	Purpose
`het`	`heterodyne`	Main CLI
`hconfig`	`heterodyne-config`	Config generator
`het-nlsq`	`heterodyne --method nlsq`	NLSQ shortcut
`het-cmc`	`heterodyne --method cmc`	CMC shortcut
`hxla`	`heterodyne-config-xla`	XLA flag configurator
`hsetup`	`heterodyne-post-install`	Post-install setup
`hclean`	`heterodyne-cleanup`	Cleanup utility

Exit Codes¶

All CLI commands use consistent exit codes:

Code	Meaning
`0`	Success
`1`	General error (invalid arguments, missing files)
`2`	Configuration error (invalid YAML, missing required fields)
`3`	Data error (corrupt HDF5, shape mismatch, NaN detected)
`4`	Optimization error (convergence failure, numerical instability)
`255`	Unhandled exception (bug – please report)

Environment Variables¶

Variable	Description
`JAX_PLATFORMS`	Force JAX backend platform (set to `cpu` for heterodyne)
`JAX_ENABLE_X64`	Enable 64-bit floating point in JAX (`true` recommended)
`OMP_NUM_THREADS`	Control OpenMP thread count for BLAS operations
`HETERODYNE_OUTPUT_DIR`	Override default output directory for results
`HETERODYNE_DEBUG`	Enable debug-level logging (`1` to enable)

CPU Optimization¶

Heterodyne includes a dedicated XLA flag configurator that tunes JAX’s compiler for your specific CPU topology (core count, NUMA nodes, cache hierarchy):

heterodyne-config-xla

This detects your hardware and writes optimal XLA flags for thread allocation, intra-op parallelism, and memory layout. The configuration is stored in $VIRTUAL_ENV/etc/heterodyne/xla_mode (or $CONDA_PREFIX/etc/heterodyne/xla_mode in conda/mamba environments, or ~/.config/heterodyne/xla_mode outside any environment) and sourced automatically on subsequent runs.

For HPC environments with many cores (36–128+), this step is strongly recommended before running any analysis.