Slater determinants

Let \(\Psi_{\mathrm{SD}}\) be an \(N_{\mathrm{e}}\)-electron Slater determinant constructed from \(N_{\mathrm{e}}\) occupied spin-orbitals \(\chi_i(\mathbfit{x})\) written in terms of the composite spin-spatial coordinates \(\mathbfit{x}\):

\[ \Psi_{\mathrm{SD}} = \sqrt{N_{\mathrm{e}}!} \hat{\mathscr{A}} \left[ \prod_{i=1}^{N_{\mathrm{e}}} \chi_i(\mathbfit{x}_i) \right], \]

where \(\hat{\mathscr{A}}\) is the antisymmetriser in the symmetric group \(\operatorname{Sym}(N_{\mathrm{e}})\) acting on the electron labels. The Slater determinant \(\Psi_{\mathrm{SD}}\) exists in some subspace of the \(N_{\mathrm{e}}\)-electron Hilbert space \(\mathcal{H}_{N_{\mathrm{e}}}\) whilst the spin-orbitals \(\chi_i(\mathbfit{x})\) each belong to some subspace of the one-electron Hilbert space \(\mathcal{H}_{1}\). QSym² is able to provide symmetry assignments for both the Slater determinant \(\Psi_{\mathrm{SD}}\) and its constituting spin-orbitals \(\chi_i(\mathbfit{x})\). The mathematical details of this can be found in Section 2.4.2 of the QSym² paper.

Requirements

Basis overlap matrix

As explained in Basics/Requirements/#Basis overlap matrix, QSym² requires the overlap matrices of the bases chosen for (some subspaces of) \(\mathcal{H}_{N_{\mathrm{e}}}\) and \(\mathcal{H}_{1}\) in order to perform representation analysis on \(\Psi_{\mathrm{SD}}\) and \(\chi_i(\mathbfit{x})\), respectively. As it turns out, since \(\Psi_{\mathrm{SD}}\) is constructed from \(\chi_i(\mathbfit{x})\), QSym² only requires the overlap matrix for the basis functions on \(\mathcal{H}_{1}\) with respect to which the spin-orbitals \(\chi_i(\mathbfit{x})\) are defined. These basis functions are typically Gaussian atomic orbitals, and most, if not all, quantum-chemistry packages compute their overlaps as part of their inner working. It is therefore more convenient to retrieve the atomic-orbital overlap matrix \(\mathbfit{S}_{\mathcal{H}_{1}}\) (also written \(\mathbfit{S}_{\mathrm{AO}}\)) (and its complex-symmetric version, \(\bar{\mathbfit{S}}_{\mathrm{AO}}\), whenever necessary), from quantum-chemistry packages whenever possible. The ways in which \(\mathbfit{S}_{\mathrm{AO}}\) can be read in by QSym² will be described below.

\(\mathbfit{S}_{\mathrm{AO}}\) from Q-Chem HDF5 archives

Note that Q-Chem HDF5 archive files do store \(\mathbfit{S}_{\mathrm{AO}}\), but the ordering of the atomic-orbital basis functions used to define this matrix (lexicographic order for Cartesian functions) is inconsistent with that used to define the molecular orbital coefficients (Q-Chem order for Cartesian functions). Hence, QSym² recomputes this matrix from the basis set information also stored in HDF5 archive files to ensure that the basis function ordering is consistent.

Atomic-orbital basis angular order

As bases for \(\mathcal{H}_{1}\) almost invariably consist of Gaussian atomic orbitals, QSym² requires information about their angular momenta and ordering conventions as described in Basics/Requirements/#Atomic-orbital basis angular order. Whenever possible, QSym² will attempt to construct the basis angular order information from available data, but if this cannot be done, then the required information must be provided manually (see Basics/Requirements/#Atomic-orbital basis angular order for details).

Parameters

Feature requirements

