Vibrational coordinates

Let \(\mathbfit{Q}_i\) be the \(i\)-th vibrational mode of a molecule consisting of \(N_{\mathrm{n}}\) nuclei. The vector \(\mathbfit{Q}_i\) contains \(3N_{\mathrm{n}}\) elements:

\[ \mathbfit{Q}_i = \begin{pmatrix} Q_i^{1x}\\ Q_i^{1y}\\ Q_i^{1z}\\ Q_i^{2x}\\ Q_i^{2y}\\ Q_i^{2z}\\ \vdots \end{pmatrix}, \]

where \(Q_i^{A\alpha}\) gives the \(\alpha\) Cartesian component of the vibrational coordinates on nucleus \(A\). The components of \(\mathbfit{Q}_i\) may or may not be mass-weighted — this does not affect the ability of QSym² to characterise its symmetry.

Requirements

Basis overlap matrix

The vibrational modes \(\mathbfit{Q}_i\) are implicitly described with respect to a basis consisting of \((\mathbfit{i}_A, \mathbfit{j}_A, \mathbfit{k}_A)\) triads centred on the nuclei \(A\) in the molecule, where the unit vectors \(\mathbfit{i}_A\), \(\mathbfit{j}_A\), and \(\mathbfit{k}_A\) are parallel to the space-fixed \(x\)-, \(y\)-, and \(z\)-axes, respectively. The overlap matrix \(\mathbfit{S}\) in this basis is simply the identity matrix \(\mathbfit{I}_{3N_{\mathrm{n}}}\) since the basis vectors are orthonormal and/or non-overlapping. Therefore, no additional basis overlap matrices are required to be supplied to QSym² for symmetry analysis.

Atomic-orbital basis angular order

As the basis in which the vibrational modes \(\mathbfit{Q}_i\) are defined does not contain atomic orbitals, no basis angular order information is required.

Parameters

Feature requirements

• Reading in Q-Chem HDF5 archive files requires the qchem feature.
• Using the Python API requires the python feature.

At the moment, QSym² offers two main ways to perform symmetry analysis for vibrational modes. They are:

• via the command-line interface reading in data from a Q-Chem HDF5 archive file,
• via the Python library API reading in data from Python data structures.

More methods might become possible in the future. The parameter specifications for the two existing methods are shown below.

Command-line interfacePython

Source: Q-Chem HDF5 archive

YAML

analysis_targets:
  - !VibrationalCoordinates #(1)!
    source: !QChemArchive #(2)!
      path: path/to/qchem/qarchive.h5 #(3)!
    control: #(4)!
      # Thresholds
      integrality_threshold: 1e-7 #(5)!
      linear_independence_threshold: 1e-7 #(6)!
      eigenvalue_comparison_mode: Modulus #(7)!
      # Analysis options
      use_magnetic_group: null #(8)!
      use_double_group: false #(9)!
      use_cayley_table: true #(10)!
      symmetry_transformation_kind: Spatial #(11)!
      infinite_order_to_finite: null #(12)!
      # Other options
      write_character_table: Symbolic #(13)!

1. This specifies a vibrational coordinate collection analysis target.
2. This specifies that the collection of vibrational coordinates to be analysed shall be retrieved from a Q-Chem HDF5 archive file. This file can be generated by running a frequency analysis job in Q-Chem 5.4 or later with the -save option and located in the job scratch directory.
3. This specifies the path to the Q-Chem HDF5 archive file to be analysed.
4. This YAML dictionary contains all control parameters for the symmetry analysis of vibrational coordinates.
5. This specifies a floating-point value for the linear independence threshold \(\lambda^{\mathrm{thresh}}_{\mathbfit{S}}\). For more information, see Basics/#Thresholds.
   
   Default: 1e-7.
6. This specifies a floating-point value for the integrality threshold \(\lambda^{\mathrm{thresh}}_{\mathrm{int}}\). For more information, see Basics/#Thresholds.
   
   Default: 1e-7.
7. This specifies the threshold comparison mode for the eigenvalues of the orbit overlap matrix \(\mathbfit{S}\). The possible options are:
   • Real: this specifies the real comparison mode where the real parts of the eigenvalues are compared against the threshold,
   • Modulus: this specifies the modulus comparison mode where the absolute values of the eigenvalues are compared against the threshold.
   For more information, see Basics/#Thresholds.
   
   Default: Modulus.
