homodyne CLI¶

Homodyne provides five command-line entry points installed into the active virtual environment.

Command	Purpose
`homodyne`	Main analysis entry point (NLSQ/CMC)
`homodyne-config`	Configuration file generation, interactive builder, and validation
`homodyne-config-xla`	XLA device count configuration per workflow mode
`homodyne-post-install`	Shell completion and alias installation
`homodyne-cleanup`	Remove shell completion files

homodyne¶

The main analysis command. Reads a YAML config file, loads the HDF5 dataset, runs NLSQ and/or CMC fitting, and writes results to the output directory.

usage: homodyne [--config CONFIG] [--method {nlsq,cmc,both}]
                [--output-dir DIR] [--nlsq-result DIR]
                [--static-mode | --laminar-flow]
                [--plot-experimental-data | --plot-simulated-data]
                [--contrast FLOAT] [--offset FLOAT]
                [--phi-angles ANGLES]
                [--verbose | --quiet]
                [--version]

Arguments¶

Argument	Description
`--config FILE`	Path to YAML configuration file (default: `homodyne_config.yaml`)
`--method {nlsq,cmc,both}`	Optimisation method. `nlsq` = trust-region NLSQ (default); `cmc` = Consensus Monte Carlo; `both` = sequential NLSQ then CMC with automatic warm-start (recommended full pipeline)
`--output-dir DIR`	Output directory for results (default: `./results`)
`--nlsq-result DIR`	Load pre-computed NLSQ warm-start from `DIR/nlsq/parameters.json`
`--static-mode`	Force static analysis mode (3 parameters: D₀, α, D_offset)
`--laminar-flow`	Force laminar-flow mode (7 parameters)
`--plot-experimental-data`	Generate data validation plots without fitting
`--plot-simulated-data`	Plot theoretical heatmaps from config parameters
`--contrast FLOAT`	Override contrast for simulated data plots
`--offset FLOAT`	Override offset for simulated data plots
`--phi-angles ANGLES`	Comma-separated phi angles for simulated plots (e.g., `"0,45,90,135"`)
`--verbose / -v`	Enable verbose (DEBUG-level) logging
`--quiet / -q`	Suppress all output except errors
`--version`	Print version and exit

Usage Examples¶

# Run NLSQ with default config
homodyne

# Run NLSQ explicitly
homodyne --method nlsq --config config.yaml --output-dir results/

# Run NLSQ then CMC in one command (recommended full pipeline)
homodyne --method both --config config.yaml --output-dir results/

# Run CMC with NLSQ warm-start (manual two-step equivalent)
homodyne --method nlsq --config config.yaml --output-dir results/
homodyne --method cmc  --config config.yaml \
         --nlsq-result results/ \
         --output-dir results/

# Force static mode
homodyne --static-mode --method nlsq

# Force laminar flow with CMC
homodyne --laminar-flow --method cmc --config config.yaml

# Validate data by plotting
homodyne --plot-experimental-data --config config.yaml

# Plot theoretical heatmaps
homodyne --plot-simulated-data --contrast 0.5 --offset 1.05 \
         --phi-angles "0,45,90,135"

Shell Aliases¶

hm          # homodyne
hm-nlsq     # homodyne --method nlsq
hm-cmc      # homodyne --method cmc
hexp        # homodyne --plot-experimental-data
hsim        # homodyne --plot-simulated-data

homodyne-config¶

Generates, validates, and interactively builds YAML configuration files.

usage: homodyne-config [-m MODE] [-o OUTPUT] [-i] [-v CONFIG] [-f]

Arguments¶

Argument	Description
`-m / --mode MODE`	Template mode: `static` or `laminar_flow`
`-o / --output FILE`	Output file path (default: `homodyne_config.yaml`)
`-i / --interactive`	Launch interactive configuration builder
`-v / --validate FILE`	Validate an existing configuration file
`-f / --force`	Overwrite existing output file without prompting

Usage Examples¶

# Generate static config template
homodyne-config --mode static --output static_config.yaml

# Generate laminar flow config
homodyne-config --mode laminar_flow --output flow_config.yaml

# Interactive builder
homodyne-config --interactive

# Validate existing config
homodyne-config --validate my_config.yaml

Shell Aliases¶

