# Kernel utilities

This section provides brief list of the functionality found in the kernel utilities folder, in alphabetic order. Service functions that have no physical or algebraic applications are not listed. Details of usage, input and output are given in the function headers.

## Contents

- 1 Reference data
- 2 Spin system editing
- 3 Rotations
- 4 Interaction specification conventions
- 5 SU(2) infrastructure
- 6 SO(3) infrastructure
- 7 Spatial dynamics infrastructure
- 8 State space indexing and manipulation
- 9 Data analysis and plotting
- 10 Numerical infrastructure
- 11 Integration grids
- 12 Housekeeping functions

## Reference data

Multiplicities and magnetogyric ratios for most non-zero spin isotopes in the periodic table are available from spin.m function.

## Spin system editing

dilute.m – splits the spin system into several independent subsystems, each containing only one instance of a user specified isotope that is deemed "dilute". All spin system data is updated accordingly and basis set information, if found, is destroyed. Used in the simulation of NMR experiments with natural abundance of 13C, 15N and other naturally dilute isotopes.

kill_spin.m – removes the specified spins from the spin_system structure and updates all internal structures accordingly. If basis set information is found, it is destroyed.

shift_iso.m – replaces the isotropic parts of interaction tensors with user-supplied values. This is useful for correcting DFT calculations, where the anisotropy is usually satisfactory, but the isotropic part often is not.

## Rotations

See the section on rotation conventions for the details of how rotations are stored and manipulated inside Spinach kernel. The list of relevant Spinach and Matlab functions appears below.

anax2dcm.m – converts angle-axis rotation parameters to directional cosine matrix. Angle should be in radians, axis is normalized by the function.

anax2quat.m – converts angle-axis rotation parameters into a quaternion. Angle should be in radians, axis is normalized by the function.

dcm2euler.m – converts a directional cosine matrix (DCM) representation of a rotation into Euler angles. This is mathematically an ill-defined procedure and numerous checks are implemented to stop the function if any loss of accuracy is likely to occur. It is not advisable to use the eigenvector matrix that comes out of a 3x3 interaction tensor diagonalization procedure as a DCM because of the intrinsic randomness that is associated with eigenvector directions and labels.

dcm2quat.m – converts a directional cosine matrix representation of a rotation into a quaternion representation.

dcm2wigner.m – converts a directional cosine matrix (DCM) representation of a rotation into a Wigner matrix representation. Wigner matrices are ordered and signed to act on a vector of irreducible spherical tensor operator coefficients ordered as described in the function header. Numerous checks are implemented to stop the function if any loss of accuracy is likely to occur. It is not advisable to use the eigenvector matrix that comes out of a 3x3 interaction tensor diagonalization procedure as a DCM because of the intrinsic randomness that is associated with eigenvector directions and labels.

euler2dcm.m – converts Euler angles into the corresponding directional cosine matrix.

wigner.m – converts Euler angles into the corresponding Wigner rotation matrix. Wigner matrices are ordered and signed to act on a vector of irreducible spherical tensor operator coefficients ordered as described in the function header.

quat2anax.m – converts a quaternion rotation specification into an angle-axis specification.

quat2dcm.m – converts a quaternion representation of a rotation into a directional cosine matrix.

## Interaction specification conventions

castep2nqi.m – converts CASTEP EFG tensor (it is printed in atomic units) to NQI tensor in Hz that is required by Spinach.

cgsppm2ang.m - converts magnetic susceptibility from the cgs-ppm (aka cm^3/mol) units quoted by quantum chemistry packages into Angstrom^3 units required by Spinach pseudocontact shift functionality.

dihedral.m – calculates the dihedral angle defined by four sets of atomic coordinates supplied.

eeqq2nqi.m – converts literature conventions for the quadrupolar interaction specification into a 3x3 matrix in Hz.

fract2cart.m – converts fractional crystallographic coordinates to Cartesian coordinates.

gauss2mhz.m – converts hyperfine coupling tensors from Gauss to MHz.

hartree2joule.m – converts Hartree energy units to Joules.

mt2hz.m – converts hyperfine tensors from milliTesla to Hz.

xyz2dd.m – converts coordinates and periodic boundary conditions into 3x3 dipolar coupling matrices.

## SU(2) infrastructure

irr_sph_ten.m – returns an array of single-spin irreducible spherical tensor operators for a given spin multiplicity. The resulting spherical tensor operators are normalized to obey so(3) and su(2) commutation relations.

ist_product_table.m - structure coefficient tables for the associateive envelopes of su(mult) algebras.

pauli.m – generates Pauli matrices of a spin with user-specified multiplicity.

