qsym2 ¶

Python-exposed function to perform symmetry projection for real and complex Slater determinants.

Parameters:

• inp_sym ¶

  (str | PathLike[str]) –

  A path to the QSym2FileType::Sym file containing the symmetry-group detection result for the system. This will be used to construct abstract groups and character tables for symmetry projection.

• pydet ¶

  (PySlaterDeterminant) –

  A Slater determinant whose coefficient matrices are of type float64 or complex128.

• projection_targets ¶

  (Sequence[str | int]) –

  A sequence of subspace labels for projection. Each label is either a symbolic string or a numerical index for the subspace in the character table of the prevailing group.

• calculate_energies ¶

  (bool) –

  A boolean indicating if the energies of the projected wavefunctions (which are multi-determinantal wavefunctions specified in an orbit basis) are to be calculated. If True, then thresh_offdiag, thresh_zeroov, enuc, onee, and either twoe or py_get_jk must also be specified for Löwdin pairing and Hamiltonian matrix element computation.

• calculate_density_matrices ¶

  (bool) –

  A boolean indicating if the density matrices for the projected wavefunctions (which are multi-determinantal wavefunctions) are to be calculated. If True, then thresh_offdiag and thresh_zeroov must also be specified for Löwdin pairing.

• pybaos ¶

  (Sequence[PyBasisAngularOrder]) –

  Python-exposed structures containing basis angular order information, one for each explicit component per coefficient matrix.

• use_magnetic_group ¶

  (MagneticSymmetryAnalysisKind | None) –

  An option indicating if the magnetic group is to be used for symmetry analysis, and if so, whether unitary representations or unitary-antiunitary corepresentations should be used.

• use_double_group ¶

  (bool) –

  A boolean indicating if the double group of the prevailing symmetry group is to be used for representation analysis instead.

• symmetry_transformation_kind ¶

  (SymmetryTransformationKind) –

  An enumerated type indicating the type of symmetry transformations to be performed on the origin Slater determinant to generate the orbit.

• write_character_table ¶

  (bool, default: True ) –

  A boolean indicating if the character table of the prevailing symmetry group is to be printed out.

• 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 symmetry analysis.

• sao ¶

  (Py2DArray_f64 | Py2DArray_c128 | None, default: None ) –

  The optional atomic-orbital overlap matrix whose elements are of type float64 or complex128. If this is not present, no squared norms, energies, or density matrices of the resulting multi-determinants will be computed.

• sao_h ¶

  (Py2DArray_f64 | Py2DArray_c128 | None, default: None ) –

  The optional complex-symmetric atomic-orbital overlap matrix whose elements are of type float64 or complex128. This is required if antiunitary symmetry operations are involved.

• enuc ¶

  (complex | None, default: None ) –

  The optional nuclear repulsion energy, which is only required for calculate_energies.

• onee ¶

  (Py2DArray_f64 | Py2DArray_c128 | None, default: None ) –

  The optional one-electron integral matrix whose elements are of type float64 or complex128, which is only required for calculate_energies.

• twoe ¶

  (Py4DArray_f64 | Py4DArray_c128 | None, default: None ) –

  The optional two-electron integral tensor in physicists' ordering whose elements are of type float64 or complex128, which is only required for calculate_energies. Either this or py_get_jk must be specified, but not both.

• py_get_jk ¶

  (Callable[[Py2DArray_f64 | Py2DArray_c128], tuple[Py2DArray_f64, Py2DArray_f64] | tuple[Py2DArray_c128, Py2DArray_c128]] | None, default: None ) –

  An optional Python function callable on a density matrix $\mathbf{D}$ to calculate the corresponding $\mathbf{J}$ and $\mathbf{K}$ matrices by contracting with appropriate two-electron integrals calculated on-the-fly, which is only required for calculate_energies. Either this or twoe must be specified, but not both.

• thresh_offdiag ¶

  (float | None, default: None ) –

  The optional threshold for identifying non-zero off-diagonal elements in Löwdin pairing, which is required for calculate_energies and calculate_density_matrices.

• thresh_zeroov ¶

  (float | None, default: None ) –

  The optional threshold for identifying non-zero overlaps in Löwdin pairing, which is required for calculate_energies and calculate_density_matrices.

Returns:

• tuple[list[str], PyMultiDeterminants] –

  The result will be returned as a tuple where the first item is a list of the labels of the subspaces used for projection, and the second item is an object containing:

  • the Slater determinant basis,
  • the linear combination coefficients as a two-dimensional array with each column corresponding to one projected state,
  • the energies of the projected states if requested, or NaN if not, and
  • the density matrices of the projected states if requested, or None if not.