# 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)
```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.

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

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

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