.\" Automatically generated by Pod::Man 4.14 (Pod::Simple 3.42)
.\"
.\" Standard preamble:
.\" ========================================================================
.de Sp \" Vertical space (when we can't use .PP)
.if t .sp .5v
.if n .sp
..
.de Vb \" Begin verbatim text
.ft CW
.nf
.ne \\$1
..
.de Ve \" End verbatim text
.ft R
.fi
..
.\" Set up some character translations and predefined strings.  \*(-- will
.\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
.\" double quote, and \*(R" will give a right double quote.  \*(C+ will
.\" give a nicer C++.  Capital omega is used to do unbreakable dashes and
.\" therefore won't be available.  \*(C` and \*(C' expand to `' in nroff,
.\" nothing in troff, for use with C<>.
.tr \(*W-
.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
.ie n \{\
.    ds -- \(*W-
.    ds PI pi
.    if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
.    if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\"  diablo 12 pitch
.    ds L" ""
.    ds R" ""
.    ds C` ""
.    ds C' ""
'br\}
.el\{\
.    ds -- \|\(em\|
.    ds PI \(*p
.    ds L" ``
.    ds R" ''
.    ds C`
.    ds C'
'br\}
.\"
.\" Escape single quotes in literal strings from groff's Unicode transform.
.ie \n(.g .ds Aq \(aq
.el       .ds Aq '
.\"
.\" If the F register is >0, we'll generate index entries on stderr for
.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
.\" entries marked with X<> in POD.  Of course, you'll have to process the
.\" output yourself in some meaningful fashion.
.\"
.\" Avoid warning from groff about undefined register 'F'.
.de IX
..
.nr rF 0
.if \n(.g .if rF .nr rF 1
.if (\n(rF:(\n(.g==0)) \{\
.    if \nF \{\
.        de IX
.        tm Index:\\$1\t\\n%\t"\\$2"
..
.        if !\nF==2 \{\
.            nr % 0
.            nr F 2
.        \}
.    \}
.\}
.rr rF
.\" ========================================================================
.\"
.IX Title "Chemistry::Atom 3pm"
.TH Chemistry::Atom 3pm "2022-07-14" "perl v5.34.0" "User Contributed Perl Documentation"
.\" For nroff, turn off justification.  Always turn off hyphenation; it makes
.\" way too many mistakes in technical documents.
.if n .ad l
.nh
.SH "NAME"
Chemistry::Atom \- Chemical atoms as objects in molecules
.SH "SYNOPSIS"
.IX Header "SYNOPSIS"
.Vb 1
\&    use Chemistry::Atom;
\&
\&    my $atom = new Chemistry::Atom(
\&        id => \*(Aqa1\*(Aq,
\&        coords => [$x, $y, $z],
\&        symbol => \*(AqBr\*(Aq
\&    );
\&
\&    print $atom\->print;
.Ve
.SH "DESCRIPTION"
.IX Header "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.
.SS "Atom Attributes"
.IX Subsection "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.
.PP
In general, to get the value of a property, use \f(CW$atom\fR\->method without
any parameters. To set the value, use \f(CW$atom\fR\->method($new_value). When setting
an attribute, the accessor returns the atom object, so that accessors can be
chained:
.PP
.Vb 1
\&    $atom\->symbol("C")\->name("CA")\->coords(1,2,3);
.Ve
.SH "METHODS"
.IX Header "METHODS"
.IP "Chemistry::Atom\->new(name => value, ...)" 4
.IX Item "Chemistry::Atom->new(name => value, ...)"
Create a new Atom object with the specified attributes.
.ie n .IP "$atom\->Z($new_Z)" 4
.el .IP "\f(CW$atom\fR\->Z($new_Z)" 4
.IX Item "$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.
.ie n .IP "$atom\->symbol($new_symbol)" 4
.el .IP "\f(CW$atom\fR\->symbol($new_symbol)" 4
.IX Item "$atom->symbol($new_symbol)"
Sets and returns the atomic symbol.
.ie n .IP "$atom\->mass($new_mass)" 4
.el .IP "\f(CW$atom\fR\->mass($new_mass)" 4
.IX Item "$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:
.Sp
1) If the mass number is undefined (see the mass_number method below), the
relative atomic mass from the 1995 \s-1IUPAC\s0 recommendation is used. (Table stolen
from the Chemistry::MolecularMass module by Maksim A.  Khrapov).
.Sp
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.
.ie n .IP "$atom\->mass_number($new_mass_number)" 4
.el .IP "\f(CW$atom\fR\->mass_number($new_mass_number)" 4
.IX Item "$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).
.ie n .IP "$atom\->coords" 4
.el .IP "\f(CW$atom\fR\->coords" 4
.IX Item "$atom->coords"
.Vb 4
\&    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
.Ve
.Sp
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.
.ie n .IP "$atom\->internal_coords" 4
.el .IP "\f(CW$atom\fR\->internal_coords" 4
.IX Item "$atom->internal_coords"
.Vb 2
\&    # 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);
.Ve
.Sp
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.
.ie n .IP "$atom\->x3, $atom\->y3, $atom\->z3" 4
.el .IP "\f(CW$atom\fR\->x3, \f(CW$atom\fR\->y3, \f(CW$atom\fR\->z3" 4
.IX Item "$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. \f(CW$atom\fR\->x3 is short for 
($atom\->coords\->array)[0], and so on.
.ie n .IP "$atom\->formal_charge($charge)" 4
.el .IP "\f(CW$atom\fR\->formal_charge($charge)" 4
.IX Item "$atom->formal_charge($charge)"
Set or get the formal charge of the atom.
.ie n .IP "$atom\->formal_radical($radical)" 4
.el .IP "\f(CW$atom\fR\->formal_radical($radical)" 4
.IX Item "$atom->formal_radical($radical)"
Set or get the formal radical multiplicity for the atom.
.ie n .IP "$atom\->implicit_hydrogens($h_count)" 4
.el .IP "\f(CW$atom\fR\->implicit_hydrogens($h_count)" 4
.IX Item "$atom->implicit_hydrogens($h_count)"
Set or get the number of implicit hydrogen atoms bonded to the atom.
.ie n .IP "$atom\->hydrogens($h_count)" 4
.el .IP "\f(CW$atom\fR\->hydrogens($h_count)" 4
.IX Item "$atom->hydrogens($h_count)"
Set or get the number of implicit hydrogen atoms bonded to the atom
(\s-1DEPRECATED: USE\s0 \f(CW\*(C`implicit_hydrogens\*(C'\fR \s-1INSTEAD\s0).
.ie n .IP "$atom\->total_hydrogens($h_count)" 4
.el .IP "\f(CW$atom\fR\->total_hydrogens($h_count)" 4
.IX Item "$atom->total_hydrogens($h_count)"
Get the total number of hydrogen atoms bonded to the atom (implicit +
explicit).
.ie n .IP "$atom\->sprout_hydrogens" 4
.el .IP "\f(CW$atom\fR\->sprout_hydrogens" 4
.IX Item "$atom->sprout_hydrogens"
Convert all the implicit hydrogens for this atom to explicit hydrogens. Note:
it does \fBnot\fR generate coordinates for the new atoms.
.ie n .IP "$atom\->collapse_hydrogens" 4
.el .IP "\f(CW$atom\fR\->collapse_hydrogens" 4
.IX Item "$atom->collapse_hydrogens"
Delete neighboring hydrogen atoms and add them as implicit hydrogens for this
atom.
.ie n .IP "$atom\->calc_implicit_hydrogens" 4
.el .IP "\f(CW$atom\fR\->calc_implicit_hydrogens" 4
.IX Item "$atom->calc_implicit_hydrogens"
Use heuristics to figure out how many implicit hydrogens should the atom have
to satisfy its normal \*(L"organic\*(R" valence. Returns the number of hydrogens but
does not affect the atom object.
.ie n .IP "$atom\->add_implicit_hydrogens" 4
.el .IP "\f(CW$atom\fR\->add_implicit_hydrogens" 4
.IX Item "$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
.Sp
.Vb 1
\&    $atom\->implicit_hydrogens($atom\->calc_implicit_hydrogens);
.Ve
.Sp
It returns the atom object.
.ie n .IP "$atom\->aromatic($bool)" 4
.el .IP "\f(CW$atom\fR\->aromatic($bool)" 4
.IX Item "$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 \*(L"intelligent aromaticity
detection\*(R"! (For that, look at the Chemistry::Ring module).
.ie n .IP "$atom\->valence" 4
.el .IP "\f(CW$atom\fR\->valence" 4
.IX Item "$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).
.ie n .IP "$atom\->explicit_valence" 4
.el .IP "\f(CW$atom\fR\->explicit_valence" 4
.IX Item "$atom->explicit_valence"
Like \f(CW\*(C`valence\*(C'\fR, but excluding implicit hydrogen atoms. To get the raw number
of bonds, without counting bond orders, call \f(CW$atom\fR\->bonds in scalar context.
.ie n .IP "$atom\->delete" 4
.el .IP "\f(CW$atom\fR\->delete" 4
.IX Item "$atom->delete"
Calls \f(CW$mol\fR\->delete_atom($atom) on the atom's parent molecule.
.ie n .IP "$atom\->parent" 4
.el .IP "\f(CW$atom\fR\->parent" 4
.IX Item "$atom->parent"
Returns the atom's containing object (the molecule to which the atom belongs).
An atom can only have one parent.
.ie n .IP "$atom\->neighbors($from)" 4
.el .IP "\f(CW$atom\fR\->neighbors($from)" 4
.IX Item "$atom->neighbors($from)"
Return a list of neighbors. If an atom object \f(CW$from\fR 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).
.ie n .IP "$atom\->bonds($from)" 4
.el .IP "\f(CW$atom\fR\->bonds($from)" 4
.IX Item "$atom->bonds($from)"
Return a list of bonds. If an atom object \f(CW$from\fR is specified, bonds to
that atom will be excluded from the list.
.ie n .IP "$atom\->bonds_neighbors($from)" 4
.el .IP "\f(CW$atom\fR\->bonds_neighbors($from)" 4
.IX Item "$atom->bonds_neighbors($from)"
Return a list of hash references, representing the bonds and neighbors from the
atom. If an atom object \f(CW$from\fR 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,
.Sp
.Vb 3
\&    for my $bn ($atom\->bonds_neighbors) {
\&        print "bond $bn\->{bond} point to atom $bn\->{to}\en";
\&    }
.Ve
.ie n .IP "($distance, $closest_atom) = $atom\->distance($obj)" 4
.el .IP "($distance, \f(CW$closest_atom\fR) = \f(CW$atom\fR\->distance($obj)" 4
.IX Item "($distance, $closest_atom) = $atom->distance($obj)"
Returns the minimum distance to \f(CW$obj\fR, 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).
.ie n .IP "$atom\->angle($atom2, $atom3)" 4
.el .IP "\f(CW$atom\fR\->angle($atom2, \f(CW$atom3\fR)" 4
.IX Item "$atom->angle($atom2, $atom3)"
Returns the angle in radians between the atoms involved. \f(CW$atom2\fR is the atom in
the middle. Can also be called as Chemistry::Atom::angle($atom1, \f(CW$atom2\fR,
\&\f(CW$atom3\fR). This function can be exported. Note: if you override this method,
you may also need to override angle_deg or strange things may happen.
.ie n .IP "$atom\->angle_deg($atom2, $atom3)" 4
.el .IP "\f(CW$atom\fR\->angle_deg($atom2, \f(CW$atom3\fR)" 4
.IX Item "$atom->angle_deg($atom2, $atom3)"
Same as \fBangle()\fR, but returns the value in degrees. May be exported.
.ie n .IP "$atom\->dihedral($atom2, $atom3, $atom4)" 4
.el .IP "\f(CW$atom\fR\->dihedral($atom2, \f(CW$atom3\fR, \f(CW$atom4\fR)" 4
.IX Item "$atom->dihedral($atom2, $atom3, $atom4)"
Returns the dihedral angle in radians between the atoms involved.  Can also be
called as Chemistry::Atom::dihedral($atom1, \f(CW$atom2\fR, \f(CW$atom3\fR, \f(CW$atom4\fR). May be
exported. Note: if you override this method, you may also need to override 
dihedral_deg and angle or strange things may happen.
.ie n .IP "$atom\->dihedral_deg($atom2, $atom3, $atom4)" 4
.el .IP "\f(CW$atom\fR\->dihedral_deg($atom2, \f(CW$atom3\fR, \f(CW$atom4\fR)" 4
.IX Item "$atom->dihedral_deg($atom2, $atom3, $atom4)"
Same as \fBdihedral()\fR, but returns the value in degrees. May be exported.
.ie n .IP "$atom\->print" 4
.el .IP "\f(CW$atom\fR\->print" 4
.IX Item "$atom->print"
Convert the atom to a string representation (used for debugging).
.ie n .IP "my $info = $atom\->sprintf($format)" 4
.el .IP "my \f(CW$info\fR = \f(CW$atom\fR\->sprintf($format)" 4
.IX Item "my $info = $atom->sprintf($format)"
Format interesting atomic information in a concise way, as specified by
a printf-like format.
.Sp
.Vb 12
\&    %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
\&    %% \- %
.Ve
.ie n .IP "$atom\->printf($format)" 4
.el .IP "\f(CW$atom\fR\->printf($format)" 4
.IX Item "$atom->printf($format)"
Same as \f(CW$atom\fR\->sprintf, but prints to standard output automatically. Used
for quick and dirty atomic information dumping.
.SH "SOURCE CODE REPOSITORY"
.IX Header "SOURCE CODE REPOSITORY"
<https://github.com/perlmol/Chemistry\-Mol>
.SH "SEE ALSO"
.IX Header "SEE ALSO"
Chemistry::Mol, Chemistry::Bond, 
Math::VectorReal, Chemistry::Tutorial,
Chemistry::InternalCoords
.SH "AUTHOR"
.IX Header "AUTHOR"
Ivan Tubert-Brohman <itub@cpan.org>
.SH "COPYRIGHT"
.IX Header "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.