hconfig     # homodyne-config
hc-stat     # homodyne-config --mode static
hc-flow     # homodyne-config --mode laminar_flow

homodyne-config-xla¶

Configures the number of XLA virtual CPU devices used by JAX. The setting is persisted to ~/.homodyne_xla_mode and read by the shell activation scripts.

usage: homodyne-config-xla [--mode {cmc,cmc-hpc,nlsq,auto}] [--show]

Arguments¶

Argument	Description
`--mode MODE`	XLA mode: `cmc` (4 devices), `cmc-hpc` (8 devices), `nlsq` (1 device), `auto` (detect)
`--show`	Show current XLA configuration

Mode	Devices	Use Case
`cmc`	4	Standard CMC on workstations
`cmc-hpc`	8	HPC clusters with 36+ cores
`nlsq`	1	NLSQ-only workflows
`auto`	Detected	Automatic based on physical CPU core count

Usage Examples¶

# Configure for CMC on a workstation
homodyne-config-xla --mode cmc

# Configure for HPC
homodyne-config-xla --mode cmc-hpc

# Show current setting
homodyne-config-xla --show

Shell Alias¶

hxla    # homodyne-config-xla

homodyne-post-install¶

Copies the shell completion and alias system into the active virtual environment. Run once after installation to enable tab completion and aliases.

usage: homodyne-post-install [-i] [--shell {bash,zsh,fish}]
                             [--xla-mode MODE] [--advanced] [-f]

Arguments¶

Argument	Description
`-i / --install`	Perform full installation into the active venv
`--shell {bash,zsh,fish}`	Target shell (default: auto-detect)
`--xla-mode MODE`	Set XLA mode during installation (default: `cmc`)
`--advanced`	Install the full interactive configuration builder
`-f / --force`	Overwrite existing completion files

Usage Example¶

# Install completions for the current shell
homodyne-post-install -i

# Install with HPC XLA preset
homodyne-post-install -i --xla-mode cmc-hpc

# Force reinstall for zsh
homodyne-post-install -i --shell zsh --force

Shell Alias¶

hsetup    # homodyne-post-install

homodyne-cleanup¶

Removes shell completion files installed by homodyne-post-install.

usage: homodyne-cleanup [-i] [-n] [-f]

Arguments¶

Argument	Description
`-i / --install`	Actually remove files (safety flag; without it, performs a dry run)
`-n / --dry-run`	List files that would be removed without deleting them
`-f / --force`	Skip confirmation prompt

Usage Example¶

# Dry run — see what would be removed
homodyne-cleanup --dry-run

# Actually remove completion files
homodyne-cleanup -i

Shell Alias¶

hclean    # homodyne-cleanup

Shell Completion System¶

After running homodyne-post-install, the virtual environment activation script sources the appropriate completion file per shell:

Shell	Sourced File	Features
bash/zsh	`$VENV/etc/homodyne/shell/completion.sh`	Tab completion + aliases + interactive builder
fish	`$VENV/etc/homodyne/shell/completion.fish`	Native fish `complete` + aliases
fallback	`$VENV/etc/zsh/homodyne-completion.zsh`	Aliases only (no tab completion)

Full alias reference:

Alias	Expands To	Purpose
`hm`	`homodyne`	Main analysis
`hconfig`	`homodyne-config`	Config management
`hm-nlsq`	`homodyne --method nlsq`	Force NLSQ
`hm-cmc`	`homodyne --method cmc`	Force CMC
`hc-stat`	`homodyne-config --mode static`	Static config template
`hc-flow`	`homodyne-config --mode laminar_flow`	Flow config template
`hexp`	`homodyne --plot-experimental-data`	Data validation plots
`hsim`	`homodyne --plot-simulated-data`	Theory plots
`hxla`	`homodyne-config-xla`	XLA configuration
`hsetup`	`homodyne-post-install`	Shell setup
`hclean`	`homodyne-cleanup`	Remove completion files

Key source files:

runtime/shell/completion.sh — source of truth for bash/zsh completion
post_install.py — installer logic
uninstall_scripts.py — cleanup logic

Minimal CLI Entry Point for Homodyne¶

Simplified command-line interface for homodyne scattering analysis with JAX-first optimization methods.

Entry point for console script: homodyne [args]

homodyne.cli.main.main()[source]

Main CLI entry point.