• Reading in Q-Chem HDF5 archive files requires the qchem feature.
• Using the Python API requires the python feature.
• Performing representation analysis for Slater determinants, molecular orbitals, and electron densities that are retrieved from Q-Chem HDF5 archive files requires the integrals feature to recompute \(\mathbfit{S}_{\mathrm{AO}}\) (see #Basis overlap matrix).

At the moment, QSym² offers three main ways to perform symmetry analysis for Slater determinants. They are:

• via the command-line interface reading in data from a Q-Chem HDF5 archive file,
• via the command-line interface reading in data from binary files,
• 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 three existing methods are shown below.

Command-line interfacePython

Source: Q-Chem HDF5 archiveSource: binary files

YAML

analysis_targets:
  - !SlaterDeterminant #(1)!
    source: !QChemArchive #(2)!
      path: path/to/qchem/qarchive.h5 #(3)!
    control: #(4)!
      # Thresholds
      linear_independence_threshold: 1e-7 #(5)!
      integrality_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)!
      write_overlap_eigenvalues: true #(14)!
      analyse_mo_symmetries: true #(15)!
      analyse_mo_mirror_parities: false #(16)!
      analyse_density_symmetries: false #(17)!

1. This specifies a Slater determinant analysis target.
2. This specifies that the Slater determinant(s) to be analysed shall be retrieved from a Q-Chem HDF5 archive file. This file can be generated by running Q-Chem 5.4 or later with the -save option and located in the job scratch directory. This file may contain multiple Slater determinants such as those arising from multiple iterations of a geometry optimisation job, or from multiple jobs in a single Q-Chem run.
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 Slater determinants.
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.
    
    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.
14. This boolean indicates if the eigenspectrum of the overlap matrix for the Slater determinant orbit should be printed out.
    
    Default: true.
15. This boolean indicates if the constituting molecular orbitals (MOs) are also symmetry-analysed.
    
    Default: true.
16. This boolean indicates if MO mirror parities (i.e. parities w.r.t. any mirror planes present in the system) are to be analysed alongside MO symmetries.
    
    Default: false.
17. This boolean indicates if density symmetries are to be analysed alongside wavefunction symmetries. If analyse_mo_symmetries is set to true, then MO density symmetries are also analysed.
    
    Default: false.

YAML

analysis_targets:
  - !SlaterDeterminant #(1)!
    source: !Binaries #(2)!
      xyz: path/to/xyz #(3)!
      sao: path/to/2c/sao #(4)!
      sao_4c: null #(5)!
      coefficients: #(6)!
      - path/to/ca
      - path/to/cb
      occupations: #(7)!
      - path/to/occa
      - path/to/occb
      spin_constraint: !Unrestricted #(8)!
      - 2
      - false
      matrix_order: RowMajor #(9)!
      byte_order: LittleEndian #(10)!
      bao: #(11)!
        ...: ...
    control: #(12)!
      ...: ...

1. This specifies a Slater determinant analysis target.
2. This specifies that the Slater determinant to be analysed and related information shall be retrieved from respective binary files. These files can be generated from various sources, but must be modified to conform to a suitable format for reading in by QSym².
   
   Under the hood, the following parameters are handled by the Rust struct BinariesSlaterDeterminantSource.
3. This specifies the path to an XYZ file containing the geometry of the molecular system.
4. This specifies the path to a binary file containing the real-valued two-centre atomic-orbital spatial overlap matrix.
5. This specifies an optional path to a binary file containing the real-valued four-centre atomic-orbital spatial overlap matrix. This is only required for density symmetry analysis.
6. This list specifies the paths to binary files containing molecular-orbital coefficient matrices. Each item in the list specifies the coefficient matrix for one spin space. The number of spin spaces must match that specified in the spin_constraint key.
7. This list specifies the paths to binary files containing occupation numbers. Each item in the list specifies the occupation numbers of the molecular orbitals in one spin space. The number of spin spaces must match that specified in the spin_constraint key.
8. Under the hood, this is handled by the Rust enum SpinConstraint.
   
   This specifies the spin constraint applicable to the Slater determinant being analysed. The list of items that follows contains the associated values and is different for each spin constraint. The possible options are:
   • !Restricted: this specifies the restricted spin constraint where spatial molecular orbitals are identical across all spin spaces. This variant takes only one associated value:
     • nspins: this unsigned integer specifies the total number of spin spaces
   • !Unrestricted: this specifies the unrestricted spin constraint where spatial molecular orbitals can be different across different spin spaces. This variant takes two associated values:
     • nspins: this unsigned integer specifies the total number of spin spaces
     • increasingm: this boolean indicates whether the spin spaces are arranged in increasing-\(m_s\) order (note: the typical \((\alpha, \beta)\) spin spaces are arranged in decreasing-\(m_s\) order, and so this boolean should be set to false)
   • !Generalised: this specifies the generalised spin constraint where each spin-orbital is now expressed in a spin-spatial direct product basis. This variant takes two associated values:
     • nspins: this unsigned integer specifies the total number of spin spaces
     • increasingm: this boolean indicates whether the spin spaces are arranged in increasing-\(m_s\) order (note: the typical \((\alpha, \beta)\) spin spaces are arranged in decreasing-\(m_s\) order, and so this boolean should be set to false)
