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.

iselectron.m - returns true if the particle is an electron.

isnucleus.m - returns true if the particle is a nucleus known to Spinach.

isoswap.m - isotope replacements in the input structures.

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

nearest_spin.m - returns the index of the nearest spin to the one specified.

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.

dcm2wigner.m - Converts a directional cosine matrix into a Wigner matrix.

euler2dcm.m - Converts Euler angles into directional cosine matrix.

euler_sup.m - Superposes two active ZYZ Euler rotations.

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.

rotmat_align.m - Rotation matrix aligning one vector with another vector.

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.

cart2mode.m - converts Cartesian derivatives of spin interactions into derivatives with respect to dimensionless bosonic mode coordinates.

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.

ejec2duffing.m - converts transmon Josephson and charging energies into Duffing frequency and anharmonicity.

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.

ham2nqi.m - converts a single-spin Hamiltonian into Zeeman and quadrupolar interaction parameters.

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.

kelvin2hz.m - converts Kelvin energy units into Hz.

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

mat2ias.m - Isotropic-antisymmetric-symmetric decomposition of an interaction matrix.

mev2hz.m - converts meV energy units into Hz.

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

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

offsetof.m - offset of the spin from magnetogyric ratio frequency.

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.

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.

superop.m - Right and left side product superoperators.

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.

qxspen_kernel.m - Distortion kernel of the QxSPEN experiment and its derivatives.

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.

flow_gen.m - diffusion and flow generator builder.

State space indexing and manipulation

adelim.m - adiabatic elimination

coherence.m - coherence order selection

correlation.m - correlation order selection

homospoil.m - transverse magnetisation removal

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

sphten2zeeman.m - basis set conversion from irreducible spherical tensors into Zeeman basis.

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

apodisation.m – performs free induction decay apodization.

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

contspacing.m - Non-linear adaptive contour spacing.

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.

heterodyne.m - carrier frequency demodulation.

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.

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.

xyz2pd.m - probability density estimation for a 3D Cartesian point cloud.

zoom_3d.m - zooming into 3D data cubes.

Relaxation theory

adelim.m - adiabatic elimination.

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_modes.m - thermalised GKSL dissipators for damped and dephasing bosonic modes.

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.

sec2kite.m - converts a secular relaxation superoperator into the Redfield kite form.

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.

expmint2.m - Nested double integral of matrix exponentials.

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.

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.

kronm_new.m - Kronecker product multiplication without opening the product.

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.

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.

rspt_eig.m - Eigensystems of spin Hamiltonians and their derivatives.

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

tikhoind.m - Tikhonov regularised indeterminate 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_polar.m - Balanced polar grid generator.

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.

cacheman.m - cache management heuristics for the scratch folder.

compile_mex.m - MEX compilation utility.

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.

forum.m - opens the Spinach support forum page.

hebrew.m - Hebrew flashcards utility.

iseye.m - returns true for unit matrices.

patrol.m - continuous patrol through the example set.

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.

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.

wipe_cache.m - forcible cache wipe.

Parallelisation and GPUs

distrib_dim.m - distributes an array in the user-specified dimension.

end_disallow_gpu.m - reinstates disabled GPU arithmetic.

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

parallel_profiler_start.m - start parallel profiling.

parallel_profiler_report.m - end parallel profiling.

poolsize.m - returns current parallel pool size.

save_anyway.m - ignores parallel pool restrictions for save operations.

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

start_disallow_gpu.m - forcibly disables GPU arithmetic.

swizzle.m - nested loop unrolling for parallel processing.

Miscellaneous utilities

autoexec.m - This include is executed at the start of create.m, it overrides all user input.

bos_product_table.m - Structure coefficient tables for the associative envelopes of truncated Weyl algebras spanned by orthogonalised bosonic mo- nomials.

fft_freq_axis.m - Frequency axis for FFT with optional zero-filling.

fwhm2rlx.m - Converts full width at half-maximum (FWHM) of an NMR signal into an approximation of the R2 rate.

icm2hz.m - Converts cm^-1 units used in spectroscopy into Hz units preferred in magnetic resonance; arrays of any dimensions are supported.

ifft_time_axis.m - Time axis for IFFT with optional zero-filling.

intrep.m - Interaction representation transformation with respect to a specified Hamiltonian to specified order in perturbation theory (https://doi.org/10.1063/1.4928978).

istraceless.m - A floating-point precision consistent check for whether a particular matrix is traceless.

kq2lin.m - Converts k,q indexing of matrices into their linear serpentine indexing.

kronm.m - Calculates (Q{1}(x)Q{2}(x)...(x)Q{n})*x without opening Kronecker products.

lcurve.m - L-curve analysis function.

lin2kq.m - Converts linear serpentine indexing of matrices into their k,q indexing.

min_int_type.m - Minimum integer data type sufficient to store the specified value.

prune_subgraphs.m - Removes subgraphs that are contained entirely within other subgraphs.

redfield_integral_async.m - Evaluates the Redfield integral through the asynchronous parallel path used inside relaxation.m, following the notation of IK's paper (http://dx.doi.org/10.1016/j.jmr.2010.12.004).

redfield_integral_serial.m - Evaluates the Redfield integral through the serial path used inside relaxation.m, following the notation of IK's paper (http://dx.doi.org/10.1016/j.jmr.2010.12.004) but replacing.

repcols.m - Replicates specified columns of a matrix or cell array a specified number of times.

reprows.m - Replicates specified rows of a matrix or cell array a specified number of times.

serpentine.m - Serpentine index matrix used in Spinach for single-index numbering of matrix elements.

st_product_table.m - Structure coefficient tables for single transition operators.

tikhol1n.m - L1 norm Tikhonov regularised solver for A*x=y where A is an ill-conditioned matrix.

unihash.m - Hash table based stable duplicate row eliminator, for use with large sparse matrices where Matlab's unique(...,'rows') is too slow.

which_subst.m - Finds out which substance hosts the specified spins; throws an error if there is more than one.

xyz2hfc.m - Converts point electron and nuclear coordinates into a hyperfine interaction tensor.

Version 2.11, authors: Ilya Kuprov