MAPLE is a machine-learning-potential-native computational chemistry toolkit for geometry optimization, transition-state search, reaction-path analysis, molecular dynamics, and related post-processing workflows.

• Python >= 3.10
• CUDA-capable GPU recommended for production workloads

MAPLE separates dependencies into three groups:

Core dependencies declared by MAPLE:

External runtime dependencies that users install manually:

git clone https://github.com/ClickFF/MAPLE.git
cd MAPLE
pip install -e .

The pip install -e . command above installs only MAPLE's core dependencies. Install PyTorch separately for your hardware. Examples:

# PyTorch example: CUDA 11.8
pip install torch --index-url https://download.pytorch.org/whl/cu118

# CPU-only PyTorch
pip install torch --index-url https://download.pytorch.org/whl/cpu

Install FAIR-Chem only if you need UMA or FAIR-Chem-backed/PBC workflows:

pip install fairchem-core

Model checkpoint boundary:

• MAPLE auto-downloads only the model files hosted at https://huggingface.co/Wayne7815/MAPLE_models.
• Auto-downloads use a pinned HuggingFace revision by default; set MAPLE_MODEL_REVISION only when intentionally refreshing model assets.
• Backend-specific or local checkpoints, such as MACE-Polar .pt files, must be present in maple/function/calculator/model/ or supplied through an explicit model path.
• UMA checkpoints are resolved through an explicit path, a local maple/function/calculator/model/uma-*.pt file, or FAIR-Chem's official model-loading path.

PBC boundary:

• PBC support is currently available through UMA/FAIR-Chem-backed workflows only.
• ANI, AIMNet2, MACE-OFF, MACE-O-MOL, and MACE-Polar are molecular no-PBC wrappers in MAPLE and fail fast when periodic atoms are supplied.
• AIMNet2 coulomb_method=ewald is disabled until validated cell/PBC/MIC inputs and reference tests exist; use simple or dsf.
• UMA stress/virial requests are rejected until MAPLE validates stress-unit conversion.

maple input.inp
maple input.inp output.out
maple --version
maple md nve

#model=uma(size=uma-s-1p1)
#opt(method=lbfgs)
#device=gpu0

0 1
C   -0.748   0.014   0.025
C    0.748  -0.014  -0.025
O    1.170   0.016   1.330
H   -1.155  -0.888  -0.460
H   -1.096   0.888  -0.530
H   -1.155   0.049   1.065
H    1.148  -0.912   0.457
H    1.096   0.869   0.513
H    0.802   0.842   1.742

#model=uma(size=uma-s-1p1)
#opt(method=lbfgs)
#device=gpu0

XYZ 0 1 /path/to/molecule.xyz

TIPS: Charge and spin multiplicity are supported only in the OMOL task mode of the UMA model and in the AIMNet2 / AIMNet2-NSE models.

#model=<model>
#<task>(options)
#device=<device>

#model=uma(...) accepts the following keys (all optional):

Inline coordinates:

#model=uma(size=uma-s-1p1,task=omol,inference=default)
#sp
#device=gpu0

0 1
C   0.000   0.000   0.000
H   1.089   0.000   0.000
...

External coordinates:

#model=uma(size=uma-s-1p1,task=omol,inference=default)
#sp
#device=gpu0

XYZ 0 1 /path/to/molecule.xyz

Multi-structure jobs such as NEB accept multiple XYZ records.
TIPS: Charge and spin multiplicity are supported only in the OMOL task mode of the UMA model

MAPLE supports custom explicit-solvent PDB templates; see the solvent documentation for usage guidance.

• Website: https://www.maplechem.org/
• Release history: https://github.com/ClickFF/MAPLE/releases
• Architecture notes: ARCHITECTURE.md
• Authoring a calculator backend: maple/function/calculator/AUTHORING.md

https://github.com/ClickFF/MAPLE

1. Fork the repository.
2. Create a feature branch.
3. Make changes with clear commits.
4. Open a pull request.

• ASE
• PyTorch
• AIMNet2
• FAIR-Chem

Version: 0.1.4
Status: Active Development
Updated: May 2026