spinguin.core.la

spinguin.core.la#

This module provides various linear algebra tools required for spin dynamics simulations.

CG_coeff(j1: float, m1: float, j2: float, m2: float, j3: float, m3: float) → float[source]#

Computes the Clebsch-Gordan coefficients.

Parameters:

  • j1 (float) – Angular momentum of state 1.

  • m1 (float) – Magnetic quantum number of state 1.

  • j2 (float) – Angular momentum of state 2.

  • m2 (float) – Magnetic quantum number of state 2.

  • j3 (float) – Total angular momentum of the coupled system.

  • m3 (float) – Magnetic quantum number of the coupled system.

Returns:

coeff – Clebsch-Gordan coefficient.

Return type:

float

angle_between_vectors(v1: ndarray, v2: ndarray) → float[source]#

Computes the angle between two vectors in radians.

Parameters:

  • v1 (ndarray) – First vector.

  • v2 (ndarray) – Second vector.

Returns:

theta – Angle between the vectors in radians.

Return type:

float

arraylike_to_array(A: Buffer | _SupportsArray[dtype[Any]] | _NestedSequence[_SupportsArray[dtype[Any]]] | complex | bytes | str | _NestedSequence[complex | bytes | str]) → ndarray[source]#

Converts an ArrayLike object into a NumPy array while ensuring that at least one dimension is created.

Parameters:

A (ArrayLike) – An object that can be converted into NumPy array.

Returns:

A – The original object converted into a NumPy array.

Return type:

ndarray

arraylike_to_tuple(A: Buffer | _SupportsArray[dtype[Any]] | _NestedSequence[_SupportsArray[dtype[Any]]] | complex | bytes | str | _NestedSequence[complex | bytes | str]) → tuple[source]#

Converts a 1-dimensional ArrayLike object into a Python tuple.

Parameters:

A (ArrayLike) – An object that can be converted into NumPy array.

Returns:

A – The original object represented as Python tuple.

Return type:

tuple

auxiliary_matrix_expm(A: ndarray | csc_array, B: ndarray | csc_array, C: ndarray | csc_array, t: float, zero_value: float) → csc_array[source]#

Computes the matrix exponential of an auxiliary matrix. This is used to calculate the Redfield integral.

Based on Goodwin and Kuprov (Eq. 3): https://doi.org/10.1063/1.4928978

Parameters:

  • A (ndarray or csc_array) – Top-left block of the auxiliary matrix.

  • B (ndarray or csc_array) – Top-right block of the auxiliary matrix.

  • C (ndarray or csc_array) – Bottom-right block of the auxiliary matrix.

  • t (float) – Integration time.

  • zero_value (float) – Threshold below which values are considered zero when exponentiating the auxiliary matrix using the Taylor series. This significantly impacts performance. Use the largest value that still provides correct results.

Returns:

expm_aux – Matrix exponential of the auxiliary matrix. The output is sparse or dense matching the sparsity of the input.

Return type:

ndarray or csc_array

bytes_to_sparse(A_bytes: bytes) → csc_array[source]#

Converts a byte representation back to a SciPy sparse array.

Parameters:

A_bytes (bytes) – Byte representation of a SciPy sparse array.

Returns:

A – Sparse array reconstructed from the byte representation.

Return type:

csc_array

cartesian_tensor_to_spherical_tensor(C: ndarray) → dict[source]#

Converts a rank-2 Cartesian tensor to a spherical tensor.

Uses the double outer product (DOP) convention from: Eqs. 293-298 in Man: Cartesian and Spherical Tensors in NMR Hamiltonians https://doi.org/10.1002/cmr.a.21289

Parameters:

C (ndarray) – Rank-2 tensor in Cartesian coordinates.

Returns:

spherical_tensor – Keys specify the rank and the projection (l, q), and the values are the components.

Return type:

dict

comm(A: csc_array | ndarray, B: csc_array | ndarray) → csc_array | ndarray[source]#

Calculates the commutator [A, B] of two operators.

Parameters:

  • A (csc_array or ndarray) – First operator.

  • B (csc_array or ndarray) – Second operator.

Returns:

C – Commutator [A, B].

Return type:

csc_array or ndarray

custom_dot(A: ndarray | csc_array, B: ndarray | csc_array, zero_value: float) → csc_array[source]#

User-friendly wrapper for the custom sparse matrix multiplication, which saves memory usage by dropping values smaller than zero_value during the calculation. The sparse multiplication is implemented with C++ / Cython and is parallelized with OpenMP.

NOTE: If either of the input arrays is NumPy array, this function falls back to the regular @ multiplication.

Parameters:

  • A (ndarray or csc_array) – First matrix in the multiplication.

  • B (ndarray or csc_array) – Second matrix in the multiplication.

  • zero_value (float) – Threshold under which the resulting matrix elements are considered as zero.

Returns:

C – Result of matrix multiplication.

Return type:

ndarray or csc_array

decompose_matrix(matrix: ndarray) → tuple[ndarray, ndarray, ndarray][source]#

Decomposes a matrix into three components:

  • Isotropic part.

  • Antisymmetric part.

  • Symmetric traceless part.

Parameters:

matrix (ndarray) – Matrix to decompose.

Returns:

  • isotropic (ndarray) – Isotropic part of the input matrix.

  • antisymmetric (ndarray) – Antisymmetric part of the input matrix.

  • symmetric_traceless (ndarray) – Symmetric traceless part of the input matrix.

