Provided by: libchemistry-mol-perl_0.39-1_all 
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. Any arbitrary mass may be set explicitly by
using this method. However, if no mass is set explicitly and this method is called as an accessor,
the return value is the following:
1) If the mass number is undefined (see the mass_number method below), the relative atomic mass from
the 1995 IUPAC recommendation is used. (Table stolen from the Chemistry::MolecularMass module by
Maksim A. Khrapov).
2) If the mass number is defined and the Chemistry::Isotope module is available and it knows the mass
for the isotope, the exact mass of the isotope is used; otherwise, the mass number is returned.
$atom->mass_number($new_mass_number)
Sets or gets the mass number. The mass number is undefined unless is set explicitly (this module does
not try to guess a default mass number based on the natural occurring isotope distribution).
$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->internal_coords;
# set a Chemistry::InternalCoords object
$atom->internal_coords($vic);
# also accepts array refs
$atom->internal_coords([8, 1.54, 7, 109.47, 6, 120.0]);
# also accepts lists
$atom->internal_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
coordinates. $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->formal_radical($radical)
Set or get the formal radical multiplicity for 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)
Get the total number of hydrogen atoms bonded to the atom (implicit + explicit).
$atom->sprout_hydrogens
Convert all the implicit hydrogens for this atom to explicit hydrogens. Note: it does not generate
coordinates for the new atoms.
$atom->collapse_hydrogens
Delete neighboring hydrogen atoms and add them as implicit hydrogens for this atom.
$atom->calc_implicit_hydrogens
Use heuristics to figure out how many implicit hydrogens should the atom have to satisfy its normal
"organic" valence. Returns the number of hydrogens but does not affect the atom object.
$atom->add_implicit_hydrogens
Similar to calc_implicit_hydrogens, but it also sets the number of implicit hydrogens in the atom to
the new calculated value. Equivalent to
$atom->implicit_hydrogens($atom->calc_implicit_hydrogens);
It returns the atom object.
$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->explicit_valence
Like "valence", but excluding implicit hydrogen atoms. To get the raw number of bonds, without
counting bond orders, call $atom->bonds in scalar context.
$atom->delete
Calls $mol->delete_atom($atom) on the atom's parent molecule.
$atom->parent
Returns the atom's containing object (the molecule to which the atom belongs). An atom can only have
one parent.
$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. Note: if
you override this method, you may also need to override angle_deg or strange things may happen.
$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. Note: if you override
this method, you may also need to override dihedral_deg and angle or strange things may happen.
$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 atomic
information dumping.
SOURCE CODE REPOSITORY
<https://github.com/perlmol/Chemistry-Mol>
SEE ALSO
Chemistry::Mol, Chemistry::Bond, Math::VectorReal, Chemistry::Tutorial, Chemistry::InternalCoords
AUTHOR
Ivan Tubert-Brohman <itub@cpan.org>
COPYRIGHT
Copyright (c) 2005 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.
perl v5.34.0 2022-07-14 Chemistry::Atom(3pm)