uma-ase 0.1.0

UMA machine-learned force-field integrated with ASE workflows

UMA-ASE

UMA-ASE bundles UMA (Universal Model for Atoms (ref1)) machine-learned force-field (MLFF) with the Atomic Simulation Environment (ASE) methods. 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

uma-ase \
  -input geometry.xyz \
  -chg +1 \
  -spin 3 \
  -run-type sp freqs \
  -temperature 300 \
  -pressure 130000.0

Key options:

• -run-type accepts any sequence of sp, geoopt, and freqs.
• -optimizer selects an ASE optimiser (LBFGS, BFGS, BFGS_LINESEARCH, FIRE, MDMIN).
• -mlff-chk / -mlff-task pick the UMA checkpoint and task names supplied by FairChem.

Each run produces a consolidated log (e.g. molecule-SP-OPT.log), an optimised geometry (*-geoopt.xyz), a trajectory (*.traj), and—when frequencies are requested—a freqs/<stem>/ folder with the vibrational normal modes. The web GUI exposes download buttons for the run log, the GeoOpt trajectory, and the optimised geometry (with the XYZ comment line populated with formula, charge, and spin).

Run uma-ase -h to see the full reference.

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