eliminate_small(A: ndarray | csc_array, zero_value: float)[source]#

Eliminates small values from the input matrix A by replacing values smaller than zero_value with zeros. Modification happens inplace.

Parameters:

  • A (ndarray or csc_array) – Array to be modified.

  • zero_value (float) – Values smaller than this threshold are set to zero.

expm(A: ndarray | csc_array, zero_value: float) → ndarray | csc_array[source]#

Calculates the matrix exponential of a SciPy sparse CSC array using the scaling and squaring method with the Taylor series, shown to be the fastest method in:

https://doi.org/10.1016/j.jmr.2010.12.004

This function uses a custom dot product implementation, which is more memory-efficient and parallelized.

Parameters:

  • A (ndarray or csc_array) – Array to be exponentiated.

  • zero_value (float) – Values below this threshold are considered zero. Used to increase the sparsity of the result and estimate the convergence of the Taylor series.

Returns:

expm_A – Matrix exponential of A.

Return type:

ndarray or csc_array

expm_taylor(A: ndarray | csc_array, zero_value: float) → ndarray | csc_array[source]#

Computes the matrix exponential using the Taylor series. This function is adapted from an older SciPy version.

It uses a custom dot product implementation, which is more memory-efficient and parallelized.

Parameters:

  • A (ndarray or csc_array) – Matrix (N, N) to be exponentiated.

  • zero_value (float) – Values below this threshold are considered zero. Used to increase sparsity and check the convergence of the series.

Returns:

eA – Matrix exponential of A.

Return type:

ndarray or csc_array

find_common_rows(A: ndarray, B: ndarray) → tuple[ndarray, ndarray][source]#

Identifies the indices of common rows between two arrays, A and B. Each row must appear only once in the arrays and they must be sorted in lexicographical order.

Parameters:

  • A (ndarray) – First array to compare.

  • B (ndarray) – Second array to compare.

Returns:

  • A_ind (ndarray) – Indices of the common rows in array A.

  • B_ind (ndarray) – Indices of the common rows in array B.

isvector(v: csc_array | ndarray, ord: str = 'col') → bool[source]#

Checks if the given array is a vector.

Parameters:

  • v (csc_array or ndarray) – Array to be checked. Must be two-dimensional.

  • ord (str) – Can be either “col” or “row”.

Returns:

True if the array is a vector.

Return type:

bool

norm_1(A: csc_array | ndarray, ord: str = 'row') → float[source]#

Calculates the 1-norm of a matrix.

Parameters:

  • A (csc_array or ndarray) – Array for which the norm is calculated.

  • ord (str, default='row') – Either ‘row’ or ‘col’, specifying the direction for the 1-norm calculation.

Returns:

norm_1 – 1-norm of the given array A.

Return type:

float

principal_axis_system(tensor: ndarray) → tuple[ndarray, ndarray, ndarray][source]#

Determines the principal axis system (PAS) of a Cartesian tensor and transforms the tensor into the PAS.

The PAS is defined as the coordinate system that diagonalizes the symmetric traceless part of the tensor.

The eigenvalues are ordered as (|largest|, |middle|, |smallest|).

Parameters:

tensor (np.ndarray) – Cartesian tensor to transform.

Returns:

  • eigenvalues (ndarray) – Eigenvalues of the tensor in the PAS.

  • eigenvectors (ndarray) – Two-dimensional array where rows contain the eigenvectors of the PAS.

  • tensor_PAS (ndarray) – Tensor transformed into the PAS.

read_shared_sparse(A_shared: dict[str, str | dtype | tuple[int]]) → tuple[csc_array, tuple[SharedMemory, SharedMemory, SharedMemory]][source]#

Reads a shared memory representation of a sparse CSC array and reconstructs it.

Parameters:

A_shared (dict) – Dictionary containing shared memory names and metadata for the sparse array’s data, indices, and indptr, along with their shapes and dtypes.

Returns:

  • A (csc_array) – Sparse array reconstructed from the shared memory.

  • A_shm (tuple) – Tuple containing the shared memory objects for the sparse array’s data, indices, and indptr.

sparse_to_bytes(A: csc_array) → bytes[source]#

Converts the given SciPy sparse array into a byte representation.

Parameters:

A (csc_array) – Sparse matrix to be converted into bytes.

Returns:

A_bytes – Byte representation of the input matrix.

Return type:

bytes

vector_to_spherical_tensor(vector: ndarray) → dict[source]#

Converts a Cartesian vector to a spherical tensor of rank 1.

Uses the covariant components. Eq. 230 in Man: Cartesian and Spherical Tensors in NMR Hamiltonians https://doi.org/10.1002/cmr.a.21289

Parameters:

vector (ndarray) – Vector in the format [x, y, z].

Returns:

spherical_tensor – Keys specify the rank and the projection (l, q), and the values are the components.

Return type:

dict

write_shared_sparse(A: csc_array) → tuple[dict[str, str | dtype | tuple[int]], tuple[SharedMemory, SharedMemory, SharedMemory]][source]#

Creates a shared memory representation of a sparse CSC array.

Parameters:

A (csc_array) – Sparse array to be shared.

Returns:

  • A_shared (dict) – Dictionary containing shared memory names and metadata for the sparse array’s data, indices, and indptr, along with their shapes and dtypes.

  • A_shm (tuple) – Tuple containing the shared memory objects for the sparse array’s data, indices, and indptr.

Contents