Chemistry::Atom(3pm)

📦
version 0.40 · 4 versions
, in ubuntu resolute, ubuntu stonking

💖 NAME 💖

Chemistry::Atom — chemical atoms as objects in molecules 🧪✨ (this is the Chemistry::Atom(3pm) page from the User Contributed Perl Documentation, and bestie, it's about to serve)

🌸 SYNOPSIS 🌸

use Chemistry::Atom;

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

print $atom->print;

🦋 DESCRIPTION 🦋

Okay so this module is literally a whole little object system for describing chemical atoms. An atom is defined by its symbol and its coordinates, plus a bunch of other attributes that we'll get into. And here's the cute part: the atomic coordinates are described by a Math::VectorReal object, so you can just yeet them straight into vector operations. 💅

🎀 Atom Attributes 🎀

Beyond the regular everyday attributes like id, name, and type, atoms also carry these: bonds, coords, internal_coords, Z, symbol, etc. (the "etc." is doing a lot of work there, but slay).

The pattern, so you don't have to guess:

  • To get a property, call $atom->method with no parameters.
  • To set it, call $atom->method($new_value).
  • And when you set something, the accessor returns the atom object itself, which means accessor chaining is absolutely valid and honestly kinda iconic:
$atom->symbol("C")->name("CA")->coords(1,2,3);

✨ METHODS ✨

  • Chemistry::Atom->new(name => value, ...) — bestie, this makes you a whole new Atom object with whatever attributes you hand it. 🌱
  • $atom->Z($new_Z) — sets and returns the atomic number (Z). If the atom's symbol doesn't match up with a known element, then Z = undef. Sorry, no guesses. 💀
  • $atom->symbol($new_symbol) — sets and returns the atomic symbol. ⭐
  • $atom->mass($new_mass) — sets and returns the atomic mass in atomic mass units. You can set any arbitrary mass explicitly with this method, no questions asked. BUT — and this is the important bit — if no mass was ever set explicitly and you call this as an accessor, here's what you get back, in order:
    1. If the mass number is undefined (peep the mass_number method below), you get the relative atomic mass from the 1995 IUPAC recommendation. (Table stolen from the Chemistry::MolecularMass module by Maksim A. Khrapov — credit where credit is due. 🫶)
    2. If the mass number is defined, and the Chemistry::Isotope module is available and it knows the mass for that isotope, you get the exact mass of the isotope. Otherwise, you just get the mass number back.
  • $atom->mass_number($new_mass_number) — sets or gets the mass number. Heads up: the mass number is undefined unless you set it explicitly, because this module does not try to guess a default based on the natural isotope distribution. It's not out here speculating about isotopes. 🙈
  • $atom->coords — sets or gets the atom's coordinates. It happily accepts a Math::VectorReal object, a reference to an array, or just the list of coordinates. Check the vibes:
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
  • $atom->internal_coords — sets or gets the atom's internal coordinates. It takes a Chemistry::InternalCoords object, an array ref, or a plain list. For those last two options, the elements of the list go in this order: 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. Like so:
# 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);
  • $atom->x3, $atom->y3, $atom->z3 — get the x, y or z 3D coordinate of the atom. These are just accessors and they don't change the coordinates at all. $atom->x3 is short for ($atom->coords->array)[0], and so on down the line. 📐
  • $atom->formal_charge($charge) — set or get the atom's formal charge. ⚡
  • $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. Like, for real, use the other one.
  • $atom->total_hydrogens($h_count) — get the total number of hydrogen atoms bonded to the atom (implicit + explicit). Yes, they get added together. Math! ✨
  • $atom->sprout_hydrogens — converts all the implicit hydrogens for this atom into explicit hydrogens. ⚠️ Note: it does not generate coordinates for the new atoms, so don't come crying about missing geometry, bestie.
  • $atom->collapse_hydrogens — deletes the neighboring hydrogen atoms and adds them back as implicit hydrogens on this atom. The reverse glow-down. 🦋
  • $atom->calc_implicit_hydrogens — uses heuristics to figure out how many implicit hydrogens the atom should have to satisfy its normal "organic" valence. It returns that number but does not touch the atom object. Just a lil peek, no commitment. 👀
  • $atom->add_implicit_hydrogens — same energy as calc_implicit_hydrogens, except it also sets the number of implicit hydrogens on the atom to the newly calculated value. It's equivalent to:
$atom->implicit_hydrogens($atom->calc_implicit_hydrogens);

And it returns the atom object.

  • $atom->aromatic($bool) — set or get whether the atom is considered aromatic. And listen: this property may be set arbitrarily — it does not imply any kind of "intelligent aromaticity detection"! 🚨 (If that's what you want, go look at the Chemistry::Ring module.) It's giving "you decide, I just hold the flag."
  • $atom->valence — returns the sum of the bond orders of all the bonds the atom is participating in, including implicit hydrogens (which are assumed to have bond orders of one).
  • $atom->explicit_valence — like "valence", but excluding implicit hydrogen atoms. And if you want the raw number of bonds without counting bond orders at all, call $atom->bonds in scalar context.
  • $atom->delete — calls $mol->delete_atom($atom) on the atom's parent molecule. bye bestie 👋
  • $atom->parent — returns the atom's containing object (the molecule it belongs to). An atom can only have one parent. No complicated family trees here.
  • $atom->neighbors($from) — returns a list of neighbors. If you pass an atom object as $from, that one gets excluded from the list. This is super useful when an atom wants to know who its neighbor's neighbors are without counting itself. iykyk. 👑
  • $atom->bonds($from) — returns a list of bonds. If you pass an atom object as $from, the bonds to that atom get excluded from the list.
  • $atom->bonds_neighbors($from) — returns a list of hash references representing the bonds and neighbors of the atom. If you pass an atom object as $from, it gets excluded from the list. The elements of each hash are 'to', an atom reference, and 'bond', a bond reference. Like:
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 you only get the distance; in list context you also get 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. Consider yourself warned.
  • $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. Same warning, different method.
  • $atom->dihedral_deg($atom2, $atom3, $atom4) — same as dihedral(), but returns the value in degrees. May be exported.
  • $atom->print — converts the atom to a string representation (used for debugging). 🐛
  • my $info = $atom->sprintf($format) — formats interesting atomic information in a concise way, as specified by a printf-like format. The whole menu of conversions:
    • %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 it 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 (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.

And that's the whole page, bestie — no cap. Signing off: this was Chemistry::Atom(3pm), served up by perl v5.40.1, dated 2025-10-13. Go build some molecules. 🧚💜

📦 where this page comes from