# 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:

```bash
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
```bash
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:

```bash
pip install fairchem-core
```
FairChem is repidly evolving. Check version changes and compatibility with uma-ase.

### From source
```bash
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)**
  ```bash
  # 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**
  ```bash
  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`)**
```text
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)

```bash
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:

```bash
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.

![uma-ase web interface](./screenshot.png)

## 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:
   ```bash
   python -m build
   ```
4. Upload to a package index (e.g., GitLab Package Registry or PyPI):
   ```bash
   python -m twine upload dist/*
   ```

## License

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