Add duecredit (#601)

* Add basic skeleton for duecredit

* Add initial duecredit tests

* add duecredit to the environment

* omit due.py from coverage

* Update environment.yml

* remove duecredit.p files

* Update openfe/tests/utils/test_duecredit.py

Co-authored-by: Irfan Alibay <[email protected]>

---------

Co-authored-by: Richard Gowers <[email protected]>

.github/workflows/ci.yaml

@@ -79,6 +79,7 @@ jobs:
         env:
           # Set the OFE_SLOW_TESTS to True if running a Cron job
           OFE_SLOW_TESTS: ${{ fromJSON('{"false":"false","true":"true"}')[github.event_name != 'pull_request'] }}
+          DUECREDIT_ENABLE: 'yes'
         run: |
           pytest -n auto -v --cov=openfe --cov=openfecli --cov-report=xml --durations=10
 

.gitignore

@@ -1,4 +1,5 @@
 # custom ignores
+.duecredit.p
 .xxrun
 .idea/
 .vscode/

environment.yml

@@ -3,6 +3,7 @@ channels:
   - jaimergp/label/unsupported-cudatoolkit-shim
   - conda-forge
 dependencies:
+  - duecredit
   - numpy<1.24
   - networkx
   - rdkit

openfe/due.py

@@ -0,0 +1,74 @@
+# emacs: at the end of the file
+# ex: set sts=4 ts=4 sw=4 et:
+# ## ### ### ### ### ### ### ### ### ### ### ### ### ### ### ### ### ### ### #
+"""
+
+Stub file for a guaranteed safe import of duecredit constructs:  if duecredit
+is not available.
+
+To use it, place it into your project codebase to be imported, e.g. copy as
+
+    cp stub.py /path/tomodule/module/due.py
+
+Note that it might be better to avoid naming it duecredit.py to avoid shadowing
+installed duecredit.
+
+Then use in your code as
+
+    from .due import due, Doi, BibTeX, Text
+
+See  https://github.com/duecredit/duecredit/blob/master/README.md for examples.
+
+Origin:     Originally a part of the duecredit
+Copyright:  2015-2021  DueCredit developers
+License:    BSD-2
+"""
+
+__version__ = '0.0.9'
+
+
+class InactiveDueCreditCollector(object):
+    """Just a stub at the Collector which would not do anything"""
+    def _donothing(self, *args, **kwargs):
+        """Perform no good and no bad"""
+        pass
+
+    def dcite(self, *args, **kwargs):
+        """If I could cite I would"""
+        def nondecorating_decorator(func):
+            return func
+        return nondecorating_decorator
+
+    active = False
+    activate = add = cite = dump = load = _donothing
+
+    def __repr__(self):
+        return self.__class__.__name__ + '()'
+
+
+def _donothing_func(*args, **kwargs):
+    """Perform no good and no bad"""
+    pass
+
+
+try:
+    from duecredit import due, BibTeX, Doi, Url, Text  # lgtm [py/unused-import]
+    if 'due' in locals() and not hasattr(due, 'cite'):
+        raise RuntimeError(
+            "Imported due lacks .cite. DueCredit is now disabled")
+except Exception as e:
+    if not isinstance(e, ImportError):
+        import logging
+        logging.getLogger("duecredit").error(
+            "Failed to import duecredit due to %s" % str(e))
+    # Initiate due stub
+    due = InactiveDueCreditCollector()
+    BibTeX = Doi = Url = Text = _donothing_func
+
+# Emacs mode definitions
+# Local Variables:
+# mode: python
+# py-indent-offset: 4
+# tab-width: 4
+# indent-tabs-mode: nil
+# End:

openfe/protocols/openmm_afe/equil_solvation_afe_method.py

@@ -23,7 +23,7 @@
 Acknowledgements
 ----------------
 * Originally based on hydration.py in
-  `espaloma <https://github.com/choderalab/espaloma_charge>`_
+  `espaloma_charge <https://github.com/choderalab/espaloma_charge>`_
 
 """
 from __future__ import annotations
@@ -56,6 +56,29 @@
 from ..openmm_utils import system_validation, settings_validation
 from .base import BaseAbsoluteUnit
 from openfe.utils import without_oechem_backend, log_system_probe
+from openfe.due import due, Doi
+
+
+due.cite(Doi("10.5281/zenodo.596504"),
+         description="Yank",
+         path="openfe.protocols.openmm_afe.equil_solvation_afe_method",
+         cite_module=True)
+
+due.cite(Doi("10.48550/ARXIV.2302.06758"),
+         description="EspalomaCharge",
+         path="openfe.protocols.openmm_afe.equil_solvation_afe_method",
+         cite_module=True)
+
+due.cite(Doi("10.5281/zenodo.596622"),
+         description="OpenMMTools",
+         path="openfe.protocols.openmm_afe.equil_solvation_afe_method",
+         cite_module=True)
+
+due.cite(Doi("10.1371/journal.pcbi.1005659"),
+         description="OpenMM",
+         path="openfe.protocols.openmm_afe.equil_solvation_afe_method",
+         cite_module=True)
+
 
 logger = logging.getLogger(__name__)
 

openfe/protocols/openmm_rfe/equil_rfe_methods.py

@@ -1,6 +1,6 @@
 # This code is part of OpenFE and is licensed under the MIT license.
 # For details, see https://github.com/OpenFreeEnergy/openfe
-"""Equilibrium Relative Free Energy methods using OpenMM in a
+"""Equilibrium Relative Free Energy methods using OpenMM and OpenMMTools in a
 Perses-like manner.
 
 This module implements the necessary methodology toolking to run calculate a
@@ -14,6 +14,10 @@
 ----
 * Improve this docstring by adding an example use case.
 
+Acknowledgements
+----------------
+This Protocol is based on, and leverages components originating from
+the Perses toolkit (https://github.com/choderalab/perses).
 """
 from __future__ import annotations
 
@@ -55,10 +59,28 @@
 )
 from . import _rfe_utils
 from ...utils import without_oechem_backend, log_system_probe
