Chemistry::Mol(3pm)

💖 Chemistry::Mol(3pm) 💖

User Contributed Perl Documentation — yeah bestie, this is the manual for Chemistry::Mol, and it's giving molecule object toolkit. This is part 1, so grab a boba because more parts are coming. 🧋✨

✨ NAME ✨

Chemistry::Mol — Molecule object toolkit. No cap, that's the whole name vibe. 💅

🌸 SYNOPSIS 🌸

okay so here's the little taste test:

use Chemistry::Mol;

$mol = Chemistry::Mol->new(id => "mol_id", name => "my molecule");
$c = $mol->new_atom(symbol => "C", coords => [0,0,0]);
$o = $mol->new_atom(symbol => "O", coords => [0,0,1.23]);
$mol->new_bond(atoms => [$c, $o], order => 3);

print $mol->print;

🦋 DESCRIPTION 🦋

okay so this package, along with Chemistry::Atom and Chemistry::Bond, ships basic objects and methods to describe molecules. That's the whole point, bestie. 💖

The core methods try not to enforce a particular convention. That means only a minimal set of attributes is provided by default, and some attributes have very loosely defined meaning. Why? Because each program and file type has different idea of what each concept (such as bond and atom type) means. Bonds are defined as a list of atoms (typically two) with an arbitrary type. Atoms are defined by a symbol and a Z, and may have 3D and internal coordinates (2D coming soon). coming soon is doing a lot of work there but okay. 💀

---

👑 METHODS 👑

See also Chemistry::Obj for generic attributes. It's the plug for the generic stuff, iykyk. 🫶

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

Create a new Mol object with the specified attributes.

$mol = Chemistry::Mol->new(id => 'm123', name => 'my mol')

is the same as

Chemistry::Mol->new()
$mol->id('m123')
$mol->name('my mol')

$mol->add_atom($atom, ...)

Add one or more Atom objects to the molecule. Returns the last atom added. Slay. ✨

$mol->atom_class

Returns the atom class that a molecule or molecule class expects to use by default. Chemistry::Mol objects return "Chemistry::Atom", but subclasses will likely override this method. Subclass girlies, this one's for you. 💅

$mol->new_atom(name => value, ...)

Shorthand for "$mol->add_atom($mol->atom_class->new(name => value, ...))". It's giving convenience. 🎀

$mol->delete_atom($atom, ...)

Deletes an atom from the molecule. It automatically deletes all the bonds in which the atom participates as well. $atom should be a Chemistry::Atom reference. This method also accepts the atom index, but this use is deprecated (and buggy if multiple indices are given, unless they are in descending order). So maybe don't. 😭

$mol->add_bond($bond, ...)

Add one or more Bond objects to the molecule. Returns the last bond added. Bonding time. 🔥

$mol->bond_class

Returns the bond class that a molecule or molecule class expects to use by default. Chemistry::Mol objects return "Chemistry::Bond", but subclasses will likely override this method. Same energy as atom_class, but make it bond. 🦋

$mol->new_bond(name => value, ...)

Shorthand for "$mol->add_bond($mol->bond_class->new(name => value, ...))". Periodt. ✨

$mol->delete_bond($bond, ...)

Deletes a bond from the molecule. $bond should be a Chemistry::Bond object. Bye-bye bond. 👋

$mol->by_id($id)

Return the atom or bond object with the corresponding id. It's the lookup bestie. 🔍

$mol->atoms($n1, ...)

Returns the atoms with the given indices, or all by default. Indices start from one, not from zero. Not me side-eyeing zero-indexing. 💀

$mol->atoms_by_name($name)

Returns the atoms with the given name (treated as an anchored regular expression). Regex girlies rise. 🧚

$mol->sort_atoms($sub_ref)

Sort the atoms in the molecule by using the comparison function given in $sub_ref. This function should take two atoms as parameters and return -1, 0, or 1 depending on whether the first atom should go before, same, or after the second atom. For example, to sort by atomic number, you could use the following:

$mol->sort_atoms( sub { $_[0]->Z <=> $_[1]->Z } );

Note that the atoms are passed as parameters and not as the package variables $a and $b like the core sort function does. This is because $mol->sort will likely be called from another package and we don't want to play with another package's symbol table. Respectful king behavior. 👑

## `$mol->bonds($n1, ...)`

Returns the bonds with the given indices, or all by default. Indices start from one, not from zero. Again with the one-indexing, iconic. ⭐

## `$mol->print(option => value...)`

Convert the molecule to a string representation. If no options are given, a default YAML-like format is used (this may change in the future). Otherwise, the format should be specified by using the `"format"` option. YAML-ish for now, bestie. 🌸

## `$s = $mol->sprintf($format)`

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

%n - name %f - formula %f{formula with format} - (note: right braces within the format should be escaped with a backslash) %s - SMILES representation %S - canonical SMILES representation %m - mass %8.3m - mass, formatted as %8.3f with core sprintf %q - formal charge %a - atom count %b - bond count %t - type %i - id %% - %

