Stereochemistry-Aware Molecular and Reaction Graphs
=====================================================

.. image:: _static/img/logo_smg.png
   :align: center
   :class: only-light
   :alt: StereoMolGraph

.. image:: _static/img/logo_smg_dark.png
   :align: center
   :class: only-dark
   :alt: StereoMolGraph

.. |pypi| image:: https://img.shields.io/pypi/v/StereoMolGraph?style=flat-square&logo=pypi&logoColor=white&color=3775A9
   :target: https://pypi.org/project/StereoMolGraph/

.. |python| image:: https://img.shields.io/pypi/pyversions/StereoMolGraph?style=flat-square&logo=python&logoColor=white&color=3776AB&label=Python
   :target: https://pypi.org/project/StereoMolGraph/

.. |license| image:: https://img.shields.io/badge/License-MIT-d4a017?style=flat-square&logo=opensourceinitiative&logoColor=white
   :target: https://opensource.org/licenses/MIT

.. |tests| image:: https://img.shields.io/github/actions/workflow/status/maxim-papusha/StereoMolGraph/run_unit_test.yaml?branch=main&style=flat-square&label=tests
   :target: https://github.com/maxim-papusha/StereoMolGraph/actions/workflows/run_unit_test.yaml

.. |doi| image:: https://img.shields.io/badge/DOI-10.1021%2Facs.jcim.5c02523-ffcc00?style=flat-square
   :target: https://doi.org/10.1021/acs.jcim.5c02523

.. |docs| image:: https://img.shields.io/badge/Documentation-docs-4C6A92?style=flat-square&logo=readthedocs&logoColor=white
   :target: https://stereomolgraph.readthedocs.io

.. |github| image:: https://img.shields.io/badge/GitHub-repository-2F3E46?style=flat-square&logo=github&logoColor=white
   :target: https://github.com/maxim-papusha/StereoMolGraph

|pypi| |python| |license| |tests| |docs| |github|  |doi|

Welcome to the documentation for **StereoMolGraph**.

This package provides a collection of :doc:`graph classes </reference/graphs/index>` for the representation of molecules and chemical reactions in a modular.
The core focus is to allow the user to work with chiral molecules in a consistent way with a simple interface.
All arising algorithmic difficulties are taken care of by the internal implementations.


Its treatment of stereochemistry is based on rigorously defined local :doc:`stereodescriptors </reference/stereodescriptors>`, which are derived from group-theoretical principles.

Building on this formal foundation, a range of graph :doc:`algorithms </reference/algorithms/index>` is implemented in a stereochemistry-aware manner, enabling consistent handling of symmetry, equivalence, and stereochemical transformations.


Magic Methods
=============

StereoMolGraph implements the following magic methods:

* ``__eq__``: based on :doc:`graph isomorphism </reference/algorithms/isomorphism>` and stereochemical equivalence [#smg]_.
* ``__hash__``: based on Circular Stereo Algorithm.

Citation
========

If you use StereoMolGraph in your work, please cite:

.. [#smg] Maxim Papusha and Kai Leonhard,
   *StereoMolGraph: Stereochemistry-Aware Molecular and Reaction Graphs*,
   *J. Chem. Inf. Model.* **2026**,
   `DOI: 10.1021/acs.jcim.5c02523 <https://doi.org/10.1021/acs.jcim.5c02523>`_

.. toctree::
   :maxdepth: 1
   :hidden:

   installation
   tutorial/index
   reference/index
   changelog