Processes command-line arguments and dispatches to appropriate command handler. Uses LogConfiguration.from_cli_args() for –verbose/-v and –quiet/-q flags. Creates timestamped log file per analysis run.

Return type:: None

homodyne.cli.main.main_hexp()[source]

Entry point for hexp — plot experimental data.

Return type:: None

homodyne.cli.main.main_hsim()[source]

Entry point for hsim — plot simulated data.

Return type:: None

Argument Parser for Homodyne CLI¶

Simplified argument parsing system for the minimal CLI interface. Focuses on essential commands while maintaining compatibility.

Note: GPU support removed in v2.3.0 - CPU-only execution.

homodyne.cli.args_parser.create_parser()[source]

Create the main argument parser for Homodyne CLI.

Return type:: ArgumentParser
Returns:: Configured ArgumentParser with essential CLI options (CPU-only)

homodyne.cli.args_parser.validate_args(args)[source]

Validate parsed command-line arguments.

Parameters:: args (Namespace) – Parsed command-line arguments
Returns:: True if arguments are valid, False otherwise
Return type:: bool

Configuration Generator for Homodyne Analysis.

This module provides the homodyne-config command-line tool for: - Generating configuration files from templates - Interactive configuration building - Validating existing configurations

Usage:: homodyne-config –mode static –output config.yaml homodyne-config –interactive homodyne-config –validate my_config.yaml

homodyne.cli.config_generator.create_parser()[source]

Create argument parser for homodyne-config.

Returns:: Configured argument parser
Return type:: ArgumentParser

homodyne.cli.config_generator.get_template_path(mode)[source]

Get template file path for given mode.

Parameters:: mode (str) – Configuration mode (‘static’ or ‘laminar_flow’)
Returns:: Path to template file
Return type:: Path
Raises:: FileNotFoundError – If template file not found

homodyne.cli.config_generator.generate_config(mode, output_path, force=False, filter_mode='full')[source]

Generate configuration from template.

Parameters:

mode (str) – Configuration mode (‘static’ or ‘laminar_flow’)
output_path (Path) – Output file path
force (bool) – Force overwrite if file exists (default: False)
filter_mode (str) – Config section filter (default: “full”)

Returns:

Generated configuration dictionary

Return type:

dict[str, Any]

Raises:

FileExistsError – If output file exists and force=False
FileNotFoundError – If template not found

homodyne.cli.config_generator.interactive_builder()[source]

Interactive configuration builder.

Returns:: Built configuration dictionary
Return type:: dict[str, Any]

homodyne.cli.config_generator.validate_config(config_path)[source]

Validate configuration file.

Parameters:: config_path (Path) – Path to configuration file
Returns:: True if valid, False otherwise
Return type:: bool

homodyne.cli.config_generator.main()[source]

Main entry point for homodyne-config.

Returns:: Exit code (0 for success, 1 for error)
Return type:: int

Configure XLA_FLAGS for Homodyne optimization workflows.

homodyne.cli.xla_config.detect_optimal_devices()[source]: Detect optimal XLA device count based on CPU cores.

homodyne.cli.xla_config.set_mode(mode)[source]

Save XLA mode preference.

Return type:: bool

homodyne.cli.xla_config.show_config()[source]: Display current XLA configuration.

homodyne.cli.xla_config.main()[source]

Main entry point for homodyne-config-xla.

Return type:: None

Internal CLI Modules¶

The main homodyne command is orchestrated by dispatch_command() in commands.py, which delegates to focused submodules. These modules are not part of the public API but are documented here for contributors.

Command Dispatcher for Homodyne CLI¶

Handles command execution and coordination between CLI arguments, configuration, and optimization methods.

This module serves as the main orchestrator and re-export hub. Implementation details are in focused submodules: - config_handling: Device config, config loading, CLI overrides - data_pipeline: Data loading, t=0 exclusion, angle filtering, MCMC pooling - optimization_runner: NLSQ/CMC optimization, warm-start - result_saving: JSON/NPZ saving for NLSQ and MCMC results - plot_dispatch: Plotting dispatch for experimental/simulated data

Functions that are mock-patched by tests via @patch(“homodyne.cli.commands.X”) remain in this module to preserve test compatibility.

homodyne.cli.commands.normalize_angle_to_symmetric_range(angle)[source]