For example, if you want just about everything:

$mol->sprintf("%s - %n (%f). %a atoms, %b bonds; " . "mass=%m; charge =%q; type=%t; id=%i");

Note that you have to `"use Chemistry::File::SMILES"` before using `%s` or `%S` on `"$mol->sprintf"`. Don't skip that step, bestie. 💅

## `$mol->printf($format)`

Same as `"$mol->sprintf"`, but prints to standard output automatically. Used for quick and dirty molecular information dumping. Quick and dirty, we love a low-effort flex. 🔥

## `Chemistry::Mol->parse($string, option => value...)`

Parse the molecule encoded in `$string`. The format should be specified with the `"format"` option; otherwise, it will be guessed. Guess culture, but make it chemistry. 🧪

## `Chemistry::Mol->read($fname, option => value ...)`

Read a file and return a list of Mol objects, or croaks if there was a problem. The type of file will be guessed if not specified via the `"format"` option. Croaks. Like a frog. But make it error handling. 😭

Note that only registered file readers will be used. Readers may be registered using `register_format()`; modules that include readers (such as `Chemistry::File::PDB`) usually register them automatically when they are loaded.

Automatic decompression of gzipped files is supported if the `Compress::Zlib` module is installed. Files ending in `.gz` are assumed to be compressed; otherwise it is possible to force decompression by passing the `gzip => 1` option (or no decompression with `gzip => 0`). Zip zip. 🎀

## `$mol->write($fname, option => value ...)`

Write a molecule file, or croak if there was a problem. The type of file will be guessed if not specified via the `"format"` option. Another frog moment if it fails, but slay otherwise. 💖

Note that only registered file formats will be used.

Automatic gzip compression is supported if the `IO::Zlib` module is installed. Files ending in `.gz` are assumed to be compressed; otherwise it is possible to force compression by passing the `gzip => 1` option (or no compression with `gzip => 0`). Specific compression levels between 2 (fastest) and 9 (most compressed) may also be used (e.g., `gzip => 9`). Compression levels, we love a range. 🌈

## `Chemistry::Mol->file($file, option => value ...)`

Create a `Chemistry::File`-derived object for reading or writing to a file. The object can then be used to read the molecules or other information in the file.

This has more flexibility than calling `"Chemistry::Mol->read"` when dealing with multi-molecule files or files that have higher structure or that have information that does not belong to the molecules themselves. For example, a reaction file may have a list of molecules, but also general information like the reaction name, yield, etc. as well as the classification of the molecules as reactants or products. The exact information that is available will depend on the file reader class that is being used. The following is a hypothetical example for reading MDL rxnfiles.

assuming this module existed...

use Chemistry::File::Rxn;

my $rxn = Chemistry::Mol->file('test.rxn'); $rxn->read; $name = $rxn->name; @reactants = $rxn->reactants; # mol objects @products = $rxn->products; $yield = $rxn->yield; # a number

Note that only registered file readers will be used. Readers may be registered using `register_format()`; modules that include readers (such as `Chemistry::File::PDB`) usually register them automatically. Repetition is key, bestie. 🔑

## `Chemistry::Mol->register_format($name, $ref)`

