{"id":32177982,"url":"https://github.com/mobleylab/chemper","last_synced_at":"2026-02-18T22:02:24.228Z","repository":{"id":29207343,"uuid":"120546688","full_name":"MobleyLab/chemper","owner":"MobleyLab","description":"Repository for Chemical Perception Sampling Tools","archived":false,"fork":false,"pushed_at":"2024-08-13T13:23:05.000Z","size":685,"stargazers_count":21,"open_issues_count":17,"forks_count":10,"subscribers_count":8,"default_branch":"master","last_synced_at":"2025-11-10T04:38:44.207Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/MobleyLab.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":"CODE_OF_CONDUCT.md","threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2018-02-07T01:34:10.000Z","updated_at":"2025-07-08T12:54:02.000Z","dependencies_parsed_at":"2022-07-27T18:04:11.478Z","dependency_job_id":null,"html_url":"https://github.com/MobleyLab/chemper","commit_stats":null,"previous_names":[],"tags_count":3,"template":false,"template_full_name":null,"purl":"pkg:github/MobleyLab/chemper","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/MobleyLab%2Fchemper","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/MobleyLab%2Fchemper/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/MobleyLab%2Fchemper/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/MobleyLab%2Fchemper/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/MobleyLab","download_url":"https://codeload.github.com/MobleyLab/chemper/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/MobleyLab%2Fchemper/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":29596330,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-02-18T20:59:56.587Z","status":"ssl_error","status_checked_at":"2026-02-18T20:58:41.434Z","response_time":162,"last_error":"SSL_connect returned=1 errno=0 peeraddr=140.82.121.6:443 state=error: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2025-10-21T20:40:28.133Z","updated_at":"2026-02-18T22:02:24.222Z","avatar_url":"https://github.com/MobleyLab.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# \u003cimg src=\"https://github.com/mobleylab/chemper/blob/master/chemper_logo.svg\" height=150\u003e\n\n[![Documentation Status](https://readthedocs.org/projects/chemper/badge/?version=latest)](http://chemper.readthedocs.io/en/latest/?badge=latest)\n[![Language grade: Python](https://img.shields.io/lgtm/grade/python/g/MobleyLab/chemper.svg?logo=lgtm\u0026logoWidth=18)](https://lgtm.com/projects/g/MobleyLab/chemper/context:python)\n[![codecov](https://codecov.io/gh/MobleyLab/chemper/branch/master/graph/badge.svg)](https://codecov.io/gh/MobleyLab/chemper)\n[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)\n\n[![DOI](https://zenodo.org/badge/120546688.svg)](https://zenodo.org/badge/latestdoi/120546688)\n\nThis repository contains a variety of tools that will be useful in automating the process\nof chemical perception for the new SMIRKS Native Open Force Field (SMIRNOFF) format\nas a part of the [Open Force Field Initiative](http://openforcefield.org) [1].\n\n`ChemPer` can be used to automatically generate SMIRKS patterns to match clustered molecular fragments.\nFor example, you may have calculated bond lengths and force constants for a variety of bonds in one group of molecules.\nYou could use that data to cluster those bonds and then use `ChemPer` to generate SMIRKS patterns which would allow\nyou to apply those lengths and force constants to a new set of molecules.\nThe algorithms implemented here were inspired by\n[SMARTY and SMIRKY](https://github.com/openforcefield/smarty) which were proven to be too inefficient for\npractical use in force field parameterization [2].\n\nFor a more extensive history and explanation, see our [preprint](http://doi.org/10.26434/chemrxiv.8304578.v1) [3].\n\n## Installation\n\nChemper is available via `conda-forge`:\n\n```shell\nconda install -c conda-forge chemper\n```\n\nThis command will install all dependencies besides a toolkit for cheminformatics or storing of molecule\ninformation. Also install [RDKit](http://www.rdkit.org/docs/Install.html) and/or\n[OpenEye toolkits](https://docs.eyesopen.com/toolkits/python/quickstart-python/linuxosx.html) by\nrunning:\n\n```bash\nconda install -c conda-forge rdkit\n```\n\nand/or\n\n```bash\nconda install -c openeye openeye-toolkits\n```\n\n\n## Supported Python versions\n\nWe test with whatever Python versions are found in `.github/workflows/ci.yaml`. Chemper may function\non some older and/or newer versions as well.\n\n## Supported chemiformatics toolkits\n\nWe seek to keep this tool independent of cheminformatics toolkit, but currently only support\n[RDKit](http://www.rdkit.org/docs/index.html) and [OpenEye Toolkits](https://www.eyesopen.com/).\nIf you wish to add support please feel free to submit a pull request.\nMake sure one of these toolkits is installed in your environment before installing chemper.\n\n# Documentation\n\nBelow are some details on the tools provided in `chemper` see\n[examples](https://github.com/MobleyLab/chemper/tree/master/examples)\nand [documentation](https://chemper.readthedocs.io/en/latest/)\nfor more detailed usage examples\n\n### SMIRKSifier\n\nThis is `chempers` main function.\nIt takes groups of molecular fragments which should be typed together and generates a heirarchical list\nof SMIRKS patterns which maintains this typing.\n`chemper`'s `SMIRKSifier` takes a list of molecules and groups of atoms based on index and generates\na hierarchical list of SMIRKS in just a few lines of code.\nIn the example, [general_smirks_for_clusters](https://chemper.readthedocs.io/en/latest/examples/general_smirks_for_clusters.html)\nwe cluster bonds in a set of simple hydrocarbons based on order. Then `SMIRKSifer` turns these clusters into a list of SMIRKS patterns.\nThe following functionalities are used to make the `SMIRKSifier` possible, but may be useful on their own.\n\n### ClusterGraph\n\nThe goal of this tool is to store all information about the atoms and bonds that could be in a SMIRKS pattern.\nThese are created assuming you already have a clustered set of molecular subgraphs. As our primary goal is to\ndetermine chemical perception for force field parameterization we image the input data being clustered subgraphs\nbased on what parameter we wish to assign those atoms, such as equilibrium\nbond lengths and force constants. However, you could imagine other reasons for wanting to store how you clustered groups\nof atoms.\n\nFor more detailed examples and illustration of how this works see [SMIRKS_from_molecules](examples/using_cluster_graph/SMIRKS_from_molecules.ipynb).\nBelow is a brief example showing the SMIRKS for the bond between two carbon atoms in propane and pentane.\n\n```python\nfrom chemper.mol_toolkits import mol_toolkit\nfrom chemper.graphs.cluster_graph import ClusterGraph\n\nmol1 = mol_toolkit.Mol.from_smiles('CCC')\nmol2 = mol_toolkit.Mol.from_smiles('CCCCC')\nsmirks_atom_lists = [[(0,1)], [(0,1), (1,2)]]\ngraph = ClusterGraph([mol1, mol2], smirks_atom_lists)\nprint(graph.as_smirks())\n# '[#6AH2X4x0r0+0,#6AH3X4x0r0+0:1]-;!@[#6AH2X4x0r0+0:2]'\n```\n\nThe idea with ClusterGraph objects is that they store all possible decorator information for each atom.\nIn this case the SMIRKS indexed atoms for propane (mol1) are one of the terminal and the middle carbons.\nIn pentane (mol2) however atom1 can be a terminal or middle of the chain carbon atom. This changes the number of\nhydrogen atoms (`Hn` decorator) on the carbon, thus there are two possible SMIRKS patterns for atom `:1`\n`#6AH2X4x0r0+0` or (indicated by the \"`,`\") `#6AH3X4x0r0+0`. But, atom `:2` only has one possibility `#6AH2X4x0r0+0`.\n\n### SingleGraph\n\nThe goal of this tool was to create an example of how you could create a SMIRKS pattern from a\nmolecule and set of atom indices.\nWhile this isn't ultimately useful in sampling chemical perception as they\nonly work for a single molecule, however it is a tool that did not exist to the best of the authors knowledge before.\nFor a detailed example see the [single_mol_smirks](examples/using_fragment_graph/single_mol_smirks.ipynb)\njupyter notebook.\n\nHere is a brief usage example for creating the SMIRKS pattern for the bond between the two carbon\natoms in ethene including atoms one bond away from the indexed atoms. The indexed atoms are the two carbon\natoms at indices 0 and 1 in the molecule are assigned to SMIRKS indices `:1` and `:2` respectively\n\n```python\nfrom chemper.mol_toolkits import mol_toolkit\nfrom chemper.graphs.single_graph import  SingleGraph\n\nmol = mol_toolkit.Mol.from_smiles('C=C') # note this adds explicit hydrogens to your molecule\nsmirks_atoms = (0,1)\ngraph = SingleGraph(mol, smirks_atoms, layers=1)\nprint(graph.as_smirks())\n# [#6AH2X3x0r0+0:1](-!@[#1AH0X1x0r0+0])(-!@[#1AH0X1x0r0+0])=!@[#6AH2X3x0r0+0:2](-!@[#1AH0X1x0r0+0])-!@[#1AH0X1x0r0+0]\n```\n\n### mol\\_toolkits\n\nAs noted [above](#installation), we seek to keep `chemper` independent of the underlying cheminformatics toolkits.\n`mol_toolkits` was created to keep all code dependent on the toolkit isolated. It can create molecules from\nan RDK or OE molecule object or from a SMILES string. It includes a variety of functions for extracting information\nabout atoms, bonds, and molecules. Also included here are subsearchs using indexed SMARTS (or SMIRKS) patterns.\n\n## Versions\n\n### 0.1.0 Alpha Release\nThis is a first release of the Alpha testing version of `chemper`. As you can follow in the [issue tracker](https://github.com/MobleyLab/chemper/issues) there are still\non going problems to resolve. This first release will allow for reference to the concepts and algorithms included here\nfor automated chemical perception. However, the API is still in flux and nothing should be considered permanent at this time.\n\n### Version 1.0.0\nThis release matches the work published in our [preprint](http://doi.org/10.26434/chemrxiv.8304578.v1).\nWhile the code is stable and there are tests showing how it should work the science it represents is still in the early stages and big changes to the algorithms and API should be expected in future releases.\n\n### Version 1.0.1\nThis release includes non-behavior-breaking changes to support distribution on Python 3.10.\n\n## Contributors\n\n* [Caitlin C. Bannan (UCI)](https://github.com/bannanc)\n* [Jessica Maat (UCI)](https://github.com/jmaat)\n* [David L. Mobley (UCI)](https://github.com/davidlmobley)\n\n## Acknowledgments\n\nCCB is funded by a fellowship from [The Molecular Sciences Software Institute](http://molssi.org/) under NSF grant ACI-1547580.\n\n## References\n\n1. D.L. Mobley et al. _JCTC,_ **2018**, _14_(11), pp 6076-6092. ([JCTC](http://doi.org/10.1021/acs.jctc.8b00640) or [bioRxiv](http://doi.org/10.1101/286542))\n2. C. Zanette and C.C. Bannan et al. _JCTC_ **2019** _15_(1), pp 402-423. ([JCTC](https://doi.org/10.1021/acs.jctc.8b00821) or [ChemRxiv](https://doi.org/10.26434/chemrxiv.6230627.v1))\n3. C.C. Bannan and D.L. Mobley _ChemRxiv_ **2019** [doi:10.26434/chemrxiv.8304578.v1](http://doi.org/10.26434/chemrxiv.8304578.v1)\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmobleylab%2Fchemper","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fmobleylab%2Fchemper","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmobleylab%2Fchemper/lists"}