Installation

Requirements

  • Python >= 3.11

  • ASE >= 3.23 (pulls in NumPy, SciPy, matplotlib)

  • (Optional) An MLIP backend such as MACE (.[mace]) or NVIDIA Alchemi (.[alchemi])

  • (Optional) mpi4py for MPI replica-exchange runs

From source

mcpy is not published on PyPI (the mcpy name there is an unrelated macro library) — install from the repository:

git clone https://github.com/farrisric/mcpy.git
cd mcpy
pip install -e .

Add the test extra to run the test suite (pip install -e .[test]).

Verify the installation

python -c "import mcpy, ase; print('mcpy', mcpy.__version__)"

MLIP backends

Install only the backends you intend to use. For MACE (MACECalculator / MACE_F_Calculator and the bundled examples):

pip install -e .[mace]

GPU support follows each backend’s own installation guide.

NVIDIA Alchemi backend (optional)

For GPU-native MACE evaluation, mcpy ships an optional AlchemiCalculator and AlchemiFCalculator backed by nvalchemi-toolkit. Recommended for systems with ≥500 atoms on CUDA — the repository benchmark measured a 3.08x speedup on a 586-atom GCMC run (20 steps, MACE+LBFGS vs Alchemi+FIRE, RTX 5090; see the README).

Install via the alchemi extra:

pip install -e .[alchemi]

This pulls in nvalchemi-toolkit[mace]. Requires a CUDA-enabled PyTorch build matching your driver.

Usage (drop-in replacement for MACE_F_Calculator):

from mcpy.calculators import AlchemiFCalculator

calc = AlchemiFCalculator(
    checkpoint='medium-mpa-0',
    steps=500,
    fmax=0.05,
    device='cuda',
    enable_cueq=True,
    compile_model=True,    # one-time warmup, then faster even at varying N
    dt=1.0,                # tuned default; not 0.1
)

See NVALCHEMI_NOTES.md in the repository root for tuning details and known pitfalls.

MPI for Replica Exchange

mpi4py is not pulled in automatically, since it depends on a system MPI implementation. Install it with conda before running RE-GCMC:

conda install mpi4py

Then launch a replica-exchange simulation with one MPI rank per replica:

mpirun -n <N> python examples/re_gcmc.py