Normalize angle(s) to [-180, 180] range.

This is a wrapper that delegates to homodyne.data.angle_filtering.

Return type:: float | ndarray[tuple[Any, ...], dtype[floating[Any]]]

homodyne.cli.commands.dispatch_command(args)[source]

Dispatch command based on parsed CLI arguments.

Parameters:: args (Namespace) – Parsed command-line arguments
Returns:: Command execution result with success status and details
Return type:: dict[str, Any]

Configuration handling for Homodyne CLI.

Manages device configuration, config file loading, CLI overrides, and MCMC runtime kwargs construction.

Data loading and preparation pipeline for Homodyne CLI.

Handles experimental data loading, t=0 exclusion, angle filtering, CMC config preparation, and MCMC data pooling.

Optimization runner for Homodyne CLI.

Handles NLSQ optimization dispatch and NLSQ warm-start resolution.

Note: _run_optimization and _generate_cmc_diagnostic_plots remain in commands.py because tests mock-patch names in the commands module namespace (e.g. @patch(“homodyne.cli.commands.fit_mcmc_jax”)).

homodyne.cli.optimization_runner.load_nlsq_result_from_file(nlsq_result_path)[source]

Load pre-computed NLSQ results from a previous hm-nlsq run.

This allows CMC to use warm-start values from a previous NLSQ analysis without re-running NLSQ inline. The recommended workflow is:

Run: homodyne –method nlsq –config config.yaml –output-dir results/
Run: homodyne –method cmc –config config.yaml –nlsq-result results/

Parameters:: nlsq_result_path (Path) – Path to NLSQ results directory (should contain nlsq/parameters.json) or directly to a parameters.json file.
Returns:: Dict with ‘params’ and ‘uncertainties’ keys containing parameter values, or None if loading failed.
Return type:: dict[str, Any] | None

Result saving for Homodyne CLI.

Handles saving NLSQ and MCMC/CMC optimization results including JSON files, NPZ data, and plot generation.

homodyne.cli.result_saving.save_nlsq_results(result, data, config, output_dir)[source]

Save complete NLSQ optimization results to structured directory.

Main orchestrator function that coordinates all helper functions to save: - parameters.json: Parameter values and uncertainties - fitted_data.npz: Experimental + theoretical + residuals - analysis_results_nlsq.json: Analysis summary - convergence_metrics.json: Convergence diagnostics

Parameters:

result (Any) – NLSQ optimization result with parameters, uncertainties, chi-squared, etc.
data (dict[str, Any]) – Experimental data with phi_angles_list, c2_exp, t1, t2, wavevector_q_list
config (Any) – Configuration with analysis_mode and metadata
output_dir (Path) – Output directory (nlsq/ subdirectory will be created)

Return type:

None

homodyne.cli.result_saving.save_mcmc_results(result, data, config, output_dir)[source]

Save CMC results with comprehensive diagnostics.

Creates cmc/ directory and saves: 1. parameters.json: Posterior mean +/- std for each parameter 2. analysis_results_cmc.json: Sampling summary and diagnostics 3. samples.npz: Full posterior samples, r_hat, ess 4. diagnostics.json: Convergence metrics 5. fitted_data.npz: Experimental + theoretical data (optional) 6. c2_heatmaps_phi_*.png: Comparison plots using posterior mean 7. ArviZ diagnostic plots: pair, forest, energy, autocorr, rank, ess

Parameters:

result (Any) – CMC optimization result with posterior samples and diagnostics
data (dict[str, Any]) – Experimental data dictionary containing c2_exp, phi_angles_list, t1, t2, q
config (Any) – Configuration manager with analysis settings
output_dir (Path) – Base output directory (cmc/ subdirectory will be created)

Return type:

None

Plot dispatch for Homodyne CLI.

Handles plotting options for experimental data, simulated data, and fit comparison visualization.

homodyne.cli.plot_dispatch.generate_nlsq_plots(phi_angles, c2_exp, c2_theoretical_scaled, residuals, t1, t2, output_dir, config=None, use_datashader=True, parallel=True, *, c2_solver_scaled=None)[source]

Generate 3-panel heatmap plots for NLSQ fit visualization.

This is a wrapper that delegates to homodyne.viz.nlsq_plots.

Return type:: None