Concepts and Conventions

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

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 global variable PRINT_WARNINGS.

The user can control this behavior with the optional parameter quiet in the aforementioned functions. When quiet is set to True, PRINT_WARNINGS is set to False, disabling all warnings and debug output.

Core Data Structures

PointGroup

Schoenflies point group descriptor.

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

Source code in minimalsym/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 minimalsym/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 (array) –

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

Candidate rotational symmetry axis, shape (3,).

Output metadata

MinimalSym 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

See the API reference for full documentation.