8. This specifies whether magnetic groups, if present, shall be used for symmetry analysis. The possible options are:
   • null: this specifies choice 1 of Basics/Analysis options/#Magnetic groups — use the irreducible representations of the unitary group \(\mathcal{G}\),
   • Representation: this specifies choice 2 of Basics/Analysis options/#Magnetic groups — use the irreducible representations of the magnetic group \(\mathcal{M}\), if \(\mathcal{M}\) is available,
   • Corepresentation: this specifies choice 3 of Basics/Analysis options/#Magnetic groups — use the irreducible corepresentations of the magnetic group \(\mathcal{M}\), if \(\mathcal{M}\) is available.
   For more information, see Basics/Analysis options/#Magnetic groups.
   
   Default: null.
9. This is a boolean specifying if double groups shall be used for symmetry analysis. The possible options are:
   • false: use only conventional irreducible representations or corepresentations of \(\mathcal{G}\),
   • true: use projective irreducible representations or corepresentations of \(\mathcal{G}\) obtainable via its double cover \(\mathcal{G}^*\).
   For more information, see Basics/Analysis options/#Double groups.
   
   Default: false.
10. This is a boolean specifying if the Cayley table for the group, if available, should be used to speed up the computation of orbit overlap matrices.
    
    Default: true.
11. This specifies the kind of symmetry transformations to be applied to generate the orbit for symmetry analysis. The possible options are:
    • Spatial: spatial transformation only,
    • SpatialWithSpinTimeReversal: spatial transformation with spin-including time reversal,
    • Spin: spin transformation only,
    • SpinSpatial: coupled spin and spatial transformations.
    For more information, see Basics/Analysis options/#Transformation kinds.
    
    However, as vibrational coordinates are spinless quantities, spin transformations have no effects.
    
    Default: Spatial.
12. This specifies the finite order \(n\) to which all infinite-order symmetry elements, if any, are restricted. The possible options are:
    • null: do not restrict infinite-order symmetry elements to finite order,
    • a positive integer value: restrict all infinite-order symmetry elements to this finite order (this will be ignored if the system has no infinite-order symmetry elements).
    For more information, see Basics/Analysis options/#Infinite-order symmetry elements.
    
    Default: null.
13. This indicates if the character table of the prevailing symmetry group is to be printed in the output. The possible options are:
    • null: do not print character tables,
    • Symbolic: print character tables symbolically,
    • Numerical: print character tables numerically.
    
    Default: Symbolic.

Python

from qsym2 import (
    rep_analyse_vibrational_coordinate_collection,
    EigenvalueComparisonMode, #(1)!
    MagneticSymmetryAnalysisKind, #(2)!
    SymmetryTransformationKind, #(3)!
    PyVibrationalCoordinateCollectionReal,
    PyVibrationalCoordinateCollectionComplex,
)

coefficients = np.array([ #(4)!
    [+1.000, +0.000],
    [+0.000, +0.707],
    [+0.000, +0.707],
    [+1.000, +0.000],
    [+0.000, +0.707],
    [+0.000, +0.707],
    ...
])

frequencies = np.array([1700.00, 2200.00]) #(5)!

pyvibs = PyVibrationalCoordinateCollectionReal( #(6)!
    coefficients=coefficients,
    frequencies=frequencies,
    threshold=1e-7, #(7)!
)

rep_analyse_vibrational_coordinate_collection( #(8)!
    # Data
    inp_sym="mol", #(9)!
    pyvibs=pyvibs, #(10)!
    # Thresholds
    linear_independence_threshold=1e-7, #(11)!
    integrality_threshold=1e-7, #(12)!
    eigenvalue_comparison_mode=EigenvalueComparisonMode.Modulus, #(13)!
    # Analysis options
    use_magnetic_group=None, #(14)!
    use_double_group=False, #(15)!
    use_cayley_table=True, #(16)!
    symmetry_transformation_kind=SymmetryTransformationKind.Spatial, #(17)!
    infinite_order_to_finite=None, #(18)!
    # Other options
    write_character_table=True, #(19)!
)

1. This is a Python-exposed Rust enum, EigenvalueComparisonMode, for indicating the mode of eigenvalue comparison. See Basics/Thresholds/Linear independence threshold/#Comparison mode for further information.
2. This is a Python-exposed Rust enum, MagneticSymmetryAnalysisKind, for indicating the type of magnetic symmetry to be used for symmetry analysis. See Basics/Analysis options/#Magnetic groups for further information.
3. This is a Python-exposed Rust enum, SymmetryTransformationKind, for indicating the kind of symmetry transformation to be applied on the target. See Basics/Analysis options/#Transformation kinds for further information.
4. This specifies a coefficient matrix for the vibrational coordinates, which is a \(3N_{\mathrm{n}} \times N_{\mathrm{modes}}\) numpy array. The number of columns, \(N_{\mathrm{modes}}\), is the number of vibrational modes to be analysed. In other words, the \(i\)-th column if this matrix contains the vector \(\mathbfit{Q}_i\) described above.
5. This specifies the corresponding frequency vector, which is a one-dimensional numpy array of size \(N_{\mathrm{modes}}\). Each value in this array gives the frequency for the corresponding vibrational mode.
6. PyVibrationalCoordinateCollectionReal constructs a real-valued object containing multiple vibrational modes. If complex-valued vibrational modes are required instead, use PyVibrationalCoordinateCollectionComplex.
7. This specifies a threshold for comparing vibrational modes. This is of no consequence for symmetry analysis.
8. This is the Python driver function for representation analysis of multiple vibrational modes.
   
   This is a Python-exposed Rust function, rep_analyse_vibrational_coordinate_collection. See the API documentation of this function for more details.
