Skip to content

MolSymPy

PyPI Python License

MolSymPy is a Python package for molecular symmetry analysis in Atomic Simulation Environment (ASE) Atoms objects, including structure symmetrization. It provides fast, geometry-based symmetry detection and manipulation, designed to integrate seamlessly into existing ASE workflows.

Internally, MolSymPy constructs symmetry operations and atom mappings, then projects atomic positions onto symmetry elements to enforce exact symmetry.

Installation

pip install molsympy
See the Installation page for details.

Getting started

MolSymPy is a Python package that provides essential symmetry functionality for molecules represented as ASE Atoms objects.

Follow the steps below to quickly set up and use MolSymPy with ASE.

Install the necessary libraries

pip install molsympy

Symmetrize a molecule

from ase.build import molecule
from molsympy import symmetrize

## Create Atoms object.
mol = molecule("H2O")

## Symmetrize molecule.
mol_symmetric = symmetrize(mol)

## Check output
print(mol_symmetric.info["pg"])

For further examples and details on how to use MolSymPy, see the Usage and API pages.

Features

  • Geometric idealization — project nearly-symmetric structures onto their exact symmetry elements and orient the molecular frame by aligning principal and secondary symmetry axes with the Cartesian coordinate system.
  • Point group detection — identify molecular point groups in Schoenflies notation, including the two infinite-order linear groups (C∞v and D∞h).
  • Symmetry-inequivalent atoms — determine symmetry-inequivalent atoms using a path-compressed union-find algorithm operating on the complete symmetry permutation map.
  • Reference database — companion collection of molecular and atomic-cluster geometries spanning the principal point groups, available in both raw and idealized forms.
  • ASE Atoms-native workflow: Directly integrates with ASE Atoms objects, enabling smooth use in existing workflows.

Scope and limitations

  • Works on finite molecules (no periodic structure support)
  • Uses geometric tolerance-based symmetry detection
  • Results depend on the chosen geom_tol

Supported point groups

Point groups are classifications of molecules based on their symmetry operations. MolSymPy can detect the following common molecular point groups:

  • C1, Cs, Ci
  • Cn, Cnv, Cnh
  • Dn, Dnh, Dₙd
  • Sn
  • T, Th, Td
  • O, Oh
  • I, Ih
  • C∞v, D∞h

Detection depends on the symmetry present in the input geometry and the tolerance used during symmetry detection.

API Overview

  • symmetrize(mol, geom_tol=...) -> Atoms
  • get_point_group(mol, geom_tol=...) -> str
  • is_planar(mol, geom_tol=...) -> bool
  • get_inequivalent(mol, geom_tol=...) -> (unique, parent)
  • generate_symmetry_candidates(mol, geom_tol=...) → list[SymmetryResult]

See the full API Reference.

Acknowledgments

This package is based on and inspired by NASymmetry / MolSym, modified to focus on core symmetry functionality.

License

Distributed under the MIT License. See LICENSE for details.

Contributing

If you find MolSymPy useful or have suggestions for improvement, please feel free to open an issue or pull request on GitHub.

If you use MolSymPy in your research, please cite the associated manuscript.