Merge branch 'main' into oechemless-registry

.github/pull_request_template.md

@@ -1,3 +1,18 @@
+<!--
+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)
+-->
+
+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

@@ -25,7 +25,7 @@ defaults:
 jobs:
   tests:
     runs-on: ${{ matrix.os }}-latest
-    name: "💻-${{matrix.os }} 🐍-${{ matrix.python-version }} 🗃️${{ matrix.pydantic-version }}"
+    name: "💻-${{matrix.os }} 🐍-${{ matrix.python-version }} 🗃️${{ matrix.pydantic-version }} oechem: ${{ matrix.openeye }}"
     strategy:
       fail-fast: false
       matrix:
@@ -35,13 +35,21 @@ jobs:
           - "3.9"
           - "3.10"
           - "3.11"
+        openeye: ["no"]
         include:
           - os: "macos"
             python-version: "3.11"
             pydantic-version: ">1"
           - os: "ubuntu"
             python-version: "3.11"
             pydantic-version: "<2"
+          - os: "ubuntu"
+            python-version: "3.11"
+            pydantic-version: ">1"
+            openeye: "yes"
+
+    env:
+      OE_LICENSE: ${{ github.workspace }}/oe_license.txt
 
     steps:
       - uses: actions/checkout@v4
@@ -66,6 +74,16 @@ jobs:
             pydantic=${{ matrix.pydantic-version }}
           init-shell: bash
 
+      - name: "Install OpenEye"
+        if: ${{ !github.event.pull_request.head.repo.fork
+                && matrix.openeye == 'yes' }}
+        env:
+          OE_LICENSE_TEXT: ${{ secrets.OE_LICENSE }}
+        run: |
+          echo "${OE_LICENSE_TEXT}" > ${OE_LICENSE}
+          micromamba install -c openeye openeye-toolkits
+          python -c "import openeye; assert openeye.oechem.OEChemIsLicensed(), 'oechem license check failed!'"
+
       - name: "Install GUFE from main@HEAD"
         run: python -m pip install --no-deps git+https://github.com/OpenFreeEnergy/gufe@main
 

.gitignore

@@ -170,3 +170,9 @@ docs/ExampleNotebooks/
 
 # duecredit
 .duecredit.p
+
+# Some charge stuff
+*.model.pt
+
+# Rever
+rever/

.pre-commit-config.yaml

@@ -0,0 +1,16 @@
+ci:
+    autofix_commit_msg: |
+        [pre-commit.ci] auto fixes from pre-commit.com hooks
+
+        for more information, see https://pre-commit.ci
+    autofix_prs: true
+    autoupdate_branch: ''
+    autoupdate_commit_msg: '[pre-commit.ci] pre-commit autoupdate'
+    autoupdate_schedule: quarterly
+    skip: []
+    submodules: false
+repos:
+- repo: https://github.com/pre-commit/pre-commit-hooks
+  rev: v4.5.0
+  hooks:
+  - id: check-added-large-files

MANIFEST.in

@@ -6,6 +6,7 @@ recursive-include openfe/tests/data/ *.graphml
 recursive-include openfe/tests/data/ *.edge
 recursive-include openfe/tests/data/ *.dat
 recursive-include openfe/tests/data/ *json.gz
