Installation

Requirements

AMBER requires Python 3.9 or higher and the following dependencies:

  • polars >= 0.20.0 - High-performance DataFrame library

  • numpy >= 1.20.0 - Numerical computing

  • networkx >= 2.5 - Graph and network analysis

  • matplotlib >= 3.3.0 - Plotting and visualization

  • seaborn >= 0.11.0 - Statistical data visualization

Install from PyPI

The easiest way to install AMBER is using pip:

pip install ambr

This will install AMBER and all required dependencies.

Install from Source

To install the latest development version from GitHub:

git clone https://github.com/a11to1n3/AMBER.git
cd AMBER
pip install -e .

Development Installation

For development, install with additional dependencies:

git clone https://github.com/a11to1n3/AMBER.git
cd AMBER
pip install -e ".[dev]"

This includes testing, documentation, and code quality tools.

Verify Installation

To verify that AMBER is installed correctly, run:

import ambr as am
print(am.__version__)

You should see the version number printed without any errors.

Optional Dependencies

AMBER extras (install what you need):

# CPU acceleration (Numba + SciPy) — recommended on Mac / no-CUDA machines
pip install 'ambr[perf]'

# SMAC Bayesian / multi-objective optimization (pins scikit-learn for SMAC 2.4)
pip install 'ambr[advanced]'

# Interactive example notebooks
pip install 'ambr[examples]'

# Documentation build tools
pip install 'ambr[docs]'

Other useful packages:

  • jupyter - interactive development

  • plotly - interactive visualizations

  • cupy-cuda12x - NVIDIA CUDA for model.gpu().run() and array kernels (not Apple Metal/MPS)

pip install jupyter plotly tqdm

Verify lanes after install:

import ambr as am
am.print_status()
print(am.recommend(10_000))
# Native GPU path (when CuPy + NVIDIA are present):
# results = MyVectorizedModel(...).gpu().run()

Troubleshooting

Common Issues

Import Error: If you get import errors, make sure all dependencies are installed:

pip install --upgrade polars numpy networkx matplotlib seaborn

Performance Issues: For large simulations, consider:

  • Using the latest version of Polars

  • pip install 'ambr[perf]' for Numba-accelerated scatter_add / subset writes

  • Installing numpy with accelerated BLAS libraries

  • Running on systems with sufficient RAM

  • For large-N runs on NVIDIA GPUs: same view-API model via model.gpu().run(), or ArrayKernelModel — see Going faster (lanes) (CuPy)

SMAC / advanced install: If SMAC fails with a scikit-learn DTYPE error, reinstall the pinned extra:

pip install 'ambr[advanced]'

Jupyter Setup: For interactive development with Jupyter:

pip install ipykernel
python -m ipykernel install --user

Getting Help

If you encounter issues:

  1. Check the GitHub Issues

  2. Read the documentation thoroughly

  3. Ask questions in the community forums

  4. Report bugs with minimal reproducible examples