Skip to content

qsym2

Functions

symmetrise_molecule

Python
symmetrise_molecule(
    inp_xyz: str | None,
    inp_mol: PyMolecule | None,
    out_target_sym: str | None = None,
    loose_moi_threshold: float = 0.01,
    loose_distance_threshold: float = 0.01,
    target_moi_threshold: float = 1e-07,
    target_distance_threshold: float = 1e-07,
    use_magnetic_group: bool = False,
    reorientate_molecule: bool = True,
    max_iterations: int = 50,
    consistent_target_symmetry_iterations: int = 10,
    verbose: int = 0,
    infinite_order_to_finite: int | None = None,
) -> PyMolecule

Python-exposed function to perform molecule symmetrisation by bootstrapping.

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 symmetrised. Only one of inp_xyz or inp_mol can be specified.

  • inp_mol

    (PyMolecule | None) –

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

  • out_target_sym

    (str | None, default: None ) –

    An optional path for a QSym2FileType::Sym file to be saved that contains the symmetry-group detection results of the symmetrised molecule at the target thresholds.

  • loose_moi_threshold

    (float, default: 0.01 ) –

    The loose MoI threshold.

  • loose_distance_threshold

    (float, default: 0.01 ) –

    The loose distance threshold.

  • target_moi_threshold

    (float, default: 1e-07 ) –

    The target (tight) MoI threshold.

  • target_distance_threshold

    (float, default: 1e-07 ) –

    The target (tight) distance threshold.

  • use_magnetic_group

    (bool, default: False ) –

    A boolean indicating if the magnetic group (i.e. the group including time-reversed operations) is to be used for the symmetrisation.

  • reorientate_molecule

    (bool, default: True ) –

    A boolean indicating if the molecule is also reoriented to align its principal axes with the Cartesian axes.

  • max_iterations

    (int, default: 50 ) –

    The maximum number of iterations for the symmetrisation process.

  • consistent_target_symmetry_iterations

    (int, default: 10 ) –

    The number of consecutive iterations during which the symmetry group at the target level of threshold must be consistently found for convergence to be reached, if this group cannot become identical to the symmetry group at the loose level of threshold.

  • verbose

    (int, default: 0 ) –

    The print-out level.

  • infinite_order_to_finite

    (int | None, default: None ) –

    The finite order with which infinite-order generators are to be interpreted to form a finite subgroup of the prevailing infinite group. This finite subgroup will be used for the symmetrisation.

Returns:

Errors

Errors if any intermediate step in the symmetrisation procedure fails.