NAME

Chemistry::InternalCoords - Represent the position of an atom using internal coordinates and convert it to Cartesian coordinates.

SYNOPSIS

use Chemistry::InternalCoords;

# ... have a molecule in $mol
my $atom = $mol->new_atom;

# create an internal coordinate object for $atom 
# with respect to atoms with indices 4, 3, and 2.
my $ic = Chemistry::InternalCoords->new(
    $atom, 4, 1.1, 3, 109.5, 2, 180.0
);

# can also use atom object references instead of indices
($atom4, $atom3, $atom2) = $mol->atoms(4,3,2);
my $ic = Chemistry::InternalCoords->new(
    $atom, $atom4, 1.1, $atom3, 109.5, $atom2, 180.0
);

# calculate the Cartesian coordinates for
# the atom from the internal coordinates
my $vector = $ic->cartesians;

# calculate and set permanently the Cartesian coordinates
# for the atom from the internal coordinates
my $vector = $ic->add_cartesians;
# same as $atom->coords($ic->cartesians);

# dump as string
print $ic;
# same as print $ic->stringify;

DESCRIPTION

This module implements an object class for representing internal coordinates and provides methods for converting them to Cartesian coordinates.

For generating an internal coordinate representation (aka a Z-matrix) of a molecule from its Cartesian coordinates, see the Chemistry::InternalCoords::Builder module.

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

METHODS

my $ic = Chemistry::InternalCoords->new($atom, $len_ref, $len_val, $ang_ref, $ang_val, $dih_ref, $dih_val)

Create a new internal coordinate object. $atom is the atom to which the coordinates apply. $len_ref, $ang_ref, and $dih_ref are either atom references or atom indices and are used to specify the distance, angle, and dihedral that are used to define the current position. $len_val, $ang_val, and $dih_val are the values of the distance, angle, and dihedral. The angle and the dihedral are expected to be in degrees.

For example,

my $ic = Chemistry::InternalCoords->new(
    $atom, 4, 1.1, 3, 109.5, 2, 180.0
);

means that $atom is 1.1 distance units from atom 4, the angle $atom-4-3 is 109.5 degrees, and the dihedral $atom-4-3-2 is 180.0 degrees.

The first three atoms in the molecule don't need all the internal coordinates: the first atom doesn't need anything (except for the atom reference $atom) because it will always be placed at the origin; the second atom only needs a distance, and it will be placed on the X axis; the third atom needs a distance and an angle, and it will be placed on the XY plane.

my ($atom, $distance) = $ic->distance

Return the atom reference and distance value contained in the Chemistry::InternalCoords object.

my ($atom, $angle) = $ic->angle

Return the atom reference and angle value contained in the Chemistry::InternalCoords object.

my ($atom, $dihedral) = $ic->dihedral

Return the atom reference and dihedral value contained in the Chemistry::InternalCoords object.

my $vector = $ic->cartesians

Calculate the Cartesian coordinates from an internal coordinate object. Returns a Math::VectorReal object. Note that the Cartesian coordinates of the atoms referenced by the $ic object should already be calculated.

my $vector = $ic->add_cartesians

Same as $ic->cartesians, but also adds the newly calculated Cartesian coordinates to the atom. It is just shorthand for the following:

$atom->coords($ic->cartesians);

The best way of calculating the Cartesian coordinates for an entire molecule, assuming that every atom is defined only in terms of previous atoms (as it should be), is the following:

# we have all the internal coords in @ics
for my $ic (@ics) {
    $ic->add_cartesians;
}

my $string = $ic->stringify

Dump the object as a string representation. May be useful for debugging. This method overloads the "" operator.

VERSION

0.17

SEE ALSO

Chemistry::InternalCoords::Builder, Chemistry::Mol, Chemistry::Atom, Math::VectorReal, http://www.perlmol.org/.

AUTHOR

Ivan Tubert <itub@cpan.org>

COPYRIGHT

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