Mandacaru

Mandacaru provides a Rust scientific core with a Python interface for electronic structure and fermionic quantum simulation. Rust owns molecular HF/DFT, variational optimization, scientific buffers and numerical kernels. Python provides input values, result views, ASE integration and external service adapters. There is no Python calculation engine or execution-engine selector.

Install and run

The base package requires Python 3.14 and NumPy. Platform wheels include the native extension. Building from source also requires Rust/Cargo.

python -m pip install mandacaru

import numpy as np
from mandacaru import Geometry, Mandacaru

geometry = Geometry((1, 1), np.array([[2.5,2.5,2.13], [2.5,2.5,2.87]]), np.eye(3)*5)
with Mandacaru(method="dft", xc="pbe", grid_spacing=.35,
               resources={"threads": 2}) as calculation:
    result = calculation.run(geometry)
    print(result.optimal_energy)  # eV
    print(result.forces())       # eV/angstrom

Install mandacaru[ase] for the optional mandacaru.integrations.ase.ASECalculator adapter. Molecular calculations accept standalone geometry values and do not require ASE.

Four-index Hamiltonians are built only when explicitly requested through result.hamiltonian, Hamiltonian export or a quantum calculation. HF and screened hybrid exchange use native Cholesky factors.

Source layout

There are no Rust sources inside the Python package. No GitHub workflows are used.

Local checks

python scripts/check_architecture.py
cargo test --release --workspace
python -m pytest test/architecture
python -m sphinx -W --keep-going -b html docs/source /tmp/mandacaru-docs

Rebuild the editable extension after changing Rust:

python -m pip install --no-deps -e .

The manual describes native coverage, scientific conventions and remaining migration work. Unsupported models raise errors and do not select a Python numerical fallback.