Molecule symmetrisation¶

Overview¶

Symmetrisation by 'bootstrapping'¶

QSym² offers a 'bootstrapping' algorithm to symmetrise molecular systems. This algorithm symmetrises a molecule iteratively by defining two threshold levels: a loose level and a target level. In every iteration, the following steps are performed:

The molecule is symmetry-analysed at the target level; any symmetry elements found are stashed and the symmetry group name, if any, is registered.
The molecule is symmetry-analysed at the loose level; any symmetry elements found are added to the stash and the symmetry group name, if any, is registered.
The convergence criteria (see below) are checked.
- If convergence has been reached, the symmetrisation procedure is terminated.
- If convergence has not been reached, the following steps are carried out.
All symmetry elements found in the stash are used to generate all possible symmetry operations which are then used to symmetrise the molecule: each symmetry operation is applied on the original molecule to produce a symmetry-equivalent copy, then all symmetry-equivalent copies are averaged to give the symmetrised molecule.
Repeat steps 1 to 4 above until convergence is reached.

Convergence criteria¶

There are two convergence criteria for the symmetrisation procedure:

either when the loose-threshold symmetry agrees with the target-threshold symmetry,
or when the target-threshold symmetry contains more elements than the loose-threshold symmetry and has been consistently identified for a pre-specified number of consecutive iterations.

At least one criterion must be satisfied in order for convergence to be reached.

Thresholds¶

As described in Symmetry-group detection/#Thresholds, for each threshold level, two values are required: one for the comparisons between moments of inertia, and one for the comparisons of atomic coordinates and normalised vector components. The choice of these thresholds affects the way the molecular system is symmetrised: the loose thresholds more or less determine the symmetry to which the system is symmetrised, and the target thresholds determine how well, or how tightly, the system is symmetrised.

External fields¶

If external fields are present, they are also symmetrised together with the molecule, as the fictitious special atoms representing these fields are included in the symmetrisation protocol described above. However, the magnitudes of these fields are not preserved during the symmetrisation for two reasons:

when fictitious special atoms are constructed, their positions do not quite reflect field magnitudes but are rather chosen to ensure numerical stability in symmetry-group detection, and
during the symmetrisation, all interatomic quantities such as bond lengths and bond angles are bound to vary so that the system can attain higher symmetry.

If the original field magnitudes are desired, it is trivial to use the positions of the fictitious special atoms after symmetrisation to reconstruct the external fields with the appropriate magnitudes.

Parameters¶

Feature requirements

Using the Python API requires the python feature.

The input parameters and their descriptions for each mode of running molecule symmetrisation in QSym² are given below. When an input parameter has a default value, the default value will be specified.

Command-line interfacePython

YAML

symmetry_group_detection: !Parameters #(1)!
  ...

analysis_targets:
- !MolecularSymmetry #(2)!
  xyz: /path/to/xyz/file #(3)!
  symmetrisation: #(4)!
    reorientate_molecule: true #(5)!
    loose_moi_threshold: 0.01 #(6)!
    loose_distance_threshold: 0.01 #(7)!
    target_moi_threshold: 1e-7 #(8)!
    target_distance_threshold: 1e-7 #(9)!
    max_iterations: 50 #(10)!
    consistent_target_symmetry_iterations: 10 #(11)!
    infinite_order_to_finite: null #(12)!
    use_magnetic_group: false #(13)!
    verbose: 0 #(14)!
    symmetrised_result_xyz: null #(15)!
    symmetrised_result_save_name: null #(16)!

This specifies the parameters for symmetry-group detection. These are required and will be used to perform a symmetry-group detection calculation on the symmetrised system. See the documentation for symmetry-group detection for more details.
Under the hood, the specification of molecule symmetrisation in a YAML configuration file is handled by the MolecularSymmetry variant of the AnalysisTarget enum. This is so that a symmetry-group detection calculation can be performed on the symmetrised system.
This specifies a path to an XYZ file containing the input molecular structure for symmetrisation.
This key is optional: if it is omitted, no symmetrisation will be performed on the input molecular structure and only symmetry-group detection will be run (see symmetry-group detection for an illustration of this).

Under the hood, this wraps around the MoleculeSymmetrisationBootstrapParams struct.
This boolean indicates if the molecule is reoriented to align its principal axes with the space-fixed Cartesian axes at every iteration in the symmetrisation.

Default: true.
This float specifies the loose moment-of-inertia threshold for the symmetrisation. The symmetry elements found at this threshold level will be used to bootstrap the symmetry of the molecule.

Default: 1e-2.
This float specifies the loose distance threshold for the symmetrisation. The symmetry elements found at this threshold level will be used to bootstrap the symmetry of the molecule.

Default: 1e-2.
This float specifies the target moment-of-inertia threshold for the symmetrisation.

Default: 1e-7.
This float specifies the target distance threshold for the symmetrisation.

