mace-inference 0.1.0

High-level Python library for MACE machine learning force field inference tasks

MACE Inference

High-level Python library for MACE machine learning force field inference tasks

Documentation • Installation • Quick Start • Examples

---

🌟 Features

• 🚀 Simple API: High-level interface for common inference tasks
• 🔌 Flexible: Works with all MACE models (MACE-MP-0, MACE-MPA-0, MACE-OMAT-0, etc.)
• ⚡ GPU Support: Automatic device detection (CPU/CUDA)
• 🧪 Complete Workflow: Single-point energy, optimization, MD, phonon, adsorption, etc.
• 🔧 CLI Tools: Command-line interface for non-programmers
• 📦 Pure Python: Built on ASE and Phonopy - no extra software required

---

📦 Installation

Basic Installation (CPU)

pip install mace-inference

GPU Support

pip install mace-inference[gpu]

With D3 Dispersion Correction

pip install mace-inference[d3]

Development Installation

git clone https://github.com/lichman0405/mace-inference.git
cd mace-inference
pip install -e ".[all]"

---

🚀 Quick Start

Python API

from ase.io import read
from mace_inference import MACEInference

# Initialize MACE calculator
calc = MACEInference(model="medium", device="auto")

# Load structure
atoms = read("structure.cif")

# Single-point energy calculation
result = calc.single_point(atoms)
print(f"Energy: {result['energy']:.4f} eV")
print(f"Max Force: {result['max_force']:.4f} eV/Å")

# Structure optimization
optimized = calc.optimize(atoms, fmax=0.05)  # Returns Atoms object
# Save with: from ase.io import write; write("optimized.cif", optimized)

# Molecular dynamics (NVT)
trajectory = calc.run_md(
    atoms, 
    ensemble="nvt", 
    temperature_K=300, 
    steps=1000
)

# Phonon calculation
phonon_result = calc.phonon(atoms, supercell_matrix=[2, 2, 2])

# Adsorption energy
result = calc.adsorption_energy(
    framework=mof,
    adsorbate="CO2",
    site_position=[10.0, 10.0, 10.0]
)
print(f"Adsorption Energy: {result['E_ads']:.3f} eV")

# Batch processing with progress callback
def progress(current, total):
    print(f"Processing {current}/{total}")

results = calc.batch_single_point(
    structures,
    progress_callback=progress
)

Command Line Interface

# Single-point energy
mace-infer energy structure.cif --model medium

# Structure optimization
mace-infer optimize structure.cif --fmax 0.05 --output optimized.cif

# Molecular dynamics
mace-infer md structure.cif --ensemble nvt --temp 300 --steps 10000

# Phonon calculation
mace-infer phonon structure.cif --supercell 2 2 2 --temp-range 0 1000 10

# Bulk modulus
mace-infer bulk-modulus structure.cif

# Adsorption energy
mace-infer adsorption mof.cif --gas CO2 --site 10.0 10.0 10.0

---

📚 Documentation

Full documentation is available at lichman0405.github.io/mace-inference

• Installation Guide - Detailed installation instructions
• Quick Start - Getting started guide
• User Guide - Detailed usage guides
• API Reference - Complete API documentation
• Examples - Usage examples and tutorials
• Changelog - Version history and updates

Available Tasks

Task	Method	Description
Single-Point Energy	single_point()	Calculate energy, forces, stress
Structure Optimization	optimize()	Minimize energy (atoms + cell)
Molecular Dynamics	run_md()	NVT/NPT simulations
Phonon Calculation	phonon()	Phonon dispersion & thermodynamics
Bulk Modulus	bulk_modulus()	Equation of state fitting
Coordination Analysis	coordination()	Metal-ligand bond lengths
Adsorption Energy	adsorption_energy()	Gas molecule binding energy
Batch Single-Point	batch_single_point()	Process multiple structures
Batch Optimize	batch_optimize()	Batch structure optimization

Supported MACE Models

• MACE-MP-0a/0b3 (Materials Project)
• MACE-MPA-0 (MPtraj + Alexandria)
• MACE-OMAT-0 (OMat24)
• MACE-MATPES-r2SCAN-0 (MatPES + MPtraj)
• Custom fine-tuned models

---

📖 Examples

See the examples/ directory for detailed usage:

• 01_basic_usage.py - Basic single-point and optimization
• 02_molecular_dynamics.py - NVT/NPT MD simulations
• 03_phonon_calculation.py - Phonon and thermal properties
• 04_adsorption_study.py - Gas adsorption in MOFs
• 05_high_throughput.py - Batch processing
• 06_d3_correction.py - Using D3 dispersion correction
• 07_batch_processing.py - Batch API and progress callbacks

---

🧪 Testing

# Run all tests
pytest

# Run with coverage
pytest --cov=mace_inference --cov-report=html

---

🤝 Contributing

Contributions are welcome! Please:

1. Fork the repository
2. Create a feature branch (git checkout -b feature/amazing-feature)
3. Commit your changes (git commit -m 'Add amazing feature')
4. Push to the branch (git push origin feature/amazing-feature)
5. Open a Pull Request

---

📄 License

This project is licensed under the MIT License - see the LICENSE file for details.

---

🙏 Acknowledgments

• MACE: ACEsuit/mace
• ASE: Atomic Simulation Environment
• Phonopy: Phonon calculations

---

📮 Citation

If you use this library in your research, please cite:

@software{mace_inference,
  title = {MACE Inference: High-level Python library for MACE force field inference},
  author = {Shibo Li},
  year = {2026},
  url = {https://github.com/lichman0405/mace-inference}
}

And the original MACE paper:

@inproceedings{Batatia2022mace,
  title={{MACE}: Higher Order Equivariant Message Passing Neural Networks for Fast and Accurate Force Fields},
  author={Ilyes Batatia and David Peter Kovacs and Gregor N. C. Simm and Christoph Ortner and Gabor Csanyi},
  booktitle={Advances in Neural Information Processing Systems},
  year={2022}
}