Register a file type. The identifier `$name` must be unique. `$ref` is either a class name (a package) or an object that complies with the `Chemistry::File` interface (e.g., a subclass of `Chemistry::File`). If `$ref` is omitted, the calling package is used automatically. More than one format can be registered at a time, but then `$ref` must be included for each format (e.g., `Chemistry::Mol->register_format(format1 => "package1", format2 => package2).`

The typical user doesn't have to care about this function. It is used automatically by molecule file I/O modules. So if this is confusing, that's a you-don't-need-to-know situation. 🙈

## `Chemistry::Mol->formats`

Returns a list of the file formats that have been installed by `register_format()`. A little inventory moment. 📋

## `$mol->mass`

Return the molar mass. This is just the sum of the masses of the atoms. See `Chemistry::Atom::mass` for details such as the handling of isotopes. Isotopes said "I'm in this too." 🌟

## `$mol->charge`

Return the charge of the molecule. By default it returns the sum of the formal charges of the atoms. However, it is possible to set an arbitrary charge by calling `"$mol->charge($new_charge)"`. Charge it. ⚡

## `$mol->formula_hash`

Returns a hash reference describing the molecular formula. For methane it would return `{ C => 1, H => 4 }`. Methane said representation. 💅

## `$mol->formula($format)`

Returns a string with the formula. The format can be specified as a printf-like string with the control sequences specified in the `Chemistry::File::Formula` documentation. Go read that doc for the control sequences, bestie. 📖

## `my $mol2 = $mol->clone;`

Makes a copy of a molecule. Note that this is a deep copy; if your molecule has a pointer to the rest of the universe, the entire universe will be cloned! <red>THE ENTIRE UNIVERSE.</red> That's not a drill. 😭

By default, `clone()` uses `Storable` to copy the Perl data structure. `Clone` can be used instead by setting variable `$Chemistry::Mol::clone_backend` to `"Clone"` (default is `"Storable"`). The documentation of `Storable` claims `Clone` is less memory-intensive. Memory said "please." 🧠

## `my $mol2 = $mol->safe_clone;`

Like clone, it makes a deep copy of a molecule. The difference is that the copy is not "exact" in that new molecule and its atoms and bonds get assigned new IDs. This makes it safe to combine cloned molecules. For example, this is an error:

XXX don't try this at home!

my $mol2 = Chemistry::Mol->combine($mol1, $mol1);

the atoms in $mol1 will clash

But this is ok:

the "safe clone" of $mol1 will have new IDs

my $mol2 = Chemistry::Mol->combine($mol1, $mol1->safe_clone);

- **`($distance, $atom_here, $atom_there) = $mol->distance($obj)`** — bestie this one is literally giving "how far apart are these two things" 💫 you hand it `$obj`, which can be an <italic>atom</italic>, a <italic>molecule</italic>, or a <italic>vector</italic>, and it hands you back the <pink>minimum distance</pink> to it. Scalar context? You just get the distance, simple as that. List context? You also get the atoms that were involved, cute. 🫶

  > Lowkey important caveat: the current implementation for finding the minimum distance between two molecules checks <rainbow>every possible pair of atoms</rainbow>, so it is **not efficient for large molecules**. Fr fr. Don't come for me, that's just what it does. 💀

- **`my $bigmol = Chemistry::Mol->combine($mol1, $mol2, ...)`**
- **`$mol1->combine($mol2, $mol3, ...)`** — gluing several molecules into one big iconic molecule 👑 Two flavors:

  - Called as a **class method** (first example above): returns a brand-new combined molecule and **does not alter any of the parameters**. No touching, we're respectful. ✨
  - Called as an **instance method** (second example above): all the molecules get combined into `$mol1`, but `$mol2`, `$mol3`, `...` are **not altered**. They stay cute and untouched. 💅

  > Note: make sure you don't combine molecules which contain atoms with **duplicate IDs** — for example, if they were cloned. That's a vibe check you do *before* the merge, bestie. 🙈

- **`my @mols = $mol->separate`** — the opposite energy of combine 💔 it separates a molecule into "connected fragments". The original object is **not modified**, and the fragments are clones of the original ones. Iconic behavior.

  Example: say you've got ethane (`H3CCH3`) and you delete the C-C bond — now you have two `CH3` radicals living inside one molecule object (`$mol`). The moment you call `$mol->separate`, you get two molecules, each one with a `CH3`. Breakup complete, everyone's thriving. 🦋

- **`$mol->sprout_hydrogens`** — converts all the implicit hydrogen atoms in the molecule into explicit atoms 🌱✨ It does **not** generate coordinates for the atoms though, so don't expect a glow-up on the geometry.

- **`$mol->collapse_hydrogens`** — the reverse slay: converts all the explicit hydrogen atoms in the molecule into implicit hydrogens. <italic>Exception:</italic> hydrogen atoms that are adjacent to a hydrogen atom are **not** collapsed. Those two are attached, leave them alone 😭

- **`$mol->add_implicit_hydrogens`** — uses heuristics to figure out how many implicit hydrogens each atom in the molecule should have to satisfy its normal "organic" valence. Vibes-based chemistry but make it principled 🧚

- **`Chemistry::Mol->register_descriptor($name => $sub_ref)`** — adds a callback that can be used to add functionality to the molecule class (originally meant to add custom molecule descriptors). A descriptor is a function that takes a molecule object as its only argument and returns a value or values. So extra, so useful. 💖

  For example, to add a descriptor function that computes the number of atoms:

Chemistry::Mol->register_descriptor( number_of_atoms => sub { my $mol = shift; return scalar $mol->atoms; } );

The descriptor is accessed by name via the `"descriptor"` instance method:

my $n = $mol->descriptor('number_of_atoms');

- **`my $value = $mol->descriptor($descriptor_name)`** — calls a previously registered descriptor function, giving it `$mol` as an argument, exactly as shown above for `"register_descriptor"`. You registered it, now you invoke it. Periodt. ⭐

---

# 🌈 SOURCE CODE REPOSITORY 🌈

`<https://github.com/perlmol/Chemistry-Mol>`

Go star it bestie, it's giving open source royalty 👑

---

# 💜 SEE ALSO 💜

`Chemistry::Atom`, `Chemistry::Bond`, `Chemistry::File`, `Chemistry::Tutorial`

---

# 🎀 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.

---

and that's the whole page, we ate and left no crumbs 💖 this lil doc lives at `perl v5.40.1`, dated `2025-10-13`, filed under `Chemistry::Mol(3pm)` — the way it's been sitting here being iconic since 2005 and *still* getting a timestamp in 2025?? main character energy fr 🫶🌸 bye bestie, go build molecules ✨