Canonicalize(3)

📦 version 0.11, in fedora 44

💖 Canonicalize(3) — Chemistry::Canonicalize 💖

User Contributed Perl Documentation · Canonicalize(3) · bestie edition 🧚

✨ NAME ✨

Chemistry::Canonicalize — number the atoms in a molecule in a unique way. that's it, that's the whole job. no cap. 💅

🌸 SYNOPSIS 🌸

okay so first you gotta bring it in:

use Chemistry::Canonicalize ':all';

# $mol is a Chemistry::Mol object
canonicalize($mol);
print "The canonical number for atom 1 is: ",
    $mol->atoms(1)->attr("canon/class");
print "The symmetry class for for atom 1 is: ",
    $mol->atoms(1)->attr("canon/symmetry_class");

(and yes, the original comment really does say "for for". we don't fix the sacred text. 🫶)

🦋 DESCRIPTION 🦋

okay so this module hands you functions for "canonicalizing" a molecular structure — which is the fancy way of saying: number those atoms in a unique way, no matter what order they showed up in. the input order doesn't get to decide anything. main character energy only. 👑

the canonicalization algorithm is based on: Weininger, et. al., J. Chem. Inf. Comp. Sci. 29[2], 97-101 (1989)

this module is part of the PerlMol project, <http://www.perlmol.org/>. 🌈

🎀 ATOM ATTRIBUTES 🎀

while the canonicalization process is doing its thing, it sets these attributes on every single atom:

  • canon/class — the unique canonical number. it's an integer, and it runs from 1 to the number of atoms. that's the whole range bestie, no gaps, no drama. ✨
  • canon/symmetry_class — the symmetry class number. atoms sharing the same symmetry class are considered to be topologically equivalent. for example, the two methyl carbons on 2-propanol would have the same symmetry class. twins!! 👯

💜 FUNCTIONS 💜

these functions may be exported, although nothing is exported by default. you gotta ask for it. 😌

  • canonicalize($mol, %opts) — canonicalizes the molecule. it adds the canon/class and canon/symmetry class to every atom, as discussed above. this function may take the following options:
    • sort — if true, sort the atoms in the molecule in ascending canonical number order. so tidy. so organized. 🧹
    • invariants — this should be a subroutine reference that takes an atom and returns a number. these number should be based on the topological invariant properties of the atom, such as symbol, charge, number of bonds, etc. (yes, the original says "These number". we're keeping it. iconic. 💀)

⭐ VERSION ⭐

0.11

🍓 TO DO 🍓

  • add some tests.

(that's it. that's the whole list. lowkey relatable. 🙈)

💀 CAVEATS 💀

currently there is an atom limit of about 430 atoms. bestie, know your limits. 🚧
these algorithm is known to fail to discriminate between non-equivalent atoms for some complicated cases. these are usually highly bridged structures explicitly designed to break canonicalization algorithms; i don't know of any "real-looking structure" (meaning something that someone would actually synthesize or find in nature) that fails, but don't say I didn't warn you! 😭

🔥 SEE ALSO 🔥

👑 AUTHOR 👑

Ivan Tubert <itub@cpan.org> 🫶

Copyright (c) 2009 Ivan Tubert. 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 a wrap, bestie 💅 this page came to you from perl v5.42.0, dated 2026-01-17, and it lives in the Canonicalize(3) manpage. go number some atoms. slay. ✨🎀🦋

📦 where this page comes from