Skip to content

qsym2

Attributes

PyMultiDeterminants module-attribute

Classes

PyMultiDeterminantsReal

Python-exposed structure to marshall real multi-determinant information between Rust and Python.

Parameters:

  • basis

    (Sequence[PySlaterDeterminantReal]) –

    The basis of Slater determinants in which the multi-determinantal states are expressed.

  • coefficients

    (Py2DArray_f64) –

    The coefficients for the multi-determinantal states in the specified basis. Each column of the coefficient matrix contains the coefficients for one state.

  • energies

    (Py1DArray_f64) –

    The energies of the multi-determinantal states.

  • density_matrices

    (Sequence[Py2DArray_f64] | None) –

    The optional density matrices of the multi-determinantal states.

  • threshold

    (float) –

    The threshold for comparisons.

Attributes

basis instance-attribute

The basis of Slater determinants in which the multi-determinantal states are expressed.

coefficients instance-attribute
Python
coefficients: Py2DArray_f64

The coefficients for the multi-determinantal states in the specified basis. Each column of the coefficient matrix contains the coefficients for one state.

energies instance-attribute
Python
energies: Py1DArray_f64

The energies of the multi-determinantal states.

density_matrices instance-attribute
Python
density_matrices: list[Py2DArray_f64] | None

The density matrices for the multi-determinantal states in the specified basis, if any.

threshold instance-attribute
Python
threshold: float

The threshold for comparisons.

Functions

complex_symmetric
Python
complex_symmetric() -> bool

Returns the boolean indicating whether inner products involving these multi-determinantal states are complex-symmetric.

state_coefficients
Python
state_coefficients(state_index: int) -> Py1DArray_f64

Returns the coefficients for a particular state.

state_energy
Python
state_energy(state_index: int) -> float

Returns the energy for a particular state.

state_density_matrix
Python
state_density_matrix(state_index: int) -> Py2DArray_f64

Returns the density matrix for a particular state.

PyMultiDeterminantsComplex

Python-exposed structure to marshall complex multi-determinant information between Rust and Python.

Parameters:

  • basis

    (Sequence[PySlaterDeterminantComplex]) –

    The basis of Slater determinants in which the multi-determinantal states are expressed.

  • coefficients

    (Py2DArray_c128) –

    The coefficients for the multi-determinantal states in the specified basis. Each column of the coefficient matrix contains the coefficients for one state.

  • energies

    (Py1DArray_c128) –

    The energies of the multi-determinantal states.

  • density_matrices

    (Sequence[Py2DArray_c128] | None) –

    The optional density matrices of the multi-determinantal states.

  • threshold

    (float) –

    The threshold for comparisons.

Attributes

basis instance-attribute

The basis of Slater determinants in which the multi-determinantal states are expressed.

coefficients instance-attribute
Python
coefficients: Py2DArray_c128

The coefficients for the multi-determinantal states in the specified basis. Each column of the coefficient matrix contains the coefficients for one state.

energies instance-attribute
Python
energies: Py1DArray_c128

The energies of the multi-determinantal states.

density_matrices instance-attribute
Python
density_matrices: list[Py2DArray_c128] | None

The density matrices for the multi-determinantal states in the specified basis, if any.

threshold instance-attribute
Python
threshold: float

The threshold for comparisons.

Functions

complex_symmetric
Python
complex_symmetric() -> bool

Returns the boolean indicating whether inner products involving these multi-determinantal states are complex-symmetric.

state_coefficients
Python
state_coefficients(state_index: int) -> Py1DArray_c128

Returns the coefficients for a particular state.

state_energy
Python
state_energy(state_index: int) -> float

Returns the energy for a particular state.

state_density_matrix
Python
state_density_matrix(state_index: int) -> Py2DArray_c128

Returns the density matrix for a particular state.

Functions

rep_analyse_multideterminants_eager_basis

Python-exposed function to perform representation symmetry analysis for real and complex multi-determinantal wavefunctions constructed from an eager basis of Slater determinants.

The result is also logged via the qsym2-output logger at the INFO level.

If symmetry_transformation_kind includes spin transformation, the provided multi-determinantal wavefunctions will be augmented to generalised spin constraint automatically.

