polymerist.rdutils.rdcoords.piercing
====================================

.. py:module:: polymerist.rdutils.rdcoords.piercing

.. autoapi-nested-parse::

   Methods for detecting ring piercing in molecular conformers



Attributes
----------

.. autoapisummary::

   polymerist.rdutils.rdcoords.piercing.N
   polymerist.rdutils.rdcoords.piercing.ring_piercing_idxs


Functions
---------

.. autoapisummary::

   polymerist.rdutils.rdcoords.piercing.PINPRICS
   polymerist.rdutils.rdcoords.piercing.detect_ring_is_pierced
   polymerist.rdutils.rdcoords.piercing.summarize_ring_piercing


Module Contents
---------------

.. py:data:: N

.. py:function:: PINPRICS(positions: numpy.ndarray[tuple[N, 3], float], bonded_atom_idxs: Sequence[tuple[int, int]], ring_atom_idxs: list[int]) -> tuple[tuple[int, int]]

   Implements the PINPRICS algorithm (Planar Intersection Nomography for Pierced Ring Identification via Cut Sets)
   Assumes rings is oblate, i.e. faces along the minor axis and is "wider than it is tall"

   :Parameters: * **positions** (*Array[[N, 3], float]*) -- An array of the 3D coordinates of all atoms in a molecule
                * **bonded_atom_idxs** (*Sequence[tuple[int, int]]*) -- A sequence of pairs of indices of all bonded atoms in the molecule
                  This represents the topology on the molecules graph
                * **ring_atom_idxs** (*list[int]*) -- List of indices of the atoms which make up the ring to be tested for piercing
                  Requirement of specifically a list (i.e. not just a Sequence etc.) is to allow for "smart" indexing in numpy

   :returns: **piercing_idxs** -- A tuple of all pairs of atom indices which were perceived to pierce the ring
   :rtype: tuple[tuple[int, int]]


.. py:data:: ring_piercing_idxs

.. py:function:: detect_ring_is_pierced(mol: rdkit.Chem.Mol, ring_atom_idxs: list[int], conformer_idx: int = 0) -> tuple[tuple[int, int]]

   Detects and returns all bonded pairs of atoms which pierce a particular ring in a molecule

   :Parameters: * **mol** (*Mol*) -- An RDKit Mol instance assumed to have at least one conformer
                * **ring_atom_idxs** (*list[int]*) -- List of indices of the atoms which make up the ring to be tested for piercing
                * **conformer_idx** (*int, default 0*) -- The index of the conformer to draw coordinates from
                  By default, will just take the first conformer

   :returns: **piercing_idxs** -- A tuple of all pairs of atom indices which were perceived to pierce the ring
   :rtype: tuple[tuple[int, int]]


.. py:function:: summarize_ring_piercing(mol: rdkit.Chem.Mol, conformer_idx: int = 0) -> dict[tuple[int], tuple[tuple[int, int]]]

   Apply PINPRICS algorithm to all ring detected in a molecule and
   provide a summary of which bonds (if any) were detected to be piercing each ring

   :Parameters: * **mol** (*Mol*) -- An RDKit Mol instance assumed to have at least one conformer
                * **conformer_idx** (*int, default 0*) -- The index of the conformer to draw coordinates from
                  By default, will just take the first conformer

   :returns: **piercing_summary** -- A dict mapping the indices of the atoms in each ring to
             a tuple of all pairs of atom indices which were perceived to pierce the ring
   :rtype: dict[tuple[int], tuple[tuple[int, int]]]