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

Mandacaru requires Python 3.14 and installs its scientific Python stack and quantum SDK integrations, including ASE, SciPy, Matplotlib, Parquet support, Qiskit, Braket and Cirq. Platform wheels include the native extension. Building from source also requires Rust/Cargo.

python -m pip install mandacaru

from ase import Atoms
from mandacaru import Mandacaru

atoms = Atoms("H2", positions=[[0, 0, 0], [0, 0, 0.74]], cell=[5, 5, 5])
atoms.center()
with Mandacaru(method="dft", xc="pbe", basis="HAO", grid_spacing=.35,
               resources={"threads": 2}) as calculation:
    atoms.calc = calculation
    print(atoms.get_potential_energy())  # eV
    print(atoms.get_forces())            # eV/angstrom

Attach the calculator directly with atoms.calc = Mandacaru(...) for ASE calculations. Standalone geometry values are also accepted. Required integration packages are imported only by the Python features that use them.

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.