Source code for schrodinger.structutils.rings

"""
Tools for detecting and characterizing rings in Structures.
"""
from schrodinger import structure
from schrodinger.infra import structure as infrastructure


def find_ring_systems(st, want_spiro=False, sort=False):
    """
    Find groups of atoms that are in conjoined rings.

    If want_spiro is True, rings are part of the same system if they share any
    atom. If False, rings must share a bond.

    :param st: Molecule to identify ring systems in
    :type st: Structure

    :param want_spiro: True if a ring system can be defined by just a common
                atom (default False)
    :type want_spiro: bool

    :param sort: True if ring systems should be sorted by minimum element
    :type sort: bool

    :return: List of the different ring systems defined by the index of the
                atoms, sorted by the minimum element in each set.
    :rtype: tuple of tuple of int
    """

    ring_systems = infrastructure.find_ring_systems(st, want_spiro)

    if sort:
        return sorted(ring_systems, key=min)

    return ring_systems


def find_ring_atoms(st):
    """
    Find the set of all atoms which are in some ring

    :param st: Molecule to identify ring systems in
    :type st: Structure

    :return: tuple of atoms ids which are in some ring
    :rtype: tuple of int
    """
    return infrastructure.find_ring_atoms(st)


def find_rings(st, sort=True):
    """
    Return the smallest set of smallest rings (SSSR) in `st`.

    See also the `schrodinger.structure.Structure.find_rings` method and
    the `schrodinger.structure.Structure.ring` iterator. This method may be
    deprecated at some point in favor of those methods.

    The return value is a list of lists of ints. Each list of ints
    corresponds to a ring, and the integer values are the atom indices. Each
    ring is ordered by connectivity.

    :type st: `Structure`
    :param st: Structure holding rings.

    :type sort: bool
    :param sort: Deprecated and unused

    :rtype: list
    :return: Each value is a list corresponding to the atom indices of a ring.
    """
    # Allow for use of integer handles to provide backward compatibility of
    # this function with version 1.25 of this file.
    if not isinstance(st, structure.Structure):
        st = structure.Structure(st)

    return st.find_rings(sort)


def find_ring_bonds(st, max_size=None):
    """
    Find all bonds that form the edge of a ring.

    The return uses frozenset to represent each atom pair to allow comparisons
    without worrying about the order of the atoms. If it used a tuple you'd
    need to do both way checks.

    Examples::

        # Operate on each ring bond:
        for atom_index0, atom_index1 in find_ring_bonds(st):
            atom0 = st.atom[atom_index0]
            atom1 = st.atom[atom_index1]
            # Do something with the atoms

        # Operate on each non-ring bond:
        ring_bonds = find_ring_bonds(st)
        for bond in st.bond:
            # skip ring bonds. Use a set for comparison:
            if {bond.atom1.index, bond.atom2.index} in ring_bonds:
                continue

    :type max_size: int or None
    :param max_size: if supplied, only include bonds that are in rings of size
        max_size or smaller

    :rtype: set of frozenset of int
    :return: set of pairs of atom indices that comprise a ring bond.
    """
    return infrastructure.find_ring_bonds(st, max_size or 0)


def find_all_rings(st, max_ring_size=50, max_seconds=1):
    """
    Find the set of all simple rings in a given structure. A simple ring is a
    cycle with no repeating atoms.

    :type max_ring_size: int
    :param max_ring_size: only include rings that are of max_ring_size or
        smaller. Default is max_ring_size = 50.

    :type max_seconds: int
    :param max_seconds: time in seconds to run find_all_rings() before timing
        out. Throws a RuntimeError if max_seconds is exceeded.

    :rtype: tuple of tuple of int
    :return: set of all simple rings in `st` of size less than or equal to
        max_ring_size
    """
    return infrastructure.find_all_rings(st, max_ring_size, max_seconds)