hilb2liouv.m – converts Hilbert space operators into Liouville space superoperators or state vectors. See function header for further information.

p_superop.m – a general function returning user-specified right and left side product superoperators. Direct calls to this function are rarely necessary – please use operator.m unless the requested state is very exotic indeed. The function accepts operator specification in the internal Spinach notation: for each spin, identity state (or equivalently spherical tensor operator) is numbered 0, is numbered 1, is numbered 2, is numbered 3, and so on (Spinach supports all spin quantum numbers) -- irreducible spherical tensors are numbered by ascending ranks and within ranks by descending projection. The resulting sequence of integers is mapped by the kernel into the sequence of operators in the direct product. A call to p_superop.m with such a string as an argument would return a right or left side product superoperator corresponding to the direct product state specified.

## SO(3) infrastructure

clebsch_gordan.m – computes Clebsch-Gordan coefficients using arbitrary-precision integer arithmetic. Indices in excess of 1,000 are handled without difficulty (a surprisingly non-trivial thing to achieve) and a fast analytical bypass is implemented for the coefficients encountered in the Stochastic Liouville Equation module.

perm_group.m – a database of common finite groups, including orders, classes and character tables. Used by the permutation symmetry module.

mat2sphten.m – translates 3x3 interaction tensors into irreducible spherical tensor coefficients: one rank 0 component, three rank 1 components and five rank 2 components to the total of nine independent components.

sphten2mat.m – Converts the nine components of the irreducible spherical tensor representation of an interaction tensor into the Cartesian representation with a 3x3 matrix.

spher_harmon.m – computes spherical harmonics.

wigner.m – computes Wigner matrices.

sle_operators.m - Wigner D function basis set and rotation generators.

## Spatial dynamics infrastructure

fdhess.m – finite-difference Hessian operators for the PCS module.

fdkup.m – finite-difference Kuprov operators for the PCS module.

fdlap.m – finite-difference Laplace operators for the PCS module.

fdmat.m – finite-difference operators for the PCS module.

fdvec.m – finite-difference operators for the PCS module.

fdweights.m – finite difference stencil weights.

fpl2phan.m – partial trace with respect to spin degrees of freedom applied to a Fokker-Planck state vector.

fpl2rho.m – partial trace with respect to spatial degrees of freedom applied to a Fokker-Planck state vector.

interpmat.m – interpolation matrices for the PCS module.

phan2fpl.m – projects a phantom into the Fokker-Planck space.

corrfun.m – computes rotational correlation functions normalized to be correlation functions of second-rank Wigner functions. Handles isotropic, axial and fully anisotropic rotational diffusion. The 625 correlation functions possible with various index combinations in the latter case have been tested against a brute-force Monte-Carlo simulation of rotational diffusion. This function is used by the Redfield theory module.

hydrodynamics.m - hydrodynamics infrastructure provider.

## State space indexing and manipulation

absorb.m – designates specific states as "dark" -- any population reaching them would stay in them forever in a frozen state. This function is only available in sphten-liouv formalism.

lin2lm.m – converts the linear indexing state specification (used by Spinach to build matrix representations of spin operators) into L,M indexing, where L is the rank and M is the projection quantum number of an irreducible spherical tensor. In the linear indexing convention, the states are listed in the order of increasing L rank, and, within ranks, in the order of decreasing M projection.

lm2lin.m – converts L,M spin state specification to linear indexing specification used by Spinach to build matrix representations of spin operators. In the linear indexing convention, the states are listed in the order of increasing L rank, and, within ranks, in the order of decreasing M projection.

lin2lmn.m – converts the linear indexing Wigner function specification (used by Spinach to build matrix representations of rotational diffusion operators) into L,M,N indices that enumerate Wigner matrix elements. In the linear indexing convention, the Wigner functions are listed in the order of increasing L rank. Within each L rank, the functions are listed in the order of decreasing left index, and, for each left index, in the order of decreasing right index.

lmn2lin.m – converts L,M,N Wigner function specification to linear indexing specification used by Spinach to build matrix representations of rotational diffusion operators. In the linear indexing convention, the Wigner functions are listed in the order of increasing L rank. Within each L rank, the functions are listed in the order of decreasing left index, and, for each left index, in the order of decreasing right index.

scomponents.m – computes the strongly connected components of a graph. Returns an index for the component number of every vertex in the graph with the given adjacency matrix. Algorithm description is at http://dx.doi.org/10.1137/0201010

sparse2csr.m – computes a partial Compressed Row Storage transformation for a given Matlab sparse matrix. Only returns the index arrays and ignores the values.

