uma-ase 0.3.0

UMA machine-learned force-field integrated with ASE workflows

UMA-ASE

UMA-ASE bundles UMA (Universal Model for Atoms (https://huggingface.co/facebook/UMA) machine-learned force-field (MLFF) with the Atomic Simulation Environment (ASE) methods (https://ase-lib.org/). It supports basic single-point energy calculations, geometry optimisation, and vibrational/thermochemical analysis from a single command-line entry point or an optional web GUI service.

Requirements

The project currently ships and has been validated with Python 3.12. The runtime stack is:

• Python ≥ 3.9 (tested with 3.12)
• ASE ≥ 3.26.0
• numpy ≥ 2.2
• torch ≥ 2.6
• fairchem-core ≥ 2.10 for UMA checkpoints and calculators
• flask ≥ 3.0 when you want the optional web UI

Install these packages with:

pip install -r requirements.txt

If you build your own environment, make sure fairchem is present—geometry optimisations rely on it to compute per-atom reference energies. On Apple Silicon you may also want to limit OpenMP threads when driving torch (e.g. export OMP_NUM_THREADS=1) to avoid shared-memory warnings.

Installation

Released package

pip install UMA-ASE[server]

The server extra installs the optional GUI web interface. Omit it when you only need the command-line tooling. Afterwards, install FairChem explicitly if your environment does not already ship it:

pip install fairchem-core

FairChem is repidly evolving. Check version changes and compatibility with uma-ase.

From source

python -m venv .venv
source .venv/bin/activate
pip install --upgrade pip
pip install -r requirements.txt
pip install -e ".[server]"

The editable install registers the uma-ase and uma-ase-server console scripts for local development.

Command-line (CLI) usage

• Installed via pip (PyPI, wheel, or editable install)

  # Set up where your local checkpoint UMA MLFF files are located.  
  export UMA_CUSTOM_CHECKPOINT_DIR=/abs/path/to/checkpoints
  (include this your .bashrc or .bash_profile conf files).
  
  # Single run
  uma-ase -input geometry.xyz -chg 0 -spin 1 -run-type sp
  
  # Using local checkpoints (optional)
  uma-ase -input geometry.xyz -chg +1 -run-type sp freqs -temperature 300 -pressure 130000.0
  

• Working from a cloned repository without installing

  export PYTHONPATH=src
  python -m uma_ase.py -input geometry.xyz -chg 0 -spin 1 -run-type geoopt
  

The CLI always emits a consolidated log (e.g. molecule-SP-OPT.log), a trajectory (*.traj), an optimised XYZ (*-geoopt-OPT.xyz), and frequency outputs when requested. Run uma-ase -h (or python -m uma_ase.cli -h) for the full reference.

FairChem’s UMA models can be loaded directly from the official distribution (see the FairChem/UMA docs), or you can download the checkpoint files yourself for extra stability and keep them wherever you prefer. Point the shell environment variable UMA_CUSTOM_CHECKPOINT_DIR at your directory so -mlff-chk uma-s-1p1 and similar shortcuts resolve against your local files. If the variable is unset, UMA-ASE looks for checkpoints under ~/.uma_ase/checkpoints. When an XYZ comment line embeds a signed integer (e.g. https://… -1), UMA-ASE reads it before invoking ASE and uses that value as the default charge unless you supplied -chg explicitly.

CLI option summary

• -input (required): input geometry file readable by ASE, typically .xyz. A standard XYZ can omit -chg when the second-line comment ends with a signed integer (optionally alongside a source URL), e.g.

  3
  https://example.org/mol/123 -1
  O  0.0 0.0 0.0
  H  0.0 0.0 0.96
  H  0.0 0.75 -0.48
  

  UMA-ASE reads the -1 before invoking ASE and uses it as the default charge.
• -chg (default 0): total molecular charge; omitted values default to 0 or to the signed integer embedded in the XYZ comment line if present.
• -spin (default 1): spin multiplicity.
• -run-type (default sp): workflow steps to run; choose any sequence of sp, geoopt, freqs.
• -iter (default 250): maximum geometry optimisation cycles.
• -grad (default 0.01 eV/Å): convergence threshold on the maximum force component.
• -optimizer (default LBFGS): ASE optimiser to use (BFGS, LBFGS, FIRE, BFGSLineSearch, MDMin).
• -mlff-chk (default uma-s-1p1): UMA checkpoint identifier.
• -mlff-task (default omol): UMA task/model name passed to the calculator.
• -temperature (default 298.15 K): vibrational/thermochemistry temperature.
• -pressure (default 101325 Pa): vibrational/thermochemistry pressure.
• -visualize: open the geoopt trajectory in ASE’s viewer after completion.

CLI help (uma-ase -h)

usage: uma-ase [-h] -input INPUT [-chg CHG] [-spin SPIN]
               [-run-type {sp,geoopt,freqs} [{sp,geoopt,freqs} ...]]
               [-iter ITER] [-grad GRAD] [-optimizer NAME]
               [-mlff-chk CHECKPOINT] [-mlff-task TASK] [-temperature T]
               [-pressure P] [-visualize]

Provide the required -input value. Charge defaults to 0 or to the signed
integer embedded in the XYZ comment line.

options:
  -h, --help            show this help message and exit
  -input INPUT          Input geometry readable by ASE (XYZ comment may append
                        a signed charge).
  -chg CHG              Molecular charge override (default 0; inferred from
                        XYZ comment when present).
  -spin SPIN            Spin multiplicity. Default 1.
  -run-type {sp,geoopt,freqs} [{sp,geoopt,freqs} ...]
                        Run type(s) to execute: 'sp', 'geoopt', 'freqs', or
                        any sequence thereof (default: sp).
  -iter ITER            Max number of geometry optimization cycles.
                        Default=250
  -grad GRAD            Max grad for convergence. Default=0.01 eV/A
  -optimizer NAME       ASE optimizer (e.g. BFGS, LBFGS, FIRE,
                        BFGSLineSearch,MDMin). Default='LBFGS'.
  -mlff-chk CHECKPOINT  UMA checkpoint identifier. Default='uma-s-1p1'.
  -mlff-task TASK       UMA task/model identifier. Default='omol'.
  -temperature T        Temperature in Kelvin for vibrational analysis
                        (default 298.15 K).
  -pressure P           Pressure in Pascals for vibrational analysis (default
                        101325.0 Pa).
  -visualize            Open the trajectory of a geoopt run in an interactive
                        viewer.

Web interface (optional)

uma-ase-server

then visit http://127.0.0.1:8000. The webapp (UMA-ASE.html) is bundled with the package and submits jobs to /api/uma-ase/run. The backend stores each uploaded geometry in a temporary directory, delegates to the CLI, returns the generated log, and removes temporary files automatically. The page focuses on job submission, showing a live summary of the uploaded structure, and exposing UMA checkpoint/task selectors.

Working directly from the source tree without installing? Prefix the module path:

PYTHONPATH=src python -m uma_ase.server
# or export PYTHONPATH=src once, then:
python -m uma_ase.server

Each run stores the returned log under ~/.uma_ase/results/ (configurable via UMA_RESULTS_DIR), and the interface enables a Download Log button once a job finishes.

Package layout

src/uma_ase/
├── __init__.py          # Version metadata
├── __main__.py          # Enables `python -m uma_ase`
├── cli.py               # Console entry point
├── server.py            # Flask application (optional)
├── utils.py             # CLI parser and helper utilities
├── workflows.py         # Core UMA/ASE workflow orchestration
└── static/UMA-ASE.html  # Single-page frontend served by the Flask app

Development workflow

1. Create a virtual environment and install the package in editable mode (pip install -e .[server]).
2. Run unit or integration tests as desired (add your preferred framework).
3. Build distributions for publishing:

   python -m build
   

4. Upload to a package index (e.g., GitLab Package Registry or PyPI):

   python -m twine upload dist/*
   

License

(c) CC BY This code has been generated by ChatGPT Codex agent under the supervision of Carles Bo.