Skip to content

qsym2

Classes

PyMolecule

Python
PyMolecule(
    atoms: Sequence[tuple[str, tuple[float, float, float]]],
    threshold: float,
    magnetic_field: tuple[float, float, float] | None = None,
    electric_field: tuple[float, float, float] | None = None,
)

Python-exposed structure to marshall molecular structure information between Rust and Python.

Parameters:

Attributes

atoms instance-attribute
Python
atoms: list[tuple[str, tuple[float, float, float]]]

The ordinary atoms in the molecule.

threshold instance-attribute
Python
threshold: float

Threshold for comparing molecules.

magnetic_field instance-attribute
Python
magnetic_field: tuple[float, float, float] | None

The uniform external magnetic field, if any.

electric_field instance-attribute
Python
electric_field: tuple[float, float, float] | None

The uniform external electric field, if any.

Functions

PySymmetry

Python-exposed structure to marshall symmetry information one-way from Rust to Python.

Attributes

group_name instance-attribute
Python
group_name: str

The name of the symmetry group.

Functions

is_infinite
Python
is_infinite() -> bool

Returns a boolean indicating if the group is infinite.

get_elements_of_kind
Python
get_elements_of_kind(
    kind: PySymmetryElementKind,
) -> dict[int, list[Py1DArray_f64]]

Returns symmetry elements of all finite orders of a given kind.

Parameters:

  • kind
    (PySymmetryElementKind) –

    The symmetry element kind.

Returns:

  • dict[int, list[Py1DArray_f64]] –

    A dictionary where the keys are integers indicating the orders of the elements and the values are vectors of one-dimensional arrays, each of which gives the axis of a symmetry element. If the order value is -1, then the associated elements have infinite order.

get_generators_of_kind
Python
get_generators_of_kind(
    kind: PySymmetryElementKind,
) -> dict[int, list[Py1DArray_f64]]

Returns symmetry generators of finite and infinite orders of a given kind.

Parameters:

  • kind
    (PySymmetryElementKind) –

    The symmetry generator kind.

Returns:

  • dict[int, list[Py1DArray_f64]] –

    A dictionary where the keys are integers indicating the orders of the generators and the values are vectors of one-dimensional arrays, each of which gives the axis of a symmetry generator. If the order value is -1, then the associated generators have infinite order.

Functions

detect_symmetry_group

Python
detect_symmetry_group(
    inp_xyz: str | None,
    inp_mol: PyMolecule | None,
    out_sym: str | None,
    moi_thresholds: Sequence[float],
    distance_thresholds: Sequence[float],
    time_reversal: bool,
    write_symmetry_elements: bool = True,
    fictitious_magnetic_field: tuple[float, float, float] | None = None,
    fictitious_electric_field: tuple[float, float, float] | None = None,
) -> tuple[PySymmetry, PySymmetry | None]

Python-exposed function to perform symmetry-group detection.

The result is also logged via the qsym2-output logger at the INFO level.

Parameters:

  • inp_xyz

    (str | None) –

    An optional string providing the path to an XYZ file containing the molecule to be analysed. Only one of inp_xyz or inp_mol can be specified.

  • inp_mol

    (PyMolecule | None) –

    An optional PyMolecule structure containing the molecule to be analysed. Only one of inp_xyz or inp_mol can be specified.

  • out_sym

    (str | None) –

    An optional name for the QSym2FileType::Sym file to be saved that contains the serialised results of the symmetry-group detection.

  • moi_thresholds

    (Sequence[float]) –

    Thresholds for comparing moments of inertia.

  • distance_thresholds

    (Sequence[float]) –

    Thresholds for comparing distances.

  • time_reversal

    (bool) –

    A boolean indicating whether elements involving time reversal should also be considered.

  • write_symmetry_elements

    (bool, default: True ) –

    A boolean indicating if detected symmetry elements should be printed in the output.

  • fictitious_magnetic_field

    (tuple[float, float, float] | None, default: None ) –

    An optional fictitious uniform external magnetic field.

  • fictitious_electric_field

    (tuple[float, float, float] | None, default: None ) –

    An optional fictitious uniform external electric field.

Returns:

  • tuple[PySymmetry, PySymmetry | None] –

    A tuple of a PySymmetry for the unitary group and another optional PySymmetry for the magnetic group if requested.

Errors

Returns an error if any intermediate step in the symmetry-group detection procedure fails.