Installation

MANDALA supports Python 3.10–3.13 and uses PyTorch, e3nn, torch-scatter and PyTorch Lightning. The commands below create an isolated environment with the tested PyTorch 2.5.1 stack.

Requirements

Python >=3.10,<3.14
A C/C++ toolchain (only when torch-scatter has to be built from source)
Git LFS for the example electronic-structure data
Optional: an NVIDIA GPU with a CUDA 12.1 compatible driver
Optional, for building this documentation: Graphviz (dot)

Clone the repository

git clone git@github.com:Mandala-org/Mandala.git mandala
cd mandala
git lfs install
git lfs pull

git lfs pull fetches the bundled OpenMX, FHI-aims and PySCF example calculations under data/; they are used by the quickstart and the tests.

Create the environment

CPU

python3.10 -m venv mandala-venv
source mandala-venv/bin/activate
python -m pip install --upgrade pip wheel
python -m pip install torch==2.5.1 --index-url https://download.pytorch.org/whl/cpu
python -m pip install torch-scatter -f https://data.pyg.org/whl/torch-2.5.1+cpu.html --no-build-isolation
python -m pip install -e '.[dev]'

CUDA 12.1

python3.10 -m venv mandala-venv
source mandala-venv/bin/activate
python -m pip install --upgrade pip wheel
python -m pip install torch==2.5.1 --index-url https://download.pytorch.org/whl/cu121
python -m pip install torch-scatter -f https://data.pyg.org/whl/torch-2.5.1+cu121.html
python -m pip install -e '.[dev]'

Only the graph stack (torch-scatter and torch_geometric) must be selected for the exact PyTorch build and CUDA wheel tag; the remaining dependencies follow pip resolution. torch-scatter contains compiled kernels, while PyG itself can use its platform-independent wheel. PyTorch CUDA wheels supply their runtime; a local toolkit is needed only to build CUDA extensions from source. Record the driver and installed versions with each run; MANDALA writes package versions into every run manifest.

Tested environments

Setups on which MANDALA has run its test suite and a GPU training step. The list is generated from docs/data/tested_environments.json with python scripts/report/render_tested_environments.py; the JSON keeps the full records.

Working setups
Python	PyTorch	CUDA	torch-scatter	torch_geometric	NVIDIA driver
3.10	2.5.1	12.1	2.1.2	2.8.1	550.163.01
3.10	2.5.1	CPU	—	—	—
3.10	2.7.1	12.8	—	—	—
3.11	2.5.1	12.1	2.1.2	2.8.1	550.163.01
3.12	2.7.1	12.8	2.1.2	2.8.1	550.163.01
3.13	2.15.0	13.4	2.1.2	2.8.1	570.158.01 with NVIDIA cuda-compat libraries
3.13	2.7.1	12.8	2.1.2	2.8.1	550.163.01
3.14	2.11.0	12.8	2.1.2	2.8.1	550.163.01
3.14	2.15.0	13.4	2.1.2	2.8.1	570.158.01 with NVIDIA cuda-compat libraries

Notes:

Only torch-scatter (and torch_geometric) must match the exact PyTorch build and CUDA tag; everything else follows pip resolution.
CUDA 13 wheels need an NVIDIA driver of the 580 family or NVIDIA’s cuda-compat libraries on older drivers; on CUDA 12 drivers use the cu128 wheels.
Python 3.15 passes the CPU test suite, but no CUDA-enabled PyTorch wheel exists for it yet, so the package metadata stays at <3.15.

Import layout

The library lives in src/ as the top-level packages core, data, net, analysis and utils; command-line workflows live in scripts/. All commands in this documentation are run from the repository root with both directories on the import path:

export PYTHONPATH=src:.

Package	Contents
`core`	Orbital/irrep bookkeeping (`OrbitalIrrepConfig`, `BlockIrrepMapper`, `ShellTensorCodec`), basis converters, sparse trace algebra and periodic Fourier transforms.
`data`	Parsers, `Snapshot`/`BlockMatrix`/`IrrepsBlockData`, graph construction, datasets, envelopes and exporters.
`net`	`E3GNN`, the typed `FeaturePipeline`, all layers and transformations, objectives, spectral loss and checkpoint utilities.
`analysis`	Evaluation reports, density-of-states and band-structure analysis, real-space density grids and sweep analysis.
`scripts`	Training, export, evaluation and benchmarking command-line tools.

Verify the installation

The layer-cookbook certificate exercises e3nn, torch-scatter, the pipeline compiler, the orbital codec and a complete model in about twenty seconds on a laptop CPU:

PYTHONPATH=src:. python examples/layer_cookbook/verify.py

It ends with:

All cookbook layers and the cookbook model are E(3)-equivariant.

A focused selection of the scientific contract tests runs with pytest:

PYTHONPATH=src:. python -m pytest -q \
  tests/physics/test_o3_model_contracts.py \
  tests/unit/net/test_hybrid_pipelines.py

Test markers select test families (unit, physics, equivariance, workflow, integration, slow, gpu, large_data). GPU tests run when MANDALA_RUN_GPU_TESTS=1 is set, large-data tests when MANDALA_LARGE_DATA_ROOT points to the corresponding datasets.

Build this documentation

The documentation is built inside the MANDALA environment, because the API pages and the generated references import the package. With the environment active (and Graphviz’s dot on the path for the diagrams):

python -m pip install sphinx sphinx-rtd-theme
PYTHONPATH=src:. python -m sphinx -b html docs docs/_build/html

The configuration reference, the irrep atlas and the transformation catalogue are generated from the source code during the build, so they always describe the installed version.