# 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 Relaxation theory
- 11 Numerical infrastructure
- 12 Integration grids
- 13 Housekeeping functions

## Reference data

spin.m - multiplicities and magnetogyric ratios for most isotopes in the periodic table.

## Spin system editing

chemshifts.m - returns chemical shifts for all spins.

cubic_lattice.m - generates a cubic lattice of spins.

dilute.m – splits the spin system into independent subsystems, each containing only one instance of a "dilute" isotope.

gtensorof.m - returns the g-tensor of the specified spin.

isnucleus.m - true of the particle is a nucleus known to *Spinach*.

kill_spin.m – removes the specified spins from the spin_system structure and updates all internal structures accordingly.

shift_iso.m – replaces the isotropic parts of interaction tensors with user-supplied values.

## Rotations

See the section on rotation conventions for the details of how rotations are stored and manipulated inside Spinach kernel.

anax2dcm.m – converts angle-axis rotation parameters to directional cosine matrix.

anax2quat.m – converts angle-axis rotation parameters into a quaternion.

dcm2euler.m – converts a directional cosine matrix into Euler angles.

dcm2quat.m – converts a directional cosine matrix into a quaternion.

dcm2wigner.m – converts a directional cosine matrix into a Wigner matrix.

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

rotor_stack.m - a rotor stack of Liouvillians or Hamiltonians.

wigner.m – converts Euler angles into Wigner rotation matrix.

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

quat2dcm.m – converts a quaternion into a directional cosine matrix.

xyz2sph.m - Cartesian into spherical coordinates.

## Interaction specification conventions

ang2cgsppm.m - cubic Angstrom units of magnetic susceptibility into CGS ppm.

anas2mat.m - anisotropy and asymmatry into 3x3 matrix.

axrh2mat.m - axiality and rhombicity into 3x3 matrix.

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.

conmat.m - molecular connectivity matrix.

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.

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

g2freq.m - g-tensor units into frequencies.

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

hartree2joule.m – converts Hartree energy units to Joules.

hz2icm.m - Hz units of energy into inverse centimetres.

mat2axrh.m - axiality and rhombicity from a 3x3 matrix.

mhz2gauss.m - converts hyperfine couplings from MHz into Gauss.

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

spsk2mat.m - span and skew into a 3x3 matrix.

tsm2param.m - traceless symmetric matrix into axiality, asymmetry, and Euler angles.

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

zfs2mat.m - converts D and E zero-field splitting parameters into a diagonal 3x3 spin interaction matrix.

## SU(2) infrastructure

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

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 – Pauli matrices of a spin with user-specified multiplicity.

sorensen.m - Sorensen bounds.

stev2sph.m - converts Stevens coefficients into irreducible spherical tensor coefficients.

stevens.m - extended Stevens operators.

p_superop.m – right and left side product superoperators.

## SO(3) infrastructure

clebsch_gordan.m – Clebsch-Gordan coefficients using arbitrary-precision integer arithmetic.

cg_fast.m - fast but less accurate Clebsch-Gordan coefficient calculation.

logfactorial.m - logarithm of the factorial function.

mat2sphten.m – translates 3x3 interaction tensors into irreducible spherical tensor coefficients.

multipack.m - packs multipole moments from a linear stream into a cell array by rank.

perm_group.m – a database of common finite groups.

rwalk.m - random walk on SO(3).

sphten2mat.m – irreducible spherical tensor coefficients into 3x3 matrix.

spher_harmon.m – computes spherical harmonics.

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

wigner.m – Wigner D matrices.

wigner_3j.m - Wigner 3j-symbols.

wigner_6j.m - Wigner 6j-symbols.

## Spatial dynamics infrastructure

corrfun.m – correlation functions for rotational diffution).

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.

hydrodynamics.m - hydrodynamics infrastructure provider.

interpmat.m – interpolation matrices for the PCS module.

oscillator.m - harmonic oscillator infrastructure provider.

overwound.m - spatial frequency distribution diagnostics.

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

## State space indexing and manipulation

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

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

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

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

axis_1d.m - axis ticks for plotting 1D spectra.

crop_2d.m - Crops 2D spectra to user-specified ranges.

int_2d.m – 2D spectral integration utility.

molplot.m – stick plots of molecules.

plot_1d.m – 1D spectral plotting utility.

plot_2d.m – 2D spectral plotting utility.

plot_3d.m – 3D spectral plotting utility.

slice_2d.m – displays slices of 2D spectra.

mri_2d_plot.m - 2D MRI plotting utility.

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

volplot.m – volumetric plotting.

zoom_3d.m - zooming into 3D data cubes.

## Relaxation theory

blinv.m - Blicharsky invariants of a matrix.

magpump.m - phenomenological pumping terms for the relaxation superoperator.

ngce.m - numerical generalised cumulant expansion.

r1csa2tauc.m - estimate of rotational correlation time from longitudinal CSA relaxation rate.

r2csa2tauc.m - estimate of rotational correlation time from transverse CSA relaxation rate.

rlx_scalar.m - scalar relaxation superoperator.

rlx_split.m - longitudinal, transverse, and mixed components of a relaxation superoperator.

rlx_t1_t2.m - extended T1/T2 model relaxation superoperator.

## Numerical infrastructure

binpack.m - a simple bin packing algorithm.

cheap_norm.m - matrix norm estimator.

clean_up.m – sparse matrix clean-up utility.

dirdiff.m – directional derivatives of matrix exponentials.

eigenfields.m - eigenfields solver.

eigentracks.m - eigenvalue tracks for matrix parameter scans.

expdrop.m - Exponential drop function.

expmint.m – matrix exponential integrals.

fftdiff.m - Fourier spectral differentiation kernel.

fourdif.m - Fourier spectral differentiation matrices.

fourlap.m - Fourier spectral Laplacian.

frob_chop.m - Truncates SVD decomposition to the user-specified threshold in the Frobenius norm.

gaussfun.m - Normalized Gaussian function in magnetic resonance notation.

hdot.m – Hadamard matrix product.

issquare.m - returns true for square matrices.

jacobianest.m - numerical Jacobian estimation.

krondelta.m – Kronecker's delta symbol.

lorentzfun.m - Normalized Lorentzian function in magnetic resonance notation.

md5_hash.m – returns MD5 hashes of matrices.

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

picks.m - all picks of the specified number of elements from the vector provided, without repetitions.

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.

snormpdf.m - Azzalini's skew normal distribution.

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

zfs_sampling.m - returns optimal ZFS distribution integration information.

## Housekeeping functions

banner.m - prints console banners.

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

existentials.m – kernel integrity control, checks for function name collisions.

exorcise.m - enforces the house style on the *Spinach* code base.

iseye.m - returns true for unit matrices.

isworkernode.m - returns true if running on a parallel worker node.

pad.m – pads character strings with spaces.

poolsize.m - returns current parallel pool size.

rearm.m - kernel integrity control, rearms the sniffer.

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

sniff.m - kernel integrity control, kernel code modification sniffer.

smack.m - forcibly shuts down the parallel pool and clears the workspace.

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

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

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

*Version 2.1, authors: Ilya Kuprov*