+recursive-include openfe/tests/data/ *json_results.gz
 include openfecli/tests/data/*.json
 include openfecli/tests/data/*.tar.gz
 recursive-include openfecli/tests/ *.sdf

codecov.yml

@@ -0,0 +1,3 @@
+coverage:
+  status:
+    project: off

devtools/data/gen-serialized-results.py → devtools/data/gen_serialized_results.py

@@ -76,23 +76,33 @@ def execute_and_serialize(dag, protocol, simname):
         json.dump(outdict, zipfile, cls=JSON_HANDLER.encoder)
 
 
-def generate_md_json(smc):
+def generate_md_settings():
     settings = PlainMDProtocol.default_settings()
     settings.simulation_settings.equilibration_length_nvt = 0.01 * unit.nanosecond
     settings.simulation_settings.equilibration_length = 0.01 * unit.nanosecond
     settings.simulation_settings.production_length = 0.01 * unit.nanosecond
     settings.forcefield_settings.nonbonded_method = "nocutoff"
-    protocol = PlainMDProtocol(settings=settings)
+
+    return settings
+
+
+def generate_md_json(smc):
+    protocol = PlainMDProtocol(settings=generate_md_settings())
     system = openfe.ChemicalSystem({"ligand": smc})
     dag = protocol.create(stateA=system, stateB=system, mapping=None)
 
     execute_and_serialize(dag, protocol, "MDProtocol")
 
 
-def generate_ahfe_json(smc):
+def generate_ahfe_settings():
     settings = AbsoluteSolvationProtocol.default_settings()
+    settings.solvent_equil_simulation_settings.equilibration_length_nvt = 10 * unit.picosecond
+    settings.solvent_equil_simulation_settings.equilibration_length = 10 * unit.picosecond
+    settings.solvent_equil_simulation_settings.production_length = 10 * unit.picosecond
     settings.solvent_simulation_settings.equilibration_length = 10 * unit.picosecond
     settings.solvent_simulation_settings.production_length = 500 * unit.picosecond
+    settings.vacuum_equil_simulation_settings.equilibration_length = 10 * unit.picosecond
+    settings.vacuum_equil_simulation_settings.production_length = 10 * unit.picosecond
     settings.vacuum_simulation_settings.equilibration_length = 10 * unit.picosecond
     settings.vacuum_simulation_settings.production_length = 1000 * unit.picosecond
     settings.lambda_settings.lambda_elec = [0.0, 0.25, 0.5, 0.75, 1.0, 1.0,
@@ -109,7 +119,11 @@ def generate_ahfe_json(smc):
     settings.vacuum_engine_settings.compute_platform = 'CPU'
     settings.solvent_engine_settings.compute_platform = 'CUDA'
 
-    protocol = AbsoluteSolvationProtocol(settings=settings)
+    return settings
+
+
+def generate_ahfe_json(smc):
+    protocol = AbsoluteSolvationProtocol(settings=generate_ahfe_settings())
     sysA = openfe.ChemicalSystem(
         {"ligand": smc, "solvent": openfe.SolventComponent()}
     )
@@ -122,12 +136,17 @@ def generate_ahfe_json(smc):
     execute_and_serialize(dag, protocol, "AHFEProtocol")
 
 
-def generate_rfe_json(smcA, smcB):
+def generate_rfe_settings():
     settings = RelativeHybridTopologyProtocol.default_settings()
     settings.simulation_settings.equilibration_length = 10 * unit.picosecond
     settings.simulation_settings.production_length = 250 * unit.picosecond
     settings.forcefield_settings.nonbonded_method = "nocutoff"
-    protocol = RelativeHybridTopologyProtocol(settings=settings)
+
+    return settings
+
+
+def generate_rfe_json(smcA, smcB):
+    protocol = RelativeHybridTopologyProtocol(settings=generate_rfe_settings())
 
     a_smcB = align_mol_shape(smcB, ref_mol=smcA)
     mapper = KartografAtomMapper(atom_map_hydrogens=True)

docs/CHANGELOG.rst

@@ -0,0 +1,5 @@
+=================
+openfe Change Log
+=================
+
+.. current developments

docs/conf.py

@@ -103,9 +103,10 @@
 
 autodoc_mock_imports = [
     "matplotlib",
-    "openmmtools",
     "mdtraj",
     "openmmforcefields",
+    "openmmtools",
+    "pymbar",
 ]
 
 # Extensions for the myst parser

docs/cookbook/creating_atom_mappings.rst

@@ -5,7 +5,7 @@ Creating Atom Mappings
 
 Once your :ref:`data has been loaded<Loading Molecules>`
 we can now proceed to defining how Components in these Systems correspond.
-``Mapping`` objects are used to defined how ``Component`` objects from different :class:`ChemicalSystems` are related.
+``Mapping`` objects are used to defined how ``Component`` objects from different :class:`.ChemicalSystem` objects are related.
 This guide will show how this concept applies to the case of a pair of ligands we wish to transform between.
 
 Generating Mappings

docs/index.rst

@@ -65,13 +65,13 @@ The **OpenFE** toolkit provides open-source frameworks for calculating alchemica
 
         Reference guide on using the OpenFE CLI.
 
-    .. grid-item-card:: OpenFE Showcase
+    .. grid-item-card:: Changelog
         :img-top: _static/Showcase.svg
         :text-align: center
-        :link: tutorials/showcase_notebook
+        :link: CHANGELOG
         :link-type: doc
 
-        Tutorial notebook showing the sorts of things OpenFE can do.
+        Any notable changes in the package for each released version
 
     .. grid-item-card:: Relative Free Energy Protocol
         :img-top: _static/Rocket.svg
@@ -92,6 +92,7 @@ The **OpenFE** toolkit provides open-source frameworks for calculating alchemica
    guide/index
    cookbook/index
    reference/index
+   CHANGELOG
 
 Indices and tables
 ------------------

docs/reference/api/atom_mappers.rst

@@ -0,0 +1,80 @@
+.. _Atom Mappers:
+
+Atom Mappings
+=============
+
+Tools for mapping atoms in one molecule to those in another. Used to generate efficient ligand networks.
+
+.. module:: openfe.setup.atom_mapping
+
+.. rubric:: Abstract Base Class
+
+.. autosummary::
+    :nosignatures:
+    :toctree: generated/
+
+    LigandAtomMapper
+
+.. rubric:: Implementations
+
+.. autosummary::
+    :nosignatures:
+    :toctree: generated/
+
+    LomapAtomMapper
+    PersesAtomMapper
+
+.. rubric:: Data Types
+
+.. autosummary::
+    :nosignatures:
+    :toctree: generated/
+
+    LigandAtomMapping
+
+.. _Atom Map Scorers:
+
+Atom Map Scorers
+----------------
+
+Scoring functions for a mapping between ligands. These are used as objective functions for :any:`Ligand Network Planners`.
+
+
+Lomap Scorers
+~~~~~~~~~~~~~
+
+Scorers implemented by the `LOMAP <https://github.com/OpenFreeEnergy/Lomap>`_ package.
+
+.. apparently we need the atom_mapping because internally autofunction is
+    trying ``import openfe.setup.lomap_scorers``, which doesn't work (whereas
+    ``from openfe.setup import lomap_scorers`` does)
+.. module:: openfe.setup.atom_mapping.lomap_scorers
+
+.. autosummary::
+    :nosignatures:
+    :toctree: generated/
+
+    default_lomap_score
+    ecr_score
+    mcsr_score
+    mncar_score
+    atomic_number_score
+    hybridization_score
+    sulfonamides_score
+    heterocycles_score
+    transmuting_methyl_into_ring_score
+    transmuting_ring_sizes_score
+
+
+Perses Scorers
+~~~~~~~~~~~~~~
+
+Scorers implemented by the `Perses <https://github.com/choderalab/perses>`_ package.
+
+.. module:: openfe.setup.atom_mapping.perses_scorers
+
+.. autosummary::
+    :nosignatures:
+    :toctree: generated/
+
+    default_perses_scorer

docs/reference/api/index.rst

@@ -6,10 +6,11 @@ OpenFE API Reference
 .. toctree::
     :maxdepth: 2
 
-    data
     systems_and_components
+    atom_mappers
     ligand_network
     alchemical_network_planning
     defining_and_executing_simulations
     openmm_rfe
     openmm_solvation_afe
+    openmm_md