feat: add MACE interface

[FelyCZ]

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.

[danielhollas]

@FelyCZ this is super exciting, thanks! Is this PR ready for review?
cc @JanosJiri probably you could do first rounds of review in case you haven't already?

[FelyCZ]

Hi @danielhollas,
Yes, it's ready for review. I just don't have the necessary permissions to request this in the PR.

I have tested the code on a local machine (WSL Ubuntu 22.04.5 LTS) and it yielded no problems.

[danielhollas]

Perfect, thanks! I just gave you Triage permissions to the repo which should give you enough rights to ask for review and run tests on GitHub (I think). I'll leave it up to @JanosJiri regarding the level of permissions that you should have (perhaps you should be a member of the PHOTOX Dev Team which has write permissions to this repo?).

Thanks for adding unit tests! One of them is failing though, can you take a look?
https://github.com/PHOTOX/ABIN/actions/runs/22808780618/job/67410107594?pr=224

The build failure of GFortran 9 is unrelated to these changes so don't worry about it, I'll fix that separately before we merge this.

Can you also please run the autoformatter? https://github.com/PHOTOX/ABIN/blob/master/CONTRIBUTING.md#code-formatting

Once the format and test pass on GitHub please ping me for review, thanks!

[FelyCZ]

Thanks for the Triage role!
I think this is enough for me, I don't need to have write permissions. :)

I've fixed the unit test and run the autoformat script. The actions are passing now.

[JanosJiri]

cc @JanosJiri probably you could do first rounds of review in case you haven't already?

I could have a look, but I won't be able to get to it for quite some time. Sorry, I'm just overwhelmed with my thesis and finishing all papers before I leave the group. Also, I have very limited knowledge of MPI, so I won't be able to review it reliably (at least now).

Perfect, thanks! I just gave you Triage permissions to the repo, which should give you enough rights to ask for review and run tests on GitHub (I think). I'll leave it up to @JanosJiri regarding the level of permissions that you should have (perhaps you should be a member of the PHOTOX Dev Team which has write permissions to this repo?).

@FelyCZ, I can add you to the PHOTOX Dev Team](https://github.com/orgs/PHOTOX/teams/devs) if you want and if you plan to work on ABIN or anything else in the repo. There is no official policy for that.

[danielhollas]

@FelyCZ if you merge in master that should fix the gcc9 build.

[danielhollas]

Just a quick comment, I don't think we should be including the MACE-OFF model in the repo, it's a huge binary blob, and it will likely become obsolete soon as new models come out.
We can definitely provide instructions and link about where it can be downloaded though!

Is this file needed for tests? If so, we should download it as part of the MACE installation script perhaps.

[FelyCZ]

I agree that it's not entirely necessary. The main idea was to provide users with a quick way to test the interface without any further configuration.

The file is not necessary for the tests; however, the default configuration (&mace namelist) uses the file as fallback.