acellera-kartograf 2.0.0__tar.gz

acellera_kartograf-2.0.0/.coveragerc

@@ -0,0 +1,14 @@
+[run]
+omit =
+    */_version.py
+    */tests/dev/*py
+    src/kartograf/tests/*
+    src/kartograf/utils/*
+
+[report]
+exclude_lines =
+    pragma: no cover
+    pragma: no-cover
+    -no-cov
+    raise NotImplementedError
+    \.\.\.

acellera_kartograf-2.0.0/.git-blame-ignore-revs

@@ -0,0 +1,4 @@
+# https://github.com/OpenFreeEnergy/kartograf/pull/124
+c04dceee6ca0d0d9f44da4193c9c29fbdacc2a16
+# https://github.com/OpenFreeEnergy/kartograf/pull/120
+e2c9a6ad260fa01e3ffc2f412647d6743af6a94c

acellera_kartograf-2.0.0/.github/ISSUE_TEMPLATE/bug_report.md

@@ -0,0 +1,38 @@
+---
+name: Bug report
+about: Create a report to help us improve
+title: ''
+labels: ''
+assignees: ''
+
+---
+
+**Describe the bug**
+A clear and concise description of what the bug is.
+
+**To Reproduce**
+Steps to reproduce the behavior:
+1. Go to '...'
+2. Click on '....'
+3. Scroll down to '....'
+4. See error
+
+**Expected behavior**
+A clear and concise description of what you expected to happen.
+
+**Screenshots**
+If applicable, add screenshots to help explain your problem.
+
+**Desktop (please complete the following information):**
+ - OS: [e.g. iOS]
+ - Browser [e.g. chrome, safari]
+ - Version [e.g. 22]
+
+**Smartphone (please complete the following information):**
+ - Device: [e.g. iPhone6]
+ - OS: [e.g. iOS8.1]
+ - Browser [e.g. stock browser, safari]
+ - Version [e.g. 22]
+
+**Additional context**
+Add any other context about the problem here.

acellera_kartograf-2.0.0/.github/ISSUE_TEMPLATE/feature_request.md

@@ -0,0 +1,20 @@
+---
+name: Feature request
+about: Suggest an idea for this project
+title: ''
+labels: ''
+assignees: ''
+
+---
+
+**Is your feature request related to a problem? Please describe.**
+A clear and concise description of what the problem is. Ex. I'm always frustrated when [...]
+
+**Describe the solution you'd like**
+A clear and concise description of what you want to happen.
+
+**Describe alternatives you've considered**
+A clear and concise description of any alternative solutions or features you've considered.
+
+**Additional context**
+Add any other context or screenshots about the feature request here.

acellera_kartograf-2.0.0/.github/PULL_REQUEST_TEMPLATE/release_template.md

@@ -0,0 +1,13 @@
+<!--
+Checklist for releasing a new version of kartograf.
+-->
+
+Make the PR:
+* [ ] Create a new release-prep branch corresponding to the version name, e.g. `release-prep-v1.2.0`.  Note: please follow [semantic versioning](https://semver.org/).
+* [ ] Check that all user-relevant updates are included in the `news/` rever `.rst` files. You can backfill any additional items by making a new .rst, e.g. `backfill.rst`
+* [ ] Run [rever](https://regro.github.io/rever-docs/index.html#), e.g. `rever 1.2.0`. This will auto-commit `docs/CHANGELOG.md` and remove the `.rst` files from `news/`.
+* [ ] Verify that`docs/CHANGELOG.md` looks correct.
+* [ ] Make the PR and verify that CI/CD passes.
+* [ ] Merge the PR into `main`.
+
+After Merging the PR [follow this guide](https://github.com/OpenFreeEnergy/openfe/wiki/How-to-create-a-new-release)

acellera_kartograf-2.0.0/.github/dependabot.yml

@@ -0,0 +1,6 @@
+version: 2
+updates:
+  - package-ecosystem: "github-actions"
+    directory: "/"
+    schedule:
+      interval: "weekly"

acellera_kartograf-2.0.0/.github/pull_request_template.md

@@ -0,0 +1,20 @@
+<!--
+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
+* [ ] All new code is appropriately documented (user-facing code _must_ have complete docstrings).
+* [ ] Added a ``news`` entry, or the changes are not user-facing.
+* [ ] Ran pre-commit: you can run [pre-commit](https://pre-commit.com) locally or comment on this PR with `pre-commit.ci autofix`.
+
+## Developers certificate of origin
+- [ ] I certify that this contribution is covered by the MIT License [here](https://github.com/OpenFreeEnergy/kartograf/blob/main/LICENSE) and the **Developer Certificate of Origin** at <https://developercertificate.org/>.

acellera_kartograf-2.0.0/.github/workflows/check_for_api_break.yaml

@@ -0,0 +1,77 @@
+name: Check for API breaks
+
+on:
+  pull_request_target:
+    branches:
+      - main
+
+jobs:
+  check:
+    runs-on: ubuntu-latest
+    permissions:
+      pull-requests: write
+
+    steps:
+    - uses: actions/checkout@v6
+      with:
+        fetch-depth: 0
+
+    - run: git fetch --depth=1 --tags
+
+    - uses: actions/setup-python@v6
+      with:
+        python-version: "3.13"
+
+    - name: Check for API breaks
+      continue-on-error: true
+      id: check
+      run: |
+        pip install griffe
+        griffe check -s src/ "kartograf" --verbose -a origin/main
+
+    - name: Manage PR Comments
+      uses: actions/github-script@v9
+      with:
+        script: |
+          const prNumber = context.payload.pull_request.number;
+          const identifier = '<!-- api-break-check -->';
+          const runUrl = `${context.serverUrl}/${context.repo.owner}/${context.repo.repo}/actions/runs/${context.runId}`;
+          const stepUrl = `${runUrl}#step:check`;
+
+          // Determine the outcome of the check step
+          const checkStepOutcome = '${{ steps.check.outcome }}';
+
+          // List existing comments
+          const { data: comments } = await github.rest.issues.listComments({
+            owner: context.repo.owner,
+            repo: context.repo.repo,
+            issue_number: prNumber,
+          });
+
+          // Delete previous comments from this action
+          for (const comment of comments) {
+            if (comment.body.includes(identifier)) {
+              await github.rest.issues.deleteComment({
+                owner: context.repo.owner,
+                repo: context.repo.repo,
+                comment_id: comment.id,
+              });
+            }
+          }
+
+          // Post a new comment only if the check step failed
+          if (checkStepOutcome === 'failure') {
+            await github.rest.issues.createComment({
+              owner: context.repo.owner,
+              repo: context.repo.repo,
+              issue_number: prNumber,
+              body: `${identifier}\n🚨 API breaking changes detected! 🚨\n[View logs for this step](${stepUrl})`
+            });
+          } else {
+            await github.rest.issues.createComment({
+              owner: context.repo.owner,
+              repo: context.repo.repo,
+              issue_number: prNumber,
+              body: `${identifier}\nNo API break detected ✅`
+            });
+          }

acellera_kartograf-2.0.0/.github/workflows/ci.yaml

@@ -0,0 +1,127 @@
+name: "CI"
+on:
+  workflow_dispatch:
+  pull_request:
+    branches:
+      - main
+  push:
+    branches:
+      - main
+  schedule:
+    # At 07:00 UTC
+    - cron: "0 7 * * *"
+
+concurrency:
+  group: "${{ github.workflow }}-${{ github.ref }}"
+  cancel-in-progress: true
+
+defaults:
+  run:
+    shell: bash -leo pipefail {0}
+
+jobs:
+  tests:
+    runs-on: ${{ matrix.OS }}-latest
+    name: "tests"
+    strategy:
+      fail-fast: false
+      matrix:
+        os: ['ubuntu',]
+        python-version:
+          - "3.11"
+          - "3.12"
+          - "3.13"
+        include:
+          - os: 'macos'
+            python-version: "3.13"
+
+    steps:
+      - uses: actions/checkout@v6
+      - name: Get current date
+        id: date
+        run: echo "date=$(date +%Y-%m-%d)" >> "${GITHUB_OUTPUT}"
+      - uses: mamba-org/setup-micromamba@v3
+        with:
+          environment-file: environment.yml
+          environment-name: kartograf
+          cache-environment: true
+          cache-downloads: true
+          cache-environment-key: environment-${{ steps.date.outputs.date }}
+          cache-downloads-key: downloads-${{ steps.date.outputs.date }}
+          create-args: >-
+            python=${{ matrix.python-version }}
+
+      - name: "Install"
+        run: pip install --no-deps -e .
+
+      - name: "Test imports"
+        run: |
+          # if we add more to this, consider changing to for + env vars
+          python -Ic "import kartograf"
+
+      - name: "Environment Information"
+        run: |
+          micromamba info
+          micromamba list
+
+      - name: "Print Version"
+        run: python -c "import kartograf; print(kartograf.__version__)"
+
+      - name: "Run tests"
+        run: |
+          # run tests
+          pytest -n auto -v --cov=kartograf --cov-report=xml
+
+      - name: "Test Notebooks"
+        if: ${{ matrix.os != 'macos' }}
+        run: |
+          # Only need to test the notebook(s) in examples/
+          pytest -v --nbval-lax examples/
+
+      - name: codecov
+        if: ${{ github.repository == 'OpenFreeEnergy/kartograf' && github.event_name != 'schedule'}}
+        uses: codecov/codecov-action@v6
+        with:
+          token: ${{ secrets.CODECOV_TOKEN }}
+          fail_ci_if_error: true
+          verbose: true
+
+  check_packaging:
+    runs-on: ubuntu-latest
+    timeout-minutes: 30
+
+    steps:
+    - uses: actions/checkout@v6
+
+    - uses: mamba-org/setup-micromamba@v3
+      with:
+          environment-file: environment.yml
+          environment-name: kartograf
+          create-args: >-
+            python=3.13
+
+    - name: install_deps
+      run: |
+        python -m pip install -U pip pipx wheel build
+
+    - name: build_package_sdist
+      run: pipx run build --sdist
+
+    - name: check_package_build
+      run: |
+        DISTRIBUTION=$(ls -t1 dist/kartograf-*.tar.gz | head -n1)
+        test -n "${DISTRIBUTION}" || { echo "no distribution dist/kartograf-*.tar.gz found"; exit 1; }
+
+    - name: install sdist
+      working-directory: ./dist
+      run: |
+        ls -a .
+        python -m pip install kartograf-*.tar.gz
+        du -sh kartograf-*.tar.gz
+
+    - name: check install
+      run: pip list
+
+    - name: run tests
+      working-directory: ./dist
+      run: python -m pytest -n logical --pyargs kartograf

acellera_kartograf-2.0.0/.gitignore

@@ -0,0 +1,101 @@
+# Byte-compiled / optimized / DLL files
+__pycache__/
+*.py[cod]
+*$py.class
+
+# Distribution / packaging
+.Python
+build/
+develop-eggs/
+dist/
+downloads/
+eggs/
+.eggs/
+lib/
+lib64/
+parts/
+sdist/
+var/
+wheels/
+pip-wheel-metadata/
+share/python-wheels/
+*.egg-info/
+.installed.cfg
+*.egg
+MANIFEST
+/src/pdbinf.egg-info/
+
+# PyInstaller
+#  Usually these files are written by a python script from a template
+#  before PyInstaller builds the exe, so as to inject date/other infos into it.
+*.manifest
+*.spec
+
+# Installer logs
+pip-log.txt
+pip-delete-this-directory.txt
+
+# Unit test / coverage reports
+htmlcov/
+.tox/
+.nox/
+.coverage
+.coverage.*
+.cache
+nosetests.xml
+coverage.xml
+*.cover
+*.py,cover
+.hypothesis/
+.pytest_cache/
+
+
+# Sphinx documentation
+docs/_build/
+
+# PyBuilder
+target/
+
+# Jupyter Notebook
+.ipynb_checkpoints
+
+# IPython
+profile_default/
+ipython_config.py
+
+# pyenv
+.python-version
+
+# PEP 582; used by e.g. github.com/David-OConnor/pyflow
+__pypackages__/
+
+# Celery stuff
+celerybeat-schedule
+celerybeat.pid
+
+# Environments
+.env
+.venv
+env/
+venv/
+ENV/
+env.bak/
+venv.bak/
+
+# mypy
+.mypy_cache/
+.dmypy.json
+dmypy.json
+
+# Pyre type checker
+.pyre/
+
+# don't check in version
+src/kartograf/_version.py
+
+#IDE
+.idea
+/src/kartograf/dev/
+
+# Rever
+rever/

acellera_kartograf-2.0.0/.pre-commit-config.yaml

@@ -0,0 +1,47 @@
+# See https://pre-commit.com for more information
+# See https://pre-commit.com/hooks.html for more hooks
+
+# comment / label "pre-commit.ci autofix" to a pull request to manually trigger auto-fixing
+ci:
+    autofix_prs: false
+    autoupdate_schedule: monthly
+repos:
+-   repo: https://github.com/pre-commit/pre-commit-hooks
+    rev: v6.0.0
+    hooks:
+    - id: trailing-whitespace
+      exclude: '\.(pdb|gro|top|sdf|xml|cif|graphml)$'
+    - id: check-added-large-files
+      args: ["--maxkb=4000"]
+    - id: check-case-conflict
+    - id: check-symlinks
+    - id: check-toml
+    - id: check-yaml
+    - id: debug-statements
+    - id: destroyed-symlinks
+    - id: end-of-file-fixer
+      exclude: '\.(graphml)$'
+
+- repo: https://github.com/tox-dev/pyproject-fmt
+  rev: "v2.21.1"
+  hooks:
+    - id: pyproject-fmt
+      args: [--max-supported-python=3.14]
+
+- repo: https://github.com/astral-sh/ruff-pre-commit
+  rev: v0.15.12
+  hooks:
+    # Run the linter.
+    - id: ruff
+      args: [--fix ]
+    # Run the formatter.
+    - id: ruff-format
+
+- repo: local
+  hooks:
+    - id: fmt-rst-codeblocks
+      name: Format Python code blocks in RST files
+      entry: python tools/fmt_rst_codeblocks.py
+      language: python
+      files: \.rst$
+      additional_dependencies: [ruff]

acellera_kartograf-2.0.0/CITATION.cff

@@ -0,0 +1,30 @@
+cff-version: 1.2.0
+message: "If you use this software, please cite it as below."
+authors:
+- family-names: "Ries"
+  given-names: "Benjamin"
+  orcid: "https://orcid.org/0000-0002-0945-8304"
+- family-names: "Alibay"
+  given-names: "Irfan"
+  orcid: "https://orcid.org/0000-0001-5787-9130"
+- family-names: "Swenson"
+  given-names: "David W.H."
+  orcid: "https://orcid.org/0000-0001-9922-7923"
+- family-names: "Baumann"
+  given-names: "Hannah M."
+  orcid: "https://orcid.org/0000-0002-1736-7744"
+- family-names: "Henry"
+  given-names: "Michael M."
+  orcid: "https://orcid.org/0000-0002-3870-9993"
+- family-names: "Eastwood"
+  given-names: "James R. B."
+  orcid: "https://orcid.org/0000-0003-3895-5227"
+- family-names: "Gowers"
+  given-names: "Richard J."
+  orcid: "https://orcid.org/0000-0002-3241-1846"
+title: "Kartograf: A Geometrically Accurate Atom Mapper for Hybrid-Topology Relative Free Energy Calculations"
+version: 1.0
+date-released: 2024-02-08
+url: "https://openfree.energy/"
+repository-code: "https://github.com/OpenFreeEnergy/kartograf"
+doi: 10.1021/acs.jctc.3c01206

acellera_kartograf-2.0.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2023 Open Free Energy
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

acellera_kartograf-2.0.0/PKG-INFO

@@ -0,0 +1,126 @@
+Metadata-Version: 2.4
+Name: acellera-kartograf
+Version: 2.0.0
+Summary: Kartograf is a package for geometrically mapping atoms of two molecules.
+Author-email: The OpenFE developers <openfe@omsf.io>
+License-Expression: MIT
+Project-URL: Homepage, https://github.com/OpenFreeEnergy/kartograf
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Dynamic: license-file
+
+<p align="center">
+    <picture align="center">
+      <source media="(prefers-color-scheme: dark)" srcset="https://github.com/OpenFreeEnergy/kartograf/blob/0a2ecb10f1c5ede3842fd9b92ffb232ad726426f/docs/_static/img/kartograf_logo_style5.png">
+      <source media="(prefers-color-scheme: light)" srcset="https://github.com/OpenFreeEnergy/kartograf/blob/0a2ecb10f1c5ede3842fd9b92ffb232ad726426f/docs/_static/img/kartograf_logo_style4.png">
+      <img alt="Kartografs fancy logo" src="https://github.com/OpenFreeEnergy/kartograf/blob/0a2ecb10f1c5ede3842fd9b92ffb232ad726426f/docs/_static/img/kartograf_logo_style4.png" width=35% >
+    </picture>
+</p>
+
+
+Kartograf: A Geometry-Based Atom Mapper
+==================================
+
+[//]: # (Badges)
+[![Logo](https://img.shields.io/badge/OSMF-OpenFreeEnergy-%23002f4a)](https://openfree.energy/)
+[![build](https://github.com/OpenFreeEnergy/kartograf/actions/workflows/ci.yaml/badge.svg)](https://github.com/OpenFreeEnergy/kartograf/actions/workflows/ci.yaml)
+[![coverage](https://codecov.io/gh/OpenFreeEnergy/kartograf/branch/main/graph/badge.svg)](https://codecov.io/gh/OpenFreeEnergy/kartograf)
+[![Documentation Status](https://readthedocs.org/projects/kartograf/badge/?version=latest)](https://kartograf.readthedocs.io/en/latest/?badge=latest)
+[![DOI](https://zenodo.org/badge/DOI/10.5281/zenodo.10566716.svg)](https://doi.org/10.5281/zenodo.10566716)
+[![Conda Install](https://img.shields.io/badge/Conda%20install---c%20conda--forge%20kartograf-009384)](https://anaconda.org/conda-forge/kartograf)
+
+Kartograf is a package for atom mappings focussing on 3D geometries.
+This package can be for example be used to generate hybrid topology systems, where an atom mapping is required to determine the core region of the approach.
+But of course there exist also other use cases for this package.
+The atom mapper takes two set of coordinates of molecules as input.
+Optionally those set of coordinates can be aligned onto each other, checkout the `atom_aligner` module functions
+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 `mapping_metrics`, which might be useful for checking quality of your mappings.
+
+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).
+
+You can find a preprint on [ChemRxiv](https://doi.org/10.26434/chemrxiv-2023-0n1pq).
+
+## Usage
+
+```python3
+from rdkit import Chem
+from kartograf.atom_aligner import align_mol_shape
+from kartograf.mapping_metrics import MappingRMSDScorer
+from kartograf import KartografAtomMapper, SmallMoleculeComponent
+
+# Preprocessing from Smiles - Here you can add your Input!
+# Generate Data: START
+smiles = ["c1ccccc1", "c1ccccc1(CO)"]
+rdmols = [Chem.MolFromSmiles(s) for s in smiles]
+rdmols = [Chem.AddHs(m, addCoords=True) for m in rdmols]
+[Chem.rdDistGeom.EmbedMolecule(m, useRandomCoords=False, randomSeed = 0) for m in rdmols]
+# Generate Data: END
+
+# Build Small Molecule Components
+molA, molB = [SmallMoleculeComponent.from_rdkit(m) for m in rdmols]
+
+# Align the mols first - this might not needed, depends on input.
+a_molB = align_mol_shape(molB, ref_mol=molA)
+
+# Build Kartograf Atom Mapper
+mapper = KartografAtomMapper(atom_map_hydrogens=True)
+
+# Get Mapping
+kartograf_mapping = next(mapper.suggest_mappings(molA, a_molB))
+
+# Score Mapping
+rmsd_scorer = MappingRMSDScorer()
+score = rmsd_scorer(mapping=kartograf_mapping)
+print(f"RMSD Score: {score}")
+
+kartograf_mapping
+```
+![](docs/_static/img/alignment_benz_ol.png)
+
+## Installation
+
+### Latest release
+Kartograf can be installed via the package following package managers:
+
+#### `conda` (conda-forge)
+
+```shell
+conda install -c conda-forge kartograf
+```
+
+Kartograf can be used via the OpenFE environment like:
+
+```python
+from openfe.setup.atom_mapping import kartograf
+```
+
+### Development version
+The developing setup of Kartograf works like this:
+
+```shell
+git clone https://github.com/OpenFreeEnergy/kartograf.git
+
+cd kartograf
+mamba env create -f environment.yml
+
+mamba activate kartograf
+pip install -e .
+
+```
+
+## License
+This library is made available under the MIT open source license.
+
+## Authors
+
+The OpenFE development team.