OpenFreeEnergy · mikemhenry · Feb 11, 2026 · Jan 13, 2026 · Jan 13, 2026 · Jan 13, 2026
diff --git a/README.md b/README.md
@@ -26,7 +26,7 @@ Optionally those set of coordinates can be aligned onto each other, checkout the
 of Kartograf that offer a shape alignment implementation and a MCS-skeleton alignment.
 The `atom_mapper` can be used to generate the 3D geometry focused atom mapping, the algorithm is described in the related publication of Kartograf (see reference).
 Additionally, rule based filter functions can be provided to demap atoms, that do not fulfill the desired criteria, see `filters`.
-Several mapping scoring metrics are provided, that evaluate geometric properties of your mapping, from `atom_mapping_scorer`, which might be useful for checking quality of your mappings.
+Several mapping scoring metrics are provided, that evaluate geometric properties of your mapping, from `mapping_metrics`, which might be useful for checking quality of your mappings.
 Finally, there is a visualization function `display_mappings_3d` that can be used to check out the mappings with a jupyter notebook widget.
 
 Checkout our article on Kartograf in the Journal of Chemical Theory and Computation: [*Kartograf: A Geometrically Accurate Atom Mapper for Hybrid-Topology Relative Free Energy Calculations* - Benjamin Ries*, Irfan Alibay, David W. H. Swenson, Hannah M. Baumann, Michael M. Henry, James R. B. Eastwood, and Richard J. Gowers](https://doi.org/10.1021/acs.jctc.3c01206).
@@ -41,7 +41,7 @@ Try our interactive demo: [![Open In Colab](https://colab.research.google.com/as
 ```python3
 from rdkit import Chem
 from kartograf.atom_aligner import align_mol_shape
-from kartograf.atom_mapping_scorer import MappingRMSDScorer
+from kartograf.mapping_metrics import MappingRMSDScorer
 from kartograf import KartografAtomMapper, SmallMoleculeComponent
 
 # Preprocessing from Smiles - Here you can add your Input!

diff --git a/docs/api/kartograf.scorers.rst b/docs/api/kartograf.scorers.rst
@@ -2,7 +2,7 @@
 kartograf.atom\_mapping\_scorer
 =================================
 
-.. automodule:: kartograf.atom_mapping_scorer
+.. automodule:: kartograf.mapping_metrics
    :members:
    :undoc-members:
    :show-inheritance:
diff --git a/docs/conf.py b/docs/conf.py
@@ -12,14 +12,15 @@
 #
 import os
 import sys
-sys.path.insert(0, os.path.abspath('../src'))
+
+sys.path.insert(0, os.path.abspath("../src"))
 
 
 # -- Project information -----------------------------------------------------
 
-project = 'kartograf'
-copyright = '2022, The OpenFE Development Team'
-author = 'The OpenFE Development Team'
+project = "kartograf"
+copyright = "2022, The OpenFE Development Team"
+author = "The OpenFE Development Team"
 
 
 # -- General configuration ---------------------------------------------------
@@ -28,20 +29,20 @@
 # extensions coming with Sphinx (named 'sphinx.ext.*') or your custom
 # ones.
 extensions = [
-    'sphinx.ext.autodoc',
-    'sphinx.ext.napoleon',
+    "sphinx.ext.autodoc",
+    "sphinx.ext.napoleon",
 ]
 
 # 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 = ['lomap', 'networkx', 'openff', 'openff.toolkit', 'rdkit', 'pytest',
+# autodoc_mock_imports = ['lomap', 'networkx', 'openff', 'openff.toolkit', 'rdkit', 'pytest',
 #                        'typing_extensions',
 #                        'click', 'plugcli']
 
@@ -50,10 +51,10 @@
 # The theme to use for HTML and HTML Help pages.  See the documentation for
 # a list of builtin themes.
 
-html_static_path = ['_static']
-html_theme = 'ofe_sphinx_theme'
-autoclass_content = 'both'
-html_favicon = '_static/img/logo/Kartograf_logo_boxed_dark.ico'
+html_static_path = ["_static"]
+html_theme = "ofe_sphinx_theme"
+autoclass_content = "both"
+html_favicon = "_static/img/logo/Kartograf_logo_boxed_dark.ico"
 html_logo = "_static/img/logo/Kartograf_logo_light_transp.png"
 html_theme_options = {
     "logo": {
@@ -69,12 +70,11 @@
     ],
     "accent_color": "FeelingSick",
 }
-#html_logo = "_static/Squaredcircle.svg"
 
 
 # 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_css_files = [
-    'css/custom.css',
+    "css/custom.css",
 ]
diff --git a/docs/index.rst b/docs/index.rst
@@ -12,7 +12,7 @@ mapping, the algorithm is described in the related publication of Kartograf (see
 Additionally, rule-based filter functions can be provided to demap atoms,
 that do not fulfill the desired criteria, see ``filters``.
 Several mapping scoring metrics are provided, that evaluate geometric
-properties of your mapping, from ``atom_mapping_scorer``, which might be
+properties of your mapping, from ``mapping_metrics``, which might be
 useful for checking the quality of your mappings.
 Finally, there is a visualization function ``display_mappings_3d`` that can be
 used to check out the mappings with a Jupyter Notebook widget.

diff --git a/docs/tutorial/mapping_tutorial.rst b/docs/tutorial/mapping_tutorial.rst
@@ -62,7 +62,7 @@ going to use the :class:`.MappingRMSDScorer`, which gives insight into how far t
 need to travel from one state to the other, if they are mapped onto each
 other::
 
-    from kartograf.atom_mapping_scorer import MappingRMSDScorer
+    from kartograf.mapping_metrics import MappingRMSDScorer
 
     # Score Mapping
     rmsd_scorer = MappingRMSDScorer()

diff --git a/environment.yml b/environment.yml
@@ -27,7 +27,8 @@ dependencies:
   # vis
   - ipywidgets
   - py3Dmol
+  # deps for testinging
+  - openfe >=1.8.1
   # docs
   - pip:
     - git+https://github.com/OpenFreeEnergy/ofe-sphinx-theme@a45f3edd5bc3e973c1a01b577c71efa1b62a65d6
-
diff --git a/examples/kartograf_example.ipynb b/examples/kartograf_example.ipynb
@@ -29,13 +29,16 @@
     "# NBVAL_SKIP\n",
     "# Only run this cell if on google colab\n",
     "import os\n",
+    "\n",
     "if \"COLAB_RELEASE_TAG\" in os.environ:\n",
     "    !pip install -U https://github.com/conda-incubator/condacolab/archive/cuda-version-12.tar.gz\n",
     "    import condacolab\n",
+    "\n",
     "    condacolab.install_mambaforge()\n",
     "    !wget -q https://raw.githubusercontent.com/OpenFreeEnergy/kartograf/main/examples/environment.yaml\n",
     "    !mamba env update -q --name=base --file=environment.yaml\n",
     "    from google.colab import output\n",
+    "\n",
     "    output.enable_custom_widget_manager()"
    ]
   },
@@ -51,23 +54,24 @@
    },
    "outputs": [],
    "source": [
-    "import sys\n",
-    "\n",
     "from rdkit import Chem\n",
+    "\n",
     "try:\n",
     "    from openfe_benchmarks import benzenes\n",
-    "except ModuleNotFoundError:\n",
-    "    !{sys.executable} -m pip install --no-deps git+https://github.com/OpenFreeEnergy/openfe-benchmarks.git\n",
+    "except (ModuleNotFoundError, ImportError):\n",
+    "    import sys  # noqa: F401\n",
+    "\n",
+    "    !{sys.executable} -m pip install --no-deps git+https://github.com/OpenFreeEnergy/openfe-benchmarks.git@d5a027e4e3cb53e47d4b230e8ddffda274b70aff\n",
     "    from openfe_benchmarks import benzenes\n",
-    "    \n",
+    "\n",
     "\n",
     "components = benzenes.get_system().ligand_components\n",
     "\n",
     "# Exclude cycle breakers! as not feasible for Hybrid topology approaches.\n",
     "not_lig = [\"lig_4\", \"lig_7\", \"lig_2\", \"lig_3\"]\n",
-    "components = [c for c in components if(c.name not in not_lig)]\n",
+    "components = [c for c in components if (c.name not in not_lig)]\n",
     "\n",
-    "Chem.Draw.MolsToGridImage([c.to_rdkit() for c in components])\n"
+    "Chem.Draw.MolsToGridImage([c.to_rdkit() for c in components])"
    ]
   },
   {
@@ -104,11 +108,11 @@
     "\n",
     "atomMapper = KartografAtomMapper()\n",
     "\n",
-    "#Generate Mappings\n",
+    "# Generate Mappings\n",
     "mappings = []\n",
-    "cA=components[-5] # central ligand from Ries et al. 2022\n",
+    "cA = components[-5]  # central ligand from Ries et al. 2022\n",
     "for cB in components:\n",
-    "    if(cA != cB):\n",
+    "    if cA != cB:\n",
     "        mapping = next(atomMapper.suggest_mappings(cA, cB))\n",
     "        mappings.append(mapping)"
    ]
@@ -129,6 +133,7 @@
    "outputs": [],
    "source": [
     "from kartograf.utils.mapping_visualization_widget import display_mappings_3d\n",
+    "\n",
     "display_mappings_3d(mappings)"
    ]
   },
@@ -162,28 +167,29 @@
    },
    "outputs": [],
    "source": [
-    "from kartograf.atom_mapping_scorer import (\n",
-    "    MappingVolumeRatioScorer, \n",
+    "from kartograf.mapping_metrics import (\n",
     "    MappingRMSDScorer,\n",
-    "    MappingShapeOverlapScorer, \n",
-    "    MappingShapeMismatchScorer\n",
-    "    )\n",
+    "    MappingShapeMismatchScorer,\n",
+    "    MappingShapeOverlapScorer,\n",
+    "    MappingVolumeRatioScorer,\n",
+    ")\n",
     "\n",
-    "scorer_dict ={\n",
+    "scorer_dict = {\n",
     "    \"volume_score\": MappingVolumeRatioScorer(),\n",
     "    \"rmsd_score\": MappingRMSDScorer(),\n",
     "    \"overlap_score\": MappingShapeOverlapScorer(),\n",
-    "    \"mismatch_score\": MappingShapeMismatchScorer()\n",
+    "    \"mismatch_score\": MappingShapeMismatchScorer(),\n",
     "}\n",
     "\n",
-    "def apply_scorers(mapping):\n",
+    "\n",
+    "def apply_scorers(mapping) -> None:\n",
     "    for score_name, scorer in scorer_dict.items():\n",
     "        setattr(mapping, score_name, scorer(mapping))\n",
     "\n",
-    "#score mappings:\n",
+    "\n",
+    "# score mappings:\n",
     "for mapping in mappings:\n",
-    "    apply_scorers(mapping)\n",
-    "\n"
+    "    apply_scorers(mapping)"
    ]
   },
   {
@@ -205,7 +211,7 @@
     "\n",
     "score_names = sorted(scorer_dict)\n",
     "plt.boxplot([[getattr(m, score_name) for m in mappings] for score_name in score_names])\n",
-    "plt.xticks(range(1, len(score_names)+1), score_names, rotation=45)"
+    "plt.xticks(range(1, len(score_names) + 1), score_names, rotation=45)"
    ]
   },
   {
@@ -223,45 +229,51 @@
    },
    "outputs": [],
    "source": [
-    "from scipy.stats import spearmanr\n",
     "from matplotlib import pyplot as plt\n",
+    "from scipy.stats import spearmanr\n",
     "\n",
     "score_names = sorted(scorer_dict)\n",
-    "fig, axes = plt.subplots(nrows=len(score_names), ncols=len(score_names), figsize=[16,9])\n",
+    "fig, axes = plt.subplots(nrows=len(score_names), ncols=len(score_names), figsize=[16, 9])\n",
     "\n",
-    "i=0\n",
+    "i = 0\n",
     "for score_nameA in score_names:\n",
-    "    j=0\n",
-    "    axes[i,j].set_ylabel(score_nameA)\n",
+    "    j = 0\n",
+    "    axes[i, j].set_ylabel(score_nameA)\n",
     "\n",
     "    for score_nameB in score_names:\n",
-    "        ax = axes[i,j]\n",
-    "        if(i == len(score_names)-1):\n",
+    "        ax = axes[i, j]\n",
+    "        if i == len(score_names) - 1:\n",
     "            ax.set_xlabel(score_nameB)\n",
     "        else:\n",
     "            ax.set_xticklabels([])\n",
-    "        if(j>0):\n",
+    "        if j > 0:\n",
     "            ax.set_yticklabels([])\n",
     "\n",
-    "\n",
     "        x = [getattr(m, score_nameA) for m in mappings]\n",
     "        y = [getattr(m, score_nameB) for m in mappings]\n",
-    "        r, _ = spearmanr(x,y)\n",
-    "        ax.scatter(x,y)\n",
-    "        ax.text(0.1,0.85, \"$r_{spearman}:~$\"+str(round(r,2)))\n",
-    "        ax.set_xlim([0,1])\n",
-    "        ax.set_ylim([0,1])\n",
+    "        r, _ = spearmanr(x, y)\n",
+    "        ax.scatter(x, y)\n",
+    "        ax.text(0.1, 0.85, \"$r_{spearman}:~$\" + str(round(r, 2)))\n",
+    "        ax.set_xlim([0, 1])\n",
+    "        ax.set_ylim([0, 1])\n",
     "\n",
-    "        j+=1\n",
-    "    i+=1\n",
+    "        j += 1\n",
+    "    i += 1\n",
     "fig.tight_layout()\n",
-    "fig.subplots_adjust(wspace=0, hspace=0)\n"
+    "fig.subplots_adjust(wspace=0, hspace=0)"
    ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {},
+   "outputs": [],
+   "source": []
   }
  ],
  "metadata": {
   "kernelspec": {
-   "display_name": "asapdiscovery",
+   "display_name": "Python 3 (ipykernel)",
    "language": "python",
    "name": "python3"
   },
@@ -275,7 +287,7 @@
    "name": "python",
    "nbconvert_exporter": "python",
    "pygments_lexer": "ipython3",
-   "version": "3.11.6"
+   "version": "3.13.11"
   }
  },
  "nbformat": 4,

diff --git a/pyproject.toml b/pyproject.toml
@@ -41,26 +41,46 @@ kartograf = [ "tests/data/*.pdb", "tests/data/*.sdf" ]
 fallback_version = "0.0.0"
 
 [tool.ruff]
+target-version = "py311"
 line-length = 120
-
-# Enable Pyflakes (`F`) and a subset of the pycodestyle (`E`)  codes by default.
+src = [ "src" ]
+# I've added all the linters that ruff supports as of 0.14.11
+# If it doesn't exist in the package (for example async) it is not enabled
+# I wanted to include it so that if there is a PR that adds async, we can
+# easily turn on the linter
+# For linters that exist and we want to use, but don't want to fix now, I've added them and then
+# excluded the rule(s) that we don't want to fix now, but would be good future TODO 
+# TODO add more linters!
 lint.select = [
-  # "F",  # Pyflakes
-  "I", # isort
-  "W", # pycodestyle warnings
-  # "E",  # pycodestyle errors
-  # "C901"  # mccabe complexity  TODO: add this back in
-  # "UP", # TODO: add this in
+  # "AIR",  # airflow https://pypi.org/project/apache-airflow/
+  # "FAST", # FastAPI https://pypi.org/project/fastapi/
+  "ANN",  # type annotations  https://pypi.org/project/flake8-annotations/
+  "E",    # pycodestyle errors
+  "ERA",  # find commented-out code https://pypi.org/project/eradicate/
+  "F",    # Pyflakes
+  "FURB", # A tool for refurbishing and modernizing Python codebases https://github.com/dosisod/refurb
+  "I",    # isort
+  # "C901",  # mccabe complexity  TODO: add this back in
+  "S",   # security related lint https://pypi.org/project/flake8-bandit/
+  "UP",  # pyupgrade 
+  "W",   # pycodestyle warnings
+  "YTT", # detect issues using sys to check python version https://pypi.org/project/flake8-2020/
 ]
+
 lint.ignore = [
-  "E402", # module-level import not at top (conflicts w/ isort)
-  "E722", # bare excepts (TODO: we should fix these in a follow-up PR)
-  "E731", # lambda expressions (TODO: we should fix these)
-  "F401", # unused imports (TODO: we should fix these)
-  "UP03", # pyupgrade linting (TODO: we should fix these)
+  "ANN001", # TODO Missing type annotation for function argument {name}
+  "ANN002", # TODO Missing type annotation for *{name}
+  "ANN003", # TODO Missing type annotation for **{name}
+  "ANN201", # TODO Missing return type annotation for public function {name}
+  "ANN202", # TODO Missing return type annotation for private function {name}
+  "ANN206", # TODO Missing return type annotation for classmethod {name}
+  "E501",   # line too long, if the formatter can't fix it then it can be okay 
 ]
 
 # ignore "unused import" error for all __init__.py files
 lint.per-file-ignores."__init__.py" = [ "E401" ]
-
-lint.isort.known-first-party = [ "gufe" ]
+# ignore securty issues in tests
+lint.per-file-ignores."src/kartograf/tests/*" = [ "S" ]
+lint.isort.combine-as-imports = true
+lint.isort.force-wrap-aliases = true
+lint.isort.known-first-party = [ "kartograf" ]