Real-space functions

Let \(f(\mathbfit{r}): \mathbb{R}^3 \to \mathbb{F}\) be a real-valued (\(\mathbb{F} = \mathbb{R}\)) or complex-valued (\(\mathbb{F} = \mathbb{C}\)) function on \(\mathbb{R}^3\) that can be specified on a grid. QSym² is able to provide symmetry assignments for such functions using the orbit-based analysis formulation detailed in Section 2.4.2 of the QSym² paper.

Requirements

Basis overlap matrix

The symmetry analysis of real-spacre functions requires the following inner product to be defined:

\[ \braket{f_1 | f_2} = \int f_{1}^*(\mathbfit{r}) f_{2}(\mathbfit{r}) w(\mathbfit{r}) \ \mathrm{d}\mathbfit{r}, \]

where \(w(\mathbfit{r})\) is an appropriate weight function. On a grid \(G\), the above integral can be approximated as

\[ \braket{f_1 | f_2} \approx \sum_{\mathbfit{r}_i \in G} f_{1}^*(\mathbfit{r}_i) f_{2}(\mathbfit{r}_i) w(\mathbfit{r}_i) \Delta\mathbfit{r}_i, \]

where the finite elements \(\Delta\mathbfit{r}_i\) can be absorbed into the weight function.

Function specification

The real-space function \(f(\mathbfit{r})\) needs to be specifiable as a closure that takes in three real-valued arguments for the three input Cartesian coordinates and returns a scalar.

Parameters

Feature requirements

• As the symmetry analysis of real-space functions is still under development, its usage requires the sandbox feature.
• Using the Python API requires the python feature.

QSym² is able to perform symmetry analysis for real-space functions that can arise from various sources, as long as they can be specified programmatically as a closure that takes in three real-valued arguments and returns a scalar. The way to do this via the Python API is shown below.

Python

Python

from qsym2 import (
    sandbox, #(1)!
    EigenvalueComparisonMode, #(2)!
    MagneticSymmetryAnalysisKind, #(3)!
    SymmetryTransformationKind, #(4)!
)

grid = np.array( #(5)!
    [
        [x, y, z]
        for x in np.arange(-1, 1.01, 0.1)
        for y in np.arange(-1, 1.01, 0.1)
        for z in np.arange(-1, 1.01, 0.1)
    ]
).T

weight = np.array( #(6)!
    [np.exp(-(np.linalg.norm(r) ** 2)) for r in grid.T],
    dtype=np.complex128
)

def real_function(x, y, z): #(7)!
    return x * y + (x**2 - y**2)

sandbox.rep_analyse_real_space_function_real( #(8)!
    # Data
    inp_sym="mol", #(9)!
    function=real_function, #(10)!
    grid_points=grid,
    weight=weight,
    # Thresholds
    linear_independence_threshold=1e-6, #(11)!
    integrality_threshold=1e-6, #(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)!
    write_overlap_eigenvalues=True, #(20)!
)

def complex_function(x, y, z): #(21)!
    return z**2 + 3j * x * (z**2 - y**2)

sandbox.rep_analyse_real_space_function_complex( #(22)!
    # Data
    inp_sym="mol",
    function=complex_function,
    grid_points=grid,
    weight=weight,
    # Thresholds
    linear_independence_threshold=1e-6,
    integrality_threshold=1e-6,
    eigenvalue_comparison_mode=EigenvalueComparisonMode.Modulus,
    # Analysis options
    use_magnetic_group=None,
    use_double_group=False,
    use_cayley_table=True,
    symmetry_transformation_kind=SymmetryTransformationKind.Spatial,
    infinite_order_to_finite=None,
    # Other options
    write_character_table=True,
    write_overlap_eigenvalues=True,
)

1. This is a submodule of QSym² containing developmental features. See Getting started/Prerequisites/Rust features/Developmental for more information.
2. 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.
3. 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.
4. 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.
5. This specifies a \(3 \times N\) array containing the Cartesian coordinates of the grid points at which the real-space function will be evaluated in the symmetry analysis. Each column of the array contains the coordinates of one grid point \(\mathbfit{r}_i\).
6. This specifies an \(N\)-element array containing the weight values \(w(\mathbfit{r}_i)\) associated with the specified grid points \(\mathbfit{r}_i\).
7. This is an example real-valued real-space function: \(f(\mathbfit{r}) = xy + (x^2 - y^2)\).
8. This is the Python driver function for representation analysis of real-valued real-space functions.
   
   This is a Python-exposed Rust function, rep_analyse_real_space_function_real. 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 Python function that defines the real-valued real-space function 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.
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.
20. This boolean indicates if the eigenspectrum of the overlap matrix for the real-space function orbit should be printed out.
    
    Default: True.
21. This is an example complex-valued real-space function: \(f(\mathbfit{r}) = z^2 + 3i \times x(z^2 - y^2)\).
22. This is the Python driver function for representation analysis of complex-valued real-space functions.
    
    This is a Python-exposed Rust function, rep_analyse_real_space_function_complex. See the API documentation of this function for more details.