Adding a generic atom mapping scorer

gufe/__init__.py

@@ -18,7 +18,7 @@
 
 from .mapping import (
     ComponentMapping,  # how individual Components relate
-    AtomMapping, AtomMapper,  # more specific to atom based components
+    AtomMapping, AtomMapper,  AtomMappingScorer,  # more specific to atom based components
     LigandAtomMapping,
 )
 

gufe/mapping/__init__.py

@@ -4,4 +4,5 @@
 from .componentmapping import ComponentMapping
 from .atom_mapping import AtomMapping
 from .atom_mapper import AtomMapper
+from .atom_mapping_scorer import AtomMappingScorer
 from .ligandatommapping import LigandAtomMapping

gufe/mapping/atom_mapping_scorer.py

@@ -0,0 +1,43 @@
+# This code is part of kartograf and is licensed under the MIT license.
+# For details, see https://github.com/OpenFreeEnergy/gufe
+
+import abc
+from ..tokenization import GufeTokenizable
+
+from . import AtomMapping
+
+
+class AtomMappingScorer(GufeTokenizable):
+    """A generic class for scoring Atom mappings.
+    this class can be used for example to build graph algorithm based networks.
+
+    Implementations of this class can require an arbitrary and non-standardised
+    number of input arguments to create.
+
+    Implementations of this class provide the :meth:`.get_score` method
+
+    """
+
+    def __call__(self, mapping: AtomMapping) -> float:
+        return self.get_score(mapping)
+
+    @abc.abstractmethod
+    def get_score(self, mapping: AtomMapping) -> float:
+        """ calculate the score for an  :class:`.AtomMapping`
+            the scoring function returns a value between 0 and 1.
+            a value close to 1.0 indicates a small distance, a score close to zero indicates a large cost/error.
+
+        Parameters
+        ----------
+        mapping: AtomMapping
+            the mapping to be scored
+        args
+        kwargs
+
+        Returns
+        -------
+        float
+            a value between [0,1] where zero is a very bad score and one a very good one.
+
+        """
+        pass

gufe/tests/test_setup_interfaces.py

@@ -0,0 +1,15 @@
+# This code is part of OpenFE and is licensed under the MIT license.
+# For details, see https://github.com/OpenFreeEnergy/gufe
+
+import pytest
+from gufe import AtomMappingScorer, AtomMapper
+
+
+def test_atom_mapping_scorer():
+    with pytest.raises(TypeError, match="Can't instantiate abstract class AtomMappingScorer"):
+        scorer = AtomMappingScorer()
+
+
+def test_atom_mapper():
+    with pytest.raises(TypeError, match="Can't instantiate abstract class AtomMapper"):
+        mapper = AtomMapper()