uma-ase 0.2.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 single-point energy evaluations, geometry optimisation, and vibrational/thermochemical analysis from a single command-line entry point or an optional web GUI service.

Installation

Released package (after publishing to PyPI)

pip install "UMA-ASE[server]"

The server extra installs the optional GUI web interface. Omit it when you only need the command-line tooling.

From source

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

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

Command-line usage

Usage depends on how you obtain the package:

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

  # Single run
  uma-ase -input geometry.xyz -chg 0 -spin 1 -run-type sp
  
  # Using local checkpoints
  export UMA_CUSTOM_CHECKPOINT_DIR=/abs/path/to/checkpoints
  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.cli -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.

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

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