Parameters:

  • inp_sym

    (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 representation analysis.

  • pydets

    (Sequence[PySlaterDeterminant]) –

    A list of Python-exposed Slater determinants. These determinants serve as basis states for non-orthogonal configuration interaction to yield multi-determinantal wavefunctions, the symmetry of which will be analysed by this function.

  • coefficients

    (Py2DArray_f64 | Py2DArray_c128) –

    The coefficient matrix where each column gives the linear combination coefficients for one multi-determinantal wavefunction. The number of rows must match the number of determinants specified in pydets.

  • energies

    (Py1DArray_f64 | Py1DArray_c128) –

    The energies of the multi-determinantal wavefunctions. The number of terms must match the number of columns of coefficients.

  • pybaos

    (Sequence[PyBasisAngularOrder]) –

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

  • integrality_threshold

    (float) –

    The threshold for verifying if subspace multiplicities are integral.

  • linear_independence_threshold

    (float) –

    The threshold for determining the linear independence subspace via the non-zero eigenvalues of the orbit overlap 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.

  • use_cayley_table

    (bool) –

    A boolean indicating if the Cayley table for the group, if available, should be used to speed up the calculation of orbit overlap matrices.

  • symmetry_transformation_kind

    (SymmetryTransformationKind) –

    An enumerated type indicating the type of symmetry transformations to be performed on the origin determinant to generate the orbit. If this contains spin transformation, the multi-determinant will be augmented to generalised spin constraint automatically.

  • eigenvalue_comparison_mode

    (EigenvalueComparisonMode) –

    An enumerated type indicating the mode of comparison of orbit overlap eigenvalues with the specified linear_independence_threshold.

  • sao

    (Py2DArray_f64 | Py2DArray_c128) –

    The atomic-orbital overlap matrix.

  • sao_h

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

    The optional complex-symmetric atomic-orbital overlap matrix. This is required if antiunitary symmetry operations are involved.

  • write_overlap_eigenvalues

    (bool, default: True ) –

    A boolean indicating if the eigenvalues of the determinant orbit overlap matrix are to be written to the output.

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

  • angular_function_integrality_threshold

    (float, default: 1e-07 ) –

    The threshold for verifying if subspace multiplicities are integral for the symmetry analysis of angular functions.

  • angular_function_linear_independence_threshold

    (float, default: 1e-07 ) –

    The threshold for determining the linear independence subspace via the non-zero eigenvalues of the orbit overlap matrix for the symmetry analysis of angular functions.

  • angular_function_max_angular_momentum

    (int, default: 2 ) –

    The maximum angular momentum order to be used in angular function symmetry analysis.

rep_analyse_multideterminants_orbit_basis_internal_solver

Python-exposed function to run non-orthogonal configuration interaction using the internal solver and then perform representation symmetry analysis on the resulting real and complex multi-determinantal wavefunctions constructed from group-generated orbits.

The result is also logged via the qsym2-output logger at the INFO level.

If symmetry_transformation_kind includes spin transformation, the provided multi-determinantal wavefunctions with spin constraint structure will be augmented to the generalised spin constraint automatically.

Parameters:

  • inp_sym

    (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 representation analysis.

  • pyorigins

    (Sequence[PySlaterDeterminant]) –

    A list of Python-exposed Slater determinants whose coefficients are of type float64 or complex128. These determinants serve as origins for group-generated orbits which serve as basis states for non-orthogonal configuration interaction to yield multi-determinantal wavefunctions, the symmetry of which will be analysed by this function.

  • pybaos

    (Sequence[PyBasisAngularOrder]) –

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

  • sao

    (Py2DArray_f64 | Py2DArray_c128) –

    The atomic-orbital overlap matrix whose elements are of type float64 or complex128.

  • enuc

    (float | complex) –

    The nuclear repulsion energy.

  • onee

    (Py2DArray_f64 | Py2DArray_c128) –

    The one-electron integral matrix whose elements are of type float64 or complex128.

  • twoe

    (Py4DArray_f64 | Py4DArray_c128 | None) –

    The two-electron integral tensor whose elements are of type float64 or complex128. 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) –

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

  • thresh_offdiag

    (float) –

    Threshold for identifying non-zero off-diagonal elements in Löwdin pairing.

  • thresh_zeroov

    (float) –

    Threshold for identifying non-zero overlaps in Löwdin pairing.

  • calculate_density_matrices

    (bool) –

    Boolean indicating if the density matrices for the resulting multi-determinants should be computed.

  • integrality_threshold

    (float) –

    The threshold for verifying if subspace multiplicities are integral.

  • linear_independence_threshold

    (float) –

    The threshold for determining the linear independence subspace via the non-zero eigenvalues of the orbit overlap 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.

  • use_cayley_table

    (bool) –

    A boolean indicating if the Cayley table for the group, if available, should be used to speed up the calculation of orbit overlap matrices.

  • symmetry_transformation_kind

    (SymmetryTransformationKind) –

    An enumerated type indicating the type of symmetry transformations to be performed on the origin determinant to generate the orbit. If this contains spin transformation, the multi-determinant will be augmented to generalised spin constraint automatically.

  • eigenvalue_comparison_mode

    (EigenvalueComparisonMode) –

    An enumerated type indicating the mode of comparison of orbit overlap eigenvalues with the specified linear_independence_threshold.

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

  • write_overlap_eigenvalues

    (bool, default: True ) –

    A boolean indicating if the eigenvalues of the determinant orbit overlap matrix are to be written to the output.

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

  • angular_function_integrality_threshold

    (float, default: 1e-07 ) –

    The threshold for verifying if subspace multiplicities are integral for the symmetry analysis of angular functions.

  • angular_function_linear_independence_threshold

    (float, default: 1e-07 ) –

    The threshold for determining the linear independence subspace via the non-zero eigenvalues of the orbit overlap matrix for the symmetry analysis of angular functions.

  • angular_function_max_angular_momentum

    (int, default: 2 ) –

    The maximum angular momentum order to be used in angular function symmetry analysis.

Returns:

  • PyMultiDeterminants

    The result will be returned as an object containing the Slater determinant basis and the linear combination coefficients as a two-dimensional array with each column corresponding to one computed multi-determinantal state.

rep_analyse_multideterminants_orbit_basis_external_solver

Python-exposed function to perform representation symmetry analysis for real and complex multi-determinantal wavefunctions constructed from group-generated orbits.

The result is also logged via the qsym2-output logger at the INFO level.

If symmetry_transformation_kind includes spin transformation, the provided multi-determinantal wavefunctions will be augmented to generalised spin constraint automatically.

Parameters:

  • inp_sym

    (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 representation analysis.

  • pyorigins

    (Sequence[PySlaterDeterminant]) –

    A list of Python-exposed Slater determinants whose coefficients are of type float64 or complex128. These determinants serve as origins for group-generated orbits which serve as basis states for non-orthogonal configuration interaction to yield multi-determinantal wavefunctions, the symmetry of which will be analysed by this function.

  • py_noci_solver

    (Callable[[Sequence[PySlaterDeterminantReal | PySlaterDeterminantComplex]], tuple[list[float], list[list[float]]] | tuple[list[complex], list[list[complex]]]]) –

    A Python function callable on a sequence of Slater determinants to perform non-orthogonal configuration interaction (NOCI) and return a list of NOCI energies and a corresponding list of lists of linear combination coefficients, where each inner list is for one multi-determinantal wavefunction resulting from the NOCI calculation.

  • pybaos

    (Sequence[PyBasisAngularOrder]) –

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

  • density_matrix_calculation_thresholds

    (tuple[float, float] | None) –

    An optional pair of thresholds for Löwdin pairing, one for checking zero off-diagonal values, one for checking zero overlaps, when computing multi-determinantal density matrices. If None, no density matrices for the resulting multi-determinants will be computed.

  • integrality_threshold

    (float) –

    The threshold for verifying if subspace multiplicities are integral.

  • linear_independence_threshold

    (float) –

    The threshold for determining the linear independence subspace via the non-zero eigenvalues of the orbit overlap 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.

  • use_cayley_table

    (bool) –

    A boolean indicating if the Cayley table for the group, if available, should be used to speed up the calculation of orbit overlap matrices.

  • symmetry_transformation_kind

    (SymmetryTransformationKind) –

    An enumerated type indicating the type of symmetry transformations to be performed on the origin determinant to generate the orbit. If this contains spin transformation, the multi-determinant will be augmented to generalised spin constraint automatically.

  • eigenvalue_comparison_mode

    (EigenvalueComparisonMode) –

    An enumerated type indicating the mode of comparison of orbit overlap eigenvalues with the specified linear_independence_threshold.

  • sao

    (Py2DArray_f64 | Py2DArray_c128) –

    The atomic-orbital overlap matrix whose elements are of type float64 or complex128.

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

  • write_overlap_eigenvalues

    (bool, default: True ) –

    A boolean indicating if the eigenvalues of the determinant orbit overlap matrix are to be written to the output.

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

  • angular_function_integrality_threshold

    (float, default: 1e-07 ) –

    The threshold for verifying if subspace multiplicities are integral for the symmetry analysis of angular functions.

  • angular_function_linear_independence_threshold

    (float, default: 1e-07 ) –

    The threshold for determining the linear independence subspace via the non-zero eigenvalues of the orbit overlap matrix for the symmetry analysis of angular functions.

  • angular_function_max_angular_momentum

    (int, default: 2 ) –

    The maximum angular momentum order to be used in angular function symmetry analysis.

Returns:

  • PyMultiDeterminants

    The result will be returned as an object containing the Slater determinant basis and the linear combination coefficients as a two-dimensional array with each column corresponding to one computed multi-determinantal state.