Chemistry::Canonicalize - Number the atoms in a molecule in a unique way


    use Chemistry::Canonicalize ':all';

    # $mol is a Chemistry::Mol object
    print "The canonical number for atom 1 is: ", 
    print "The symmetry class for for atom 1 is: ", 


This module provides functions for "canonicalizing" a molecular structure; that is, to number the atoms in a unique way regardless of the input order.

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,


During the canonicalization process, the following attributes are set on each atom:

  • canon/class
  • The unique canonical number; it is an integer going from 1 to the number of atoms.

  • canon/symmetry_class
  • The symmetry class number. Atoms that have the same symmetry class are considered to be topologicaly equivalent. For example, the two methyl carbons on 2-propanol would have the same symmetry class.


These functions may be exported, although nothing is exported by default.

  • 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.

    • 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.




Add some tests.


Currently there is an atom limit of about 430 atoms.

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!


Chemistry::Mol, Chemistry::Atom, Chemistry::Obj,


Ivan Tubert <>


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.