Kernel utilities

From Spinach Documentation Wiki
Jump to: navigation, search

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.

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.


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

Converts angle-axis rotation parameters to directional cosine matrix.
Converts angle-axis rotation parameters into a quaternion.
Roughly averages an interaction tensor with respect to the rotation around a user-specified axis.
Converts a directional cosine matrix into Euler angles.
Converts a directional cosine matrix into a quaternion.
Converts a directional cosine matrix into a Wigner matrix.
Converts Euler angles into directional cosine matrix.
Produces rotor stack of Liouvillians or Hamiltonians.
Converts Euler angles into Wigner rotation matrix.
Converts a quaternion into an angle-axis specification.
Converts a quaternion into a directional cosine matrix.
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.

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) infrastructure

Reduces direct products of two su(2) irreps.
Converts Hilbert space operators into Liouville space superoperators or state vectors. See function header for further information.
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.
Structure coefficient tables for the associateive envelopes of su(mult) algebras.
(L,0)(+)(0,L) irrp of the of the Lorentz group with inversion.
Right and left side product superoperators.
Pauli matrices of a spin with user-specified multiplicity.
Right-ordered nested commutator.
Sorensen bounds.
Converts Stevens coefficients into irreducible spherical tensor coefficients.
Extended Stevens operators.
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 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.

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

A simple bin packing algorithm.
Matrix norm estimator.
Sparse matrix clean-up utility.
Directional derivatives of matrix exponentials.
Eigenfields solver.
Exponential drop function.
Matrix exponential integrals.
Fourier spectral differentiation kernel.
Fourier spectral differentiation matrices.
Fourier spectral Laplacian.
Truncates SVD decomposition to the user-specified threshold in the Frobenius norm.
Normalised Gaussian function in magnetic resonance notation.
Hadamard matrix inner product.
Cubic Hermite spline on [0,1] interval from values and derivatives at the interval edges.
Returns true for square matrices.
Numerical Jacobian estimation.
Truncates SVD decomposition to the user-specified threshold in the singular value count.
Kronecker's delta symbol.
Normalised Lorentzian function in magnetic resonance notation.
Returns MD5 hashes of matrices.
Preallocates an operator in the current formalism and basis.
All picks of the specified number of elements from the vector provided, without repetitions.
Returns the non-NaN elements of a numerical array.
The part of the matrix that commutes with another matrix.
Rayleigh-Schrodinger perturbation theory to arbitrary order.
Azzalini's skew normal distribution.
Vector-covector pairs for the parallel propagation in Hilbert space.
Returns a unit operator in the current formalism and basis.
Returns a unit state in the current formalism and basis.
Van Vleck perturbation theory.

Integration grids

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

Arc length between two points on the unit sphere.
Gauss-Legendre quadrature grids and weights.
Generates a convex hull of a two-angle grid for 2D surface plotting.
Igloo type spherical quadrature grids.
Fibonacci type spherical quadrature grids.
Spherical grid direct product.
Spherical quadrature grid plotter.
Plots grid integration quality as a function of spherical rank.
Triangular spherical quadrature grids.
Solid angle of a convex spherical polygon.
Generates REPULSION grids on a unit hypersphere.
Computes SHREWD weights for a given two- or three-angle spherical grid.
Area of the curvilinear triangle on the unit sphere.
Spherical triangle subdivision.
Solid angle of a spherical Voronoi cell.
Adaptively recursed Voitlander integrator.
Voronoi tessellation on a sphere.
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

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