Skip to content

feat: add MACE interface#224

Open
FelyCZ wants to merge 13 commits intoPHOTOX:masterfrom
FelyCZ:feat/add-mace
Open

feat: add MACE interface#224
FelyCZ wants to merge 13 commits intoPHOTOX:masterfrom
FelyCZ:feat/add-mace

Conversation

@FelyCZ
Copy link

@FelyCZ FelyCZ commented Mar 7, 2026

Add MACE Interface via MPI

Description

This PR adds a new interface for the MACE (Machine Learning Atomic Cluster Expansion) potential to ABIN. MACE is integrated via an MPI-based client-server architecture: a Python server loads and evaluates the MACE ML model, while the Fortran side communicates coordinates, energies, and forces over MPI. This follows the same pattern used for the existing TeraChem (_tera_) interface.

The interface supports configurable model paths, device selection (CPU/CUDA), precision settings, and various MACE-specific options -- all controlled through a new &mace namelist in the ABIN input file.


File Changes

Fortran Core

File Description
src/mace_mpi_api.F90 [NEW] Core MPI API module (mod_mace_mpi). Handles MPI port connection to the Python server, sends atom types/config/coordinates, and defines all MACE namelist variables (model path, device, dtype, batch size, etc.).
src/force_mace.F90 [NEW] Force driver module (mod_force_mace). Orchestrates per-bead force evaluation -- sends coordinates via send_mace, receives energy and forces via receive_mace. Supports OpenMP.
src/forces.F90 Added _mace_ case to the force_wrapper potential selector, routing to force_mace().
src/init.F90 Added &mace namelist reading and MACE interface/server initialization when pot='_mace_'.
src/mpi_wrapper.F90 Added _mace_ to the MPI-required potential check so non-MPI builds raise a clear error.
src/Makefile Added mace_mpi_api.o and force_mace.o to the build.

Python Server

File Description
interfaces/MACE/mace_server.py [NEW] MACE MPI server. Opens MPI port, accepts connection from ABIN, receives configuration and atom data, loads the MACE model, and returns energies/forces each step. Handles unit conversions (Bohr <-> Å, Hartree <-> eV) and supports foundation model auto-download.
interfaces/MACE/README.md [NEW] Documentation covering requirements, manual/automatic launch instructions, and a full configuration reference table for all &mace namelist parameters. Includes MACE-OFF licensing notice.
interfaces/MACE/MACE-OFF23_medium.model [NEW] Bundled pre-trained MACE-OFF23 medium model (~18 MB) for out-of-the-box usage. Licensing notice is included in the README.

Tests

File Description
tests/MACE/test.sh [NEW] Integration test script. Launches the mock MACE server and ABIN via MPI, runs a short MD simulation, and validates output against reference files.
tests/MACE/mock_mace_server.py [NEW] Mock MACE server for testing. Implements the same MPI protocol as the real server but returns forces from a simple harmonic potential, avoiding the need for mace-torch/PyTorch.
tests/MACE/input.in [NEW] Test input file with pot='_mace_' and &mace namelist.
tests/MACE/mini.xyz [NEW] Test geometry (water molecule).
tests/MACE/*.ref [NEW] Reference output files (energies.dat.ref, forces.xyz.ref, movie.xyz.ref, velocities.xyz.ref, temper.dat.ref).
tests/test.sh Registered MACE in the MPI test folder list.
unit_tests/test_mace.pf [NEW] pFUnit tests verifying default namelist values, MPI tag constants, and non-MPI error handling.
unit_tests/Makefile Added mace target to the unit test build, test runner, and clean targets.

Utilities & Docs

File Description
utils/run.mace_mpi_abin.sh [NEW] Launch script that starts both the MACE Python server and ABIN, connects them via MPI, and monitors both processes with automatic cleanup.
dev_scripts/install_mace.sh [NEW] Convenience script to clone the MACE repo and install dependencies (mace-torch, mpi4py).
sample_inputs/input.in.mace [NEW] Sample input file demonstrating &mace namelist configuration.
README.md Added MACE to the list of optional libraries with a brief description and install reference.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant