# 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.
- axis_tsymm.m
- Roughly averages an interaction tensor with respect to the rotation around a user-specified axis.
- 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
- Produces 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
- Converts 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.

dictum.m - overrides interaction strength specifications.

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.

ppm2hz.m - converts chemical shifts into resonance offsets.

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

- add_spins.m
- Reduces direct products of two su(2) irreps.
- 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.
- lorentz.m
- (L,0)(+)(0,L) irrp of the of the Lorentz group with inversion.
- p_superop.m
- Right and left side product superoperators.
- pauli.m
- Pauli matrices of a spin with user-specified multiplicity.
- rocomm.m
- Right-ordered nested commutator.
- sorensen.m
- Sorensen bounds.
- stev2sph.m
- Converts Stevens coefficients into irreducible spherical tensor coefficients.
- stevens.m
- Extended Stevens operators.
- twospinist.m
- Two-spin irreducible spherical tensor operators.

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

human2opspec.m – converts human-readable operator specs into IST format.

lin2lm.m – IST index conversion from linear to (L,M)

lm2lin.m – IST index conversion from (L,M) to linear

lin2lmn.m – Wigner D function index conversion from (L,M,N) to linear

lmn2lin.m – Wigner D function index conversion from linear to (L,M,N)

scomponents.m – strongly connected components of a graph

sinkhole.m – designates specific states as sinkholes

sparse2csr.m – partial Compressed Row Storage transformation

path_trace.m – disconnected subspace discovery by Liouvillian path tracing

dfpt.m – depth-first path tracing module

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

zte.m – zero track elimination

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

ft_axis.m - Fourier transform axis ticks generator

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.

plot_uf.m - ultrafast NMR plotting utility.

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 - Blicharski invariants of spin interaction tensors.

blprod.m - Blicharski scalar products of spin interaction tensors.

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

ngce.m - numerical generalised cumulant expansion.

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.

eigenfolds.m - eigensystem linkage on a graph.

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.

keep_rank.m - Truncates SVD decomposition to the user-specified threshold in the singular value count.

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.

remncomm.m - the part of the matrix that commutes with another matrix.

rspert.m - Rayleigh-Schrodinger perturbation theory to arbitrary order.

svd_shrink.m – vector-covector pairs for the parallel propagation in Hilbert space.

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.
- sphtrsubd.m
- Spherical triangle subdivision.
- voronoisphere.m
- Voronoi tessellation on a sphere.
- 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.

parallel_profiler_start.m - start parallel profiling

parallel_profiler_report.m - end parallel profiling

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.5, authors: Ilya Kuprov*