9. This specifies the order in which matrix elements are packed in the supplied binary files. The possible options are:
   • RowMajor: C-like order where the first index is the slowest and the last index is the fastest,
   • ColMajor: Fortran-like order where the first index is the fastest and the last index is the slowest.
   
   Default: RowMajor.
10. This specifies the endianness of the byte values in the supplied binary files. The possible options are:
    • LittleEndian: the least-significant byte is stored at the smallest memory address,
    • BigEndian: the least-significant byte is stored at the largest memory address.
    Most systems are little-endian, but this should be verified to ensure that the values in the binary files are read in correctly.
    
    Default: LittleEndian.
11. This YAML dictionary specifies the basis angular order information for the underlying calculation. For more information, see Basics/Requirements/#Atomic-orbital basis angular order.
12. This YAML dictionary contains all control parameters for the symmetry analysis of Slater determinants and is identical to that specified for Slater determinant Q-Chem HDF5 archive source.

Python

from qsym2 import (
    rep_analyse_slater_determinant,
    EigenvalueComparisonMode, #(1)!
    MagneticSymmetryAnalysisKind, #(2)!
    SymmetryTransformationKind, #(3)!
    PySpinConstraint, #(4)!
    PySlaterDeterminantReal,
    PySlaterDeterminantComplex,
)

ca = np.array([ #(5)!
    [+1.000, +0.000],
    [+0.000, +0.707],
    [+0.000, +0.707],
    ...
])
cb = np.array([
    [+0.000, +0.707],
    [+1.000, +0.000],
    [+0.000, -0.707],
    ...
])

occa = np.array([1.0, 1.0]) #(6)!
occb = np.array([1.0, 0.0])

ea = np.array([-0.51, -0.38]) #(7)!
eb = np.array([-0.50, +0.02])

pydet = PySlaterDeterminantReal( #(8)!
    spin_constraint=PySpinConstraint.Unrestricted, #(9)!
    complex_symmetric=False, #(10)!
    coefficients=[ca, cb], #(11)!
    occupations=[occa, occb], #(12)!
    threshold=1e-7, #(13)!
    mo_energies=[ea, eb], #(14)!
    energy=-1.30, #(15)!
)

sda_res = rep_analyse_slater_determinant( #(16)!
    # Data
    inp_sym="mol", #(17)!
    pydet=pydet, #(18)!
    pybao=pybao, #(19)!
    sao_spatial=sao_spatial, #(20)!
    sao_spatial_h=None, #(21)!
    sao_spatial_4c=None, #(22)!
    sao_spatial_4c_h=None, #(23)!
    # Thresholds
    linear_independence_threshold=1e-7, #(24)!
    integrality_threshold=1e-7, #(25)!
    eigenvalue_comparison_mode=EigenvalueComparisonMode.Modulus, #(26)!
    # Analysis options
    use_magnetic_group=None, #(27)!
    use_double_group=False, #(28)!
    use_cayley_table=True, #(29)!
    symmetry_transformation_kind=SymmetryTransformationKind.Spatial, #(30)!
    infinite_order_to_finite=None, #(31)!
    # Other options
    write_character_table=True, #(32)!
    write_overlap_eigenvalues=True, #(33)!
    analyse_mo_symmetries=True, #(34)!
    analyse_mo_mirror_parities=False, #(35)!
    analyse_density_symmetries=False, #(36)!
) #(37)!

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 is a Python-exposed Rust enum, PySpinConstraint, for indicating the spin constraint applicable to the Slater determinant. In the Python API, only two spin spaces arranged in decreasing-\(m_s\) order are permitted because Python enums do not support associated values.
5. This specifies a coefficient matrix for one spin space, which is a \(N_{\mathrm{bas}} \times N_{\mathrm{MO}}\) numpy array. The number of basis functions, \(N_{\mathrm{bas}}\), depends on the underlying spin constraint: for generalised spin constraint, this is twice the number of spatial basis functions, whereas for restricted and unrestricted spin constraints, this is the same as the number of spatial basis functions. Each column in the array specifies a molecular orbital which can be occupied or virtual as specified by the occupation numbers.
6. This specifies an occupation number vector for one spin space, which is a one-dimensional numpy array of size \(N_{\mathrm{MO}}\). Each value in this array gives the occupation number for the corresponding molecular orbital. Fractional values are allowed, but only when occupation numbers are either \(0\) or \(1\) can the Slater determinant symmetry be well-defined (otherwise the collection of fractionally occupied molecular orbitals does not actually form a single-determinantal wavefunction).
7. This specifies an optional orbital energy vector for one spin space, which is a one-dimensional numpy array of size \(N_{\mathrm{MO}}\). Each value in this array gives the orbital energy for the corresponding molecular orbital.
8. PySlaterDeterminantReal constructs a real-valued Slater determinant object. If a complex-valued Slater determinant is required instead, use PySlaterDeterminantComplex.
9. This specifies the spin constraint applicable to the Slater determinant being specified. The possible options are:
   • PySpinConstraint.Restricted: this specifies the restricted spin constraint where spatial molecular orbitals are identical across both spin spaces,
   • PySpinConstraint.Unrestricted: this specifies the unrestricted spin constraint where spatial molecular orbitals can be different across the two spin spaces,
   • PySpinConstraint.Generalised: this specifies the generalised spin constraint where each spin-orbital is now expressed in a spin-spatial direct product basis.
