Merge branch 'main' into transformation-base-class

Addressed conflicts and refined docstrings, addressed reviews.

.git-blame-ignore-revs

@@ -0,0 +1,2 @@
+# https://github.com/OpenFreeEnergy/gufe/pull/421 -- big auto format MMH
+d27100a5b7b303df155e2b6d7874883d105e24bf

.github/pull_request_template.md

@@ -0,0 +1,22 @@
+<!--
+Thank you for pull request.
+Below are a few things we ask you kindly to self-check before getting a review. Remove checks that are not relevant.
+-->
+
+<!--
+Please note any issues this fixes using [closing keywords]( https://help.github.com/articles/closing-issues-using-keywords/ ):
+-->
+
+<!--
+see https://regro.github.io/rever-docs/news.html for details on how to add news entry (you do not need to run the rever command)
+-->
+Tips
+* Comment "pre-commit.ci autofix" to have pre-commit.ci atomically format your PR.
+  Since this will create a commit, it is best to make this comment when you are finished with your work.
+
+
+Checklist
+* [ ] Added a ``news`` entry
+
+## Developers certificate of origin
+- [ ] I certify that this contribution is covered by the MIT License [here](https://github.com/OpenFreeEnergy/openfe/blob/main/LICENSE) and the **Developer Certificate of Origin** at <https://developercertificate.org/>.

.github/workflows/ci.yaml

@@ -27,18 +27,15 @@ jobs:
     strategy:
       fail-fast: false
       matrix:
-        os: ['ubuntu-latest']
+        os: ['ubuntu-latest', macos-latest]
         pydantic-version: [">1"]
         python-version:
           - "3.10"
-          - "3.11"  
+          - "3.11"
           - "3.12"
         include:
-            # Note: pinned to macos-12
+            # Note: we still need to add support for macos-13
             # see https://github.com/OpenFreeEnergy/openfe/issues/842
-          - os: "macos-12"
-            python-version: "3.11"
-            pydantic-version: ">1"
           - os: "ubuntu-latest"
             python-version: "3.11"
             pydantic-version: "<2"

.github/workflows/clean_cache.yaml

@@ -11,18 +11,18 @@ jobs:
     steps:
       - name: Check out code
         uses: actions/checkout@v3
-        
+
       - name: Cleanup
         run: |
           gh extension install actions/gh-actions-cache
-          
+
           REPO=${{ github.repository }}
           BRANCH="refs/pull/${{ github.event.pull_request.number }}/merge"
 
           echo "Fetching list of cache key"
           cacheKeysForPR=$(gh actions-cache list -R $REPO -B $BRANCH | cut -f 1 )
 
-          ## Setting this to not fail the workflow while deleting cache keys. 
+          ## Setting this to not fail the workflow while deleting cache keys.
           set +e
           echo "Deleting caches..."
           for cacheKey in $cacheKeysForPR

.github/workflows/conda_cron.yaml

@@ -24,7 +24,7 @@ jobs:
     strategy:
       fail-fast: false
       matrix:
-        os: ['ubuntu-latest', 'macos-14']
+        os: ['ubuntu-latest', 'macos-latest']
         python-version:
           - "3.10"
           - "3.11"

.pre-commit-config.yaml

@@ -0,0 +1,41 @@
+ci:
+  autoupdate_schedule: "quarterly"
+  # comment / label "pre-commit.ci autofix" to a pull request to manually trigger auto-fixing
+  autofix_prs: false
+repos:
+- repo: https://github.com/pre-commit/pre-commit-hooks
+  rev: v4.5.0
+  hooks:
+  - id: check-added-large-files
+  - id: check-case-conflict
+  - id: check-executables-have-shebangs
+  - id: check-symlinks
+  - id: check-toml
+  - id: check-yaml
+  - id: debug-statements
+  - id: destroyed-symlinks
+  - id: end-of-file-fixer
+    exclude: '\.(graphml)$'
+  - id: trailing-whitespace
+    exclude: '\.(pdb|gro|top|sdf|xml|cif|graphml)$'
+- repo: https://github.com/psf/black-pre-commit-mirror
+  rev: 24.2.0
+  hooks:
+  - id: black
+  - id: black-jupyter
+- repo: https://github.com/PyCQA/isort
+  rev: 5.13.2
+  hooks:
+  - id: isort
+    args: ["--profile", "black", "--filter-files"]
+- repo: https://github.com/econchick/interrogate
+  rev: 1.5.0
+  hooks:
+    - id: interrogate
+      args: [--fail-under=28]
+      pass_filenames: false
+- repo: https://github.com/asottile/pyupgrade
+  rev: v3.15.0
+  hooks:
+  - id: pyupgrade
+    args: ["--py39-plus"]

README.md

@@ -2,6 +2,7 @@
 [![build](https://github.com/OpenFreeEnergy/gufe/actions/workflows/ci.yaml/badge.svg)](https://github.com/OpenFreeEnergy/gufe/actions/workflows/ci.yaml)
 [![coverage](https://codecov.io/gh/OpenFreeEnergy/gufe/branch/main/graph/badge.svg)](https://codecov.io/gh/OpenFreeEnergy/gufe)
 [![Documentation Status](https://readthedocs.org/projects/gufe/badge/?version=latest)](https://gufe.readthedocs.io/en/latest/?badge=latest)
+[![pre-commit.ci status](https://results.pre-commit.ci/badge/github/OpenFreeEnergy/gufe/main.svg)](https://results.pre-commit.ci/latest/github/OpenFreeEnergy/gufe/main)
 
 # gufe - Grand Unified Free Energy
 

devtools/raise-or-close-issue.py

@@ -5,24 +5,24 @@
 #  - TITLE: A string title which the issue will have.
 
 import os
-from github import Github
 
+from github import Github
 
 if __name__ == "__main__":
-    git = Github(os.environ['GITHUB_TOKEN'])
-    status = os.environ['CI_OUTCOME']
-    repo = git.get_repo('OpenFreeEnergy/gufe')
-    title = os.environ['TITLE']
-    
+    git = Github(os.environ["GITHUB_TOKEN"])
+    status = os.environ["CI_OUTCOME"]
+    repo = git.get_repo("OpenFreeEnergy/gufe")
+    title = os.environ["TITLE"]
+
     target_issue = None
     for issue in repo.get_issues():
         if issue.title == title:
             target_issue = issue
-    
+
     # Close any issues with given title if CI returned green
-    if status == 'success':
+    if status == "success":
         if target_issue is not None:
-            target_issue.edit(state='closed')
+            target_issue.edit(state="closed")
     else:
         # Otherwise raise an issue
         if target_issue is None:

docs/CHANGELOG.rst

@@ -28,5 +28,3 @@ v1.1.0
 * Fixed an issue where ProtocolDAG DAG order & keys were unstable /
   non-deterministic between processes under some circumstances (PR #315).
 * Fixed a bug where edge annotations were lost when converting a ``LigandNetwork`` to graphml, all JSON codec types are now supported.
-
-

docs/_static/.gitkeep

@@ -1 +0,0 @@
-

docs/conf.py

@@ -12,14 +12,15 @@
 #
 import os
 import sys
-sys.path.insert(0, os.path.abspath('../'))
+
+sys.path.insert(0, os.path.abspath("../"))
 
 
 # -- Project information -----------------------------------------------------
 
-project = 'gufe'
-copyright = '2022, The OpenFE Development Team'
-author = 'The OpenFE Development Team'
+project = "gufe"
+copyright = "2022, The OpenFE Development Team"
+author = "The OpenFE Development Team"
 
 
 # -- General configuration ---------------------------------------------------
@@ -28,14 +29,14 @@
 # extensions coming with Sphinx (named 'sphinx.ext.*') or your custom
 # ones.
 extensions = [
-    'sphinx.ext.autodoc',
-    'sphinx.ext.autosummary',
-    'sphinx.ext.napoleon',
-    'sphinxcontrib.autodoc_pydantic',
-    'sphinx.ext.intersphinx',
+    "sphinx.ext.autodoc",
+    "sphinx.ext.autosummary",
+    "sphinx.ext.napoleon",
+    "sphinxcontrib.autodoc_pydantic",
+    "sphinx.ext.intersphinx",
 ]
 
-autoclass_content = 'both'
+autoclass_content = "both"
 
 autodoc_default_options = {
     "members": True,
@@ -47,20 +48,21 @@
 autosummary_generate = True
 
 intersphinx_mapping = {
-    'rdkit': ('https://www.rdkit.org/docs/', None),
+    "rdkit": ("https://www.rdkit.org/docs/", None),
 }
 
 # Add any paths that contain templates here, relative to this directory.
-templates_path = ['_templates']
+templates_path = ["_templates"]
 
 # List of patterns, relative to source directory, that match files and
 # directories to ignore when looking for source files.
 # This pattern also affects html_static_path and html_extra_path.
-exclude_patterns = ['_build', 'Thumbs.db', '.DS_Store']
+exclude_patterns = ["_build", "Thumbs.db", ".DS_Store"]
 
-autodoc_mock_imports = ["openff.models",
-                        "rdkit",
-                        "networkx",
+autodoc_mock_imports = [
+    "openff.models",
+    "rdkit",
+    "networkx",
 ]
 
 
@@ -77,7 +79,7 @@
 # Add any paths that contain custom static files (such as style sheets) here,
 # relative to this directory. They are copied after the builtin static files,
 # so a file named "default.css" will overwrite the builtin "default.css".
-html_static_path = ['_static']
+html_static_path = ["_static"]
 
 # replace macros
 rst_prolog = """

docs/guide/overview.rst

@@ -25,7 +25,7 @@ Ligand network setup
 GUFE defines a basic API for the common case of performing alchemical
 transformations between small molecules, either for relative binding free
 energies of relative hydration free energies. This handles how mappings
-between different molecules are defined for alchemical transformations, 
+between different molecules are defined for alchemical transformations,
 by defining both the :class:`.LigandAtomMapping` object that contains the
 details of a specific mapping, and the :class:`.AtomMapper` abstract API for
 an object that creates the mappings.

docs/guide/serialization.rst

@@ -245,7 +245,7 @@ classmethod:
 .. Using JSON codecs outside of JSON
 .. ---------------------------------
 
-.. In a custom recursive storage scheme, 
+.. In a custom recursive storage scheme,
 
 .. TODO: DWHS wants to write something here that describes how to use the
    codecs in your own non-JSON storage scheme. But this is complicated

gufe/__init__.py

@@ -3,40 +3,21 @@
 
 from importlib.metadata import version
 
-from . import tokenization
-
-from . import visualization
-
-from .components import (
-    Component,
-    SmallMoleculeComponent,
-    ProteinComponent,
-    SolventComponent
-)
-
+from . import tokenization, visualization
 from .chemicalsystem import ChemicalSystem
-
-from .mapping import (
-    ComponentMapping,  # how individual Components relate
-    AtomMapping, AtomMapper,  # more specific to atom based components
-    LigandAtomMapping,
-)
-
-from .settings import Settings
-
-from .protocols import (
-    Context,
-    Protocol,  # description of a method
-    ProtocolUnit,  # the individual step within a method
-    ProtocolDAG,  # many Units forming a workflow
-    ProtocolUnitResult,  # the result of a single Unit
-    ProtocolDAGResult,  # the collected result of a DAG
-    ProtocolResult,  # potentially many DAGs together, giving an estimate
-)
-
-from .transformations import Transformation, NonTransformation
-
-from .network import AlchemicalNetwork
+from .components import Component, ProteinComponent, SmallMoleculeComponent, SolventComponent
 from .ligandnetwork import LigandNetwork
+from .mapping import AtomMapper  # more specific to atom based components
+from .mapping import ComponentMapping  # how individual Components relate
+from .mapping import AtomMapping, LigandAtomMapping
+from .network import AlchemicalNetwork
+from .protocols import Protocol  # description of a method
+from .protocols import ProtocolDAG  # many Units forming a workflow
+from .protocols import ProtocolDAGResult  # the collected result of a DAG
+from .protocols import ProtocolUnit  # the individual step within a method
+from .protocols import ProtocolUnitResult  # the result of a single Unit
+from .protocols import Context, ProtocolResult  # potentially many DAGs together, giving an estimate
+from .settings import Settings
+from .transformations import NonTransformation, Transformation
 
 __version__ = version("gufe")

gufe/chemicalsystem.py

@@ -4,8 +4,8 @@
 from collections import abc
 from typing import Optional
 
-from .tokenization import GufeTokenizable
 from .components import Component
+from .tokenization import GufeTokenizable
 
 
 class ChemicalSystem(GufeTokenizable, abc.Mapping):
@@ -14,14 +14,14 @@ def __init__(
         components: dict[str, Component],
         name: Optional[str] = "",
     ):
-        """A combination of Components that form a system
+        r"""A combination of Components that form a system
 
         Containing a combination of :class:`.SmallMoleculeComponent`,
         :class:`.SolventComponent` and :class:`.ProteinComponent`, this object
         typically represents all the molecules in a simulation box.
 
         Used as a node for an :class:`.AlchemicalNetwork`.
-        
+
         Parameters
         ----------
         components
@@ -40,24 +40,18 @@ def __init__(
         self._name = name
 
     def __repr__(self):
-        return (
-            f"{self.__class__.__name__}(name={self.name}, components={self.components})"
-        )
+        return f"{self.__class__.__name__}(name={self.name}, components={self.components})"
 
     def _to_dict(self):
         return {
-            "components": {
-                key: value for key, value in sorted(self.components.items())
-            },
+            "components": {key: value for key, value in sorted(self.components.items())},
             "name": self.name,
         }
 
     @classmethod
     def _from_dict(cls, d):
         return cls(
-            components={
-                key: value for key, value in d["components"].items()
-            },
+            components={key: value for key, value in d["components"].items()},
             name=d["name"],
         )
 
@@ -86,7 +80,7 @@ def name(self):
     def total_charge(self):
         """Formal charge for the ChemicalSystem."""
         # This might evaluate the property twice?
-        #return sum(component.total_charge
+        # return sum(component.total_charge
         #           for component in self._components.values()
         #           if component.total_charge is not None)
         total_charge = 0

gufe/components/__init__.py

@@ -1,7 +1,6 @@
 """The building blocks for defining systems"""
 
 from .component import Component
-
-from .smallmoleculecomponent import SmallMoleculeComponent
 from .proteincomponent import ProteinComponent
+from .smallmoleculecomponent import SmallMoleculeComponent
 from .solventcomponent import SolventComponent