Installation Guide

System Requirements

  • Python: 3.12 or higher

  • Operating System: Windows, macOS, or Linux

  • Storage: ~500MB for full installation with dependencies

Optional Installation Extras

You can install specific feature sets using pip extras:

For Enhanced Performance (Numba JIT acceleration):

pip install heterodyne-analysis[performance]

For Robust Optimization (Noise-Resistant Methods):

pip install heterodyne-analysis[robust]
# Includes CVXPY for distributionally robust optimization

For XPCS Data Handling:

pip install heterodyne-analysis[data]

For Documentation Building:

pip install heterodyne-analysis[docs]

For Development:

pip install heterodyne-analysis[dev]

For Gurobi Optimization (Requires License):

pip install heterodyne-analysis[gurobi]
# or manually: pip install gurobipy

For Shell Tab Completion:

pip install heterodyne-analysis[completion]
# Then install completion for your shell:
heterodyne --install-completion bash  # or zsh, fish, powershell

# To remove completion later:
heterodyne --uninstall-completion bash  # or zsh, fish, powershell

For Security and Code Quality Tools:

pip install heterodyne-analysis[quality]
# Includes black, isort, flake8, mypy, ruff, bandit, pip-audit

Enhanced Shell Experience:

The completion system provides multiple interaction methods:

  • Tab completion: heterodyne --method <TAB> shows available options

  • Help reference: heterodyne_help shows all available options and current config files

# After installation, restart shell or reload config
source ~/.zshrc  # or ~/.bashrc for bash

# Test shortcuts (always work even if tab completion fails)
hc --verbose     # heterodyne --method classical --verbose
heterodyne_help    # Show all options and current config files

All Dependencies:

pip install heterodyne-analysis[all]

Development Installation

For development, contributing, or accessing the latest unreleased features:

Step 1: Clone the Repository

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

Step 2: Install in Development Mode

# Install with all development dependencies
pip install -e .[all]

# Or install minimal development setup
pip install -e .[dev]

Verification

Test your installation:

import heterodyne
print(f"Heterodyne version: {heterodyne.__version__}")

# Test basic functionality
from heterodyne import ConfigManager
config = ConfigManager()
print("✅ Installation successful!")

Common Issues

Import Errors:

If you encounter import errors, try reinstalling the package:

pip install --upgrade heterodyne-analysis

# Or with all dependencies
pip install --upgrade heterodyne-analysis[all]

Performance Issues:

For optimal performance, install the performance extras:

pip install heterodyne-analysis[performance]
python -c "import numba; print(f'Numba version: {numba.__version__}')"

Gurobi License Issues:

Gurobi optimization requires a valid license. For academic users, free licenses are available:

# Install Gurobi
pip install gurobipy

# Verify license (should not raise errors)
python -c "import gurobipy as gp; m = gp.Model(); print('✅ Gurobi license valid')"

For licensing help, visit Gurobi Academic Licenses.

Package Not Found:

If pip cannot find the package, ensure you’re using the correct name:

pip install heterodyne-analysis  # Correct package name
# NOT: pip install heterodyne    # This won't work

Getting Help

If you encounter installation issues:

  1. Check the troubleshooting guide

  2. Search existing GitHub issues

  3. Create a new issue with your system details and error messages