Metadata-Version: 2.4
Name: acellera-openff-nagl-models
Version: 2026.9.0
Summary: OpenFF NAGL Models
Author-email: Lily Wang <lily.wang@openforcefield.org>
Maintainer-email: Lily Wang <lily.wang@openforcefield.org>
License-Expression: MIT
Project-URL: Documentation, https://openff-nagl-models.readthedocs.io
Project-URL: Repository, https://github.com/openforcefield/openff-nagl-models
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: packaging
Requires-Dist: platformdirs
Provides-Extra: test
Requires-Dist: numpy; extra == "test"
Requires-Dist: pytest>=6; extra == "test"
Dynamic: license-file

# OpenFF NAGL Models

| **Latest release** | [![Last release tag](https://img.shields.io/github/release-pre/openforcefield/openff-nagl-models.svg)](https://github.com/openforcefield/openff-nagl-models/releases) ![GitHub commits since latest release (by date) for a branch](https://img.shields.io/github/commits-since/openforcefield/openff-nagl-models/latest)  [![Documentation Status](https://readthedocs.org/projects/openff-nagl-models/badge/?version=latest)](https://openff-nagl-models.readthedocs.io/en/latest/)                                                                                                        |
| :----------------- | :--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Status**         | [![GH Actions Status](https://github.com/openforcefield/openff-nagl-models/actions/workflows/CI.yml/badge.svg)](https://github.com/openforcefield/openff-nagl-models/actions?query=branch%3Amain+workflow%3ACI) |
| **Community**      | [![License: CC-BY 4.0](https://img.shields.io/badge/license-CC--BY--NC--SA--4.0-yellow)](https://creativecommons.org/licenses/by/4.0/deed.en) [![DOI](https://zenodo.org/badge/DOI/10.5281/zenodo.13119685.svg)](https://doi.org/10.5281/zenodo.13119685) |

This repository contains NAGL models released by the [Open Force Field Initiative](https://openforcefield.org). They are intended to be used by [OpenFF NAGL](https://github.com/openforcefield/openff-nagl).

<!-- models-start -->
## Models

| Model name | Introduced in `openff-nagl-models` version | Release state | Further notes |
|---|---|---|---|
| `openff-gnn-am1bcc-1.0.0.pt` | [v2025.09.0](https://github.com/openforcefield/openff-nagl-models/releases/tag/v2025.09.0) | Production | [Link](docs/models/openff-gnn-am1bcc-1.0.0/index.md)
| `openff-gnn-am1bcc-0.1.0-rc.3.pt` | [v0.3.0](https://github.com/openforcefield/openff-nagl-models/releases/tag/v0.3.0) | pre-production | [Link](docs/models/openff-gnn-am1bcc-0.1.0-rc3/index.md)
| `openff-gnn-am1bcc-0.1.0-rc.1.pt` | [v0.2.0](https://github.com/openforcefield/openff-nagl-models/releases/tag/v0.2.0) | pre-production | [Link](docs/models/openff-gnn-am1bcc-0.1.0-rc2/index.md)
| `openff-gnn-am1bcc-0.1.0-rc.1.pt` | [v0.1.0](https://github.com/openforcefield/openff-nagl-models/releases/tag/v0.1.0) | pre-production | [Link](docs/models/openff-gnn-am1bcc-0.1.0-rc1/index.md)
| `openff-gnn-am1bcc-0.0.1-alpha.1.pt` $^1$ | [v0.0.1](https://github.com/openforcefield/openff-nagl-models/releases/tag/v0.0.1) | pre-production/experimental $^1$ | [Link](docs/models/openff-gnn-am1bcc-0.0.1-alpha.1/index.md) |

$^1$ We do *not* recommend using this model to assign charges in scientific work.
<!-- models-end -->

<!-- usage-start -->
## Usage

Current models available in this repository can be applied with:

```python
from openff.nagl_models import validate_nagl_model_path
from openff.toolkit.utils.nagl_wrapper import NAGLToolkitWrapper

# optional
model_path = validate_nagl_model_path("openff-gnn-am1bcc-1.0.0.pt")

offmol = Molecule.from_smiles("CCO")
offmol.assign_partial_charges(partial_charge_method="openff-gnn-am1bcc-1.0.0.pt")
```

Installing this package exposes an entry point that makes it easy to access models installed in this package.

A convenience function is provided to wrap this for you:

```python
>>> from openff.nagl_models import load_nagl_model_directory_entry_points
>>> load_nagl_model_directory_entry_points()
[PosixPath('/home/.../openff-nagl-models/openff/nagl_models/models/am1bcc')]
```

You can also list all available models **from all entry points**:

```python
>>> from openff.nagl_models import list_available_nagl_models
>>> list_available_nagl_models()
[PosixPath('/home/.../openff-nagl-models/openff/nagl_models/models/am1bcc/openff-gnn-am1bcc-0.0.1-alpha.1.pt'), PosixPath('/home/.../openff-nagl-models/openff/nagl_models/models/am1bcc/openff-gnn-am1bcc-0.1.0-rc.1.pt'), PosixPath('/home/.../openff-nagl-models/openff/nagl_models/models/am1bcc/openff-gnn-am1bcc-0.1.0-rc.2.pt'), PosixPath('/home/.../openff-nagl-models/openff/nagl_models/models/am1bcc/openff-gnn-am1bcc-0.1.0-rc.3.pt'), PosixPath('/home/.../openff-nagl-models/openff/nagl_models/models/am1bcc/openff-gnn-am1bcc-1.0.0.pt')]
```

To list available models (also listed in the [Models](#models) table above):
```python
>>> from openff.nagl_models import list_available_nagl_models
>>> list_available_nagl_models(with_path=False)
['openff-gnn-am1bcc-1.0.0.pt', 'openff-gnn-am1bcc-0.1.0-rc.1.pt', 'openff-gnn-am1bcc-0.1.0-rc.3.pt', 'openff-gnn-am1bcc-0.0.1-alpha.1.pt', 'openff-gnn-am1bcc-0.1.0-rc.2.pt']
```

Or validate if a model name is found in the local directory, or an entry point directory:

```python
>>> from openff.nagl_models import validate_nagl_model_path
>>> validate_nagl_model_path("openff-gnn-am1bcc-1.0.0.pt")
PosixPath('/home/.../openff-nagl-models/openff/nagl_models/models/am1bcc/openff-gnn-am1bcc-1.0.0.pt')
```

Finally, if you want to find all models for a particular type, use `get_models_by_type`.
These will come sorted according to semantic versioning, where the latest release is last:

```python
>>> from openff.nagl_models import get_models_by_type
>>> get_models_by_type("am1bcc")
[PosixPath('/home/.../openff-nagl-models/openff/nagl_models/models/am1bcc/openff-gnn-am1bcc-0.0.1-alpha.1.pt'), PosixPath('/home/.../openff-nagl-models/openff/nagl_models/models/am1bcc/openff-gnn-am1bcc-0.1.0-rc.1.pt'), PosixPath('/home/.../openff-nagl-models/openff/nagl_models/models/am1bcc/openff-gnn-am1bcc-0.1.0-rc.2.pt'), PosixPath('/home/.../openff-nagl-models/openff/nagl_models/models/am1bcc/openff-gnn-am1bcc-0.1.0-rc.3.pt'), PosixPath('/home/.../openff-nagl-models/openff/nagl_models/models/am1bcc/openff-gnn-am1bcc-1.0.0.pt')]
```

<!-- usage-end -->

## License

See the [LICENSE](LICENSE) file.

## Acknowledgements

Project based on the
[Computational Molecular Science Python Cookiecutter](https://github.com/molssi/cookiecutter-cms) version 1.0.