Default: 1e-7.
This integer specifies the maximum number of symmetrisation iterations.

Default: 50.
This integer specifies 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.

Default: 10.
This optional integer specifies the finite order to which any infinite-order symmetry element is reduced, so that a finite number of symmetry operations can be used for the symmetrisation.

Default: null.
This boolean indicates if any available magnetic group should be used for symmetrisation instead of the unitary group, i.e. if time-reversed operations, if any, should also be considered.

Default: false.
This integer sppecifies the output verbosity level.

Default: 0.
This specifies an optional name (without the .xyz extension) for writing the symmetrised molecule to an XYZ file. If null, no XYZ files will be written.

Default: null.
This specifies an optional name (without the .qsym2.sym extension) for saving the symmetry-group detection verification result of the symmetrised system as a binary file of type [QSym2FileType::Sym]. If null, the result will not be saved. Note that this is different from the result_save_name key of the symmetry_group_detection section.

Default: null.

Python

from qsym2 import symmetrise_molecule, PyMolecule

pymol = PyMolecule( #(1)!
    atoms=[ #(2)!
        ("V", [+0.0, +0.0, +0.0]),
        ("F", [+1.0, +0.0, +0.0]),
        ("F", [-1.0, +0.0, +0.0]),
        ("F", [+0.0, +1.0, +0.0]),
        ("F", [+0.0, -1.0, +0.0]),
        ("F", [+0.0, +0.0, +1.1]),
        ("F", [+0.0, +0.0, -1.0]),
    ],
    threshold=1e-7, #(3)!
    magnetic_field=[0.0, 0.1, 0.0], #(4)!
    electric_field=None, #(5)!
)

symmol = symmetrise_molecule( #(6)!
    inp_xyz=None, #(7)!
    inp_mol=pymol, #(8)!
    out_target_sym=None, #(9)!
    loose_moi_threshold=1e-1, #(10)!
    loose_distance_threshold=1.5e-1, #(11)!
    target_moi_threshold=1e-8, #(12)!
    target_distance_threshold=1e-8, #(13)!
    use_magnetic_group=False, #(14)!
    reorientate_molecule=True, #(15)!
    max_iterations=50, #(16)!
    consistent_target_symmetry_iterations=10, #(17)!
    verbose=2, #(18)!
) #(19)!

This specifies the molecular system for symmetrisation. The PyMolecule class, constructible in Python, contains geometry information that can be interpreted by QSym² on the Rust side. The API documentation for this class can be consulted for further information.
The coordinates of the atoms specified in this list can be in any units. QSym² does not care what the actual units are — symmetry properties are invariant to any change in length scale. The only exception is when QSym² evaluates molecular integrals: here, atomic units will be assumed.
This specifies the threshold for comparing molecules. Note that this threshold is not the same as those specified in symmetrise_molecule below.
This list gives the components of an optional uniform external magnetic field that is present in the system. When external fields are present, they are also included in the symmetrisation process.

Default: None.
This list gives the components of an optional uniform external electric field that is present in the system. When external fields are present, they are also included in the symmetrisation process.

Default: None.
The symmetrise_molecule function performs molecule symmetrisation by bootstrapping and logs the result via the qsym2-output logger at the INFO level. The API documentation for this function can be consulted for further information.
This specifies a path to an XYZ file containing the geometry of the molecule for symmetrisation. One and only one of inp_xyz or inp_mol must be specified, and the other must be None.
This specifies a PyMolecule object containing the molecular system for symmetrisation. One and only one of inp_xyz or inp_mol must be specified, and the other must be None.
This specifies an optional name for the .qsym2.sym file to be saved that contains the serialised results of the verification symmetry-group detection of the symmetrised molecule at the target thresholds. This name does not need to contain the .qsym2.sym extension.

Default: None.
This float specifies the loose moment-of-inertia threshold for the symmetrisation. The symmetry elements found at this threshold level will be used to bootstrap the symmetry of the molecule.

Default: 1e-2.
This float specifies the loose distance threshold for the symmetrisation. The symmetry elements found at this threshold level will be used to bootstrap the symmetry of the molecule.

Default: 1e-2.
This float specifies the target moment-of-inertia threshold for the symmetrisation.

Default: 1e-7.
This float specifies the target distance threshold for the symmetrisation.

Default: 1e-7.
This boolean indicates if any available magnetic group should be used for symmetrisation instead of the unitary group, i.e. if time-reversed operations, if any, should also be considered.

Default: False.
This boolean indicates if the molecule is reoriented to align its principal axes with the space-fixed Cartesian axes at every iteration in the symmetrisation.

Default: True.
This integer specifies the maximum number of symmetrisation iterations.

Default: 50.
This integer specifies 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.

Default: 10.
This integer sppecifies the output verbosity level.

Default: 0.
The symmetrise_molecule function returns a PyMolecule obect containing the symmetrised molecular system.