Skip to content

Install

Get Mandacaru 26.9.33

MIT licensed. pip install mandacaru gets a released version; from source is what you want if you intend to change anything or compile the C integral backend yourself.

Requirements

  • Python 3.14 or newer
  • A C compiler with OpenMP support (GCC or Clang)
  • CMake 3.15 or newer, to compile the integral backend
  • pip

Install, then build the C backend

Pick pip or an editable checkout — not both. The C backend step is optional either way: everything still runs on the NumPy fallback without it, just without OpenMP parallelism.

  1. Install from PyPI

    $ pip install mandacaru

  2. Or install from source, editable

    $ git clone https://github.com/seixas-research/mandacaru.git $ cd mandacaru $ pip install -e .

  3. Link the PAW datasets (only for basis="PAW")

    # kept in their own repository because of their size $ git clone https://github.com/seixas-research/mandacaru-paw.git $ mandacaru --link-paw mandacaru-paw

  4. Compile the C integral backend (recommended)

    # macOS — requires Homebrew libomp $ cd src/mandacaru/integrals/csrc $ cmake -S . -B build -DCMAKE_BUILD_TYPE=Release -DOpenMP_ROOT=$(brew --prefix libomp) $ cmake --build build

A calculation is a Python script, not a command line: it builds an ASE Atoms object, attaches a Mandacaru, and calls get_total_energy() or get_potential_energy(). The mandacaru command exists for the jobs that sit outside a run — linking a pseudopotential library, as above, and --dry-run to size a system's qubit register.

Confirm the C backend compiled

HAS_C_BACKEND is False until the CMake step above succeeds — everything still runs, on the pure-NumPy fallback, just without OpenMP parallelism.

$ python -c "from mandacaru.integrals import HAS_C_BACKEND; print(HAS_C_BACKEND)"

True means libmandacaru_integrals loaded; False means every integral routes through the slower NumPy path in _backend.py.

Running the test suite

1358 tests cover integrals, basis definitions, operators, the Hartree–Fock solvers, VQE/ADAPT-VQE, the analytic forces, wavefunction checkpoints and QPE, the particle-number sector, the dry run, the Hamiltonian cache, backend-provider equivalence and the Braket and IBM Quantum measurement paths.

# from the project root $ pytest

Compiling the C backend first (previous step) is optional for this — the suite falls back to the NumPy integral path automatically when it isn't built.

Stuck on something?

The installation guide on Read the Docs covers the same ground in more detail, including platform-specific notes for the CMake step.

Documentation