+from openfe.due import due, Doi
+
 
 logger = logging.getLogger(__name__)
 
 
+due.cite(Doi("10.5281/zenodo.1297683"),
+         description="Perses",
+         path="openfe.protocols.openmm_rfe.equil_rfe_methods",
+         cite_module=True)
+
+due.cite(Doi("10.5281/zenodo.596622"),
+         description="OpenMMTools",
+         path="openfe.protocols.openmm_rfe.equil_rfe_methods",
+         cite_module=True)
+
+due.cite(Doi("10.1371/journal.pcbi.1005659"),
+         description="OpenMM",
+         path="openfe.protocols.openmm_rfe.equil_rfe_methods",
+         cite_module=True)
+
+
 def _get_resname(off_mol) -> str:
     # behaviour changed between 0.10 and 0.11
     omm_top = off_mol.to_topology().to_openmm()

openfe/tests/utils/test_duecredit.py

@@ -0,0 +1,30 @@
+import os
+import importlib
+import pytest
+
+import openfe
+
+
+pytest.importorskip('duecredit')
+
+
+@pytest.mark.skipif((os.environ.get('DUECREDIT_ENABLE', 'no').lower()
+                     in ('no', '0', 'false')),
+                     reason="duecredit is disabled")
+class TestDuecredit:
+
+    @pytest.mark.parametrize('module, dois', [
+        ['openfe.protocols.openmm_afe.equil_solvation_afe_method',
+         ['10.5281/zenodo.596504', '10.48550/arxiv.2302.06758',
+          '10.5281/zenodo.596622', '10.1371/journal.pcbi.1005659']],
+        ['openfe.protocols.openmm_rfe.equil_rfe_methods',
+         ['10.5281/zenodo.1297683', '10.5281/zenodo.596622',
+          '10.1371/journal.pcbi.1005659']],
+    ])
+    def test_duecredit_protocol_collection(self, module, dois):
+        importlib.import_module(module)
+        for doi in dois:
+            assert openfe.due.due.citations[(module, doi)].cites_module
+
+    def test_duecredit_active(self):
+        assert openfe.due.due.active

pyproject.toml

@@ -57,6 +57,7 @@ ignore_missing_imports = true
 
 [tool.coverage.run]
 omit = [
+    "openfe/due.py",
     "*/tests/dev/*py",
     "*/tests/protocols/test_openmm_rfe_slow.py"
 ]