Chemistry::Ring::Find - Find the rings (cycles) in a molecule

       Ivan Tubert-Brohman <itub@cpan.org>

       The  "all" option in find_ring doesn't quite work as expected. It finds all simple rings and some bridged
       rings. It never finds fused rings (which is good).

       Copyright (c) 2009 Ivan Tubert-Brohman. All rights reserved. This  program  is  free  software;  you  can
       redistribute it and/or modify it under the same terms as Perl itself.

perl v5.36.0                                       2022-12-18                         Chemistry::Ring::Find(3pm)

       The Chemistry::Ring::Find module implements a breadth-first ring finding algorithm, and it can find all
       rings that contain a given atom or bond, the Smallest Set of Smallest Rings (SSSR), or the "almost SSSR",
       which is an unambiguous set of rings for cases such as cubane.The algorithms are  based on ideas from:

       1) Leach, A. R.; Dolata, D. P.; Prout, P. Automated Conformational Analysis and Structure Generation:
       Algorithms for Molecular Perception J. Chem. Inf. Comput.  Sci. 1990, 30, 316-324

       2) Figueras, J. Ring perception using breadth-first search. J. Chem. Inf.  Comput.  Sci. 1996, 36,
       986-991.

       Ref. 2 is only used for find_ring, not for find_rings, because it has been shown that the overall SSSR
       method in ref 2 has bugs. Ref 1 inspired find_rings, which depends on find_ring.

       This module is part of the PerlMol project, <http://www.perlmol.org/>.

       These functions may be exported explicitly, or all by using the :all tag, but nothing is exported by
       default.

       find_ring($origin, %opts)
           Find  the  smallest  ring  containing  $origin,  which  may  be  either an atom or a bond.  Returns a
           Chemistry::Ring object. Options:

           all If true, find all the rings containing $origin. If false, return the first ring  found.  Defaults
               to  false.  "All"  is  supposed  to  include  only  "simple" rings, that is, rings that are not a
               combination of smaller rings.

           min Only find rings with a the given minimum size. Defaults to zero.

           max Only find rings up to the given maximium size. Defaults to unlimited size.

           size
               Only find rings with this size. Same  as  setting  min  and  max  to  the  same  size.   Default:
               unspecified.

           exclude
               An  array  reference containing a list of atoms that must NOT be present in the ring. Defaults to
               the empty list.

           mirror
               If true, find each ring twice (forwards and backwards). Defaults to false.

       @rings = find_rings($mol, %options)
           Find "all" the rings in the molecule. In general it return the Smallest Set of Smallest Rings (SSSR).
           However, since it is well known that the SSSR is not unique for molecules such as cubane  (where  the
           SSSR  consists  of  five  unspecified  four-member  rings, even if the symmetry of the molecule would
           suggest that the six faces of the cube are equivalent), in such cases find_rings will return  a  non-
           ambiguous "non-smallest" set of smallest rings, unless the "sssr" option is given. For example,

               @rings = find_rings($cubane);
               # returns SIX four-member rings

               @rings = find_rings($cubane, sssr => 1);
               # returns FIVE four-member rings (an unspecified subset of
               # the six rings above.)

       Chemistry::Ring::Find - Find the rings (cycles) in a molecule

       Chemistry::Ring

       <https://github.com/perlmol/Chemistry-Ring>

           use Chemistry::Ring::Find ':all';

           # find the smallest ring containing $atom
           my $ring = find_ring($atom);

           # find all the rings containing $bond
           my @rings = find_ring($bond, all => 1);

           # see below for more options

           # find the six 4-atom rings in cubane
           @rings = find_rings($cubane);

           # find a cubane SSSR with five rings
           @rings = find_rings($cubane, sssr => 1);