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 also given in the function headers.

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.

get_coupling.m - Extracts the 3x3 coupling tensor between a pair of spins back from the spin_system data structure.

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

idxof.m - returns the index of the spin that has the specified label.

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 by 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 - converts g-tensor units into resonance frequencies.

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

hartree2joule.m – converts Hartree energy units to Joules.

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

hz2ppm.m - converts resonance offsets into chemical shifts.

ias2mat.m - Interaction matrix from isotropic-antisymmetric-symmetric decomposition.

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

mat2ias.m - Isotropic-antisymmetric-symmetric decomposition of an interaction 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), SO(3), and other groups

add_spins.m - Reduces direct products of two su(2) irreps.

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

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

comm.m - Commutator of two matrices.

hilb2liouv.m - Converts Hilbert space operators into Liouville space superoperators or state vectors.

irr_sph_ten.m - Single-spin irreducible spherical tensor operators for a given spin multiplicity.

ist_product_table.m - Structure coefficient tables for the associative envelopes of su(n) algebras.

lorentz.m - (L,0)(+)(0,L) irrep of the of the Lorentz group with inversion.

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.

p_superop.m - Right and left side product superoperators.

pauli.m - spin operators with user-specified multiplicity.

rocomm.m - Right-ordered nested commutator.

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

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

sorensen.m - Sorensen bounds.

spher_harmon.m – computes spherical harmonics.

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

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

stevens.m - Extended Stevens operators.

twospinist.m - Two-spin irreducible spherical tensor operators.

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

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.

spden.m - Lorentzian spectral density function for rotational diffusion at the user-specified frequency.

Chemical dynamics infrastructure

equilibrate.m - equilibrates linear kinetics.

kinetics.m - linear kinetics superoperator.

magpump.m - phenomenological magnetisation pumping.

react_gen.m - chemical reaction generator builder.

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.

plot_uf.m - ultrafast NMR plotting utility.

slice_2d.m – displays slices of 2D spectra.

stack_2d.m - stack plotting utility for 2D NMR spectra.

try_to_savefig.m - figure save replacement that tolerates write-protected media

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.

corrfun.m – correlation functions for rotational diffusion.

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.

spden.m - Lorentzian spectral density function for rotational diffusion at the user-specified frequency.

Numerical infrastructure

acomm.m - Matrix anticommutator.

arnoldi.m - Arnoldi orthogonalisation process.

atranspose.m - Antidiagonal array transpose.

aux_mat.m - Auxiliary matrices for directional derivatives of the trapezium product quadrature propagator.

binpack.m - A simple bin packing algorithm.

cheap_norm.m - Matrix norm estimator.

cheb_coeff.m - Chebyshev expansion coefficients.

clean_up.m - Sparse matrix clean-up utility.

dirdiff.m - Directional derivatives of matrix exponentials.

eigenfields.m - Eigenfields solver.

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 - Normalised Gaussian function in magnetic resonance notation.

hdot.m - Hadamard matrix inner product.

herm_spline.m - Cubic Hermite spline on [0,1] interval from values and derivatives at the interval edges.

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.

logfactorial.m - Logarithm of the factorial function.

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

lorentzcon.m - Normalised Lorentzian function and its convolution with a triangular function.

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.

present.m - Returns the non-NaN elements of a numerical array.

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

remtrace.m - Zeroes out the trace of a 3x3 interaction tensor.

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

snormpdf.m - Azzalini's skew normal distribution.

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

tikhonov.m - Tikhonov regularised positive solution to K*x=y

trapdiff.m - Directional derivatives for the trapezium product quadrature.

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.

vvpert.m - Van Vleck perturbation theory.

Integration grids

The functions below generate grids procedurally. For pre-computed spherical quadrature grids, see Appendix I: powder grids.

arclength.m - Arc length between two points on the unit sphere.

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_igloo.m - Igloo type spherical quadrature grids.

grid_fibon.m - Fibonacci type spherical quadrature grids.

grid_kron.m - Spherical grid direct product.

grid_plot.m - Spherical quadrature grid plotter.

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

grid_trian.m - Triangular spherical quadrature grids.

one_vcell_solidangle.m - Solid angle of a convex spherical polygon.

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

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

sphtarea.m - Area of the curvilinear triangle on the unit sphere.

sphtrsubd.m - Spherical triangle subdivision.

vcell_solidangle.m - Solid angle of a spherical Voronoi cell.

voitlander.m - Adaptively recursed Voitlander integrator.

voronoisphere.m - Voronoi tessellation on a sphere.

zfs_sampling.m - GdDOTA ZFS probability distribution function

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.

patrol.m - continuous patrol through the example set.

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.

wiki.m - opens Spinach documentation Wiki.

Matlab overloads and replacements

kcolourbar.m - LaTeX ticks and label on the standard colour bar.

kgrid.m - grey (rather than black-and-transparent) coordinate system grid.

klegend.m - LaTeX legend.

ktitle.m - bold LaTeX title.

kxlabel.m - LaTeX ticks and label on the standard X axis.

kylabel.m - LaTeX ticks and label on the standard Y axis.

kzlabel.m - LaTeX ticks and label on the standard Z axis.

Version 2.8, authors: Ilya Kuprov