Metadata-Version: 2.4
Name: g16-mlips
Version: 1.0.0
Summary: MLIP plugins for Gaussian16 External (UMA, ORB, MACE, AIMNet2)
License-Expression: MIT
Project-URL: Homepage, https://github.com/t-0hmura/g16-mlips
Project-URL: Repository, https://github.com/t-0hmura/g16-mlips
Requires-Python: >=3.9
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: numpy
Requires-Dist: ase
Provides-Extra: uma
Requires-Dist: torch>=2.8.0; extra == "uma"
Requires-Dist: fairchem-core>=2.13; extra == "uma"
Provides-Extra: orb
Requires-Dist: torch>=2.8.0; extra == "orb"
Requires-Dist: orb-models; extra == "orb"
Provides-Extra: mace
Requires-Dist: torch>=2.8.0; extra == "mace"
Requires-Dist: mace-torch; extra == "mace"
Provides-Extra: aimnet2
Requires-Dist: torch>=2.8.0; extra == "aimnet2"
Requires-Dist: aimnet; extra == "aimnet2"
Dynamic: license-file

# g16-mlips

MLIP (Machine Learning Interatomic Potential) plugins for Gaussian 16 `External` interface.

Four model families are currently supported:
- **UMA** ([fairchem](https://github.com/facebookresearch/fairchem)) — default model: `uma-s-1p1`
- **ORB** ([orb-models](https://github.com/orbital-materials/orb-models)) — default model: `orb_v3_conservative_omol`
- **MACE** ([mace](https://github.com/ACEsuit/mace)) — default model: `MACE-OMOL-0`
- **AIMNet2** ([aimnetcentral](https://github.com/isayevlab/aimnetcentral)) — default model: `aimnet2`

All backends provide energy, gradient, and **analytical Hessian** to **Gaussian 16**.  

> The model server starts automatically and stays resident, so repeated calls during optimization are fast.  

Requires **Python 3.9** or later.

## Quick Start (Default = UMA)

1. Install PyTorch for your environment (CUDA/CPU).
```bash
pip install torch==2.8.0 --index-url https://download.pytorch.org/whl/cu129
```

2. Install the package with UMA profile. If you need ORB/MACE/AIMNet2, use `g16-mlips[orb]`/`g16-mlips[mace]`/`g16-mlips[aimnet2]`.
```bash
pip install "g16-mlips[uma]"
```

3. Log in to Hugging Face for UMA model access. (Not required for ORB/MACE/AIMNet2)
```bash
huggingface-cli login
```

4. Use in a Gaussian input file. `nomicro` is required. If you use ORB/MACE/AIMNet2, use `external="orb"`/`external="mace"`/`external="aimnet2"`.
For detailed Gaussian `External` usage, see https://gaussian.com/external/
```text
%nprocshared=8
%mem=32GB
%chk=water_ext.chk
#p external="uma" opt(nomicro)

Water external UMA example

0 1
O  0.000000  0.000000  0.000000
H  0.758602  0.000000  0.504284
H -0.758602  0.000000  0.504284
```

Other backends:
```text
#p external="orb" opt(nomicro)
#p external="mace" opt(nomicro)
#p external="aimnet2" opt(nomicro)
```

> **Important:** For Gaussian `External` geometry optimization, always include `nomicro` in `opt(...)`.
> Without it, Gaussian uses micro-iterations that assume an internal gradient routine, which is incompatible with the external interface.

### Analytical Hessian (optional)

Optimization and IRC can run without providing an initial Hessian — Gaussian builds one internally using estimated force constants. Providing an MLIP analytical Hessian via `freq` + `readfc` improves convergence, especially for TS searches.

Gaussian `freq` (with `external=...`) is the only path that requests the plugin's analytical Hessian directly.

**Frequency calculation**

```text
%nprocshared=8
%mem=32GB
%chk=cla_ext.chk
#p external="uma" freq

CLA freq UMA

0 1
...
```
Gaussian sends `igrd=2` and stores the result in the `.chk` file.

### Using analytical Hessian in optimization jobs

To use MLIP analytical Hessian in `opt`/`irc`, read the Hessian from an existing checkpoint using Gaussian `%oldchk` + `readfc`.

```text
%nprocshared=8
%mem=32GB
%chk=cla_ext.chk
%oldchk=cla_ext.chk

#p external="uma" opt(readfc,nomicro)

CLA opt UMA

0 1
...
```

`readfc` reads the force constants from `%oldchk`. This applies to `opt` and `irc` runs.
Note that `freq` is the only job type that requests analytical Hessian (`igrd=2`) from the plugin. `opt` and `irc` themselves never request it directly.

> **Note:** Run `uma --list-models` to see available models. If the `uma` alias conflicts in your environment, use `g16-mlips-uma` instead.

Additional examples: `examples/cla_freq_uma.gjf` + `examples/cla_uma.gjf`, `examples/sn2_freq_orb.gjf` + `examples/sn2_orb.gjf`, `examples/water_freq_mace.gjf` + `examples/water_mace.gjf`, `examples/cla_freq_aimnet2.gjf` + `examples/cla_aimnet2.gjf`

## Installing Model Families

```bash
pip install "g16-mlips[uma]"         # UMA (default)
pip install "g16-mlips[orb]"         # ORB
pip install "g16-mlips[mace]"        # MACE
pip install "g16-mlips[orb,mace]"    # ORB + MACE
pip install "g16-mlips[aimnet2]"     # AIMNet2
pip install "g16-mlips[orb,mace,aimnet2]"  # ORB + MACE + AIMNet2
pip install g16-mlips                # core only
```

> **Note:** UMA and MACE conflict at dependency level (`e3nn`). Use separate environments.

Local install:
```bash
git clone https://github.com/t-0hmura/g16-mlips.git
cd g16-mlips
pip install ".[uma]"
```

Model download notes:
- **UMA**: Hosted on Hugging Face Hub. Run `huggingface-cli login` once.
- **ORB / MACE / AIMNet2**: Downloaded automatically on first use.

## Upstream Model Sources

- UMA / FAIR-Chem: https://github.com/facebookresearch/fairchem
- ORB / orb-models: https://github.com/orbital-materials/orb-models
- MACE: https://github.com/ACEsuit/mace
- AIMNet2: https://github.com/isayevlab/aimnetcentral

## Advanced Options

See `OPTIONS.md` for backend-specific tuning parameters.

Command aliases:
- Short: `uma`, `orb`, `mace`, `aimnet2`
- Prefixed: `g16-mlips-uma`, `g16-mlips-orb`, `g16-mlips-mace`, `g16-mlips-aimnet2`

## Troubleshooting

- **`external="uma"` runs the wrong plugin** — Use `external="g16-mlips-uma"` to avoid alias conflicts.
- **`external="aimnet2"` runs the wrong plugin** — Use `external="g16-mlips-aimnet2"` to avoid alias conflicts.
- **`uma` command not found** — Activate the conda environment where the package is installed.
- **UMA model download fails (401/403)** — Run `huggingface-cli login`. Some models require access approval on Hugging Face.
- **Works interactively but fails in PBS jobs** — Use absolute path from `which uma` in the Gaussian input.

## Citation

If you use this package, please cite:

```bibtex
@software{ohmura2026g16mlips,
  author       = {Ohmura, Takuto},
  title        = {g16-mlips},
  year         = {2026},
  month        = {2},
  version      = {1.0.0},
  url          = {https://github.com/t-0hmura/g16-mlips},
  license      = {MIT},
  doi          = {10.5281/zenodo.18691993}
}
```

## References

- Gaussian External interface (official): https://gaussian.com/external/
- Gaussian External: `$g16root/g16/doc/extern.txt`, `$g16root/g16/doc/extgau`
