Concepts and Conventions

This page introduces the core concepts, assumptions, and numerical conventions used throughout MolSymPy.

Understanding these is important for correctly interpreting results, especially when working with symmetry detection and symmetrization.

If you're looking for quick usage examples, start with Examples.

Tolerance

Geometric Tolerance

Symmetry and point group detection utilize a geometric tolerance set in Atoms.info["geom_tol"] with units in Å. Typical value is 0.05.

This value is used to determine if positional variation is low enough after symmetry operations to be considered equivalent. Larger tolerances make the algorithm more permissive when identifying symmetry operations.

When using symmetrize(), get_point_group(), get_inequivalent(), the tolerance is set via the geom_tol argument. If not specified, the default value is 0.05.

Relative eigen tolerance

Warning

By default, eigen_tol is derived from geom_tol and the molecular size, ensuring that inertia comparisons are consistent with the allowed geometric perturbation. Be careful when overriding this parameter, as values that are inconsistent with the geometric tolerance will result in unexpected behaviour.

In most cases, the automatically estimated value is recommended.

Symmetry and point group detection utilize a relative tolerance set in Atoms.info["eigen_tol"]. Typical value is in the range of 1e-02 and 1e-05.

This value is used to compare the relative difference between eigenvalues (moments of inertia). Used for molecular classification (linear, spherical top, etc.) Larger tolerances make the algorithm more permissive when identifying degeneracies in the moments of inertia, which affects molecular classification.

When using symmetrize(), get_point_group(), get_inequivalent() and generate_symmetry_candidates() the tolerance is set via the eigen_tol argument. If not specified, the default value is None and a function will automatically try to determine an adequate float given the input molecule and geometric tolerance.

The relative eigen tolerance is estimated from the geometric tolerance by propagating positional uncertainty into the expected relative variation of the moments of inertia. Roughly, eigen_tol ∝ geom_tol / molecular_size, so larger molecules require tighter relative tolerances.

Warnings and debug output

When using symmetrize(), get_point_group(), get_inequivalent(), and generate_symmetry_candidates, warnings and debug output may be triggered. Printing is controlled by the python logging module.

By default the debug and warning output will be hidden, the user can choose to enable the output by adding this snippet in their calling script.

import logging

handler = logging.StreamHandler()
handler.setFormatter(logging.Formatter(
    "%(name)s - %(levelname)s - %(message)s"
))

logger = logging.getLogger("molsympy")
logger.setLevel(logging.DEBUG)
logger.addHandler(handler)
logger.propagate = False

Core Data Structures

PointGroup

Schoenflies point group descriptor.

Parses and validates a point group string into its family, order, and subfamily.

Source code in molsympy/core/point_group.py

def __init__(self, s, family, n, subfamily):
    self.str = s
    self.family = family
    self.n = n
    if self.n == 0:
        self.is_linear = True
    else:
        self.is_linear = False
    self.subfamily = subfamily
    self.dumb_pg()

SymmetryResult

Container for a found symmetry result.

Attributes:

mol (Atoms) –

Symmetrized molecule.
pg (str) –

Schoenflies symbol of the point group.
rmsd (float) –

RMSD between the original and symmetrized structure.

PointGroupResult

Return value of find_point_group().

Attributes:

pg (str) –

Schoenflies point-group symbol (e.g. "C2v", "D3h", "Oh").
paxis ((ndarray, shape(3))) –

Principal symmetry axis in the original molecule frame. Zero vector when not applicable (e.g. C1).
saxis ((ndarray, shape(3))) –

Secondary axis defining the canonical orientation. Zero vector when not applicable.

Symel

Symmetry element (SymEl): Symmetry operation with its symbol, representative axis, matrix representation and metadata.

Parameters:

symbol (str) –

Schoenflies symbol of the symmetry element (e.g. "C_3", "sigma_h", "i").
vector (ndarray | None) –

Axis vector for Cn and Sn; plane normal vector for sigma; None for E and i.
rrep (ndarray) –

3x3 real-space matrix representation of the operation.
m (int | None, default: None ) –

Power of the generator (e.g. m=2 for C_3^2).
n (int | None, default: None ) –

Order of the principal axis of the generating cycle.
O (str | None, default: None ) –

Origin class of the element. Options: "E", "sigma_v", "C_2'", "i", "sigma_h".

Symtext

Full symmetry characterization of a molecule.

Holds the point group, list of symmetry elements, atom permutation map, and the rotation matrices that relate the molecule to the canonical orientation defined by the symmetry elements.

Source code in molsympy/core/symtext.py

def __init__(self, mol, rotate_to_std, reverse_rotate, pg, symels, atom_map):
    self.mol = mol
    self.rotate_to_std = rotate_to_std
    self.reverse_rotate = reverse_rotate
    self.pg = pg
    self.symels = symels
    self.atom_map = atom_map
    if pg.is_linear:
        # Linear groups have infinitely many symmetry elements; the finite
        # atom_map covers only the operations that actually permute atoms.
        self.order = atom_map.shape[1]
    else:
        self.order = len(symels)

SEA (Symmetry Equivalent Atoms)

Symmetry equivalent atoms (SEA).

SEAs are atoms that can be swapped with no distinguishable change in the molecule.

Parameters:

label (str or None) –

Rotor type of the SEA set (e.g. Single Atom, Linear, Spherical, Regular Polygon, Oblate Symmetric Top).
subset (ndarray) –

Atom indices in the molecule that belong to this SEA set, shape (N,).
axis (ndarray or None) –

Candidate rotational symmetry axis, shape (3,).

Output metadata

MolSymPy stores symmetry information in the Atoms.info dictionary of the returned Atoms object.

Key	Description
`"pg"`	detected point group
`"geom_tol"`	positional tolerance
`"eigen_tol"`	eigenvalues relative tolerance

Canonical Orientation

After any symmetrization process the package will return the molecule in a canonical orientation. The orientation is dictated by the alignement of the primary and secondary axes. The primary axis will be aligned with the z+ axis and the secondary axis will be aligned with the x+ axis.

The positioning of the primary and secondary axis is dependent on the rotational axes of the molecule as shown in the following table.

Point group	Primary axis	Secondary axis
C1, Ci	None	None
Cs	Normal vector to the plane of symmetry	None
Cn, Cnh	n-fold rotation axis	None
Cnv	n-fold rotation axis	Coplanar to a σˆv symmetry plane
S2n	n-fold rotation axis	None
Dn, Dnd, Dnh	n-fold rotation axis	Cˆ2 orthogonal to n-fold rotation axis
C∞v, D∞h	Molecular axis	None
T, Th, Td	One of the Cˆ2 axes	Another Cˆ2 axis
O, Oh	One of the Cˆ4 axes	Another Cˆ4 axis
I, Ih	One of the Cˆ5 axes	Cˆ2 axis

In the case there is no secondary axis one will be generated. The axis will be defined by an arbitrary direction orthogonal to the primary axis.

In the case there are no primary or secondary axes the orientation of the molecule will not be canonicalized and remain unchanged.

See the API reference for full documentation.