9. This specifies the path to the .qsym2.sym file that contains the serialised results of the symmetry-group detection (see the documentation for the out_sym parameter of the Python detect_symmetry_group function in Symmetry-group detection/#Parameters). This file should have been generated by the detect_symmetry_group function on the underlying molecular system prior to representation analysis.
   
   This name does not need to contain the .qsym2.sym extension.
   
   The symmetry results in this file will be used to construct the symmetry group \(\mathcal{G}\) to be used in the subsequent representation analysis.
10. This specifies the vibrational coordinate collection to be symmetry-analysed.
11. This specifies a floating-point value for the linear independence threshold \(\lambda^{\mathrm{thresh}}_{\mathbfit{S}}\). For more information, see Basics/#Thresholds.
12. This specifies a floating-point value for the integrality threshold \(\lambda^{\mathrm{thresh}}_{\mathrm{int}}\). For more information, see Basics/#Thresholds.
13. This specifies the threshold comparison mode for the eigenvalues of the orbit overlap matrix \(\mathbfit{S}\). The possible options are:
    • EigenvalueComparisonMode.Real: this specifies the real comparison mode where the real parts of the eigenvalues are compared against the threshold,
    • EigenvalueComparisonMode.Modulus: this specifies the modulus comparison mode where the absolute values of the eigenvalues are compared against the threshold.
    For more information, see Basics/#Thresholds.
14. This specifies whether magnetic groups, if present, shall be used for symmetry analysis. The possible options are:
    • None: this specifies choice 1 of Basics/Analysis options/#Magnetic groups — use the irreducible representations of the unitary group \(\mathcal{G}\),
    • MagneticSymmetryAnalysisKind.Representation: this specifies choice 2 of Basics/Analysis options/#Magnetic groups — use the irreducible representations of the magnetic group \(\mathcal{M}\), if \(\mathcal{M}\) is available,
    • MagneticSymmetryAnalysisKind.Corepresentation: this specifies choice 3 of Basics/Analysis options/#Magnetic groups — use the irreducible corepresentations of the magnetic group \(\mathcal{M}\), if \(\mathcal{M}\) is available.
    For more information, see Basics/Analysis options/#Magnetic groups.
15. This is a boolean specifying if double groups shall be used for symmetry analysis. The possible options are:
    • False: use only conventional irreducible representations or corepresentations of \(\mathcal{G}\),
    • True: use projective irreducible representations or corepresentations of \(\mathcal{G}\) obtainable via its double cover \(\mathcal{G}^*\).
    For more information, see Basics/Analysis options/#Double groups.
16. This is a boolean specifying if the Cayley table for the group, if available, should be used to speed up the computation of orbit overlap matrices.
    
    Default: True.
17. This specifies the kind of symmetry transformations to be applied to generate the orbit for symmetry analysis. The possible options are:
    • SymmetryTransformationKind.Spatial: spatial transformation only,
    • SymmetryTransformationKind.SpatialWithSpinTimeReversal: spatial transformation with spin-including time reversal,
    • SymmetryTransformationKind.Spin: spin transformation only,
    • SymmetryTransformationKind.SpinSpatial: coupled spin and spatial transformations.
    For more information, see Basics/Analysis options/#Transformation kinds.
    
    However, as vibrational coordinates are spinless quantities, spin transformations have no effects.
18. This specifies the finite order \(n\) to which all infinite-order symmetry elements, if any, are restricted. The possible options are:
    • None: do not restrict infinite-order symmetry elements to finite order,
    • a positive integer value: restrict all infinite-order symmetry elements to this finite order (this will be ignored if the system has no infinite-order symmetry elements).
    For more information, see Basics/Analysis options/#Infinite-order symmetry elements.
    
    Default: None.
19. This boolean indicates if the symbolic character table of the prevailing symmetry group is to be printed in the output.
    
    Default: True.