CLI¶

Command-line interface entry points, analysis commands, configuration generation, XLA flag setup, optimization orchestration, and data pipeline management.

Entry Points¶

The following commands are registered as console scripts:

Command	Short alias	Purpose
`heterodyne`	`ht`	Main analysis (NLSQ/CMC)
`heterodyne-config`	`ht-config`	Config generation/validation
`heterodyne-config-xla`	`ht-config-xla`	XLA device configuration
`heterodyne-post-install`	`ht-post-install`	Shell completion setup
`heterodyne-cleanup`	`ht-cleanup`	Remove shell completion files
`heterodyne-validate`	`ht-validate`	System validation
`hexp`	—	Plot experimental data (skip optimization)
`hsim`	—	Plot simulated C2 heatmaps from config parameters

Plotting Commands¶

hexp and hsim are standalone plotting entry points that bypass optimization entirely:

# Inspect experimental data for quality checking
hexp --config config.yaml

# Preview simulated C2 heatmaps with custom scaling
hsim --config config.yaml --contrast 0.3 --offset-sim 1.0

These are equivalent to passing --plot-experimental-data or --plot-simulated-data to the main heterodyne command.

Main Module¶

Main entry point for heterodyne CLI.

heterodyne.cli.main.main(argv=None)[source]

Main entry point for heterodyne CLI.

Parameters:: argv (list[str] | None) – Command-line arguments (default: sys.argv[1:])
Return type:: int
Returns:: Exit code (0 for success)

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

Entry point for hexp — plot experimental data.

Return type:: int

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

Entry point for hsim — plot simulated data.

Return type:: int

Commands¶

Command dispatch for heterodyne CLI.

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

Dispatch to appropriate analysis command.

Supports --plot-only (skip optimisation, generate plots from existing results) and --simulate-only (skip optimisation, save simulated data from the configured model).

Parameters:: args (Namespace) – Parsed command-line arguments.
Return type:: int
Returns:: Exit code (0 on success).

Config Generator¶

Configuration file generator for heterodyne analysis.

heterodyne.cli.config_generator.get_template_path()[source]

Get path to master template file.

Return type:: Path
Returns:: Path to template YAML

heterodyne.cli.config_generator.generate_config(output_path, data_path=None, q=None, dt=None, time_length=None, overwrite=False, mode='full')[source]

Generate configuration file from template.

Parameters:

output_path (Path | str) – Output path for configuration
data_path (str | None) – Path to experimental data file
q (float | None) – Wavevector value
dt (float | None) – Time step
time_length (int | None) – Number of time points
overwrite (bool) – Whether to overwrite existing file
mode (str) – Template mode — “full” (all sections), “minimal” (data+temporal+ scattering only), “nlsq_only” (NLSQ without CMC), or “cmc_only” (CMC without NLSQ).

Return type:

Path

Returns:

Path to generated config

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

CLI entry point for config generator.

Return type:: None

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

Build a configuration dict interactively via sequential prompts.

Return type:: dict[str, Any]
Returns:: Complete configuration dictionary matching the expected schema.

heterodyne.cli.config_generator.validate_config(path)[source]

Validate an existing YAML configuration file.

Loads the file, runs schema validation via validate_config_schema(), and attempts to load it into ConfigManager to catch structural issues.

Parameters:: path (Path | str) – Path to the YAML configuration file.
Return type:: bool
Returns:: True if the configuration is valid, False otherwise.

XLA Configuration¶

XLA configuration for JAX on CPU.

heterodyne.cli.xla_config.configure_xla(num_threads=None, disable_jit=False, enable_x64=True)[source]

Configure XLA/JAX environment variables for CPU execution.

MUST be called before importing JAX.

Parameters:

num_threads (int | None) – Number of CPU threads (None for auto)
disable_jit (bool) – Disable JIT compilation (for debugging)
enable_x64 (bool) – Enable 64-bit float precision

Return type:

dict[str, str]

Returns:

Dict of environment variables that were set

heterodyne.cli.xla_config.get_cpu_info()[source]

Get CPU information for configuration.

