.\" Automatically generated by Pod::Man 4.14 (Pod::Simple 3.43)
.\"
.\" Standard preamble:
.\" ========================================================================
.de Sp \" Vertical space (when we can't use .PP)
.if t .sp .5v
.if n .sp
..
.de Vb \" Begin verbatim text
.ft CW
.nf
.ne \\$1
..
.de Ve \" End verbatim text
.ft R
.fi
..
.\" Set up some character translations and predefined strings. \*(-- will
.\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
.\" double quote, and \*(R" will give a right double quote. \*(C+ will
.\" give a nicer C++. Capital omega is used to do unbreakable dashes and
.\" therefore won't be available. \*(C` and \*(C' expand to `' in nroff,
.\" nothing in troff, for use with C<>.
.tr \(*W-
.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
.ie n \{\
. ds -- \(*W-
. ds PI pi
. if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
. if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\" diablo 12 pitch
. ds L" ""
. ds R" ""
. ds C` ""
. ds C' ""
'br\}
.el\{\
. ds -- \|\(em\|
. ds PI \(*p
. ds L" ``
. ds R" ''
. ds C`
. ds C'
'br\}
.\"
.\" Escape single quotes in literal strings from groff's Unicode transform.
.ie \n(.g .ds Aq \(aq
.el .ds Aq '
.\"
.\" If the F register is >0, we'll generate index entries on stderr for
.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
.\" entries marked with X<> in POD. Of course, you'll have to process the
.\" output yourself in some meaningful fashion.
.\"
.\" Avoid warning from groff about undefined register 'F'.
.de IX
..
.nr rF 0
.if \n(.g .if rF .nr rF 1
.if (\n(rF:(\n(.g==0)) \{\
. if \nF \{\
. de IX
. tm Index:\\$1\t\\n%\t"\\$2"
..
. if !\nF==2 \{\
. nr % 0
. nr F 2
. \}
. \}
.\}
.rr rF
.\" ========================================================================
.\"
.IX Title "Chemistry::Ring::Find 3pm"
.TH Chemistry::Ring::Find 3pm "2022-12-18" "perl v5.36.0" "User Contributed Perl Documentation"
.\" For nroff, turn off justification. Always turn off hyphenation; it makes
.\" way too many mistakes in technical documents.
.if n .ad l
.nh
.SH "NAME"
Chemistry::Ring::Find \- Find the rings (cycles) in a molecule
.SH "SYNOPSIS"
.IX Header "SYNOPSIS"
.Vb 1
\& use Chemistry::Ring::Find \*(Aq:all\*(Aq;
\&
\& # 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);
.Ve
.SH "DESCRIPTION"
.IX Header "DESCRIPTION"
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 (\s-1SSSR\s0), or the \*(L"almost \s-1SSSR\*(R",\s0 which is an
unambiguous set of rings for cases such as cubane.The algorithms are based on
ideas from:
.PP
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
.PP
2) Figueras, J. Ring perception using breadth-first search. J. Chem. Inf.
Comput. Sci. 1996, 36, 986\-991.
.PP
Ref. 2 is only used for find_ring, not for find_rings, because it has been
shown that the overall \s-1SSSR\s0 method in ref 2 has bugs. Ref 1 inspired
find_rings, which depends on find_ring.
.PP
This module is part of the PerlMol project, .
.SH "FUNCTIONS"
.IX Header "FUNCTIONS"
These functions may be exported explicitly, or all by using the :all tag, but
nothing is exported by default.
.ie n .IP "find_ring($origin, %opts)" 4
.el .IP "find_ring($origin, \f(CW%opts\fR)" 4
.IX Item "find_ring($origin, %opts)"
Find the smallest ring containing \f(CW$origin\fR, which may be either an atom or a bond.
Returns a Chemistry::Ring object. Options:
.RS 4
.IP "all" 4
.IX Item "all"
If true, find all the rings containing \f(CW$origin\fR. If false, return the first ring
found. Defaults to false. \*(L"All\*(R" is supposed to include only \*(L"simple\*(R" rings,
that is, rings that are not a combination of smaller rings.
.IP "min" 4
.IX Item "min"
Only find rings with a the given minimum size. Defaults to zero.
.IP "max" 4
.IX Item "max"
Only find rings up to the given maximium size. Defaults to unlimited size.
.IP "size" 4
.IX Item "size"
Only find rings with this size. Same as setting min and max to the same size.
Default: unspecified.
.IP "exclude" 4
.IX Item "exclude"
An array reference containing a list of atoms that must \s-1NOT\s0 be present in the
ring. Defaults to the empty list.
.IP "mirror" 4
.IX Item "mirror"
If true, find each ring twice (forwards and backwards). Defaults to false.
.RE
.RS 4
.RE
.ie n .IP "@rings = find_rings($mol, %options)" 4
.el .IP "\f(CW@rings\fR = find_rings($mol, \f(CW%options\fR)" 4
.IX Item "@rings = find_rings($mol, %options)"
Find \*(L"all\*(R" the rings in the molecule. In general it return the Smallest Set of
Smallest Rings (\s-1SSSR\s0). However, since it is well known that the \s-1SSSR\s0 is not
unique for molecules such as cubane (where the \s-1SSSR\s0 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 \*(L"non-smallest\*(R" set of smallest rings,
unless the \*(L"sssr\*(R" option is given. For example,
.Sp
.Vb 2
\& @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.)
.Ve
.SH "BUGS"
.IX Header "BUGS"
The \*(L"all\*(R" 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).
.SH "SOURCE CODE REPOSITORY"
.IX Header "SOURCE CODE REPOSITORY"
.SH "SEE ALSO"
.IX Header "SEE ALSO"
Chemistry::Ring
.SH "AUTHOR"
.IX Header "AUTHOR"
Ivan Tubert-Brohman
.SH "COPYRIGHT"
.IX Header "COPYRIGHT"
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.