NAME

       Chemistry::Ring - Represent a ring as a substructure of a molecule

SYNOPSIS

           use Chemistry::Ring;

           # already have a molecule in $mol...
           # create a ring with the first six atoms in $mol
           my $ring = Chemistry::Ring->new;
           $ring->add_atom($_) for $mol->atoms(1 .. 6);

           # find the centroid
           my $vector = $ring->centroid;

           # find the plane that fits the ring
           my ($normal, $distance) = $ring->plane;

           # is the ring aromatic?
           print "is aromatic!\n" if $ring->is_aromatic;

           # "aromatize" a molecule
           Chemistry::Ring::aromatize_mol($mol);

           # get the rings involving an atom (after aromatizing)
           my $rings = $mol->atoms(3)->attr('ring/rings');

DESCRIPTION

       This module provides some basic methods for representing a ring. A ring is a subclass of
       molecule, because it has atoms and bonds. Besides that, it has some useful geometric
       methods for finding the centroid and the ring plane, and methods for aromaticity
       detection.

       This module does not detect the rings by itself; for that, look at Chemistry::Ring::Find.

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

METHODS

       Chemistry::Ring->new(name => value, ...)
           Create a new Ring object with the specified attributes. Same as "Chemistry::Mol->new".

       $ring->centroid
           Returns a vector with the centroid, defined as the average of the coordinates of all
           the atoms in the ring. The vecotr is a Math::VectorReal object.

       my ($norm, $d) = $ring->plane
           Returns the normal and distance to the origin that define the plane that best fits the
           atoms in the ring, by using multivariate regression. The normal vector is a
           Math::VectorReal object.

       $ring->is_aromatic
           Naively guess whether ring is aromatic from the molecular graph, with a method based
           on Huckel's rule. This method is not very accurate, but works for simple molecules.
           Returns true or false.

EXPORTABLE SUBROUTINES

       Nothing is exported by default, but you can export these subroutines explicitly, or all of
       them by using the ':all' tag.

       aromatize_mol($mol)
           Finds all the aromatic rings in the molecule and marks all the atoms and bonds in
           those rings as aromatic.

           It also adds the 'ring/rings' attribute to the molecule and to all ring atoms and
           bonds; this attribute is an array reference containing the list of rings that involve
           that atom or bond (or all the rings in the case of the molecule).  NOTE (the
           ring/rings attribute is experimental and might change in future versions).

VERSION

       0.20

SEE ALSO

       Chemistry::Mol, Chemistry::Atom, Chemistry::Ring::Find, Math::VectorReal.

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.