FAMEX: Fast Mechanistic Explorer

FAMEX provides a unified interface for molecular geometry optimization using machine learning potentials. It supports minima optimization, transition state searches, and reaction path calculations through both a command-line interface and Python API.

Quick Start

Installation

pip install famex
# Or from source:
git clone https://github.com/rlaplaza-lab/famex.git && cd famex && pip install -e .

Install a backend separately:

Note: Python 3.10+ required. MACE and UMA conflict - use separate environments.

Your First Optimization

Command Line:

# Create a test structure
echo "3
Water
O 0.0 0.0 0.0
H 0.0 0.0 1.0
H 0.0 1.0 0.0" > water.xyz

# Optimize it (default backend is uma; use aimnet2 for torch-only install)
famex minima --strategy local water.xyz
# famex minima --strategy local water.xyz --backend aimnet2

Python API:

import famex

# Load and optimize
explorer = famex.Explorer.from_file("water.xyz", backend="aimnet2", target="minima", strategy="local")
result = explorer.run(fmax=0.05, steps=1000)

# Save results
explorer.save_structure(result["optimized_atoms"], "water_optimized.xyz")
print(f"Final energy: {result['optimized_atoms'].get_potential_energy():.6f} eV")

Key Features

• Multiple ML backends (UMA, AIMNet2, MACE, SO3LR, Orb, TBLite, PET)
• GPU acceleration with CUDA support
• Semantic target/strategy interface (minima, ts, path)
• Advanced methods (NEB, CI-NEB, IRC, growing string)
• Frequency analysis and thermodynamics
• Command-line and Python API
• Supports XYZ, CIF, PDB via ASE

Documentation

• Documentation index - Overview and defaults
• User Guide - Complete reference for CLI, Python API, and backends
• Tutorials - Hands-on guides for optimization and transition states
• FAQ - Troubleshooting and common questions

Examples

Runnable demos and benchmarks: examples/README.md.

# Transition state search
famex ts --strategy interpolate reactant.xyz --product product.xyz

# NEB reaction path
famex path --strategy neb reactant.xyz product.xyz --npoints 11

# IRC from transition state
famex path --strategy irc ts.xyz --direction both

Community and Support

• GitHub Repository: https://github.com/rlaplaza-lab/famex
• Issues: Report bugs and request features
• License: MIT License

Citation

@software{famex2026,
  title={FAMEX: Fast Mechanistic Explorer},
  author={FAMEX Development Team},
  year={2026},
  url={https://github.com/rlaplaza-lab/famex}
}