Installation Guide

System Requirements

• Python: 3.12 or higher

• Operating System: Windows, macOS, or Linux

• Storage: ~500MB for full installation with dependencies

Quick Installation (Recommended)

The easiest way to install the Homodyne Analysis package is from PyPI using pip:

Basic Installation

pip install homodyne-analysis

This installs the core dependencies (numpy, scipy, matplotlib) along with the main package.

Full Installation with All Features

pip install homodyne-analysis[all]

Optional Installation Extras

You can install specific feature sets using pip extras:

For Enhanced Performance (Numba JIT acceleration):

pip install homodyne-analysis[performance]

For Robust Optimization (Noise-Resistant Methods):

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

For XPCS Data Handling:

pip install homodyne-analysis[data]

For Documentation Building:

pip install homodyne-analysis[docs]

For Development:

pip install homodyne-analysis[dev]

For Gurobi Optimization (Requires License):

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

For Shell Tab Completion:

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

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

For Security and Code Quality Tools:

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

Enhanced Shell Experience:

The completion system provides multiple interaction methods:

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

• Help reference: homodyne_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     # homodyne --method classical --verbose
homodyne_help    # Show all options and current config files

All Dependencies:

pip install homodyne-analysis[all]

Development Installation

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

Step 1: Clone the Repository

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

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 homodyne
print(f"Homodyne version: {homodyne.__version__}")

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

Common Issues

Import Errors:

If you encounter import errors, try reinstalling the package:

pip install --upgrade homodyne-analysis

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

Performance Issues:

For optimal performance, install the performance extras:

pip install homodyne-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 homodyne-analysis  # Correct package name
# NOT: pip install homodyne    # 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