Database Helpers (Internal)

These functions support the database API by handling database generation from .npz files.

---

Overview

The database helper layer is responsible for:

• Generating the database from .npz files to ASE Atoms
• Getting the correct structure by its molecular formula or point group key

---

Notes

• These functions are internal to the database layer and not intended for direct use

---

collections

MolSymPy reference-structure collections.

Usage

from molsympy.collections import symmetrized, unsymmetrized

# idealized / symmetrized structures
for name in symmetrized.names:
    atoms = symmetrized[name]

# raw / unsymmetrized structures
atoms = unsymmetrized['C2v_1']
print(unsymmetrized.point_groups)

MolSymPyCollection

MolSymPyCollection(db, is_symmetrized: bool = False)

Collection of molecular reference structures indexed by point group.

Keys have the form '{PointGroup}_{index}' (e.g. 'C2v_1', 'Td_3', 'Ih_1').

Attributes:

• symmetrized (bool) –

  True if this collection contains idealized/symmetrized structures.

• names (list[str]) –

  Sorted list of all available keys.

• point_groups (list[str]) –

  Sorted list of unique Schoenflies symbols in the collection.

Examples:

from molsympy.collections import symmetrized, unsymmetrized

for name in symmetrized.names:
    atoms = symmetrized[name]

atoms = unsymmetrized['C2v_1']

Used by:

• API Public API High-level database API  collections
  •  symmetrized
  •  unsymmetrized

Source code in molsympy/collections/__init__.py

def __init__(self, db, is_symmetrized: bool = False):
    self._db = db
    self.symmetrized = is_symmetrized
    self._formula_to_key: dict[str, str] = {}
    for k in db.files:
        try:
            f = db[k].item().get("formula", "")
            if f:
                self._formula_to_key[str(f).strip()] = k
        except Exception:
            pass

names property

names: list[str]

Sorted list of all keys in the collection.

point_groups property

point_groups: list[str]

Sorted list of unique Schoenflies symbols.

formulas property

formulas: list[str]

Sorted list of molecular formulas available in the collection.

__getitem__

__getitem__(key: str) -> Atoms

Return the structure for key as an ASE Atoms object.

Parameters:

• key (str) –

  Database key of the form '{PointGroup}_{index}', e.g. 'C2v_1'.

Returns:

• Atoms –

  Atoms object with atoms.info populated: 'point_group', 'index', 'energy', 'dataset'.

Raises:

• KeyError –

  If key is not in the collection.

Source code in molsympy/collections/__init__.py

def __getitem__(self, key: str) -> Atoms:
    """Return the structure for *key* as an ASE Atoms object.

    Parameters
    ----------
    key : str
        Database key of the form ``'{PointGroup}_{index}'``,
        e.g. ``'C2v_1'``.

    Returns
    -------
    ase.Atoms
        Atoms object with ``atoms.info`` populated:
        ``'point_group'``, ``'index'``, ``'energy'``, ``'dataset'``.

    Raises
    ------
    KeyError
        If *key* is not in the collection.
    """
    if key not in self._db:
        # Try resolving as a molecular formula (e.g. 'CNH' → 'C0v_1')
        if key in self._formula_to_key:
            key = self._formula_to_key[key]
        else:
            pg = key.rsplit("_", 1)[0] if "_" in key else key
            available = [k for k in self._db.files if k.rsplit("_", 1)[0] == pg]
            hint = (
                f"Available for '{pg}': {sorted(available)}"
                if available
                else f"Known point groups: {self.point_groups}"
            )
            raise KeyError(f"'{key}' not in collection. {hint}")

    data = self._db[key].item()
    atoms = Atoms(symbols=list(data["elements"]), positions=data["positions"])
    atoms.info["point_group"] = data["point_group"]
    atoms.info["index"]       = data["index"]
    atoms.info["energy"]      = data["energy"]
    atoms.info["dataset"]     = data["dataset"]
    return atoms

get

get(key: str, symbol: str | None = None) -> Atoms

Like __getitem__ but optionally override all chemical symbols.

Parameters:

• key (str) –

  Database key (e.g. 'Td_1').

• symbol (str or None, default: None ) –

  If given, replace every element with this symbol (e.g. 'Mo').

Returns:

• Atoms –

Source code in molsympy/collections/__init__.py

def get(self, key: str, symbol: str | None = None) -> Atoms:
    """Like ``__getitem__`` but optionally override all chemical symbols.

    Parameters
    ----------
    key : str
        Database key (e.g. ``'Td_1'``).
    symbol : str or None
        If given, replace every element with this symbol (e.g. ``'Mo'``).

    Returns
    -------
    ase.Atoms
    """
    atoms = self[key]
    if symbol is not None:
        atoms.symbols = [symbol] * len(atoms)
    return atoms