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

```so sobash
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)

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

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