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, Qiskit, Braket and Cirq. Parquet files are read and written by the native extension and need no Python package. 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=[10, 10, 10])

atoms.center()

atoms.calc = Mandacaru(method="dft",
                       xc="pbe",
                       basis="HAO",
                       grid_spacing=0.20,
                       resources={"threads": 2})

print(atoms.get_potential_energy())  # eV
print(atoms.get_forces())            # eV/angstrom

Source layout

Location	Responsibility
Cargo.toml, Cargo.lock	Native workspace and locked dependencies
crates/mandacaru-core	Basis, models, molecular/periodic solvers, PAW and quantum algorithms
crates/mandacaru-kernels	Low-level numerical kernels
crates/mandacaru-python	PyO3 bindings and checked NumPy transfers
src/mandacaru	Python interface, workflows, result views and integrations
build_hooks/native.py	Native extension build hook
scripts	Local architectural and installation checks
docs	Sphinx manual

There are no Rust sources inside the Python package.

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.