deprecate perses functionality (#1857)

* add tests that should fail

* add deprecation warnings

* news item

* raises-> warns fix

* Update news/deprecate_perses.rst

Co-authored-by: Mike Henry <11765982+mikemhenry@users.noreply.github.com>

* add issues link

---------

Co-authored-by: Mike Henry <11765982+mikemhenry@users.noreply.github.com>

Author: atravitz

news/deprecate_perses.rst

@@ -0,0 +1,24 @@
+**Added:**
+
+* <news item>
+
+**Changed:**
+
+* <news item>
+
+**Deprecated:**
+
+* Perses atom mapper and scorer functionality is deprecated, slated to be removed in ``openfe v2.0``. 
+This includes ``PersesAtomMapper`` and ``default_perses_scorer``.
+
+**Removed:**
+
+* <news item>
+
+**Fixed:**
+
+* <news item>
+
+**Security:**
+
+* <news item>

src/openfe/setup/atom_mapping/perses_mapper.py

@@ -6,6 +6,8 @@
 
 """
 
+import warnings
+
 from gufe.settings.typing import AngstromQuantity
 from openff.units import Quantity, unit
 from openff.units.openmm import to_openmm
@@ -75,6 +77,10 @@ def __init__(
             can be mapped, default: 0.25*unit.angstrom
 
         """
+        warnings.warn(
+            "PersesAtomMapper is deprecated and is planned to be removed in openfe v2.0. If you have questions related to this, please open an issue at https://github.com/OpenFreeEnergy/openfe/issues.",
+            DeprecationWarning,
+        )
         self.allow_ring_breaking = allow_ring_breaking
         self.preserve_chirality = preserve_chirality
         self.use_positions = use_positions

src/openfe/setup/atom_mapping/perses_scorers.py

@@ -1,6 +1,7 @@
 # This code is part of OpenFE and is licensed under the MIT license.
 # For details, see https://github.com/OpenFreeEnergy/openfe
 
+import warnings
 from typing import Callable
 
 from openfe.utils import requires_package
@@ -67,6 +68,11 @@ def default_perses_scorer(
     -------
         float
     """
+    warnings.warn(
+        "default_perses_scorer is deprecated and is planned to be removed in openfe v2.0. If you have questions related to this, please open an issue at https://github.com/OpenFreeEnergy/openfe/issues",
+        DeprecationWarning,
+    )
+
     score = AtomMapper(use_positions=use_positions).score_mapping(
         AtomMapping(
             old_mol=mapping.componentA.to_openff(),

src/openfe/tests/setup/atom_mapping/test_perses_atommapper.py

@@ -13,8 +13,8 @@ def test_simple(atom_mapping_basic_test_files):
     # basic sanity check on the LigandAtomMapper
     mol1 = atom_mapping_basic_test_files["methylcyclohexane"]
     mol2 = atom_mapping_basic_test_files["toluene"]
-
-    mapper = PersesAtomMapper()
+    with pytest.warns(DeprecationWarning, match="PersesAtomMapper"):
+        mapper = PersesAtomMapper()
 
     mapping_gen = mapper.suggest_mappings(mol1, mol2)
 
@@ -31,8 +31,8 @@ def test_generator_length(atom_mapping_basic_test_files):
     # generator stops correctly
     mol1 = atom_mapping_basic_test_files["methylcyclohexane"]
     mol2 = atom_mapping_basic_test_files["toluene"]
-
-    mapper = PersesAtomMapper()
+    with pytest.warns(DeprecationWarning, match="PersesAtomMapper"):
+        mapper = PersesAtomMapper()
 
     mapping_gen = mapper.suggest_mappings(mol1, mol2)
 
@@ -45,7 +45,8 @@ def test_generator_length(atom_mapping_basic_test_files):
 @skip_if_missing("perses")
 def test_empty_atommappings(mol_pair_to_shock_perses_mapper):
     mol1, mol2 = mol_pair_to_shock_perses_mapper
-    mapper = PersesAtomMapper()
+    with pytest.warns(DeprecationWarning, match="PersesAtomMapper"):
+        mapper = PersesAtomMapper()
 
     mapping_gen = mapper.suggest_mappings(mol1, mol2)
 
@@ -59,11 +60,12 @@ def test_empty_atommappings(mol_pair_to_shock_perses_mapper):
 @skip_if_missing("openeye")
 @skip_if_missing("perses")
 def test_dict_round_trip():
-    # use some none defaults
-    mapper1 = PersesAtomMapper(
-        allow_ring_breaking=False,
-        preserve_chirality=False,
-        coordinate_tolerance=0.01 * unit.nanometer,
-    )
-    mapper2 = PersesAtomMapper.from_dict(mapper1.to_dict())
+    with pytest.warns(DeprecationWarning, match="PersesAtomMapper"):
+        # use some none defaults
+        mapper1 = PersesAtomMapper(
+            allow_ring_breaking=False,
+            preserve_chirality=False,
+            coordinate_tolerance=0.01 * unit.nanometer,
+        )
+        mapper2 = PersesAtomMapper.from_dict(mapper1.to_dict())
     assert mapper2.to_dict() == mapper1.to_dict()

src/openfe/tests/setup/atom_mapping/test_perses_scorers.py

@@ -18,7 +18,8 @@
 @pytest.mark.xfail(not USING_OLD_OFF, reason="perses #1108")
 def test_perses_normalization_not_using_positions(gufe_atom_mapping_matrix):
     # now run the openfe equivalent with the same ligand atom _mappings
-    scorer = perses_scorers.default_perses_scorer
+    with pytest.warns(DeprecationWarning, match="default_perses_scorer"):
+        scorer = perses_scorers.default_perses_scorer
     molecule_row = np.max(list(gufe_atom_mapping_matrix.keys())) + 1
     norm_scores = np.zeros([molecule_row, molecule_row])
 
@@ -41,7 +42,8 @@ def test_perses_normalization_not_using_positions(gufe_atom_mapping_matrix):
 @skip_if_missing("perses")
 @pytest.mark.xfail(not USING_OLD_OFF, reason="perses #1108")
 def test_perses_not_implemented_position_using(gufe_atom_mapping_matrix):
-    scorer = perses_scorers.default_perses_scorer
+    with pytest.warns(DeprecationWarning, match="default_perses_scorer"):
+        scorer = perses_scorers.default_perses_scorer
 
     first_key = list(gufe_atom_mapping_matrix.keys())[0]
     match_re = "normalizing using positions is not currently implemented"
@@ -76,7 +78,8 @@ def test_perses_regression(gufe_atom_mapping_matrix):
     assert matrix.shape == (8, 8)
 
     # now run the openfe equivalent with the same ligand atom _mappings
-    scorer = perses_scorers.default_perses_scorer
+    with pytest.warns(DeprecationWarning, match="default_perses_scorer"):
+        scorer = perses_scorers.default_perses_scorer
     scores = np.zeros_like(matrix)
     for (i, j), ligand_atom_mapping in gufe_atom_mapping_matrix.items():
         score = scorer(