Metadata-Version: 2.4
Name: g16-mlips
Version: 1.2.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

[![DOI](https://zenodo.org/badge/1160316483.svg)](https://doi.org/10.5281/zenodo.18691993)

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** for **Gaussian 16**.
An optional **implicit-solvent** correction (`xTB`) is also available via `--solvent`.

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

Requires **Python 3.9** or later.

> If you use ORCA, see also: https://github.com/t-0hmura/orca-mlips

## Quick Start (Default = UMA)

1. Install PyTorch suitable for your CUDA environment (CUDA 13.0 recommended).
```bash
pip install torch==2.13.0 --index-url https://download.pytorch.org/whl/cu130
```

2. Install the package with the 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
hf auth login
```
> UMA model is on Hugging Face Hub. You need to log in once (See https://github.com/facebookresearch/fairchem):

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 rely on an internal gradient routine, which is incompatible with the external interface.
> ONIOM is supported with both `ActiveAtoms` and `AllAtoms`.
> With `AllAtoms`, Gaussian passes `IAn=0` MM point-charge rows to the plugin.
> By default these `IAn=0` rows are excluded from MLIP evaluation and returned as zero force/Hessian blocks.

For ONIOM point-charge embedding correction via xTB:
```text
#p oniom(external=("uma --embedcharge",AllAtoms):amber=softfirst) opt(nomicro)
```
`--embedcharge` adds an xTB point-charge embedding correction using ONIOM MM charges.
When `igrd=2`, it also returns MM point-charge force/Hessian terms from the embedding correction.

### 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 job type 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.

## Implicit Solvent Correction (xTB)

You can use an implicit-solvent correction via xTB. To use it, install xTB and pass the `--solvent` option to `external`.

Install xTB in your conda environment (or built from source):

```bash
conda install xtb
```

Use `--solvent <name>` in `external="..."` (examples: `water`, `thf`):

```text
#p external="uma --solvent water" opt(nomicro)
#p external="uma --solvent thf" freq
```

For details, see [`SOLVENT_EFFECTS.md`](SOLVENT_EFFECTS.md).

This implementation follows the solvent-correction approach described in:
Zhang, C., Leforestier, B., Besnard, C., & Mazet, C. (2025). Pd-catalyzed regiodivergent arylation of cyclic allylboronates. Chemical Science, 16, 22656-22665. https://doi.org/10.1039/d5sc07577g

If citing this correction in a paper, you can use the following:
`Implicit solvent effects were accounted for by integrating the ALPB [or CPCM-X] solvation model from the xtb package as an additional correction to UMA-generated energies, gradients, and Hessians.`

> **Note:** `--solvent-model cpcmx` (CPCM-X) requires xTB built from source with `-DWITH_CPCMX=ON`. The conda-forge `xtb` package does not include CPCM-X support. See [`SOLVENT_EFFECTS.md`](SOLVENT_EFFECTS.md) for build instructions.

### Using the analytical Hessian in optimization jobs

To use the 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 the analytical Hessian (`igrd=2`) from the plugin. `opt` and `irc` themselves never request it directly.

## Local Model Weights

Use `-w` / `--weights-file` to load a downloaded checkpoint:

```text
#p external="g16-mlips-orb --model orb-v3-conservative-omol --weights-file orb.ckpt"
```

The option works with UMA, ORB, MACE, and AIMNet2. For ORB, `--model` selects the architecture and `--weights-file` supplies its weights. Local weights bypass automatic checkpoint downloads.

## Installing Model Families

Use Python 3.12 or newer for current ORB releases.

```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 conflicts with MACE (`e3nn`) and ORB (`nvalchemi-toolkit-ops`) in the current upstream releases. Install UMA in its own environment.

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 `hf auth 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`](OPTIONS.md) for backend-specific tuning parameters.
For solvent correction options, see [`SOLVENT_EFFECTS.md`](SOLVENT_EFFECTS.md).

> **Note:** For ORB and MACE, FP32 runs faster than FP64 and is useful for generating starting geometries for subsequent DFT refinement, but extra imaginary frequencies may remain after the MLIP optimization reports convergence. If you need an MLIP local minimum with no imaginary frequencies or a TS with only its single imaginary mode, we recommend FP64: `--precision float64` for ORB or `--dtype float64` for MACE.

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 `hf auth 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        = {10},
  version      = {1.2.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`
