Installation

Requirements

  • Python >= 3.10, < 3.14

  • Core: matplotlib, tqdm, h5py

  • Scientific (recommended): numpy >= 1.26, scipy >= 1.5

  • Quantum: qutip >= 5.1, scqubits >= 4.3

Quick install

Install the full package with all dependencies:

pip install HybridSuperQubits[full]

This installs NumPy, SciPy, QuTiP, and scqubits alongside the core package.

Minimal install

If you manage scientific dependencies separately (e.g., via conda):

pip install HybridSuperQubits

Then install numpy, scipy, matplotlib, qutip, and scqubits through your preferred package manager.

Apple Silicon (M1/M2/M3/M4)

For optimal performance on Apple Silicon Macs, scientific libraries should be installed through conda-forge to get native ARM builds:

# Option 1: Use the provided environment file
conda env create -f environment.yml
conda activate hybridsuperqubits

# Option 2: Manual setup
conda create -n hybridsuperqubits python>=3.10
conda activate hybridsuperqubits
conda install -c conda-forge numpy scipy matplotlib qutip scqubits
pip install -e . --no-deps

Note

Using pip install on Apple Silicon may pull in non-optimized x86 wheels for NumPy and SciPy, resulting in significantly slower performance.

See INSTALL_APPLE_SILICON.md for a detailed guide.

Development install

Clone the repository and install in editable mode:

git clone https://github.com/joanjcaceres/HybridSuperQubits.git
cd HybridSuperQubits
pip install -e .[full]

To run tests:

pytest tests/

Optional dependency groups

The package provides several extras for selective installation:

# Full installation (all optional dependencies)
pip install HybridSuperQubits[full]

# Core scientific computing only (NumPy + SciPy)
pip install HybridSuperQubits[scientific]

# QuTiP ecosystem (QuTiP + scqubits)
pip install HybridSuperQubits[qutip]