Return type:: dict[str, int | str]
Returns:: Dict with cpu_count, physical_cores, etc.

heterodyne.cli.xla_config.auto_configure()[source]

Automatically configure XLA based on system resources.

Return type:: dict[str, str]
Returns:: Dict of environment variables set

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

CLI entry point for XLA configuration.

Return type:: None

Optimization Runner¶

Optimization execution for heterodyne CLI.

Manages NLSQ and CMC fitting runs, including warm-start resolution.

heterodyne.cli.optimization_runner.run_nlsq(model, c2_data, phi_angles, config_manager, args, output_dir, summary=None, data_phi_angles=None)[source]

Run NLSQ analysis for all phi angles.

Parameters:

model (HeterodyneModel) – Configured HeterodyneModel.
c2_data (ndarray) – Correlation data (2D or 3D).
phi_angles (list[float]) – Phi angles to analyze.
config_manager (ConfigManager) – Configuration manager.
args (Namespace) – CLI arguments.
output_dir (Path) – Output directory for results.
summary (AnalysisSummaryLogger | None) – Optional summary logger for phase tracking.

Return type:

list[NLSQResult]

Returns:

List of NLSQResult objects, one per phi angle.

heterodyne.cli.optimization_runner.run_cmc(model, c2_data, phi_angles, config_manager, args, output_dir, nlsq_results=None, summary=None, data_phi_angles=None)[source]

Run CMC Bayesian analysis for all phi angles.

Parameters:

model (HeterodyneModel) – Configured HeterodyneModel.
c2_data (ndarray) – Correlation data.
phi_angles (list[float]) – Phi angles to analyze.
config_manager (ConfigManager) – Configuration manager.
args (Namespace) – CLI arguments.
output_dir (Path) – Output directory.
nlsq_results (list[NLSQResult] | None) – Optional NLSQ results for warm-starting.
summary (AnalysisSummaryLogger | None) – Optional summary logger for phase tracking.

Return type:

CMCResult

Returns:

Joint multi-phi CMCResult (homodyne parity). Reflects ONE NUTS inference across all phi angles with shared 14 physics params and per-angle scaling in mean_contrast / std_contrast / mean_offset / std_offset arrays of length n_phi.

heterodyne.cli.optimization_runner.resolve_nlsq_warmstart(args, output_dir)[source]

Attempt to load previously saved NLSQ results for warm-starting CMC.

Parameters:

args (Namespace) – CLI arguments (--nlsq-result PATH stored as args.nlsq_result; legacy args.warmstart_path accepted).
output_dir (Path) – Default directory to search for NLSQ results.

Return type:

NLSQResult | None

Returns:

NLSQResult if found, None otherwise.

Data Pipeline¶

Data loading and validation pipeline for heterodyne CLI.

heterodyne.cli.data_pipeline.load_and_validate_data(config_manager)[source]

Load and validate XPCS experimental data.

Parameters:: config_manager (ConfigManager) – Configuration with data file path.
Return type:: XPCSData
Returns:: Validated XPCSData object.
Raises:: ValueError – If data validation fails with errors.

heterodyne.cli.data_pipeline.resolve_phi_angles(args, config_manager, data_phi_angles=None)[source]

Determine phi angles from CLI args or configuration.

Priority: CLI –phi > config scattering.phi_angles > phi_filtering > default [0.0].

Parameters:

args (Namespace) – Parsed CLI arguments (may have .phi attribute).
config_manager (ConfigManager) – Configuration manager.
data_phi_angles (ndarray | None) – Actual phi angles present in the loaded data (for phi_filtering). When provided, phi_filtering.target_ranges is applied against these angles instead of falling back to [0.0].

Return type:

list[float]

Returns:

List of phi angles in degrees.

heterodyne.cli.data_pipeline.prepare_cmc_data(data, phi_angles)[source]

Prepare data for CMC analysis.

Extracts and organizes correlation data for each phi angle.

Parameters:

data (Any) – XPCSData object with correlation matrices.
phi_angles (list[float]) – List of phi angles to process.

Return type:

dict[str, Any]

Returns:

Dictionary with prepared data keyed by purpose.