Skip to content

Electron densities

Let \(\rho(\mathbfit{r})\) be the one-electron density defined based on an \(N_{\mathrm{e}}\)-electron wavefunction \(\Psi(\mathbfit{x}_1, \ldots, \mathbfit{x}_{N_{\mathrm{e}}})\) as

\[ \rho(\mathbfit{r}) = N_{\mathrm{e}} \int \Psi(\mathbfit{r}, s, \mathbfit{x}_2, \ldots, \mathbfit{x}_{N_{\mathrm{e}}})^* \Psi(\mathbfit{r}, s, \mathbfit{x}_2, \ldots, \mathbfit{x}_{N_{\mathrm{e}}}) \ \mathrm{d}s \ \mathrm{d}\mathbfit{x}_2 \ldots \mathrm{d}\mathbfit{x}_{N_{\mathrm{e}}}. \]

In an atomic-orbital basis \(\{ \phi_{\gamma}(\mathbfit{r}), \phi_{\delta}(\mathbfit{r}), \ldots \}\), the density \(\rho(\mathbfit{r})\) can be expanded as

\[ \rho(\mathbfit{r}) = \sum_{\gamma \delta} \phi_{\gamma}(\mathbfit{r}) \phi_{\delta}(\mathbfit{r}) P_{\delta \gamma}, \]

where \(P_{\delta \gamma}\) are elements of the corresponding density matrix \(\mathbfit{P}\) in this basis. The projected density is thus

\[ \hat{\mathscr{P}^{(\Gamma)}} \rho(\mathbfit{r}) = \sum_{\gamma \delta} \phi_{\gamma}(\mathbfit{r}) \phi_{\delta}(\mathbfit{r}) \frac{d_{\Gamma}}{|\mathcal{G}|} \sum_{i = 1}^{|\mathcal{G}|} \chi^{(\Gamma)}(g_i)^* P_{\delta \gamma}(g_i) = \sum_{\gamma \delta} \phi_{\gamma}(\mathbfit{r}) \phi_{\delta}(\mathbfit{r}) P^{(\Gamma)}_{\delta \gamma}, \]

where \(P_{\delta \gamma}(g_i)\) is the density matrix of the density transformed by \(\hat{g}_i\) and

\[ P^{(\Gamma)}_{\delta \gamma} = \frac{d_{\Gamma}}{|\mathcal{G}|} \sum_{i = 1}^{|\mathcal{G}|} \chi^{(\Gamma)}(g_i)^* P_{\delta \gamma}(g_i) \]

is the resulting density matrix of the projected density. It is clear that projected densities \(\hat{\mathscr{P}}^{(\Gamma)} \rho(\mathbfit{r})\) are themselves densities.

Requirements

As electron densities are expanded in atomic-orbital bases in QSym², information about their angular momenta and ordering conventions as described in Representation analysis/Basics/Requirements/#Atomic-orbital basis angular order is required.

Parameters

Feature requirements

QSym² is able to perform symmetry projection for electron densities that can arise from various sources via the Python library API reading in data from Python data structures. The way to do this is shown below.

Python
from qsym2 import (
    project_densities,
    SymmetryTransformationKind, #(1)!
    PyDensityReal,
    PyDensityComplex,
    MagneticSymmetryAnalysisKind, #(2)!
)

dmao_a = np.array([ #(3)!
    [1.0, 0.0, 0.0, 0.0],
    [0.0, 0.5, 0.0, 0.0],
    [0.0, 0.0, 0.5, 0.0],
    [0.0, 0.0, 0.5, 0.8],
])
dmao_b = np.array([
    [0.7, 0.0, 0.0, 0.0],
    [0.0, 1.0, 0.0, 0.0],
    [0.0, 0.0, 0.7, 0.0],
    [0.0, 0.0, 0.5, 0.8],
])

pydens = [
    (
        "alpha_density", PyDensityReal(
            complex_symmetric=False,
            density_matrix=dmao_a,
            threshold=1e-7,
        )
    ),
    (
        "beta_density", PyDensityReal(
            complex_symmetric=False,
            density_matrix=dmao_b,
            threshold=1e-7,
        )
    ),
    (
        "total_density", PyDensityReal(
            complex_symmetric=False,
            density_matrix=dmao_a+dmao_b,
            threshold=1e-7,
        )
    ),
    (
        "spin_density", PyDensityReal(
            complex_symmetric=False,
            density_matrix=dmao_a-dmao_b,
            threshold=1e-7,
        )
    ),
]

result = project_densities( #(4)!
    # Data
    inp_sym="mol", #(5)!
    pydens=pydens, #(6)!
    projection_targets=[0, "||A|_(2g)|"], #(7)!
    pybao=pybao, #(8)!
    # Projection options
    use_magnetic_group=None, #(9)!
    use_double_group=False, #(10)!
    symmetry_transformation_kind=SymmetryTransformationKind.Spatial, #(11)!
    infinite_order_to_finite=None, #(12)!
    # Other options
    write_character_table=True, #(13)!
) #(14)!
  1. This is a Python-exposed Rust enum, SymmetryTransformationKind, for indicating the kind of symmetry transformation to be applied on the target. See Representation analysis/Basics/Analysis options/#Transformation kinds for further information.
  2. This is a Python-exposed Rust enum, MagneticSymmetryAnalysisKind, for indicating the type of magnetic symmetry to be used for symmetry projection. Note that projections using corepresentations of magnetic-represented groups are not yet supported. See Representation analysis/Basics/Analysis options/#Magnetic groups for further information.
  3. This specifies a density matrix in the atomic-orbital basis, \(\mathbfit{P}\), for one electron density, which is a \(N_{\mathrm{bas}} \times N_{\mathrm{bas}}\) numpy array. The number of basis functions, \(N_{\mathrm{bas}}\), is always the number of spatial basis functions because electron densities are entirely spatial quantities.
  4. This is the Python driver function for symmetry projection of electron densities.

    This is a Python-exposed Rust function, project_densities. See the API documentation of this function for more details.
  5. 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 symmetry projection.

    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 symmetry projection.
  6. This specifies a list of densities to be symmetry-projected. Each element in this list is a tuple containing a brief string description for the density and a specification for the density itself.
  7. This specifies the irreducible representations of the group onto which the provided densities are projected. Each element in this list is either an integer indicating the index of an irreducible representation in the group, or a string of the format |^(presup)_(presub)|main|^(postsup)_(postsub)| (note that four | characters are required), such as ||A|_(2g)| or ||E|^(')_(1)|, specifying the label of the irreducible representation.
  8. This specifies the basis angular order information for the underlying basis. See Representation analysis/Basics/Requirements/#Atomic-orbital basis angular order for details of how to specify this.
  9. This specifies whether magnetic groups, if present, shall be used for symmetry projection. The possible options are:
  10. This is a boolean specifying if double groups shall be used for symmetry projection. 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 Representation analysis/Basics/Analysis options/#Double groups.
  11. This specifies the kind of symmetry transformations to be applied to generate the orbit for symmetry projection. 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 Representation analysis/Basics/Analysis options/#Transformation kinds.
  12. This specifies the finite order \(n\) to which all infinite-order symmetry elements, if any, are restricted. The possible options are:
  13. This boolean indicates if the symbolic character table of the prevailing symmetry group is to be printed in the output.

    Default: True.
  14. The returned result is a list of tuples, each of which contains a string describing the density being projected and a dictionary a dictionary in which the keys are the irreducible representation labels and the values are the corresponding projected density. See project_densities for more details.