NAME

Chemistry::Atom - Chemical atoms as objects in molecules

SYNOPSIS

    use Chemistry::Atom;

    my $atom = new Chemistry::Atom(
        id => 'a1',
        coords => [$x, $y, $z],
        symbol => 'Br'
    );

    print $atom->print;

DESCRIPTION

This module includes objects to describe chemical atoms. An atom is defined by its symbol and its coordinates, among other attributes. Atomic coordinates are described by a Math::VectorReal object, so that they can be easily used in vector operations.

Atom Attributes

In addition to common attributes such as id, name, and type, atoms have the following attributes, which are accessed or modified through methods defined below: bonds, coords, internal_coords, Z, symbol, etc.

In general, to get the value of a property, use $atom->method without any parameters. To set the value, use $atom->method($new_value). When setting an attribute, the accessor returns the atom object, so that accessors can be chained:

    $atom->symbol("C")->name("CA")->coords(1,2,3);

METHODS

Chemistry::Atom->new(name => value, ...)

Create a new Atom object with the specified attributes.

$atom->Z($new_Z)

Sets and returns the atomic number (Z). If the symbol of the atom doesn't correspond to a known element, Z = undef.

$atom->symbol($new_symbol)

Sets and returns the atomic symbol.

$atom->mass($new_mass)

Sets and returns the atomic mass in atomic mass units. By default, relative atomic masses from the 1995 IUPAC recommendation are used. (Table stolen from the Chemistry::MolecularMass module by Maksim A. Khrapov).

$atom->coords

    my $vector = $atom->coords;  # get a Math::VectorReal object
    $atom->coords($vector);      # set a Math::VectorReal object 
    $atom->coords([$x, $y, $z]); # also accepts array refs 
    $atom->coords($x, $y, $z);   # also accepts lists

Sets or gets the atom's coordinates. It can take as a parameter a Math::VectorReal object, a reference to an array, or the list of coordinates.

$atom->internal_coords

    # get a Chemistry::InternalCoords object
    my $ic = $atom->coords;      

    # set a Chemistry::InternalCoords object 
    $atom->coords($vic);         

    # also accepts array refs 
    $atom->coords([8, 1.54, 7, 109.47, 6, 120.0]);   

    # also accepts lists
    $atom->coords(8, 1.54, 7, 109.47, 6, 120.0);    

Sets or gets the atom's internal coordinates. It can take as a parameter a Chemistry::InternalCoords object, a reference to an array, or the list of coordinates. In the last two cases, the list elements are the following: atom number or reference for distance, distance, atom number or reference for angle, angle in degrees, atom number or reference for dihedral, dihedral in degrees.

$atom->x3, $atom->y3, $atom->z3

Get the x, y or z 3D coordinate of the atom. This methods are just accessors that don't change the coordinats. $atom->x3 is short for ($atom->coords->array)[0], and so on.

$atom->formal_charge($charge)

Set or get the formal charge of the atom.

$atom->implicit_hydrogens($h_count)

Set or get the number of implicit hydrogen atoms bonded to the atom.

$atom->hydrogens($h_count)

Set or get the number of implicit hydrogen atoms bonded to the atom (DEPRECATED: USE implicit_hydrogens INSTEAD).

$atom->total_hydrogens($h_count)

Set or get the total number of hydrogen atoms bonded to the atom.

$atom->aromatic($bool)

Set or get whether the atom is considered to be aromatic. This property may be set arbitrarily, it doesn't imply any kind of "intelligent aromaticity detection"! (For that, look at the Chemistry::Ring module).

$atom->valence

Returns the sum of the bond orders of the bonds in which the atom participates, including implicit hydrogens (which are assumed to have bond orders of one).

$atom->valence

Like c<valence>, but excluding implicit hydrogen atoms.

$atom->add_bond($bond)

Adds a new bond to the atom, as defined by the Chemistry::Bond object $bond.

$atom->delete

Calls $mol->delete_atom($atom) on the atom's parent molecule. Note that an atom should belong to only one molecule or strange things will happen.

$atom->neighbors($from)

Return a list of neighbors. If an atom object $from is specified, it will be excluded from the list (this is useful if an atom wants to know who its neighbor's neighbors are, without counting itself).

$atom->bonds($from)

Return a list of bonds. If an atom object $from is specified, bonds to that atom will be excluded from the list.

$atom->bonds_neighbors($from)

Return a list of hash references, representing the bonds and neighbors from the atom. If an atom object $from is specified, it will be excluded from the list. The elements of the hash are 'to', and atom reference, and 'bond', a bond reference. For example,

    for my $bn ($atom->bonds_neighbors) {
        print "bond $bn->{bond} point to atom $bn->{to}\n";
    }

($distance, $closest_atom) = $atom->distance($obj)

Returns the minimum distance to $obj, which can be an atom, a molecule, or a vector. In scalar context it returns only the distance; in list context it also returns the closest atom found. It can also be called as a function, Chemistry::Atom::distance (which can be exported).

$atom->angle($atom2, $atom3)

Returns the angle in radians between the atoms involved. $atom2 is the atom in the middle. Can also be called as Chemistry::Atom::angle($atom1, $atom2, $atom3). This function can be exported.

$atom->angle_deg($atom2, $atom3)

Same as angle(), but returns the value in degrees. May be exported.

$atom->dihedral($atom2, $atom3, $atom4)

Returns the dihedral angle in radians between the atoms involved. Can also be called as Chemistry::Atom::dihedral($atom1, $atom2, $atom3, $atom4). May be exported.

$atom->dihedral_deg($atom2, $atom3, $atom4)

Same as dihedral(), but returns the value in degrees. May be exported.

$atom->print

Convert the atom to a string representation (used for debugging).

my $info = $atom->sprintf($format)

Format interesting atomic information in a concise way, as specified by a printf-like format.

    %s - symbol
    %Z - atomic number
    %n - name
    %q - formal charge
    %h - implicit hydrogen count
    %v - valence
    %i - id
    %8.3m - mass, formatted as %8.3f with core sprintf
    %8.3x - x coordinate, formatted as %8.3f with core sprintf
    %8.3y - y coordinate, formatted as %8.3f with core sprintf
    %8.3z - z coordinate, formatted as %8.3f with core sprintf
    %% - %

$atom->printf($format)

Same as $atom->sprintf, but prints to standard output automatically. Used for quick and dirty molecular information dumping.

VERSION

0.26

SEE ALSO

Chemistry::Mol, Chemistry::Bond, Math::VectorReal, Chemistry::Tutorial

The PerlMol website http://www.perlmol.org/

AUTHOR

Ivan Tubert-Brohman <itub@cpan.org>

COPYRIGHT

Copyright (c) 2004 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.