path_trace.m – Liouvillian path tracing. Treats the user-supplied Liouvillian as the adjacency matrix of a graph, computes the weakly connected subgraphs of that graph and returns a cell array of projectors into the corresponding independently evolving subspaces. This function runs in linear time with respect to the number of non-zeros of a matrix, but provides cubic benefit by effectively block-diagonalizing the Liouvillian.

A significant number of independently evolving or dropped subspaces is often an indication of an overlooked symmetry or a conservation law – it is a good idea to examine the dropped subspaces and try finding out why they are not being populated. The efficiency of the path tracing procedure depends on the choice of the basis set. For the spherical tensor basis sets used in Spinach, there are usually at least two (in some EPR examples), and sometimes over a hundred (in large HSQC examples) independent subspaces, depending on the calculation type and spin interactions present.

dfpt.m – depth-first path tracing module. Analyses the system connectivity graph and creates a list of all connected subgraphs of up to the user-specified size by crawling the graph in all available directions. Used in the construction of connectivity-adaptive basis sets.

svd_shrink.m – generates a minimal set of vector-covector pairs for the parallel propagation in Hilbert space.

stitch.m – runs the stitching stage of bidirectional 3D NMR simulations.

zte.m – zero track elimination function. Inspects the first few steps in the system trajectory and drops the states that did not get populated to a user-specified tolerance. See Kuprov group publications for further details of this particular approximation.

human2opspec.m – converts human-readable operator specifications into operators specifications understood by the operator generation functions of Spinach kernel.

## Data analysis and plotting

slice_2d.m – displays slices of 2D spectra.

plot_1d.m – 1D spectral plotting utility.

plot_2d.m – 2D spectral plotting utility.

plot_3d.m – 3D spectral plotting utility.

volplot.m – volumetric ploting.

molplot.m – stick plots of molecules.

fprint.m – 2D spectrum fingerprinting utility.

apodization.m – performs free induction decay apodization. Supports 1D, 2D and 3D FIDs.

int_2d.m – 2D spectral integration utility.

sweep2ticks.m – converts spectral sweep width information into a vector of frequency axis ticks.

tensor_analysis.m – returns basic diagnostic information about a 3x3 interaction tensor.

## Numerical infrastructure

dirdiff.m – directional derivatives of matrix exponentials.

expmint.m – matrix exponential integrals.

hdot.m – Hadamard matrix product, a full sum of an element-by-element product of two matrices. Used as a computationally efficient way of computing the trace of a product of two matrices.

krondelta.m – Kronecker's delta symbol.

md5_hash.m – returns MD5 hashes of matrices.

mprealloc.m – preallocates an operator in the current formalism and basis.

unit_oper.m – returns a unit operator in the current formalism and basis.

unit_state.m – returns a unit state in the current formalism and basis.

clean_up.m – sparse matrix clean-up utility. Drops all elements that are found to be smaller in absolute value than a user-specified threshold from the non-zero index of a sparse array. If a dense array is supplied as an input, it is returned unchanged. If the sparse array is found to have non-zero density above the Spinach threshold (spin_system.tols.dense_matrix), the array is converted into dense type. This utility is invoked after every sparse matrix-matrix multiplication in Spinach in order to remove inconsequential non-zeros and keep the memory footprint to a minimum. The functions that critically rely on array clean-up for efficiency are the matrix exponentiation and the Redfield theory module.

statmerge.m – merges means and standard deviations for multiple sample sets.

symmetrize.m – symmetrises 3x3 interaction tensors. Antisymmetric (i.e. spherical tensor rank 1) parts of many spin interactions are inconsequential and best ignored in practical simulations.

## Integration grids

gaussleg.m - Gauss-Legendre quadrature grids and weights.

get_hull.m - generates a convex hull of a two-angle grid for 2D surface plotting.

grid_kron.m - spherical grid direct product.

grid_test.m - plots grid integration quality as a function of spherical rank.

repulsion.m - generates REPULSION grids on a unit hypersphere.

shrewd.m - computes SHREWD weights for a given two- or three-angle spherical grid.

## Housekeeping functions

report.m – Spinach kernel user feedback function, should not be called directly.

pad.m – pads character strings with spaces.

significant.m – returns true of the supplied object is significant to the specified tolerance.

negligible.m – returns true if the object supplied is negligible to the given tolerance.

summary.m – prints various summaries for Spinach kernel. Should not be called directly.

tolerances.m – tolerance information for Spinach kernel. Should not be called directly.

existentials.m – kernel integrity control function. Should not be called directly.

dipolar.m – converts coordinates into dipolar coupling tensors. This function is called by Spinach kernel and should not be used directly.

symmetry.m - Symmetry treatment. This is a service function of the Spinach kernel that should not be called directly.