From 4221442dc9c506f26255a547a2e6b8009b3d30af Mon Sep 17 00:00:00 2001 From: "Matthew W. Thompson" Date: Fri, 28 Mar 2025 10:13:18 -0500 Subject: [PATCH 01/23] Begin drafting GNN section --- docs/enhancement-proposals/off-ep-00XX.md | 79 +++++++++++++++++++++++ docs/index.md | 2 + 2 files changed, 81 insertions(+) create mode 100644 docs/enhancement-proposals/off-ep-00XX.md diff --git a/docs/enhancement-proposals/off-ep-00XX.md b/docs/enhancement-proposals/off-ep-00XX.md new file mode 100644 index 0000000..a61c092 --- /dev/null +++ b/docs/enhancement-proposals/off-ep-00XX.md @@ -0,0 +1,79 @@ +# OFF-EP X — Template + +**Status:** Draft + +**Authors:** Lily Wang + +**Stakeholders:** <list of stakeholders that would be affected by this proposal> + +**Acceptance criteria:** + +**Created:** <date created> + +**Discussion:** <link to the PR / issue where proposal is being discussed> + +**Implementation:** <link an example / reference implementation of the proposal> + +## Abstract + +A short description of the change being addressed. + +## Motivation and Scope + +This section describes the need for the proposed change. It should +describe the existing problem, who it affects, what it is trying to +solve, and why. This section should explicitly address the scope of and +key requirements for the proposed change. +If the proposal is based around changes to software, this section should clearly indicate which package(s) would be changed. + +## Usage and Impact + +This section describes how users of the ecosystem will use features +described in this SMIRNOFF EP. It should be comprised mainly of code / file +examples that wouldn't be possible without acceptance and implementation +of this proposal, as well as the impact the proposed changes would have +on the ecosystem. + +## Backward compatibility + +This adds a new section which cannot meaningfully be converted to any existing sections. + +## Detailed description + +This section should provide a detailed description of the proposed +change. It should include examples of how the new functionality would be +used, intended use-cases and pseudo-code illustrating its use. + +## Alternatives + +The first GNN trained with the intent to be shipped in SMIRNOFF force fields is one that models AM1-BCC partial +charges, so another solution could involve updating the existing `` section instead of adding a new +section altogether. This might involve a new tag in the `` section that distinguishes a particular GNN +from the existing QuacPac and/or `sqm`-based approach. This approach is limiting, however, since GNNs can be used to +predict other charge models than AM1-BCC; if a GNN was trained to ABCG2 or a RESP variant, it's not obvious if that +could drop in to ``. + +Another similar solution could involve not updating the SMIRNOFF specification at all and simply letting +implementations use GNNs in place of QuacPac or `sqm` as currently specified. This in principle produces the same +results, to the extent that the GNN accurately reproduces AM1-BCC charges, but is inconsistent with the philosophy that +the details of a force field must be communicated to users and not hidden from view. + +The solution in this proposal makes clear to any person or tool inspecting a force field that GNNs are a different tool +than existing AM1-BCC charge providers. It attempts to provide enough detail that somebody could re-implement the same +GNN provided weights that are shipped alongside a force field. It allows for future modifications in which a different +underlying charge model is targeted. + +## Discussion + +This section may just be a bullet list including links to any discussions +regarding the proposal: + +- This includes links to mailing list threads and / or relevant GitHub issues. + +## Copyright + +*This template is based upon the [``numpy`` NEP template]( +https://github.com/numpy/numpy/blob/master/doc/neps/nep-template.rst) and the +[``conda-forge`` CFEP template.](https://github.com/conda-forge/cfep/blob/master/cfep-00.md)* + +*All OFF-EPs are explicitly [CC0 1.0 Universal](https://creativecommons.org/publicdomain/zero/1.0/).* diff --git a/docs/index.md b/docs/index.md index 9b3adc6..988dafa 100644 --- a/docs/index.md +++ b/docs/index.md @@ -35,6 +35,8 @@ stages of discussion or completion. ##### Open Proposals +* [OFF-EP XX — GNN Charges](enhancement-proposals/off-ep-00XX.md) + ##### Final Proposals ##### Rejected Proposals From 854f375c6c50ec2dd98f4d87d6a1f9602b138e6c Mon Sep 17 00:00:00 2001 From: "Matthew W. Thompson" Date: Fri, 28 Mar 2025 14:50:51 -0500 Subject: [PATCH 02/23] Add motivation and scope --- docs/enhancement-proposals/off-ep-00XX.md | 22 +++++++++++++++++----- 1 file changed, 17 insertions(+), 5 deletions(-) diff --git a/docs/enhancement-proposals/off-ep-00XX.md b/docs/enhancement-proposals/off-ep-00XX.md index a61c092..1784091 100644 --- a/docs/enhancement-proposals/off-ep-00XX.md +++ b/docs/enhancement-proposals/off-ep-00XX.md @@ -20,11 +20,23 @@ A short description of the change being addressed. ## Motivation and Scope -This section describes the need for the proposed change. It should -describe the existing problem, who it affects, what it is trying to -solve, and why. This section should explicitly address the scope of and -key requirements for the proposed change. -If the proposal is based around changes to software, this section should clearly indicate which package(s) would be changed. +OpenFF NAGL has built on existing work and trained a GNN that reproduced AM1-BCC partial charges for a substantial set of chemistries. Currently, there is not a canonically method by which these charges can be used in a SMIRNOFF force field. Generating partial charges from a GNN and passing them alongside a SMIRNOFF force field as prespecified charges works but is discouraged as this pathway exists only as a convenience to a user. Using an external tool to assign charges also bypasses the need to specify the contents of the GNN sufficient for somebody else to reimplement them. Developers and users for SMIRNOFF force fields would benefit from information about these GNNs being encoded directly into the force field itself. + +This affects any consumer of SMIRNOFF force fields which includes ``. Since it is not a required section, force field developers who choose to use other partial charge methods would not be affected. SMIRNOFF implementations must implement ``, by definition, to use force fields that include this section. Existing force fields cannot use this section, so they are not affected. + +The introduction of this section lays the groundwork for supporting future models with improved performance and scope. This may include, for example: + +- support for more elements +- improved runtime performance on large and/or complex molecule(s) such as biopolymers +- modelling of charge methods other than AM1-BCC +- models employing different architecture, featurization, and/or normalization techniques + +OpenFF has produced a reference implementation of this section in its package OpenFF NAGL. The contents of this proposal derive from the current structure of OpenFF NAGL and the model(s) it implements. If this proposal is accepted, OpenFF NAGL will need minor updates to properly check its GNN implementation against the details encoded in a SMIRNOFF force field, but we expect these changes will be minor because the proposed changes derive directly from this software. The OpenFF Toolkit and Interchange will need minor updates to properly support this section and some edge cases that arise from using this section in combination with other section(s) and tools, such as prespecified charges and virtual site parameter which modify charges. Similar tools which also implement the encoded GNN and/or the SMIRNOFF specification more broadly will need similar updates. + +This proposal does not include changes or interactions with sections that do not modify partial charges, such as ``, ``, ``, ``, etc. + +# TODO: Describe where in the charge method hierarchy this exists +# TODO: Describe interaction(s) with virtual sites ## Usage and Impact From 7a127d0ddc0c114537e91acd1fbade430a6fa771 Mon Sep 17 00:00:00 2001 From: "Matthew W. Thompson" Date: Fri, 28 Mar 2025 15:50:56 -0500 Subject: [PATCH 03/23] Add rough description --- docs/enhancement-proposals/off-ep-00XX.md | 61 +++++++++++++++++++++-- 1 file changed, 58 insertions(+), 3 deletions(-) diff --git a/docs/enhancement-proposals/off-ep-00XX.md b/docs/enhancement-proposals/off-ep-00XX.md index 1784091..52c43c9 100644 --- a/docs/enhancement-proposals/off-ep-00XX.md +++ b/docs/enhancement-proposals/off-ep-00XX.md @@ -52,9 +52,64 @@ This adds a new section which cannot meaningfully be converted to any existing s ## Detailed description -This section should provide a detailed description of the proposed -change. It should include examples of how the new functionality would be -used, intended use-cases and pseudo-code illustrating its use. +This proposal adds a section named `. Version 0.1 of this section includes tags for + +- a file containing model weights +- information about atom and bond features +- a description of the model architecture +- the reactions used for standardization. + +The tag `weights` points to a file that includes models weights. This by convention is a PyTorch `.pt` file, but in principle could be any file that describe model weight as used by the GNN. By their nature, GNNs use many more weights than can reasonably be encoded into an XML file, so pointing to another file is an necessary and unavoidable layer of compleity. + +The tag `AtomFeatures` includes a list of `AtomFeature`s, each of which describes a feature used by the model. Each feature includes descriptive a `name` attribute and other attribute-specific properties. The following attributes are supported: + +- `"atomic_element"`, specifying also (in a comma-separated stringified list) the elements supported by the mode, in the order in which they are one-hot encoded +- `"atom_connectivity"`, specifying also the range of values this feature can take +- `"atom_average_formal_charge"` +- `"atom_in_ring_of_size"`, specifying also an integer `"ring_size"`, the size of a ring that an atom is either in or not in + +- The `AtomFeatures` tag includes an attribute `feature_size` which is a (stringified) integer of the total number of atom features. This should be redundant with the total number of atom features and serves as a consistency check. + +The tag `BondFeatures` structurally mirrors the `AtomFeatures` section, but describes bond featurization with analogously-named elements. + +The tag `Model` describes the model architecture of the GNN. + +The tag `Standardizations` enumerates a number of reactions used for (molecule? output?) standardization. Each `Reaction` containts a SMARTS string that describes a chemical reaction used in (same question) standardization. This tag also has a `max_iter` attribute that specifies the maximum number of iterations used in the normalizaiton process. + +Below is an example `` section: + +```xml + + + + + + + + + + + + + + + + + + + + + + + + + + + + ... + +``` ## Alternatives From ee0e4a5c2bb42f8af9e9bebaa31bd97222efa576 Mon Sep 17 00:00:00 2001 From: "Matthew W. Thompson" Date: Fri, 28 Mar 2025 15:54:38 -0500 Subject: [PATCH 04/23] Add abstract --- docs/enhancement-proposals/off-ep-00XX.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/enhancement-proposals/off-ep-00XX.md b/docs/enhancement-proposals/off-ep-00XX.md index 52c43c9..75ec018 100644 --- a/docs/enhancement-proposals/off-ep-00XX.md +++ b/docs/enhancement-proposals/off-ep-00XX.md @@ -16,7 +16,7 @@ ## Abstract -A short description of the change being addressed. +This change adds a `` tag which describes a graph-convolutional neutral network (GNN) that can be used to assign atomic partial charges. ## Motivation and Scope From 543974e633fac9743abda2e74af4866f4d25b39c Mon Sep 17 00:00:00 2001 From: Matt Thompson Date: Tue, 1 Apr 2025 08:51:36 -0500 Subject: [PATCH 05/23] Apply suggestions from code review Co-authored-by: Lily Wang <31115101+lilyminium@users.noreply.github.com> Co-authored-by: Jeff Wagner --- docs/enhancement-proposals/off-ep-00XX.md | 12 ++++++------ 1 file changed, 6 insertions(+), 6 deletions(-) diff --git a/docs/enhancement-proposals/off-ep-00XX.md b/docs/enhancement-proposals/off-ep-00XX.md index 75ec018..e5e2eeb 100644 --- a/docs/enhancement-proposals/off-ep-00XX.md +++ b/docs/enhancement-proposals/off-ep-00XX.md @@ -16,13 +16,13 @@ ## Abstract -This change adds a `` tag which describes a graph-convolutional neutral network (GNN) that can be used to assign atomic partial charges. +This change adds a `` tag which describes a graph-convolutional neural network (GNN) that can be used to assign atomic partial charges. ## Motivation and Scope -OpenFF NAGL has built on existing work and trained a GNN that reproduced AM1-BCC partial charges for a substantial set of chemistries. Currently, there is not a canonically method by which these charges can be used in a SMIRNOFF force field. Generating partial charges from a GNN and passing them alongside a SMIRNOFF force field as prespecified charges works but is discouraged as this pathway exists only as a convenience to a user. Using an external tool to assign charges also bypasses the need to specify the contents of the GNN sufficient for somebody else to reimplement them. Developers and users for SMIRNOFF force fields would benefit from information about these GNNs being encoded directly into the force field itself. +OpenFF NAGL has built on existing work and trained a GNN that reproduced AM1-BCC partial charges for a substantial set of chemistries. Currently, there is not a canonical method by which these charges can be used in a SMIRNOFF force field. Generating partial charges from a GNN and passing them alongside a SMIRNOFF force field as prespecified charges works but is discouraged as this pathway exists only as a convenience to a user. Using an external tool to assign charges also bypasses the need to specify the contents of the GNN sufficient for somebody else to reimplement them. Developers and users for SMIRNOFF force fields would benefit from information about these GNNs being encoded directly into the force field itself. -This affects any consumer of SMIRNOFF force fields which includes ``. Since it is not a required section, force field developers who choose to use other partial charge methods would not be affected. SMIRNOFF implementations must implement ``, by definition, to use force fields that include this section. Existing force fields cannot use this section, so they are not affected. +The changes outlined in this proposal affect any consumer of SMIRNOFF force fields which include ``, which is likely to be the case for `openff-2.3.0` and beyond. Since it is not a required section, force field developers who choose to use other partial charge methods would not be affected. SMIRNOFF implementations must implement ``, by definition, to use force fields that include this section. Existing force fields cannot use this section, so they are not affected. The introduction of this section lays the groundwork for supporting future models with improved performance and scope. This may include, for example: @@ -59,11 +59,11 @@ This proposal adds a section named `. Version 0.1 of this section i - a description of the model architecture - the reactions used for standardization. -The tag `weights` points to a file that includes models weights. This by convention is a PyTorch `.pt` file, but in principle could be any file that describe model weight as used by the GNN. By their nature, GNNs use many more weights than can reasonably be encoded into an XML file, so pointing to another file is an necessary and unavoidable layer of compleity. +The tag `weights` points to a file that includes models weights. This by convention is a PyTorch `.pt` file, but in principle could be any file that describe model weight as used by the GNN. By their nature, GNNs use many more weights than can reasonably be encoded into an XML file, so pointing to another file is an necessary and unavoidable layer of complexity. The tag `AtomFeatures` includes a list of `AtomFeature`s, each of which describes a feature used by the model. Each feature includes descriptive a `name` attribute and other attribute-specific properties. The following attributes are supported: -- `"atomic_element"`, specifying also (in a comma-separated stringified list) the elements supported by the mode, in the order in which they are one-hot encoded +- `"atomic_element"`, specifying also (in a comma-separated stringified list) the elements supported by the model, in the order in which they are one-hot encoded - `"atom_connectivity"`, specifying also the range of values this feature can take - `"atom_average_formal_charge"` - `"atom_in_ring_of_size"`, specifying also an integer `"ring_size"`, the size of a ring that an atom is either in or not in @@ -74,7 +74,7 @@ The tag `BondFeatures` structurally mirrors the `AtomFeatures` section, but desc The tag `Model` describes the model architecture of the GNN. -The tag `Standardizations` enumerates a number of reactions used for (molecule? output?) standardization. Each `Reaction` containts a SMARTS string that describes a chemical reaction used in (same question) standardization. This tag also has a `max_iter` attribute that specifies the maximum number of iterations used in the normalizaiton process. +The tag `Standardizations` enumerates a number of reactions used for molecule standardization. Each `Reaction` contains a SMARTS string that describes a chemical reaction used in molecule standardization. This tag also has a `max_iter` attribute that specifies the maximum number of iterations used in the normalization process. Below is an example `` section: From 469f5f62e85c6428b1d3df4cceb1db2e378c3c85 Mon Sep 17 00:00:00 2001 From: Matt Thompson Date: Tue, 1 Apr 2025 08:51:54 -0500 Subject: [PATCH 06/23] Apply suggestions from code review Co-authored-by: Jeff Wagner --- docs/enhancement-proposals/off-ep-00XX.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/enhancement-proposals/off-ep-00XX.md b/docs/enhancement-proposals/off-ep-00XX.md index e5e2eeb..4774f46 100644 --- a/docs/enhancement-proposals/off-ep-00XX.md +++ b/docs/enhancement-proposals/off-ep-00XX.md @@ -107,7 +107,7 @@ Below is an example `` section: ... - ``` From fadad40a3f1c17942e41dd2ef3645346e366bef6 Mon Sep 17 00:00:00 2001 From: Jeff Wagner Date: Wed, 2 Apr 2025 09:04:19 -0700 Subject: [PATCH 07/23] Apply suggestions from code review --- docs/enhancement-proposals/off-ep-00XX.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/enhancement-proposals/off-ep-00XX.md b/docs/enhancement-proposals/off-ep-00XX.md index 4774f46..c2bd9d7 100644 --- a/docs/enhancement-proposals/off-ep-00XX.md +++ b/docs/enhancement-proposals/off-ep-00XX.md @@ -48,7 +48,7 @@ on the ecosystem. ## Backward compatibility -This adds a new section which cannot meaningfully be converted to any existing sections. +This proposal adds a new section which does not affect backwards compatibility. While in practice we intend for the GNNCharges section to become the new default charge method in our future flagship force fields, we do not propose that existing force fields with the ToolkitAM1BCC section be assumed to be compatible with/automatically upgrade-able to GNNCharges sections. ## Detailed description @@ -64,7 +64,7 @@ The tag `weights` points to a file that includes models weights. This by convent The tag `AtomFeatures` includes a list of `AtomFeature`s, each of which describes a feature used by the model. Each feature includes descriptive a `name` attribute and other attribute-specific properties. The following attributes are supported: - `"atomic_element"`, specifying also (in a comma-separated stringified list) the elements supported by the model, in the order in which they are one-hot encoded -- `"atom_connectivity"`, specifying also the range of values this feature can take +- `"atom_connectivity"`, referring to the number of unique bonds this atom is involved in (not considering bond order), specifying the range of values this feature can take. - `"atom_average_formal_charge"` - `"atom_in_ring_of_size"`, specifying also an integer `"ring_size"`, the size of a ring that an atom is either in or not in From d66c07320ec16423e75ca152eac3e1e2adac6a08 Mon Sep 17 00:00:00 2001 From: Jeff Wagner Date: Thu, 3 Apr 2025 10:49:00 -0700 Subject: [PATCH 08/23] First round of updates --- docs/enhancement-proposals/off-ep-00XX.md | 31 +++++++++++++++-------- 1 file changed, 21 insertions(+), 10 deletions(-) diff --git a/docs/enhancement-proposals/off-ep-00XX.md b/docs/enhancement-proposals/off-ep-00XX.md index c2bd9d7..7d6d75c 100644 --- a/docs/enhancement-proposals/off-ep-00XX.md +++ b/docs/enhancement-proposals/off-ep-00XX.md @@ -16,13 +16,13 @@ ## Abstract -This change adds a `` tag which describes a graph-convolutional neural network (GNN) that can be used to assign atomic partial charges. +This change adds a `` tag which describes a graph-convolutional neural network (GNN) that can be used to assign atomic partial charges. ## Motivation and Scope OpenFF NAGL has built on existing work and trained a GNN that reproduced AM1-BCC partial charges for a substantial set of chemistries. Currently, there is not a canonical method by which these charges can be used in a SMIRNOFF force field. Generating partial charges from a GNN and passing them alongside a SMIRNOFF force field as prespecified charges works but is discouraged as this pathway exists only as a convenience to a user. Using an external tool to assign charges also bypasses the need to specify the contents of the GNN sufficient for somebody else to reimplement them. Developers and users for SMIRNOFF force fields would benefit from information about these GNNs being encoded directly into the force field itself. -The changes outlined in this proposal affect any consumer of SMIRNOFF force fields which include ``, which is likely to be the case for `openff-2.3.0` and beyond. Since it is not a required section, force field developers who choose to use other partial charge methods would not be affected. SMIRNOFF implementations must implement ``, by definition, to use force fields that include this section. Existing force fields cannot use this section, so they are not affected. +The changes outlined in this proposal affect any consumer of SMIRNOFF force fields which include ``, which is likely to be the case for `openff-2.3.0` and beyond. Since it is not a required section, force field developers who choose to use other partial charge methods would not be affected. SMIRNOFF implementations must implement ``, by definition, to use force fields that include this section. Existing force fields cannot use this section, so they are not affected. The introduction of this section lays the groundwork for supporting future models with improved performance and scope. This may include, for example: @@ -35,8 +35,16 @@ OpenFF has produced a reference implementation of this section in its package Op This proposal does not include changes or interactions with sections that do not modify partial charges, such as ``, ``, ``, ``, etc. -# TODO: Describe where in the charge method hierarchy this exists -# TODO: Describe interaction(s) with virtual sites +`NAGLCharges` fits into the current charge hierarchy as follows (with methods high in the list taking priority over those lower): + +- Pre-specified charges (charge_from_molecules) +- Library charges +- GNN charges +- ToolkitAM1BCC charges +- ChargeIncrementModel charges + + +Future iterations of this section may include direct assignment of partial charges to virtual sites. However in this initial version, there is no special behavior around virtual sites. If the `NAGLCharges` section is present in a force field with virtual sites, NAGL is used to assign initial charges to the molecule, and then virtual sites apply their charge increments on top of those initial charges. ## Usage and Impact @@ -48,11 +56,11 @@ on the ecosystem. ## Backward compatibility -This proposal adds a new section which does not affect backwards compatibility. While in practice we intend for the GNNCharges section to become the new default charge method in our future flagship force fields, we do not propose that existing force fields with the ToolkitAM1BCC section be assumed to be compatible with/automatically upgrade-able to GNNCharges sections. +This proposal adds a new section which does not affect backwards compatibility. While in practice we intend for the NAGLCharges section to become the new default charge method in our future flagship force fields, we do not propose that existing force fields with the ToolkitAM1BCC section be assumed to be compatible with/automatically upgrade-able to NAGLCharges sections. ## Detailed description -This proposal adds a section named `. Version 0.1 of this section includes tags for +This proposal adds a section named `. The initial version of this section, 0.3, includes tags for - a file containing model weights - information about atom and bond features @@ -61,6 +69,8 @@ This proposal adds a section named `. Version 0.1 of this section i The tag `weights` points to a file that includes models weights. This by convention is a PyTorch `.pt` file, but in principle could be any file that describe model weight as used by the GNN. By their nature, GNNs use many more weights than can reasonably be encoded into an XML file, so pointing to another file is an necessary and unavoidable layer of complexity. +Both of the following tags - `AtomFeatures` and `BondFeatures` - operate on a "resonance-averaged" representation of the molecule. This representation is generated by enumerating all resonance forms of the molecule using the method described in [Gilson et al.](https://pubs.acs.org/doi/10.1021/ci034148o), and then averaging the formal charges and bond orders to get a single "resonance-averaged" molecule representation. Importantly, this means that there may be noninteger formal charges and bond orders fed into the network. + The tag `AtomFeatures` includes a list of `AtomFeature`s, each of which describes a feature used by the model. Each feature includes descriptive a `name` attribute and other attribute-specific properties. The following attributes are supported: - `"atomic_element"`, specifying also (in a comma-separated stringified list) the elements supported by the model, in the order in which they are one-hot encoded @@ -71,15 +81,16 @@ The tag `AtomFeatures` includes a list of `AtomFeature`s, each of which describe - The `AtomFeatures` tag includes an attribute `feature_size` which is a (stringified) integer of the total number of atom features. This should be redundant with the total number of atom features and serves as a consistency check. The tag `BondFeatures` structurally mirrors the `AtomFeatures` section, but describes bond featurization with analogously-named elements. +- (need to talk to Lily for details here) The tag `Model` describes the model architecture of the GNN. The tag `Standardizations` enumerates a number of reactions used for molecule standardization. Each `Reaction` contains a SMARTS string that describes a chemical reaction used in molecule standardization. This tag also has a `max_iter` attribute that specifies the maximum number of iterations used in the normalization process. -Below is an example `` section: +Below is an example `` section: ```xml - + @@ -101,14 +112,14 @@ Below is an example `` section: - + ... - + ``` ## Alternatives From 66949cd442d8c44fbdf6f37cd654200abf52cccb Mon Sep 17 00:00:00 2001 From: Jeff Wagner Date: Mon, 7 Apr 2025 10:41:40 -0700 Subject: [PATCH 09/23] more details and clarification --- docs/enhancement-proposals/off-ep-00XX.md | 71 ++++++++--------------- 1 file changed, 25 insertions(+), 46 deletions(-) diff --git a/docs/enhancement-proposals/off-ep-00XX.md b/docs/enhancement-proposals/off-ep-00XX.md index 7d6d75c..b8f6ad1 100644 --- a/docs/enhancement-proposals/off-ep-00XX.md +++ b/docs/enhancement-proposals/off-ep-00XX.md @@ -2,7 +2,7 @@ **Status:** Draft -**Authors:** Lily Wang +**Authors:** Lily Wang, Matt Thompson, Jeff Wagner **Stakeholders:** <list of stakeholders that would be affected by this proposal> @@ -20,20 +20,13 @@ This change adds a `` tag which describes a graph-convolutional neu ## Motivation and Scope -OpenFF NAGL has built on existing work and trained a GNN that reproduced AM1-BCC partial charges for a substantial set of chemistries. Currently, there is not a canonical method by which these charges can be used in a SMIRNOFF force field. Generating partial charges from a GNN and passing them alongside a SMIRNOFF force field as prespecified charges works but is discouraged as this pathway exists only as a convenience to a user. Using an external tool to assign charges also bypasses the need to specify the contents of the GNN sufficient for somebody else to reimplement them. Developers and users for SMIRNOFF force fields would benefit from information about these GNNs being encoded directly into the force field itself. +**Motivation:** OpenFF NAGL has built on existing work and trained a GNN that reproduced AM1-BCC ELF10 partial charges for a substantial set of chemistries. Currently, there is not a canonical method by which these GNN-provided charges can be requested in a SMIRNOFF force field. At the moment, a user can generate partial charges from a GNN and pass them to `create_interchange` or `create_openmm_system` alongside a SMIRNOFF force field as prespecified charges. To use GNNs in a flagship force field, this approach is not sufficient, and the SMIRNOFF specification must be updated to include enough information that an external developer have sufficient guidance to implement the charge method themselves. -The changes outlined in this proposal affect any consumer of SMIRNOFF force fields which include ``, which is likely to be the case for `openff-2.3.0` and beyond. Since it is not a required section, force field developers who choose to use other partial charge methods would not be affected. SMIRNOFF implementations must implement ``, by definition, to use force fields that include this section. Existing force fields cannot use this section, so they are not affected. +**Who this EP would affect:** The changes outlined in this proposal affect any consumer of SMIRNOFF force fields which include ``, which is likely to be the case for `openff-2.3.0` and beyond. Since it is not a required section, force field developers who choose to use other partial charge methods would not be affected. SMIRNOFF implementations must implement ``, by definition, to use force fields that include this section. Existing force fields cannot use this section, so they are not affected. -The introduction of this section lays the groundwork for supporting future models with improved performance and scope. This may include, for example: +**Changes needed:** The contents of this proposal derive from the current structure of OpenFF NAGL and the model(s) it implements. If this proposal is accepted, OpenFF NAGL will need minor updates to properly check its GNN implementation against the details encoded in a SMIRNOFF force field, but we expect these changes will be minor because the proposed changes derive directly from this software. The OpenFF Toolkit and Interchange will need minor updates to properly support this section and some edge cases that arise from using this section in combination with other section(s) and tools, such as prespecified charges and virtual site parameter which modify charges. Similar tools which also implement the encoded GNN and/or the SMIRNOFF specification more broadly will need similar updates. -- support for more elements -- improved runtime performance on large and/or complex molecule(s) such as biopolymers -- modelling of charge methods other than AM1-BCC -- models employing different architecture, featurization, and/or normalization techniques - -OpenFF has produced a reference implementation of this section in its package OpenFF NAGL. The contents of this proposal derive from the current structure of OpenFF NAGL and the model(s) it implements. If this proposal is accepted, OpenFF NAGL will need minor updates to properly check its GNN implementation against the details encoded in a SMIRNOFF force field, but we expect these changes will be minor because the proposed changes derive directly from this software. The OpenFF Toolkit and Interchange will need minor updates to properly support this section and some edge cases that arise from using this section in combination with other section(s) and tools, such as prespecified charges and virtual site parameter which modify charges. Similar tools which also implement the encoded GNN and/or the SMIRNOFF specification more broadly will need similar updates. - -This proposal does not include changes or interactions with sections that do not modify partial charges, such as ``, ``, ``, ``, etc. +**Interaction with other sections:** This proposal does not include changes or interactions with sections that do not modify partial charges, such as ``, ``, ``, ``, etc. `NAGLCharges` fits into the current charge hierarchy as follows (with methods high in the list taking priority over those lower): @@ -43,8 +36,7 @@ This proposal does not include changes or interactions with sections that do not - ToolkitAM1BCC charges - ChargeIncrementModel charges - -Future iterations of this section may include direct assignment of partial charges to virtual sites. However in this initial version, there is no special behavior around virtual sites. If the `NAGLCharges` section is present in a force field with virtual sites, NAGL is used to assign initial charges to the molecule, and then virtual sites apply their charge increments on top of those initial charges. +The initial `0.3` version of the `NAGLCharges` section does have special interactions with virtual sites, though future versions of this section may include direct assignment of partial charges to virtual sites. If the `NAGLCharges` section is present in a force field with virtual sites, NAGL is used to assign initial charges to the molecule, and then virtual sites apply their charge increments on top of those initial charges. ## Usage and Impact @@ -60,32 +52,32 @@ This proposal adds a new section which does not affect backwards compatibility. ## Detailed description -This proposal adds a section named `. The initial version of this section, 0.3, includes tags for +This proposal adds a section named `. The initial version of this section, 0.3, is defined as follows: -- a file containing model weights -- information about atom and bond features -- a description of the model architecture -- the reactions used for standardization. +The `NAGLCharges` top-level element defines that the force field should use the `openff-nagl` software to assign partial charges. It contains the following attributes: -The tag `weights` points to a file that includes models weights. This by convention is a PyTorch `.pt` file, but in principle could be any file that describe model weight as used by the GNN. By their nature, GNNs use many more weights than can reasonably be encoded into an XML file, so pointing to another file is an necessary and unavoidable layer of complexity. +- `version` +- `weights` -Both of the following tags - `AtomFeatures` and `BondFeatures` - operate on a "resonance-averaged" representation of the molecule. This representation is generated by enumerating all resonance forms of the molecule using the method described in [Gilson et al.](https://pubs.acs.org/doi/10.1021/ci034148o), and then averaging the formal charges and bond orders to get a single "resonance-averaged" molecule representation. Importantly, this means that there may be noninteger formal charges and bond orders fed into the network. +The attribute `weights` points to a file that includes models weights. This by convention is a PyTorch `.pt` file containing additional information about the model that is read by the `openff-nagl` software. By their nature, GNNs use many more weights than can reasonably be encoded into an XML file, so pointing to an external file is a necessary and unavoidable layer of complexity. -The tag `AtomFeatures` includes a list of `AtomFeature`s, each of which describes a feature used by the model. Each feature includes descriptive a `name` attribute and other attribute-specific properties. The following attributes are supported: +The `NAGLCharges` top-level element contains the following elements: -- `"atomic_element"`, specifying also (in a comma-separated stringified list) the elements supported by the model, in the order in which they are one-hot encoded -- `"atom_connectivity"`, referring to the number of unique bonds this atom is involved in (not considering bond order), specifying the range of values this feature can take. -- `"atom_average_formal_charge"` -- `"atom_in_ring_of_size"`, specifying also an integer `"ring_size"`, the size of a ring that an atom is either in or not in +- `AtomFeatures`: information about atom features +- `BondFeatures`: information about bond features -- The `AtomFeatures` tag includes an attribute `feature_size` which is a (stringified) integer of the total number of atom features. This should be redundant with the total number of atom features and serves as a consistency check. +Both of the inner elements - `AtomFeatures` and `BondFeatures` - operate on a "resonance-averaged" representation of the molecule. This representation is generated by enumerating all resonance forms of the molecule using the method described in [Gilson et al.](https://pubs.acs.org/doi/10.1021/ci034148o), and then averaging the formal charges and bond orders to get a single "resonance-averaged" molecule representation. Importantly, this means that there may be noninteger formal charges and bond orders fed into the network. -The tag `BondFeatures` structurally mirrors the `AtomFeatures` section, but describes bond featurization with analogously-named elements. -- (need to talk to Lily for details here) +The second-level element `AtomFeatures` includes a list of `AtomFeature` elements, each of which describes a feature used by the model. Each feature includes a descriptive `name` attribute and other attribute-specific properties. The following attributes are supported: + +- `"atomic_element"`, which represents the elemental symbol of an atom, containing the `categories` attribute which specifies (in a comma-separated stringified list) the elements supported by the model, in the order in which they are one-hot encoded. +- `"atom_connectivity"`, which represents the number of unique bonds an atom is involved in (not considering bond order), containing the `categories` attribute which specifies (in a comma-separated stringified list) the per-atom bond counts supported by this model and the order in which they are one-hot encoded. +- `"atom_average_formal_charge"`, corresponding to the resonance-averaged formal charge as described above, containing no attributes. +- `"atom_in_ring_of_size"`, which represents the ring membership of an atom, containing the `"ring_size"` attribute. -The tag `Model` describes the model architecture of the GNN. -The tag `Standardizations` enumerates a number of reactions used for molecule standardization. Each `Reaction` contains a SMARTS string that describes a chemical reaction used in molecule standardization. This tag also has a `max_iter` attribute that specifies the maximum number of iterations used in the normalization process. +The tag `BondFeatures` structurally mirrors the `AtomFeatures` section, but describes bond featurization with analogously-named elements. +- (need to talk to Lily for details here) Below is an example `` section: @@ -93,7 +85,7 @@ Below is an example `` section: - + @@ -106,19 +98,6 @@ Below is an example `` section: - - - - - - - - - - - - ... - ``` @@ -131,7 +110,7 @@ from the existing QuacPac and/or `sqm`-based approach. This approach is limiting predict other charge models than AM1-BCC; if a GNN was trained to ABCG2 or a RESP variant, it's not obvious if that could drop in to ``. -Another similar solution could involve not updating the SMIRNOFF specification at all and simply letting +Another similar solution could involve not updating the `ToolkitAM1BCC` specification at all and simply letting implementations use GNNs in place of QuacPac or `sqm` as currently specified. This in principle produces the same results, to the extent that the GNN accurately reproduces AM1-BCC charges, but is inconsistent with the philosophy that the details of a force field must be communicated to users and not hidden from view. From 737c850a292e4704d2207ac06d8ab5d3352db635 Mon Sep 17 00:00:00 2001 From: Jeff Wagner Date: Mon, 7 Apr 2025 13:32:46 -0700 Subject: [PATCH 10/23] more edits --- docs/enhancement-proposals/off-ep-00XX.md | 31 ++++++++--------------- 1 file changed, 10 insertions(+), 21 deletions(-) diff --git a/docs/enhancement-proposals/off-ep-00XX.md b/docs/enhancement-proposals/off-ep-00XX.md index b8f6ad1..6a2032b 100644 --- a/docs/enhancement-proposals/off-ep-00XX.md +++ b/docs/enhancement-proposals/off-ep-00XX.md @@ -38,42 +38,34 @@ This change adds a `` tag which describes a graph-convolutional neu The initial `0.3` version of the `NAGLCharges` section does have special interactions with virtual sites, though future versions of this section may include direct assignment of partial charges to virtual sites. If the `NAGLCharges` section is present in a force field with virtual sites, NAGL is used to assign initial charges to the molecule, and then virtual sites apply their charge increments on top of those initial charges. -## Usage and Impact - -This section describes how users of the ecosystem will use features -described in this SMIRNOFF EP. It should be comprised mainly of code / file -examples that wouldn't be possible without acceptance and implementation -of this proposal, as well as the impact the proposed changes would have -on the ecosystem. - ## Backward compatibility This proposal adds a new section which does not affect backwards compatibility. While in practice we intend for the NAGLCharges section to become the new default charge method in our future flagship force fields, we do not propose that existing force fields with the ToolkitAM1BCC section be assumed to be compatible with/automatically upgrade-able to NAGLCharges sections. ## Detailed description -This proposal adds a section named `. The initial version of this section, 0.3, is defined as follows: +This proposal adds a section named `. The proposed initial version of this section (0.3) is as follows, and will be added verbatim to the specification if this EP is approved: -The `NAGLCharges` top-level element defines that the force field should use the `openff-nagl` software to assign partial charges. It contains the following attributes: +The `NAGLCharges` section-level element defines that the force field should use the `openff-nagl` software to assign partial charges. It contains the following attributes: - `version` - `weights` -The attribute `weights` points to a file that includes models weights. This by convention is a PyTorch `.pt` file containing additional information about the model that is read by the `openff-nagl` software. By their nature, GNNs use many more weights than can reasonably be encoded into an XML file, so pointing to an external file is a necessary and unavoidable layer of complexity. +The attribute `weights` points to a file that includes model weights. This by convention is a PyTorch `.pt` file containing additional information about the model that is read by the `openff-nagl` software. By their nature, GNNs use many more weights than can reasonably be encoded into an XML file, so pointing to an external file is a necessary and unavoidable layer of complexity. The `NAGLCharges` top-level element contains the following elements: - `AtomFeatures`: information about atom features - `BondFeatures`: information about bond features -Both of the inner elements - `AtomFeatures` and `BondFeatures` - operate on a "resonance-averaged" representation of the molecule. This representation is generated by enumerating all resonance forms of the molecule using the method described in [Gilson et al.](https://pubs.acs.org/doi/10.1021/ci034148o), and then averaging the formal charges and bond orders to get a single "resonance-averaged" molecule representation. Importantly, this means that there may be noninteger formal charges and bond orders fed into the network. +Both of these elements - `AtomFeatures` and `BondFeatures` - operate on a "resonance-averaged" representation of the molecule. This representation is generated by enumerating all resonance forms of the molecule using the method described in [Gilson et al.](https://pubs.acs.org/doi/10.1021/ci034148o), and then averaging the formal charges and bond orders to get a single "resonance-averaged" molecule representation. Importantly, this means that there may be noninteger formal charges and bond orders fed into the network. -The second-level element `AtomFeatures` includes a list of `AtomFeature` elements, each of which describes a feature used by the model. Each feature includes a descriptive `name` attribute and other attribute-specific properties. The following attributes are supported: +The `AtomFeatures` element has no attributes, and contains a list of `AtomFeature` elements, each of which describes a feature used by the model. Each feature includes a descriptive `name` attribute, and may support additional attributes based on the name, listed as follows. -- `"atomic_element"`, which represents the elemental symbol of an atom, containing the `categories` attribute which specifies (in a comma-separated stringified list) the elements supported by the model, in the order in which they are one-hot encoded. -- `"atom_connectivity"`, which represents the number of unique bonds an atom is involved in (not considering bond order), containing the `categories` attribute which specifies (in a comma-separated stringified list) the per-atom bond counts supported by this model and the order in which they are one-hot encoded. -- `"atom_average_formal_charge"`, corresponding to the resonance-averaged formal charge as described above, containing no attributes. -- `"atom_in_ring_of_size"`, which represents the ring membership of an atom, containing the `"ring_size"` attribute. +- `name="atomic_element"` represents the elemental symbol of an atom, containing the `categories` attribute which specifies (in a comma-separated stringified list) the elements supported by the model, in the order in which they are one-hot encoded. +- `name="atom_connectivity"` represents the number of unique bonds an atom is involved in (not considering bond order), containing the `categories` attribute which specifies (in a comma-separated stringified list) the per-atom bond counts supported by this model and the order in which they are one-hot encoded. +- `name="atom_average_formal_charge"` represents the resonance-averaged formal charge as described above (in units of elementary charge), containing no attributes. +- `name="atom_in_ring_of_size"` represents the ring membership of an atom, where the ring size is specified by the `"ring_size"` attribute. The tag `BondFeatures` structurally mirrors the `AtomFeatures` section, but describes bond featurization with analogously-named elements. @@ -83,10 +75,7 @@ Below is an example `` section: ```xml - - - @@ -125,7 +114,7 @@ underlying charge model is targeted. This section may just be a bullet list including links to any discussions regarding the proposal: -- This includes links to mailing list threads and / or relevant GitHub issues. +- [Original SMIRNOFF EP](https://github.com/openforcefield/standards/pull/71) ## Copyright From 988a5ce2f86b3cf51919e74c9c718ee7c496c9ae Mon Sep 17 00:00:00 2001 From: Jeff Wagner Date: Thu, 10 Apr 2025 14:00:40 -0400 Subject: [PATCH 11/23] simplify further, basically say everything is in the pt file --- docs/enhancement-proposals/off-ep-00XX.md | 39 +++-------------------- 1 file changed, 4 insertions(+), 35 deletions(-) diff --git a/docs/enhancement-proposals/off-ep-00XX.md b/docs/enhancement-proposals/off-ep-00XX.md index 6a2032b..25c292b 100644 --- a/docs/enhancement-proposals/off-ep-00XX.md +++ b/docs/enhancement-proposals/off-ep-00XX.md @@ -16,13 +16,13 @@ ## Abstract -This change adds a `` tag which describes a graph-convolutional neural network (GNN) that can be used to assign atomic partial charges. +This change adds a `` section which calls for the NAGL program to be used to assign atomic partial charges. ## Motivation and Scope -**Motivation:** OpenFF NAGL has built on existing work and trained a GNN that reproduced AM1-BCC ELF10 partial charges for a substantial set of chemistries. Currently, there is not a canonical method by which these GNN-provided charges can be requested in a SMIRNOFF force field. At the moment, a user can generate partial charges from a GNN and pass them to `create_interchange` or `create_openmm_system` alongside a SMIRNOFF force field as prespecified charges. To use GNNs in a flagship force field, this approach is not sufficient, and the SMIRNOFF specification must be updated to include enough information that an external developer have sufficient guidance to implement the charge method themselves. +**Motivation:** OpenFF NAGL has built on existing work and trained a graph-convolutional neural network (GNN) that reproduces AM1-BCC ELF10 partial charges for a substantial set of chemistries. Currently, there is not a canonical method by which these GNN-provided charges can be requested in a SMIRNOFF force field. At the moment, a user can generate partial charges from a GNN and pass them to `create_interchange` or `create_openmm_system` alongside a SMIRNOFF force field as prespecified charges. To use GNNs in a flagship force field, this approach is not sufficient, and the SMIRNOFF specification must be updated to include enough information that an external developer could get the same charges themselves. -**Who this EP would affect:** The changes outlined in this proposal affect any consumer of SMIRNOFF force fields which include ``, which is likely to be the case for `openff-2.3.0` and beyond. Since it is not a required section, force field developers who choose to use other partial charge methods would not be affected. SMIRNOFF implementations must implement ``, by definition, to use force fields that include this section. Existing force fields cannot use this section, so they are not affected. +**Who this EP would affect:** The changes outlined in this proposal affect any consumer of SMIRNOFF force fields that include ``, which is likely to be the case for `openff-2.3.0` and beyond. Since it is not a required section, force field developers who choose to use other partial charge methods would not be affected. SMIRNOFF implementations must implement ``, by definition, to use force fields that include this section. Existing force fields cannot use this section, so they are not affected. **Changes needed:** The contents of this proposal derive from the current structure of OpenFF NAGL and the model(s) it implements. If this proposal is accepted, OpenFF NAGL will need minor updates to properly check its GNN implementation against the details encoded in a SMIRNOFF force field, but we expect these changes will be minor because the proposed changes derive directly from this software. The OpenFF Toolkit and Interchange will need minor updates to properly support this section and some edge cases that arise from using this section in combination with other section(s) and tools, such as prespecified charges and virtual site parameter which modify charges. Similar tools which also implement the encoded GNN and/or the SMIRNOFF specification more broadly will need similar updates. @@ -53,41 +53,10 @@ The `NAGLCharges` section-level element defines that the force field should use The attribute `weights` points to a file that includes model weights. This by convention is a PyTorch `.pt` file containing additional information about the model that is read by the `openff-nagl` software. By their nature, GNNs use many more weights than can reasonably be encoded into an XML file, so pointing to an external file is a necessary and unavoidable layer of complexity. -The `NAGLCharges` top-level element contains the following elements: - -- `AtomFeatures`: information about atom features -- `BondFeatures`: information about bond features - -Both of these elements - `AtomFeatures` and `BondFeatures` - operate on a "resonance-averaged" representation of the molecule. This representation is generated by enumerating all resonance forms of the molecule using the method described in [Gilson et al.](https://pubs.acs.org/doi/10.1021/ci034148o), and then averaging the formal charges and bond orders to get a single "resonance-averaged" molecule representation. Importantly, this means that there may be noninteger formal charges and bond orders fed into the network. - -The `AtomFeatures` element has no attributes, and contains a list of `AtomFeature` elements, each of which describes a feature used by the model. Each feature includes a descriptive `name` attribute, and may support additional attributes based on the name, listed as follows. - -- `name="atomic_element"` represents the elemental symbol of an atom, containing the `categories` attribute which specifies (in a comma-separated stringified list) the elements supported by the model, in the order in which they are one-hot encoded. -- `name="atom_connectivity"` represents the number of unique bonds an atom is involved in (not considering bond order), containing the `categories` attribute which specifies (in a comma-separated stringified list) the per-atom bond counts supported by this model and the order in which they are one-hot encoded. -- `name="atom_average_formal_charge"` represents the resonance-averaged formal charge as described above (in units of elementary charge), containing no attributes. -- `name="atom_in_ring_of_size"` represents the ring membership of an atom, where the ring size is specified by the `"ring_size"` attribute. - - -The tag `BondFeatures` structurally mirrors the `AtomFeatures` section, but describes bond featurization with analogously-named elements. -- (need to talk to Lily for details here) - Below is an example `` section: ```xml - - - - - - - - - - - - - - + ``` ## Alternatives From 61db77d1625a3ee37ef8f02a91fc6b0132097f32 Mon Sep 17 00:00:00 2001 From: Jeff Wagner Date: Tue, 15 Apr 2025 09:05:14 -0700 Subject: [PATCH 12/23] Cleanups --- docs/enhancement-proposals/off-ep-00XX.md | 23 +++++++++++------------ 1 file changed, 11 insertions(+), 12 deletions(-) diff --git a/docs/enhancement-proposals/off-ep-00XX.md b/docs/enhancement-proposals/off-ep-00XX.md index 25c292b..4f3d11a 100644 --- a/docs/enhancement-proposals/off-ep-00XX.md +++ b/docs/enhancement-proposals/off-ep-00XX.md @@ -6,17 +6,17 @@ **Stakeholders:** <list of stakeholders that would be affected by this proposal> -**Acceptance criteria:** +**Acceptance criteria:** Unanimity (4 approving reviews) or partial support (2 approvals and 2 week period with no reviews requesting changes)[https://openforcefield.atlassian.net/wiki/spaces/MEET/pages/2638774273/09-05-23+SMIRNOFF+Committee+Meeting] -**Created:** <date created> +**Created:** 2025-04-01 -**Discussion:** <link to the PR / issue where proposal is being discussed> +**Discussion:** [PR #71](https://github.com/openforcefield/standards/pull/71) **Implementation:** <link an example / reference implementation of the proposal> ## Abstract -This change adds a `` section which calls for the NAGL program to be used to assign atomic partial charges. +This change adds a `` section which calls for a specific NAGL model to be used to assign atomic partial charges. ## Motivation and Scope @@ -36,7 +36,7 @@ This change adds a `` section which calls for the NAGL program to b - ToolkitAM1BCC charges - ChargeIncrementModel charges -The initial `0.3` version of the `NAGLCharges` section does have special interactions with virtual sites, though future versions of this section may include direct assignment of partial charges to virtual sites. If the `NAGLCharges` section is present in a force field with virtual sites, NAGL is used to assign initial charges to the molecule, and then virtual sites apply their charge increments on top of those initial charges. +The initial `0.3` version of the `NAGLCharges` section does have special interactions with virtual sites, though future versions of this section may include direct assignment of partial charges to virtual sites. But for the 0.3 version of this section proposed by this EP, the behavior will be that, if the `NAGLCharges` section is present in a force field with virtual sites, NAGL is used to assign initial charges to the molecule, and then virtual sites apply their charge increments on top of those initial charges. ## Backward compatibility @@ -46,19 +46,21 @@ This proposal adds a new section which does not affect backwards compatibility. This proposal adds a section named `. The proposed initial version of this section (0.3) is as follows, and will be added verbatim to the specification if this EP is approved: -The `NAGLCharges` section-level element defines that the force field should use the `openff-nagl` software to assign partial charges. It contains the following attributes: +The `NAGLCharges` section-level element defines that the force field should use a sepcific model file in conjunction with the `openff-nagl` software to assign partial charges. It contains the following attributes: - `version` -- `weights` +- `model_file` -The attribute `weights` points to a file that includes model weights. This by convention is a PyTorch `.pt` file containing additional information about the model that is read by the `openff-nagl` software. By their nature, GNNs use many more weights than can reasonably be encoded into an XML file, so pointing to an external file is a necessary and unavoidable layer of complexity. +The attribute `model_file` points to a file that includes model weights and other information. This by convention is a PyTorch `.pt` file, extended to contain additional information about the model that is read by the `openff-nagl` software. By their nature, GNNs use many more weights than can reasonably be encoded into an XML file, so pointing to an external file is a necessary and unavoidable layer of complexity. Below is an example `` section: ```xml - + ``` +This section only specifies a model file name, not a version of the NAGL software. The NAGL software is responsible for rejecting model files which it can not correctly interpret. + ## Alternatives The first GNN trained with the intent to be shipped in SMIRNOFF force fields is one that models AM1-BCC partial @@ -80,9 +82,6 @@ underlying charge model is targeted. ## Discussion -This section may just be a bullet list including links to any discussions -regarding the proposal: - - [Original SMIRNOFF EP](https://github.com/openforcefield/standards/pull/71) ## Copyright From dfb76d632f43c872777c94f6afb32c916bfb4ae1 Mon Sep 17 00:00:00 2001 From: Jeff Wagner Date: Fri, 25 Apr 2025 15:00:06 -0700 Subject: [PATCH 13/23] update with charge method precendence, small fixes --- .../{off-ep-00XX.md => off-ep-0011.md} | 17 ++++++++----- docs/standards/smirnoff.md | 25 +++++++++++++++++-- 2 files changed, 34 insertions(+), 8 deletions(-) rename docs/enhancement-proposals/{off-ep-00XX.md => off-ep-0011.md} (94%) diff --git a/docs/enhancement-proposals/off-ep-00XX.md b/docs/enhancement-proposals/off-ep-0011.md similarity index 94% rename from docs/enhancement-proposals/off-ep-00XX.md rename to docs/enhancement-proposals/off-ep-0011.md index 4f3d11a..353dafa 100644 --- a/docs/enhancement-proposals/off-ep-00XX.md +++ b/docs/enhancement-proposals/off-ep-0011.md @@ -1,4 +1,4 @@ -# OFF-EP X — Template +# OFF-EP 11 — Add NAGLCharges section to spec **Status:** Draft @@ -24,8 +24,6 @@ This change adds a `` section which calls for a specific NAGL model **Who this EP would affect:** The changes outlined in this proposal affect any consumer of SMIRNOFF force fields that include ``, which is likely to be the case for `openff-2.3.0` and beyond. Since it is not a required section, force field developers who choose to use other partial charge methods would not be affected. SMIRNOFF implementations must implement ``, by definition, to use force fields that include this section. Existing force fields cannot use this section, so they are not affected. -**Changes needed:** The contents of this proposal derive from the current structure of OpenFF NAGL and the model(s) it implements. If this proposal is accepted, OpenFF NAGL will need minor updates to properly check its GNN implementation against the details encoded in a SMIRNOFF force field, but we expect these changes will be minor because the proposed changes derive directly from this software. The OpenFF Toolkit and Interchange will need minor updates to properly support this section and some edge cases that arise from using this section in combination with other section(s) and tools, such as prespecified charges and virtual site parameter which modify charges. Similar tools which also implement the encoded GNN and/or the SMIRNOFF specification more broadly will need similar updates. - **Interaction with other sections:** This proposal does not include changes or interactions with sections that do not modify partial charges, such as ``, ``, ``, ``, etc. `NAGLCharges` fits into the current charge hierarchy as follows (with methods high in the list taking priority over those lower): @@ -33,11 +31,13 @@ This change adds a `` section which calls for a specific NAGL model - Pre-specified charges (charge_from_molecules) - Library charges - GNN charges -- ToolkitAM1BCC charges - ChargeIncrementModel charges +- ToolkitAM1BCC charges The initial `0.3` version of the `NAGLCharges` section does have special interactions with virtual sites, though future versions of this section may include direct assignment of partial charges to virtual sites. But for the 0.3 version of this section proposed by this EP, the behavior will be that, if the `NAGLCharges` section is present in a force field with virtual sites, NAGL is used to assign initial charges to the molecule, and then virtual sites apply their charge increments on top of those initial charges. +**Changes needed:** The contents of this proposal derive from the current structure of OpenFF NAGL and the model(s) it implements. If this proposal is accepted, OpenFF NAGL will need minor updates to properly check its GNN implementation against the details encoded in a SMIRNOFF force field, but we expect these changes will be minor because the proposed changes derive directly from this software. The OpenFF Toolkit and Interchange will need minor updates to properly support this section and some edge cases that arise from using this section in combination with other section(s) and tools, such as prespecified charges and virtual site parameter which modify charges. Similar tools which also implement the encoded GNN and/or the SMIRNOFF specification more broadly will need similar updates. + ## Backward compatibility This proposal adds a new section which does not affect backwards compatibility. While in practice we intend for the NAGLCharges section to become the new default charge method in our future flagship force fields, we do not propose that existing force fields with the ToolkitAM1BCC section be assumed to be compatible with/automatically upgrade-able to NAGLCharges sections. @@ -46,7 +46,9 @@ This proposal adds a new section which does not affect backwards compatibility. This proposal adds a section named `. The proposed initial version of this section (0.3) is as follows, and will be added verbatim to the specification if this EP is approved: -The `NAGLCharges` section-level element defines that the force field should use a sepcific model file in conjunction with the `openff-nagl` software to assign partial charges. It contains the following attributes: +### ``: Use a specified NAGL model file for charge assignment + +The `NAGLCharges` section-level element defines that the force field should use a sepcific model file in conjunction with the `openff-nagl` software to assign partial charges. It contains the following attributes: - `version` - `model_file` @@ -59,7 +61,10 @@ Below is an example `` section: ``` -This section only specifies a model file name, not a version of the NAGL software. The NAGL software is responsible for rejecting model files which it can not correctly interpret. +This section only specifies a model file name, not a version of the NAGL software. The NAGL software is responsible for only accepting model files which it can not correctly interpret. + +Note that atoms for which prespecified or `` charges have already been applied are excluded from charging via ``. + ## Alternatives diff --git a/docs/standards/smirnoff.md b/docs/standards/smirnoff.md index 1708d7e..b0d1865 100644 --- a/docs/standards/smirnoff.md +++ b/docs/standards/smirnoff.md @@ -229,6 +229,9 @@ For example, to ensure water molecules are assigned partial charges for [TIP3P]( | 0.3 | | `smirks`, `charge` (indexed) | `name`, `id`, `parent_id` | +Note that atoms for which prespecifie charges have already been applied are excluded from charging via ``. + + ### ``: Small molecule and fragment charges @@ -263,7 +266,8 @@ The missing `charge_increment` value must be that of the highest tagged atom ind This missing `charge_increment` will be calculated to offset the sum of the other `charge_increment`s in the same `ChargeIncrement` parameter to achieve a net value of 0. This allows `ChargeIncrement` parameters to be defined similar to bond charge corrections. -Note that atoms for which library charges have already been applied are excluded from charging via ``. +Note that atoms for which prespecified, ``, or `` charges have already been applied are excluded from charging via ``. + Future additions will provide options for intelligently fragmenting large molecules and biopolymers, as well as a `capping` attribute to specify how fragments with dangling bonds are to be capped to allow these groups to be charged. @@ -288,9 +292,26 @@ If RDKit/AmberTools are used as the toolkit backend for this calculation, only t The charges generated by this tag may differ depending on which toolkits are available. -Note that atoms for which prespecified or library charges have already been applied are excluded from charging via ``. +Note that atoms for which prespecified, ``, ``, or `` charges have already been applied are excluded from charging via ``. + +### ``: Use a specified NAGL model file for charge assignment + +The `NAGLCharges` section-level element defines that the force field should use a sepcific model file in conjunction with the `openff-nagl` software to assign partial charges. It contains the following attributes: + +- `version` +- `model_file` + +The attribute `model_file` points to a file that includes model weights and other information. This by convention is a PyTorch `.pt` file, extended to contain additional information about the model that is read by the `openff-nagl` software. By their nature, GNNs use many more weights than can reasonably be encoded into an XML file, so pointing to an external file is a necessary and unavoidable layer of complexity. + +Below is an example `` section: + +```xml + +``` +This section only specifies a model file name, not a version of the NAGL software. The NAGL software is responsible for only accepting model files which it can not correctly interpret. +Note that atoms for which prespecified or `` charges have already been applied are excluded from charging via ``. ### Prespecified charges (reference implementation only) From bff08f02581c6361eb43397c40ea301f5048c894 Mon Sep 17 00:00:00 2001 From: Jeff Wagner Date: Tue, 29 Apr 2025 10:50:54 -0700 Subject: [PATCH 14/23] add hash and DOI option for model fetching+validation --- docs/enhancement-proposals/off-ep-0011.md | 20 ++++++++++++-------- 1 file changed, 12 insertions(+), 8 deletions(-) diff --git a/docs/enhancement-proposals/off-ep-0011.md b/docs/enhancement-proposals/off-ep-0011.md index 353dafa..c25ab44 100644 --- a/docs/enhancement-proposals/off-ep-0011.md +++ b/docs/enhancement-proposals/off-ep-0011.md @@ -4,15 +4,13 @@ **Authors:** Lily Wang, Matt Thompson, Jeff Wagner -**Stakeholders:** <list of stakeholders that would be affected by this proposal> - **Acceptance criteria:** Unanimity (4 approving reviews) or partial support (2 approvals and 2 week period with no reviews requesting changes)[https://openforcefield.atlassian.net/wiki/spaces/MEET/pages/2638774273/09-05-23+SMIRNOFF+Committee+Meeting] **Created:** 2025-04-01 **Discussion:** [PR #71](https://github.com/openforcefield/standards/pull/71) -**Implementation:** <link an example / reference implementation of the proposal> +**Implementation:** https://github.com/openforcefield/openff-interchange/pull/1206 https://github.com/openforcefield/openff-toolkit/pull/2048 ## Abstract @@ -36,11 +34,11 @@ This change adds a `` section which calls for a specific NAGL model The initial `0.3` version of the `NAGLCharges` section does have special interactions with virtual sites, though future versions of this section may include direct assignment of partial charges to virtual sites. But for the 0.3 version of this section proposed by this EP, the behavior will be that, if the `NAGLCharges` section is present in a force field with virtual sites, NAGL is used to assign initial charges to the molecule, and then virtual sites apply their charge increments on top of those initial charges. -**Changes needed:** The contents of this proposal derive from the current structure of OpenFF NAGL and the model(s) it implements. If this proposal is accepted, OpenFF NAGL will need minor updates to properly check its GNN implementation against the details encoded in a SMIRNOFF force field, but we expect these changes will be minor because the proposed changes derive directly from this software. The OpenFF Toolkit and Interchange will need minor updates to properly support this section and some edge cases that arise from using this section in combination with other section(s) and tools, such as prespecified charges and virtual site parameter which modify charges. Similar tools which also implement the encoded GNN and/or the SMIRNOFF specification more broadly will need similar updates. +**Changes needed:** The contents of this proposal derive from the current structure of OpenFF NAGL and the model(s) it implements. If this proposal is accepted, OpenFF NAGL will need minor updates to properly check its GNN implementation against the details encoded in a SMIRNOFF force field, but we expect these changes will be minor because the proposed changes derive directly from this software. The OpenFF Toolkit and Interchange will need minor updates to properly support this section and some edge cases that arise from using this section in combination with other section(s) and tools (such as prespecified charges and virtual site parameters which modify charges). Similar tools which also implement the encoded GNN and/or the SMIRNOFF specification more broadly will need similar updates. ## Backward compatibility -This proposal adds a new section which does not affect backwards compatibility. While in practice we intend for the NAGLCharges section to become the new default charge method in our future flagship force fields, we do not propose that existing force fields with the ToolkitAM1BCC section be assumed to be compatible with/automatically upgrade-able to NAGLCharges sections. +This proposal adds a new section which does not affect backwards compatibility. While in practice the first version of the NAGLCharges section is very likely to be trained on AM1BCC ELF10 charges, we do not propose that existing force fields with the ToolkitAM1BCC section be assumed to be compatible with/automatically upgrade-able to NAGLCharges sections. ## Detailed description @@ -48,17 +46,23 @@ This proposal adds a section named `. The proposed initial version ### ``: Use a specified NAGL model file for charge assignment -The `NAGLCharges` section-level element defines that the force field should use a sepcific model file in conjunction with the `openff-nagl` software to assign partial charges. It contains the following attributes: +The `NAGLCharges` section-level element defines that the force field should use a specific model file in conjunction with the `openff-nagl` software to assign partial charges. It contains the following attributes: - `version` - `model_file` +- `model_file_hash` (optional) +- `digital_object_identifier` (optional) + +The attribute `model_file` is a string identifying a file that includes model weights and other information. This by convention is a PyTorch `.pt` file, extended to contain additional information about the model that is read by the `openff-nagl` software. By their nature, GNNs use many more weights than can reasonably be encoded into an XML file, so pointing to an external file is a necessary and unavoidable layer of complexity. -The attribute `model_file` points to a file that includes model weights and other information. This by convention is a PyTorch `.pt` file, extended to contain additional information about the model that is read by the `openff-nagl` software. By their nature, GNNs use many more weights than can reasonably be encoded into an XML file, so pointing to an external file is a necessary and unavoidable layer of complexity. + Because the NAGLCharges section requires loading information from a source outside the SMIRNOFF force field, two optional attributes are provided for ease and reproducibility of use. + - The optional attribute `model_file_hash` is a string that contains a SHA-256 file checksum, which will be checked against the loaded file. If no `model_file_hash` is provided, then no hash comparison will be performed. + - The optional attribute `digital_object_identifier` is a string that contains a [Zenodo](https://zenodo.org/) [Digital Object Identifier](https://www.doi.org/) that can be accessed to fetch the model file. If the file can not be found locally, it may be from this Zenodo entry. The Zenodo entry must have an attached file matching the `model_file` to be fetched. Below is an example `` section: ```xml - + ``` This section only specifies a model file name, not a version of the NAGL software. The NAGL software is responsible for only accepting model files which it can not correctly interpret. From 12d9db62e863f43f4250f20f773663f0a45255dc Mon Sep 17 00:00:00 2001 From: Jeff Wagner Date: Wed, 21 May 2025 15:57:51 -0700 Subject: [PATCH 15/23] Simplication and proofreading --- docs/enhancement-proposals/off-ep-0011.md | 30 ++++------------------- 1 file changed, 5 insertions(+), 25 deletions(-) diff --git a/docs/enhancement-proposals/off-ep-0011.md b/docs/enhancement-proposals/off-ep-0011.md index c25ab44..142d0ac 100644 --- a/docs/enhancement-proposals/off-ep-0011.md +++ b/docs/enhancement-proposals/off-ep-0011.md @@ -20,7 +20,7 @@ This change adds a `` section which calls for a specific NAGL model **Motivation:** OpenFF NAGL has built on existing work and trained a graph-convolutional neural network (GNN) that reproduces AM1-BCC ELF10 partial charges for a substantial set of chemistries. Currently, there is not a canonical method by which these GNN-provided charges can be requested in a SMIRNOFF force field. At the moment, a user can generate partial charges from a GNN and pass them to `create_interchange` or `create_openmm_system` alongside a SMIRNOFF force field as prespecified charges. To use GNNs in a flagship force field, this approach is not sufficient, and the SMIRNOFF specification must be updated to include enough information that an external developer could get the same charges themselves. -**Who this EP would affect:** The changes outlined in this proposal affect any consumer of SMIRNOFF force fields that include ``, which is likely to be the case for `openff-2.3.0` and beyond. Since it is not a required section, force field developers who choose to use other partial charge methods would not be affected. SMIRNOFF implementations must implement ``, by definition, to use force fields that include this section. Existing force fields cannot use this section, so they are not affected. +**Who this EP would affect:** The changes described in this proposal affect any consumer of SMIRNOFF force fields that include ``, which is likely to be the case for `openff-2.3.0` and beyond. Since it is not a required section, force field developers who choose to use other partial charge methods would not be affected. SMIRNOFF implementations must implement ``, by definition, to use force fields that include this section. Existing force fields do not use this section, so they are not affected. **Interaction with other sections:** This proposal does not include changes or interactions with sections that do not modify partial charges, such as ``, ``, ``, ``, etc. @@ -34,7 +34,7 @@ This change adds a `` section which calls for a specific NAGL model The initial `0.3` version of the `NAGLCharges` section does have special interactions with virtual sites, though future versions of this section may include direct assignment of partial charges to virtual sites. But for the 0.3 version of this section proposed by this EP, the behavior will be that, if the `NAGLCharges` section is present in a force field with virtual sites, NAGL is used to assign initial charges to the molecule, and then virtual sites apply their charge increments on top of those initial charges. -**Changes needed:** The contents of this proposal derive from the current structure of OpenFF NAGL and the model(s) it implements. If this proposal is accepted, OpenFF NAGL will need minor updates to properly check its GNN implementation against the details encoded in a SMIRNOFF force field, but we expect these changes will be minor because the proposed changes derive directly from this software. The OpenFF Toolkit and Interchange will need minor updates to properly support this section and some edge cases that arise from using this section in combination with other section(s) and tools (such as prespecified charges and virtual site parameters which modify charges). Similar tools which also implement the encoded GNN and/or the SMIRNOFF specification more broadly will need similar updates. +**Changes needed:** The contents of this proposal derive from the current structure of OpenFF NAGL and the model(s) it implements. If this proposal is accepted, OpenFF NAGL may need minor updates to properly check its GNN implementation against the details encoded in a SMIRNOFF force field, but we expect these changes will be minor because the proposed changes derive directly from this software. The OpenFF Toolkit and Interchange will need minor updates to properly support this section and some edge cases that arise from using this section in combination with other section(s) and tools (such as prespecified charges and virtual site parameters which modify charges). Similar tools which also implement the encoded GNN and/or the SMIRNOFF specification more broadly will need similar updates. ## Backward compatibility @@ -46,7 +46,7 @@ This proposal adds a section named `. The proposed initial version ### ``: Use a specified NAGL model file for charge assignment -The `NAGLCharges` section-level element defines that the force field should use a specific model file in conjunction with the `openff-nagl` software to assign partial charges. It contains the following attributes: +The `NAGLCharges` section-level element specifies that the force field should use a specific model file in conjunction with the `openff-nagl` software to assign partial charges. It contains the following attributes: - `version` - `model_file` @@ -57,7 +57,7 @@ The attribute `model_file` is a string identifying a file that includes model we Because the NAGLCharges section requires loading information from a source outside the SMIRNOFF force field, two optional attributes are provided for ease and reproducibility of use. - The optional attribute `model_file_hash` is a string that contains a SHA-256 file checksum, which will be checked against the loaded file. If no `model_file_hash` is provided, then no hash comparison will be performed. - - The optional attribute `digital_object_identifier` is a string that contains a [Zenodo](https://zenodo.org/) [Digital Object Identifier](https://www.doi.org/) that can be accessed to fetch the model file. If the file can not be found locally, it may be from this Zenodo entry. The Zenodo entry must have an attached file matching the `model_file` to be fetched. + - The optional attribute `digital_object_identifier` is a string that contains a [Zenodo](https://zenodo.org/) [Digital Object Identifier](https://www.doi.org/) that can be accessed to fetch the model file. If the file can not be found locally, it may be from this Zenodo entry. The Zenodo entry must have an attached file with a name matching the `model_file` string to be fetched. Below is an example `` section: @@ -65,30 +65,10 @@ Below is an example `` section: ``` -This section only specifies a model file name, not a version of the NAGL software. The NAGL software is responsible for only accepting model files which it can not correctly interpret. +This section only specifies a model file name, not a version of the NAGL software. The NAGL software is responsible for only accepting model files which it can correctly interpret. Note that atoms for which prespecified or `` charges have already been applied are excluded from charging via ``. - -## Alternatives - -The first GNN trained with the intent to be shipped in SMIRNOFF force fields is one that models AM1-BCC partial -charges, so another solution could involve updating the existing `` section instead of adding a new -section altogether. This might involve a new tag in the `` section that distinguishes a particular GNN -from the existing QuacPac and/or `sqm`-based approach. This approach is limiting, however, since GNNs can be used to -predict other charge models than AM1-BCC; if a GNN was trained to ABCG2 or a RESP variant, it's not obvious if that -could drop in to ``. - -Another similar solution could involve not updating the `ToolkitAM1BCC` specification at all and simply letting -implementations use GNNs in place of QuacPac or `sqm` as currently specified. This in principle produces the same -results, to the extent that the GNN accurately reproduces AM1-BCC charges, but is inconsistent with the philosophy that -the details of a force field must be communicated to users and not hidden from view. - -The solution in this proposal makes clear to any person or tool inspecting a force field that GNNs are a different tool -than existing AM1-BCC charge providers. It attempts to provide enough detail that somebody could re-implement the same -GNN provided weights that are shipped alongside a force field. It allows for future modifications in which a different -underlying charge model is targeted. - ## Discussion - [Original SMIRNOFF EP](https://github.com/openforcefield/standards/pull/71) From 9e83ecb321820ff1710d69b65b9066b9c4c02366 Mon Sep 17 00:00:00 2001 From: Jeff Wagner Date: Wed, 21 May 2025 16:11:02 -0700 Subject: [PATCH 16/23] paste up-to-date version of EP in smirnoff spec --- docs/standards/smirnoff.md | 14 ++++++++++---- 1 file changed, 10 insertions(+), 4 deletions(-) diff --git a/docs/standards/smirnoff.md b/docs/standards/smirnoff.md index b0d1865..365bbe6 100644 --- a/docs/standards/smirnoff.md +++ b/docs/standards/smirnoff.md @@ -296,20 +296,26 @@ Note that atoms for which prespecified, ``, ``, or ### ``: Use a specified NAGL model file for charge assignment -The `NAGLCharges` section-level element defines that the force field should use a sepcific model file in conjunction with the `openff-nagl` software to assign partial charges. It contains the following attributes: +The `NAGLCharges` section-level element specifies that the force field should use a specific model file in conjunction with the `openff-nagl` software to assign partial charges. It contains the following attributes: - `version` - `model_file` +- `model_file_hash` (optional) +- `digital_object_identifier` (optional) -The attribute `model_file` points to a file that includes model weights and other information. This by convention is a PyTorch `.pt` file, extended to contain additional information about the model that is read by the `openff-nagl` software. By their nature, GNNs use many more weights than can reasonably be encoded into an XML file, so pointing to an external file is a necessary and unavoidable layer of complexity. +The attribute `model_file` is a string identifying a file that includes model weights and other information. This by convention is a PyTorch `.pt` file, extended to contain additional information about the model that is read by the `openff-nagl` software. By their nature, GNNs use many more weights than can reasonably be encoded into an XML file, so pointing to an external file is a necessary and unavoidable layer of complexity. + + Because the NAGLCharges section requires loading information from a source outside the SMIRNOFF force field, two optional attributes are provided for ease and reproducibility of use. + - The optional attribute `model_file_hash` is a string that contains a SHA-256 file checksum, which will be checked against the loaded file. If no `model_file_hash` is provided, then no hash comparison will be performed. + - The optional attribute `digital_object_identifier` is a string that contains a [Zenodo](https://zenodo.org/) [Digital Object Identifier](https://www.doi.org/) that can be accessed to fetch the model file. If the file can not be found locally, it may be from this Zenodo entry. The Zenodo entry must have an attached file with a name matching the `model_file` string to be fetched. Below is an example `` section: ```xml - + ``` -This section only specifies a model file name, not a version of the NAGL software. The NAGL software is responsible for only accepting model files which it can not correctly interpret. +This section only specifies a model file name, not a version of the NAGL software. The NAGL software is responsible for only accepting model files which it can correctly interpret. Note that atoms for which prespecified or `` charges have already been applied are excluded from charging via ``. From f41470facc1ddd2cd679a21085d474a9cddda0a9 Mon Sep 17 00:00:00 2001 From: Jeff Wagner Date: Thu, 22 May 2025 13:20:26 -0700 Subject: [PATCH 17/23] Update docs/standards/smirnoff.md Co-authored-by: Lily Wang <31115101+lilyminium@users.noreply.github.com> --- docs/standards/smirnoff.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/standards/smirnoff.md b/docs/standards/smirnoff.md index 365bbe6..87312a8 100644 --- a/docs/standards/smirnoff.md +++ b/docs/standards/smirnoff.md @@ -229,7 +229,7 @@ For example, to ensure water molecules are assigned partial charges for [TIP3P]( | 0.3 | | `smirks`, `charge` (indexed) | `name`, `id`, `parent_id` | -Note that atoms for which prespecifie charges have already been applied are excluded from charging via ``. +Note that atoms for which prespecified charges have already been applied are excluded from charging via ``. From be2da598f4950c927fd36a78fcabb9e440824cee Mon Sep 17 00:00:00 2001 From: Jeff Wagner Date: Tue, 17 Jun 2025 21:14:40 -0700 Subject: [PATCH 18/23] Remove file hash --- docs/enhancement-proposals/off-ep-0011.md | 7 ++----- 1 file changed, 2 insertions(+), 5 deletions(-) diff --git a/docs/enhancement-proposals/off-ep-0011.md b/docs/enhancement-proposals/off-ep-0011.md index 142d0ac..1cdbc83 100644 --- a/docs/enhancement-proposals/off-ep-0011.md +++ b/docs/enhancement-proposals/off-ep-0011.md @@ -50,19 +50,16 @@ The `NAGLCharges` section-level element specifies that the force field should us - `version` - `model_file` -- `model_file_hash` (optional) - `digital_object_identifier` (optional) The attribute `model_file` is a string identifying a file that includes model weights and other information. This by convention is a PyTorch `.pt` file, extended to contain additional information about the model that is read by the `openff-nagl` software. By their nature, GNNs use many more weights than can reasonably be encoded into an XML file, so pointing to an external file is a necessary and unavoidable layer of complexity. - Because the NAGLCharges section requires loading information from a source outside the SMIRNOFF force field, two optional attributes are provided for ease and reproducibility of use. - - The optional attribute `model_file_hash` is a string that contains a SHA-256 file checksum, which will be checked against the loaded file. If no `model_file_hash` is provided, then no hash comparison will be performed. - - The optional attribute `digital_object_identifier` is a string that contains a [Zenodo](https://zenodo.org/) [Digital Object Identifier](https://www.doi.org/) that can be accessed to fetch the model file. If the file can not be found locally, it may be from this Zenodo entry. The Zenodo entry must have an attached file with a name matching the `model_file` string to be fetched. +Because the NAGLCharges section requires loading information from a source outside the SMIRNOFF force field, the optional attribute `digital_object_identifier` is provided for ease and reproducibility of use. `digital_object_identifier` is a string that contains a [Zenodo](https://zenodo.org/) [Digital Object Identifier (DOI)](https://www.doi.org/) that can be accessed to fetch the model file. If the file can not be found locally, it may be fetched from this Zenodo entry. The Zenodo entry must have an attached file with a name matching the `model_file` string to be fetched. Below is an example `` section: ```xml - + ``` This section only specifies a model file name, not a version of the NAGL software. The NAGL software is responsible for only accepting model files which it can correctly interpret. From 9702fbd49cc43ac4056608ef50fe64ada208dd9b Mon Sep 17 00:00:00 2001 From: Jeff Wagner Date: Fri, 27 Jun 2025 18:06:41 -0700 Subject: [PATCH 19/23] add hash back --- docs/enhancement-proposals/off-ep-0011.md | 7 +++++-- 1 file changed, 5 insertions(+), 2 deletions(-) diff --git a/docs/enhancement-proposals/off-ep-0011.md b/docs/enhancement-proposals/off-ep-0011.md index 1cdbc83..805534e 100644 --- a/docs/enhancement-proposals/off-ep-0011.md +++ b/docs/enhancement-proposals/off-ep-0011.md @@ -50,16 +50,19 @@ The `NAGLCharges` section-level element specifies that the force field should us - `version` - `model_file` +- `model_file_hash` (optional) - `digital_object_identifier` (optional) The attribute `model_file` is a string identifying a file that includes model weights and other information. This by convention is a PyTorch `.pt` file, extended to contain additional information about the model that is read by the `openff-nagl` software. By their nature, GNNs use many more weights than can reasonably be encoded into an XML file, so pointing to an external file is a necessary and unavoidable layer of complexity. -Because the NAGLCharges section requires loading information from a source outside the SMIRNOFF force field, the optional attribute `digital_object_identifier` is provided for ease and reproducibility of use. `digital_object_identifier` is a string that contains a [Zenodo](https://zenodo.org/) [Digital Object Identifier (DOI)](https://www.doi.org/) that can be accessed to fetch the model file. If the file can not be found locally, it may be fetched from this Zenodo entry. The Zenodo entry must have an attached file with a name matching the `model_file` string to be fetched. +Because the NAGLCharges section requires loading information from a source outside the SMIRNOFF force field, two optional attributes are provided for ease and reproducibility of use. +- The optional attribute `model_file_hash` is a string that contains a SHA-256 file checksum, which will be checked against the loaded file. If no `model_file_hash` is provided, then no hash comparison will be performed. +- The optional attribute `digital_object_identifier` is a string that contains a [Zenodo](https://zenodo.org/) [Digital Object Identifier](https://www.doi.org/) that can be accessed to fetch the model file. If the file can not be found locally, it may be from this Zenodo entry. The Zenodo entry must have an attached file with a name matching the `model_file` string to be fetched. Below is an example `` section: ```xml - + ``` This section only specifies a model file name, not a version of the NAGL software. The NAGL software is responsible for only accepting model files which it can correctly interpret. From 91bbfea7ee668d6c587d22fbf37b7b4d385442e6 Mon Sep 17 00:00:00 2001 From: Jeff Wagner Date: Wed, 9 Jul 2025 13:55:03 -0700 Subject: [PATCH 20/23] clarify hierarchy --- docs/enhancement-proposals/off-ep-0011.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/enhancement-proposals/off-ep-0011.md b/docs/enhancement-proposals/off-ep-0011.md index 805534e..264afe4 100644 --- a/docs/enhancement-proposals/off-ep-0011.md +++ b/docs/enhancement-proposals/off-ep-0011.md @@ -28,7 +28,7 @@ This change adds a `` section which calls for a specific NAGL model - Pre-specified charges (charge_from_molecules) - Library charges -- GNN charges +- NAGL charges - ChargeIncrementModel charges - ToolkitAM1BCC charges From 2b6ef83b1a1928c63c465a0c921a5f663a540bf4 Mon Sep 17 00:00:00 2001 From: Jeff Wagner Date: Wed, 6 Aug 2025 15:46:05 -0700 Subject: [PATCH 21/23] clarify that the doi field isn't used for model file validation --- docs/enhancement-proposals/off-ep-0011.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/enhancement-proposals/off-ep-0011.md b/docs/enhancement-proposals/off-ep-0011.md index 264afe4..c0c6e2d 100644 --- a/docs/enhancement-proposals/off-ep-0011.md +++ b/docs/enhancement-proposals/off-ep-0011.md @@ -57,7 +57,7 @@ The attribute `model_file` is a string identifying a file that includes model we Because the NAGLCharges section requires loading information from a source outside the SMIRNOFF force field, two optional attributes are provided for ease and reproducibility of use. - The optional attribute `model_file_hash` is a string that contains a SHA-256 file checksum, which will be checked against the loaded file. If no `model_file_hash` is provided, then no hash comparison will be performed. -- The optional attribute `digital_object_identifier` is a string that contains a [Zenodo](https://zenodo.org/) [Digital Object Identifier](https://www.doi.org/) that can be accessed to fetch the model file. If the file can not be found locally, it may be from this Zenodo entry. The Zenodo entry must have an attached file with a name matching the `model_file` string to be fetched. +- The optional attribute `digital_object_identifier` is a string that contains a [Zenodo](https://zenodo.org/) [Digital Object Identifier](https://www.doi.org/) that can be accessed to fetch the model file. If the file can not be found locally, it may be fetched from this Zenodo entry. The Zenodo entry must have an attached file with a name matching the `model_file` string to be fetched. This field is not used for validating the model file contents, so if a model publisher wants to ensure that the user's local model file matches that at the DOI, they should use the `model_file_hash` field. . Below is an example `` section: From c6dd3af98b6736fbed3a49182ac264e28bd84fd2 Mon Sep 17 00:00:00 2001 From: Jeff Wagner Date: Wed, 6 Aug 2025 15:46:49 -0700 Subject: [PATCH 22/23] fix typo --- docs/enhancement-proposals/off-ep-0011.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/enhancement-proposals/off-ep-0011.md b/docs/enhancement-proposals/off-ep-0011.md index c0c6e2d..0afb7bc 100644 --- a/docs/enhancement-proposals/off-ep-0011.md +++ b/docs/enhancement-proposals/off-ep-0011.md @@ -57,7 +57,7 @@ The attribute `model_file` is a string identifying a file that includes model we Because the NAGLCharges section requires loading information from a source outside the SMIRNOFF force field, two optional attributes are provided for ease and reproducibility of use. - The optional attribute `model_file_hash` is a string that contains a SHA-256 file checksum, which will be checked against the loaded file. If no `model_file_hash` is provided, then no hash comparison will be performed. -- The optional attribute `digital_object_identifier` is a string that contains a [Zenodo](https://zenodo.org/) [Digital Object Identifier](https://www.doi.org/) that can be accessed to fetch the model file. If the file can not be found locally, it may be fetched from this Zenodo entry. The Zenodo entry must have an attached file with a name matching the `model_file` string to be fetched. This field is not used for validating the model file contents, so if a model publisher wants to ensure that the user's local model file matches that at the DOI, they should use the `model_file_hash` field. . +- The optional attribute `digital_object_identifier` is a string that contains a [Zenodo](https://zenodo.org/) [Digital Object Identifier](https://www.doi.org/) that can be accessed to fetch the model file. If the file can not be found locally, it may be fetched from this Zenodo entry. The Zenodo entry must have an attached file with a name matching the `model_file` string to be fetched. This field is not used for validating the model file contents, so if a model publisher wants to ensure that a user's local model file matches that at the DOI, they should use the `model_file_hash` field. Below is an example `` section: From 8f056343f92f769120951fd42fdf38a796b93fdc Mon Sep 17 00:00:00 2001 From: Jeff Wagner Date: Thu, 14 Aug 2025 09:12:18 -0700 Subject: [PATCH 23/23] sync EP text and spec contents --- docs/standards/smirnoff.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/docs/standards/smirnoff.md b/docs/standards/smirnoff.md index 87312a8..3d32447 100644 --- a/docs/standards/smirnoff.md +++ b/docs/standards/smirnoff.md @@ -305,9 +305,9 @@ The `NAGLCharges` section-level element specifies that the force field should us The attribute `model_file` is a string identifying a file that includes model weights and other information. This by convention is a PyTorch `.pt` file, extended to contain additional information about the model that is read by the `openff-nagl` software. By their nature, GNNs use many more weights than can reasonably be encoded into an XML file, so pointing to an external file is a necessary and unavoidable layer of complexity. - Because the NAGLCharges section requires loading information from a source outside the SMIRNOFF force field, two optional attributes are provided for ease and reproducibility of use. - - The optional attribute `model_file_hash` is a string that contains a SHA-256 file checksum, which will be checked against the loaded file. If no `model_file_hash` is provided, then no hash comparison will be performed. - - The optional attribute `digital_object_identifier` is a string that contains a [Zenodo](https://zenodo.org/) [Digital Object Identifier](https://www.doi.org/) that can be accessed to fetch the model file. If the file can not be found locally, it may be from this Zenodo entry. The Zenodo entry must have an attached file with a name matching the `model_file` string to be fetched. +Because the NAGLCharges section requires loading information from a source outside the SMIRNOFF force field, two optional attributes are provided for ease and reproducibility of use. +- The optional attribute `model_file_hash` is a string that contains a SHA-256 file checksum, which will be checked against the loaded file. If no `model_file_hash` is provided, then no hash comparison will be performed. +- The optional attribute `digital_object_identifier` is a string that contains a [Zenodo](https://zenodo.org/) [Digital Object Identifier](https://www.doi.org/) that can be accessed to fetch the model file. If the file can not be found locally, it may be fetched from this Zenodo entry. The Zenodo entry must have an attached file with a name matching the `model_file` string to be fetched. This field is not used for validating the model file contents, so if a model publisher wants to ensure that a user's local model file matches that at the DOI, they should use the `model_file_hash` field. Below is an example `` section: