Chemis...g::Find(3pm)

💖 NAME 💖

Chemistry::Ring::Find — bestie, this is the module that finds the rings (cycles) in a molecule. That's it, that's the whole job, and it slays at it. 💅

---

✨ SYNOPSIS ✨

okay so here's the vibe, literally copy-paste energy:

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);

---

🦋 DESCRIPTION 🦋

Chemistry::Ring::Find 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/>. 🧚

---

🎀 FUNCTIONS 🎀

These functions may be exported explicitly, or all by using the :all tag, but nothing is exported by default. (so don't come for me when nothing shows up, you have to ASK for it bestie 🫶)

💜 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 — and this is the drama — 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.)

---

💀 BUGS 💀

ngl 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). 🙈

---

⭐ SOURCE CODE REPOSITORY ⭐

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

---

👑 SEE ALSO 👑

Chemistry::Ring

---

🌸 AUTHOR 🌸

Ivan Tubert-Brohman <itub@cpan.org>

---

🍓 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.

---

okay that's the whole page, mwah 💅 this was documented with perl v5.36.0 and dated 2022-12-18, and it lives in the User Contributed Perl Documentation corner of the manual. go find some rings, bestie, you got this 💖✨