10. This specifies whether the Slater determinant is to be symmetry-analysed using the bilinear inner product instead of the conventional sesquilinear inner product.
11. This specifies the coefficient matrices constituting this Slater determinant. Each matrix in this list is for one spin space.
12. This specifies the occupation numbers for the specified molecular orbitals. Each vector in this list is for one spin space.
13. This specifies a threshold for comparing Slater determinants. This is of no consequence for symmetry analysis.
14. This is optional.
15. This is optional.
16. This is the Python driver function for representation analysis of Slater determinants.
    
    This is a Python-exposed Rust function, rep_analyse_slater_determinant. See the API documentation of this function for more details.
17. 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.
18. This specifies the Slater determinant to be symmetry-analysed.
19. This specifies the basis angular order information for the underlying basis. See Basics/Requirements/#Atomic-orbital basis angular order for details of how to specify this.
20. This specifies the two-centre atomic-orbital spatial overlap matrix as a two-dimensional numpy array.
21. This specifies the optional complex-symmetric two-centre atomic-orbital spatial overlap matrix as a two-dimensional numpy array. This is only required if antiunitary operations are ppresent.
    
    Default: None.
22. This specifies the optional four-centre atomic-orbital spatial overlap tensor as a four-dimensional numpy array. This is only required for density symmetry analysis.
    
    Default: None.
23. This specifies the optional complex-symmetric four-centre atomic-orbital spatial overlap tensor as a four-dimensional numpy array. This is only required for density symmetry analysis in the presence of antiunitary operations.
    
    Default: None.
24. This specifies a floating-point value for the linear independence threshold \(\lambda^{\mathrm{thresh}}_{\mathbfit{S}}\). For more information, see Basics/#Thresholds.
25. This specifies a floating-point value for the integrality threshold \(\lambda^{\mathrm{thresh}}_{\mathrm{int}}\). For more information, see Basics/#Thresholds.
26. 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.
27. 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.
28. 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.
29. 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.
30. 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.
31. 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.
32. This boolean indicates if the symbolic character table of the prevailing symmetry group is to be printed in the output.
    
    Default: True.
33. This boolean indicates if the eigenspectrum of the overlap matrix for the Slater determinant orbit should be printed out.
    
    Default: True.
34. This boolean indicates if the constituting molecular orbitals (MOs) are also symmetry-analysed.
    
    Default: True.
35. This boolean indicates if MO mirror parities (i.e. parities w.r.t. any mirror planes present in the system) are to be analysed alongside MO symmetries.
    
    Default: False.
36. This boolean indicates if density symmetries are to be analysed alongside wavefunction symmetries. If analyse_mo_symmetries is set to True, then MO density symmetries are also analysed.
    
    Default: False.
37. The rep_analyse_slater_determinant function returns a single PySlaterDeterminantRepAnalysisResult object containing the Python-exposed results of the representation analysis.