Difference between revisions of "Kernel utilities"

From Spinach Documentation Wiki
Jump to: navigation, search
(→‎Numerical infrastructure)
(Index entries for the functions added in Spinach 2.13)
 
(135 intermediate revisions by the same user not shown)
Line 1: Line 1:
−
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.
+
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==
 
==Reference data==
Line 12: Line 12:
  
 
[[dilute.m]] – splits the spin system into independent subsystems, each containing only one instance of a "dilute" isotope.
 
[[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.
 
[[gtensorof.m]] - returns the g-tensor of the specified spin.
  
−
[[isnucleus.m]] - true of the particle is a nucleus known to ''Spinach''.
+
[[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.
 
[[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.
 
[[shift_iso.m]] – replaces the isotropic parts of interaction tensors with user-supplied values.
Line 23: Line 33:
 
==Rotations==
 
==Rotations==
  
−
See the section on [[rotation conventions]] for the details of how rotations are stored and manipulated inside Spinach kernel.
+
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.
+
[[anax2dcm.m]] - Converts angle-axis rotation parameters to directional cosine matrix.
  
−
[[anax2quat.m]] – converts angle-axis rotation parameters into a quaternion.
+
[[anax2qter.m]] - Converts angle-axis rotation parameters into a quaternion.
  
−
[[dcm2euler.m]] – converts a directional cosine matrix into Euler angles.
+
[[axis_tsymm.m]] - Roughly averages an interaction tensor with respect to the rotation around a user-specified axis.
  
−
[[dcm2quat.m]] – converts a directional cosine matrix into a quaternion.
+
[[dcm2euler.m]] - Converts a directional cosine matrix into Euler angles.
  
−
[[dcm2wigner.m]] – converts a directional cosine matrix into a Wigner matrix.  
+
[[dcm2qter.m]] - Converts a directional cosine matrix into a unit quaternion.
  
−
[[euler2dcm.m]] – converts Euler angles into directional cosine matrix.
+
[[dcm2wigner.m]] - Converts a directional cosine matrix into a Wigner matrix.  
  
−
[[rotor_stack.m]] - a rotor stack of Liouvillians or Hamiltonians.
+
[[euler2dcm.m]] - Converts Euler angles into directional cosine matrix.
  
−
[[wigner.m]] – converts Euler angles into Wigner rotation matrix.
+
[[euler2qter.m]] - Converts Euler angles into a unit quaternion.
  
−
[[quat2anax.m]] – converts a quaternion into an angle-axis specification.
+
[[euler_equiv.m]] - Checks whether two Euler angle sets specify the same rotation.
  
−
[[quat2dcm.m]] – converts a quaternion into a directional cosine matrix.
+
[[euler_sup.m]] - Superposes two active ZYZ Euler rotations.
  
−
[[xyz2sph.m]] - Cartesian into spherical coordinates.
+
[[qter2dcm.m]] - Converts a unit quaternion into a directional cosine matrix.
 +
 
 +
[[qter2euler.m]] - Converts a unit quaternion into Euler angles.
 +
 
 +
[[rotor_stack.m]] - Produces rotor stack of Liouvillians or Hamiltonians.
 +
 
 +
[[wigner.m]] - Converts Euler angles into Wigner rotation matrix.
 +
 
 +
[[qter2anax.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==
 
==Interaction specification conventions==
Line 54: Line 76:
  
 
[[axrh2mat.m]] - axiality and rhombicity 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.
 
[[castep2nqi.m]] – converts CASTEP EFG tensor (it is printed in atomic units) to NQI tensor in Hz that is required by Spinach.
Line 64: Line 88:
  
 
[[dihedral.m]] – calculates the dihedral angle defined by four sets of atomic coordinates supplied.
 
[[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.
 
[[eeqq2nqi.m]] – converts literature conventions for the quadrupolar interaction specification into a 3x3 matrix in Hz.
Line 69: Line 95:
 
[[frac2cart.m]] – converts fractional crystallographic coordinates to Cartesian coordinates.
 
[[frac2cart.m]] – converts fractional crystallographic coordinates to Cartesian coordinates.
  
−
[[g2freq.m]] - g-tensor units into frequencies.
+
[[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.
 
[[gauss2mhz.m]] – converts hyperfine coupling tensors from Gauss to MHz.
Line 75: Line 103:
 
[[hartree2joule.m]] – converts Hartree energy units to Joules.
 
[[hartree2joule.m]] – converts Hartree energy units to Joules.
  
−
[[hz2icm.m]] - Hz units of energy into inverse centimetres.
+
[[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.
 
[[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.
 
[[mhz2gauss.m]] - converts hyperfine couplings from MHz into Gauss.
  
 
[[mt2hz.m]] – converts hyperfine tensors from milliTesla to Hz.
 
[[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.
 
[[ppm2hz.m]] - converts chemical shifts into resonance offsets.
Line 93: Line 133:
 
[[zfs2mat.m]] - converts D and E zero-field splitting parameters into a diagonal 3x3 spin interaction matrix.
 
[[zfs2mat.m]] - converts D and E zero-field splitting parameters into a diagonal 3x3 spin interaction matrix.
  
−
==SU(2) infrastructure==
+
==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.
  
−
[[add_spins.m]] - reduces of direct products of two su(2) irreps.
+
[[clebsch_gordan.m]] – Clebsch-Gordan coefficients using arbitrary-precision integer arithmetic.
  
−
[[hilb2liouv.m]] – converts Hilbert space operators into Liouville space superoperators or state vectors. See function header for further information.
+
[[comm.m]] - Commutator of two matrices.
  
−
[[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.
+
[[hilb2liouv.m]] - Converts Hilbert space operators into Liouville space superoperators or state vectors.
  
−
[[ist_product_table.m]] - structure coefficient tables for the associateive envelopes of su(mult) algebras.
+
[[irr_sph_ten.m]] - Single-spin irreducible spherical tensor operators for a given spin multiplicity.
  
−
[[pauli.m]] – Pauli matrices of a spin with user-specified multiplicity.
+
[[ist_product_table.m]] - Structure coefficient tables for the associative envelopes of su(n) algebras.
  
−
[[sorensen.m]] - Sorensen bounds.
+
[[lorentz.m]] - (L,0)(+)(0,L) irrep of the of the Lorentz group with inversion.
  
−
[[stev2sph.m]] - converts Stevens coefficients into irreducible spherical tensor coefficients.
+
[[mat2sphten.m]] – translates 3x3 interaction tensors into irreducible spherical tensor coefficients.
  
−
[[stevens.m]] - extended Stevens operators.  
+
[[multipack.m]] - packs multipole moments from a linear stream into a cell array by rank.
  
−
[[p_superop.m]] – right and left side product superoperators.
+
[[perm_group.m]] – a database of common finite groups.
  
−
==SO(3) infrastructure==
+
[[pauli.m]] - spin operators with user-specified multiplicity.
  
−
[[clebsch_gordan.m]] – Clebsch-Gordan coefficients using arbitrary-precision integer arithmetic.
+
[[rocomm.m]] - Right-ordered nested commutator.
  
−
[[cg_fast.m]] - fast but less accurate Clebsch-Gordan coefficient calculation.
+
[[rwalk.m]] - random walk on SO(3).
  
−
[[logfactorial.m]] - logarithm of the factorial function.
+
[[sle_operators.m]] - Wigner D function basis set and rotation generators.
  
−
[[mat2sphten.m]] – translates 3x3 interaction tensors into irreducible spherical tensor coefficients.
+
[[sorensen.m]] - Sorensen bounds.
  
−
[[multipack.m]] - packs multipole moments from a linear stream into a cell array by rank.
+
[[spher_harmon.m]] – computes spherical harmonics.
  
−
[[perm_group.m]] – a database of common finite groups.
+
[[sphten2mat.m]] – irreducible spherical tensor coefficients into 3x3 matrix.
  
−
[[rwalk.m]] - random walk on SO(3).
+
[[stev2sph.m]] - Converts Stevens coefficients into irreducible spherical tensor coefficients.
  
−
[[sphten2mat.m]] – irreducible spherical tensor coefficients into 3x3 matrix.
+
[[stevens.m]] - Extended Stevens operators.
  
−
[[spher_harmon.m]] – computes spherical harmonics.
+
[[superop.m]] - Right and left side product superoperators.
  
−
[[sle_operators.m]] - Wigner D function basis set and rotation generators.
+
[[twospinist.m]] - Two-spin irreducible spherical tensor operators.
  
 
[[wigner.m]] – Wigner D matrices.
 
[[wigner.m]] – Wigner D matrices.
Line 143: Line 186:
 
==Spatial dynamics infrastructure==
 
==Spatial dynamics infrastructure==
  
−
[[corrfun.m]] – correlation functions for rotational diffution).
+
[[corrfun.m]] – correlation functions for rotational diffusion.
  
 
[[fdhess.m]] – finite-difference Hessian operators for the PCS module.
 
[[fdhess.m]] – finite-difference Hessian operators for the PCS module.
Line 156: Line 199:
  
 
[[fdweights.m]] – finite difference stencil weights.
 
[[fdweights.m]] – finite difference stencil weights.
 +
 +
[[fluxonium.m]] - fluxonium circuit Hamiltonian in the truncated harmonic oscillator basis.
  
 
[[fpl2phan.m]] – partial trace with respect to spin degrees of freedom applied to a Fokker-Planck state vector.
 
[[fpl2phan.m]] – partial trace with respect to spin degrees of freedom applied to a Fokker-Planck state vector.
Line 170: Line 215:
  
 
[[phan2fpl.m]] – projects a phantom into the Fokker-Planck space.
 
[[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==
 
==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.
+
[[adelim.m]] - adiabatic elimination
  
−
[[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.
+
[[coherence.m]] - coherence order selection
  
−
[[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.
+
[[correlation.m]] - correlation order selection
  
−
[[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.
+
[[homospoil.m]] - transverse magnetisation removal
  
−
[[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
+
[[human2opspec.m]] – converts human-readable operator specs into IST format
  
−
[[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.
+
[[lin2lm.m]] – IST index conversion from linear to (L,M)
  
−
[[sparse2csr.m]] – computes a partial Compressed Row Storage transformation for a given Matlab sparse matrix. Only returns the index arrays and ignores the values.
+
[[lm2lin.m]] – IST index conversion from (L,M) to linear
  
−
[[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.
+
[[lin2lmn.m]] – Wigner D function index conversion from (L,M,N) to linear
  
−
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.
+
[[lmn2lin.m]] – Wigner D function index conversion from linear to (L,M,N)
−
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.
+
[[scomponents.m]] – strongly connected components of a graph
  
−
[[svd_shrink.m]] – generates a minimal set of vector-covector pairs for the parallel propagation in Hilbert space.
+
[[sim2liouv.m]] – moves a zeeman-hilb simulation context into Liouville space
  
−
[[stitch.m]] – runs the stitching stage of bidirectional 3D NMR simulations.
+
[[sinkhole.m]] – designates specific states as sinkholes
  
−
[[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.
+
[[sparse2csr.m]] – partial Compressed Row Storage transformation
  
−
[[human2opspec.m]] – converts human-readable operator specifications into operators specifications understood by the operator generation functions of Spinach kernel.
+
[[sphten2zeeman.m]] - basis set conversion from irreducible spherical tensors into Zeeman basis.
 +
 
 +
[[spsortrows.m]] – row-sorting permutation for sparse matrices
 +
 
 +
[[spunicols.m]] – unique columns of a sparse matrix
 +
 
 +
[[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==
 
==Data analysis and plotting==
  
−
[[apodization.m]] – performs free induction decay apodization. Supports 1D, 2D and 3D FIDs.
+
[[apodisation.m]] – performs free induction decay apodization.
  
 
[[axis_1d.m]] - axis ticks for plotting 1D spectra.
 
[[axis_1d.m]] - axis ticks for plotting 1D spectra.
 +
 +
[[bloch_axis.m]] - instantaneous Bloch equation rotation axis from a trajectory.
 +
 +
[[contspacing.m]] - Non-linear adaptive contour spacing.
  
 
[[crop_2d.m]] - Crops 2D spectra to user-specified ranges.
 
[[crop_2d.m]] - Crops 2D spectra to user-specified ranges.
 +
 +
[[fig2tiles.m]] - Combines Matlab figure files into a single tiled figure.
  
 
[[int_2d.m]] – 2D spectral integration utility.
 
[[int_2d.m]] – 2D spectral integration utility.
 +
 +
[[ft_axis.m]] - Fourier transform axis ticks generator.
 +
 +
[[heterodyne.m]] - carrier frequency demodulation.
 +
 +
[[kletter.m]] - journal style panel letter label in the top left corner of the current axes.
  
 
[[molplot.m]] – stick plots of molecules.
 
[[molplot.m]] – stick plots of molecules.
 +
 +
[[nutation_dist.m]] - nutation frequency distribution from a nutation curve.
  
 
[[plot_1d.m]] – 1D spectral plotting utility.
 
[[plot_1d.m]] – 1D spectral plotting utility.
Line 219: Line 305:
  
 
[[plot_3d.m]] – 3D spectral plotting utility.
 
[[plot_3d.m]] – 3D spectral plotting utility.
 +
 +
[[plot_uf.m]] - ultrafast NMR plotting utility.
 +
 +
[[pseudomodulation.m]] - Fourier-domain pseudomodulation of uniformly sampled spectra.
  
 
[[slice_2d.m]] – displays slices of 2D spectra.
 
[[slice_2d.m]] – displays slices of 2D spectra.
  
−
[[plot_uf.m]] - ultrafast NMR plotting utility.
+
[[stack_2d.m]] - stack plotting utility for 2D NMR spectra.
  
 
[[mri_2d_plot.m]] - 2D MRI plotting utility.
 
[[mri_2d_plot.m]] - 2D MRI plotting utility.
Line 229: Line 319:
  
 
[[volplot.m]] – volumetric plotting.
 
[[volplot.m]] – volumetric plotting.
 +
 +
[[wigner_fock.m]] - Wigner function of a bosonic mode state given in a truncated Fock basis.
 +
 +
[[xyz2pd.m]] - probability density estimation for a 3D Cartesian point cloud.
  
 
[[zoom_3d.m]] - zooming into 3D data cubes.
 
[[zoom_3d.m]] - zooming into 3D data cubes.
Line 234: Line 328:
 
==Relaxation theory==
 
==Relaxation theory==
  
−
[[blinv.m]] - Blicharsky invariants of a matrix.
+
[[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.
 
[[magpump.m]] - phenomenological pumping terms for the relaxation superoperator.
Line 240: Line 340:
 
[[ngce.m]] - numerical generalised cumulant expansion.
 
[[ngce.m]] - numerical generalised cumulant expansion.
  
−
[[r1csa2tauc.m]] - estimate of rotational correlation time from longitudinal CSA relaxation rate.
+
[[rlx_modes.m]] - thermalised GKSL dissipators for damped and dephasing bosonic modes.
  
−
[[r2csa2tauc.m]] - estimate of rotational correlation time from transverse CSA relaxation rate.
+
[[rlx_phonon.m]] - spin-phonon relaxation in the generalised Lindblad form of Saito and Miyashita.
  
 
[[rlx_scalar.m]] - scalar relaxation superoperator.
 
[[rlx_scalar.m]] - scalar relaxation superoperator.
Line 249: Line 349:
  
 
[[rlx_t1_t2.m]] - extended T1/T2 model 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==
 
== Numerical infrastructure==
 +
[[acomm.m]] - Matrix anticommutator.
  
−
[[binpack.m]] - a simple bin packing algorithm.
+
[[arnoldi.m]] - Arnoldi orthogonalisation process.
  
−
[[cheap_norm.m]] - matrix norm estimator.
+
[[atranspose.m]] - Antidiagonal array transpose.
  
−
[[clean_up.m]] – sparse matrix clean-up utility.
+
[[aux_mat.m]] - Auxiliary matrices for directional derivatives of the trapezium product quadrature propagator.
  
−
[[dirdiff.m]] – directional derivatives of matrix exponentials.
+
[[binpack.m]] - A simple bin packing algorithm.
  
−
[[eigenfields.m]] - eigenfields solver.
+
[[cheap_norm.m]] - Matrix norm estimator.
  
−
[[eigenfolds.m]] - eigensystem linkage on a graph.
+
[[cheb_coeff.m]] - Chebyshev expansion coefficients.
  
−
[[eigentracks.m]] - eigenvalue tracks for matrix parameter scans.  
+
[[clean_up.m]] - Sparse matrix clean-up utility.
 +
 
 +
[[cubic_roots.m]] - Real roots of a cubic polynomial in the unit interval.
 +
 
 +
[[dhofun.m]] - Normalised damped harmonic oscillator response function.
 +
 
 +
[[dirdiff.m]] - Directional derivatives of matrix exponentials.
 +
 
 +
[[eigenfields.m]] - Eigenfields solver.
  
 
[[expdrop.m]] - Exponential drop function.
 
[[expdrop.m]] - Exponential drop function.
  
−
[[expmint.m]] – matrix exponential integrals.
+
[[expmint.m]] - Matrix exponential integrals.
 +
 
 +
[[expmint2.m]] - Nested double integral of matrix exponentials.
  
 
[[fftdiff.m]] - Fourier spectral differentiation kernel.
 
[[fftdiff.m]] - Fourier spectral differentiation kernel.
Line 278: Line 393:
 
[[frob_chop.m]] - Truncates SVD decomposition to the user-specified threshold in the Frobenius norm.
 
[[frob_chop.m]] - Truncates SVD decomposition to the user-specified threshold in the Frobenius norm.
  
−
[[gaussfun.m]] - Normalized Gaussian function in magnetic resonance notation.
+
[[gausscon.m]] - Normalised Gaussian function and its convolution with a triangular function.
 +
 
 +
[[gaussfun.m]] - Normalised Gaussian function in magnetic resonance notation.
  
−
[[hdot.m]] – Hadamard matrix product.
+
[[hdot.m]] - Hadamard matrix inner product.
  
−
[[issquare.m]] - returns true for square matrices.
+
[[herm_spline.m]] - Cubic Hermite spline on [0,1] interval from values and derivatives at the interval edges.
  
−
[[jacobianest.m]] - numerical Jacobian estimation.
+
[[jacobianest.m]] - Numerical Jacobian estimation.
  
 
[[keep_rank.m]] - Truncates SVD decomposition to the user-specified threshold in the singular value count.
 
[[keep_rank.m]] - Truncates SVD decomposition to the user-specified threshold in the singular value count.
  
−
[[krondelta.m]] – Kronecker's delta symbol.
+
[[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.
 +
 
 +
[[pink_noise.m]] - trajectories of a real random process with a 1/f power spectral density.
  
−
[[lorentzfun.m]] - Normalized Lorentzian function in magnetic resonance notation.
+
[[remncomm.m]] - The part of the matrix that commutes with another matrix.
  
−
[[md5_hash.m]] – returns MD5 hashes of matrices.
+
[[remtrace.m]] - Zeroes out the trace of a 3x3 interaction tensor.
  
−
[[mprealloc.m]] – preallocates an operator in the current formalism and basis.
+
[[rootmatch.m]] - Order-preserving root matching between three magnetic field root lists.
  
−
[[picks.m]] - all picks of the specified number of elements from the vector provided, without repetitions.
+
[[rspert.m]] - Rayleigh-Schrodinger perturbation theory to arbitrary order.
  
−
[[unit_oper.m]] – returns a unit operator in the current formalism and basis.
+
[[rspt_eig.m]] - Eigensystems of spin Hamiltonians and their derivatives.
  
−
[[unit_state.m]] – returns a unit state in the current formalism and basis.
+
[[sgolaydiff.m]] - Savitzky-Golay differentiation of noisy sampled signals.
  
 
[[snormpdf.m]] - Azzalini's skew normal distribution.
 
[[snormpdf.m]] - Azzalini's skew normal distribution.
 +
 +
[[sp_block_diag.m]] - Sparse block diagonal matrix from a stack of matrix blocks.
 +
 +
[[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==
 
==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.
 
[[gaussleg.m]] - Gauss-Legendre quadrature grids and weights.
  
−
[[get_hull.m]] - generates a convex hull of a two-angle grid for 2D surface plotting.
+
[[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.
  
−
[[grid_kron.m]] - spherical grid direct product.
+
[[sphtarea.m]] - Area of the curvilinear triangle on the unit sphere.
  
−
[[grid_test.m]] - plots grid integration quality as a function of spherical rank.
+
[[sphtrsubd.m]] - Spherical triangle subdivision.
  
−
[[repulsion.m]] - generates REPULSION grids on a unit hypersphere.
+
[[vcell_solidangle.m]] - Solid angle of a spherical Voronoi cell.
  
−
[[shrewd.m]] - computes SHREWD weights for a given two- or three-angle spherical grid.
+
[[voitlander.m]] - Adaptively recursed Voitlander integrator.  
  
−
[[zfs_sampling.m]] - returns optimal ZFS distribution integration information.
+
[[voronoisphere.m]] - Voronoi tessellation on a sphere.
 +
 
 +
[[zfs_sampling.m]] - GdDOTA ZFS probability distribution function
  
 
==Housekeeping functions==
 
==Housekeeping functions==
Line 324: Line 496:
 
[[banner.m]] - prints console banners.
 
[[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.
+
[[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.
+
[[existentials.m]] - kernel integrity control, checks for function name collisions.
  
 
[[exorcise.m]] - enforces the house style on the ''Spinach'' code base.
 
[[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.
 
[[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_basis.m]] - prints the basis-set state summary. Should not be called directly.
 +
 +
[[summary_basis_opts.m]] - prints the basis-set option summary. Should not be called directly.
 +
 +
[[summary_chemistry.m]] - prints the chemical subsystem and exchange summary. Should not be called directly.
 +
 +
[[summary_coordinates.m]] - prints the atomic coordinate summary. Should not be called directly.
 +
 +
[[summary_couplings.m]] - prints the spin-spin coupling tensor summary. Should not be called directly.
 +
 +
[[summary_mode_coup.m]] - prints the bosonic mode coupling summary. Should not be called directly.
 +
 +
[[summary_mode_mods.m]] - prints the summary of spin Hamiltonian modulation by bosonic mode coordinates. Should not be called directly.
 +
 +
[[summary_modes.m]] - prints the bosonic mode parameter summary. Should not be called directly.
 +
 +
[[summary_pbc.m]] - prints the periodic boundary condition vector summary. Should not be called directly.
 +
 +
[[summary_rlx_lindblad.m]] - prints the Lindblad relaxation rate summary. Should not be called directly.
 +
 +
[[summary_rlx_nott.m]] - prints the Nottingham DNP relaxation rate summary. Should not be called directly.
 +
 +
[[summary_rlx_t1_t2.m]] - prints the T1 and T2 relaxation rate summary. Should not be called directly.
 +
 +
[[summary_rlx_weiz.m]] - prints the Weizmann DNP relaxation rate summary. Should not be called directly.
 +
 +
[[summary_symmetry.m]] - prints the permutation symmetry summary. Should not be called directly.
 +
 +
[[summary_zeeman.m]] - prints the Zeeman interaction tensor summary. 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.
 +
 +
[[validate_sym.m]] - validates user-declared permutation symmetry against the interaction data. 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.
 
[[isworkernode.m]] - returns true if running on a parallel worker node.
  
−
[[pad.m]] – pads character strings with spaces.
+
[[load_vstore.m]] - loads the parallel pool ValueStore from a MAT file.
  
−
[[parallel_profiler_start.m]] - start parallel profiling
+
[[parallel_profiler_start.m]] - start parallel profiling.
  
−
[[parallel_profiler_report.m]] - end parallel profiling
+
[[parallel_profiler_report.m]] - end parallel profiling.
  
 
[[poolsize.m]] - returns current parallel pool size.
 
[[poolsize.m]] - returns current parallel pool size.
  
−
[[rearm.m]] - kernel integrity control, rearms the sniffer.
+
[[save_anyway.m]] - ignores parallel pool restrictions for save operations.
 +
 
 +
[[save_vstore.m]] - saves the parallel pool ValueStore into a MAT file.
 +
 
 +
[[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.
  
−
[[report.m]] – Spinach kernel user feedback function, should not be called directly.
+
[[reprows.m]] - Replicates specified rows of a matrix or cell array a specified number of times.
  
−
[[sniff.m]] - kernel integrity control, kernel code modification sniffer.
+
[[serpentine.m]] - Serpentine index matrix used in Spinach for single-index numbering of matrix elements.
  
−
[[smack.m]] - forcibly shuts down the parallel pool and clears the workspace.
+
[[st_product_table.m]] - Structure coefficient tables for single transition operators.
  
−
[[summary.m]] – prints various summaries for Spinach kernel. Should not be called directly.
+
[[tikhol1n.m]] - L1 norm Tikhonov regularised solver for A*x=y where A is an ill-conditioned matrix.
  
−
[[symmetry.m]] - Symmetry treatment. This is a service function of the Spinach kernel that should not be called directly.
+
[[unihash.m]] - Hash table based stable duplicate row eliminator, for use with large sparse matrices where Matlab's unique(...,'rows') is too slow.
  
−
[[tolerances.m]] – tolerance information for Spinach kernel. Should not be called directly.
+
[[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.4, authors: [[Ilya Kuprov]]''
+
''Version 2.11, authors: [[Ilya Kuprov]]''

Latest revision as of 16:32, 22 September 2026

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.

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

dcm2qter.m - Converts a directional cosine matrix into a unit quaternion.

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

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

euler2qter.m - Converts Euler angles into a unit quaternion.

euler_equiv.m - Checks whether two Euler angle sets specify the same rotation.

euler_sup.m - Superposes two active ZYZ Euler rotations.

qter2dcm.m - Converts a unit quaternion into a directional cosine matrix.

qter2euler.m - Converts a unit quaternion into Euler angles.

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

wigner.m - Converts Euler angles into Wigner rotation matrix.

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

fluxonium.m - fluxonium circuit Hamiltonian in the truncated harmonic oscillator basis.

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

sim2liouv.m – moves a zeeman-hilb simulation context into Liouville space

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.

spsortrows.m – row-sorting permutation for sparse matrices

spunicols.m – unique columns of a sparse matrix

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.

bloch_axis.m - instantaneous Bloch equation rotation axis from a trajectory.

contspacing.m - Non-linear adaptive contour spacing.

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

fig2tiles.m - Combines Matlab figure files into a single tiled figure.

int_2d.m – 2D spectral integration utility.

ft_axis.m - Fourier transform axis ticks generator.

heterodyne.m - carrier frequency demodulation.

kletter.m - journal style panel letter label in the top left corner of the current axes.

molplot.m – stick plots of molecules.

nutation_dist.m - nutation frequency distribution from a nutation curve.

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.

pseudomodulation.m - Fourier-domain pseudomodulation of uniformly sampled spectra.

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.

wigner_fock.m - Wigner function of a bosonic mode state given in a truncated Fock basis.

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_phonon.m - spin-phonon relaxation in the generalised Lindblad form of Saito and Miyashita.

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.

cubic_roots.m - Real roots of a cubic polynomial in the unit interval.

dhofun.m - Normalised damped harmonic oscillator response function.

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.

gausscon.m - Normalised Gaussian function and its convolution with a triangular function.

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.

pink_noise.m - trajectories of a real random process with a 1/f power spectral density.

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

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

rootmatch.m - Order-preserving root matching between three magnetic field root lists.

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

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

sgolaydiff.m - Savitzky-Golay differentiation of noisy sampled signals.

snormpdf.m - Azzalini's skew normal distribution.

sp_block_diag.m - Sparse block diagonal matrix from a stack of matrix blocks.

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_basis.m - prints the basis-set state summary. Should not be called directly.

summary_basis_opts.m - prints the basis-set option summary. Should not be called directly.

summary_chemistry.m - prints the chemical subsystem and exchange summary. Should not be called directly.

summary_coordinates.m - prints the atomic coordinate summary. Should not be called directly.

summary_couplings.m - prints the spin-spin coupling tensor summary. Should not be called directly.

summary_mode_coup.m - prints the bosonic mode coupling summary. Should not be called directly.

summary_mode_mods.m - prints the summary of spin Hamiltonian modulation by bosonic mode coordinates. Should not be called directly.

summary_modes.m - prints the bosonic mode parameter summary. Should not be called directly.

summary_pbc.m - prints the periodic boundary condition vector summary. Should not be called directly.

summary_rlx_lindblad.m - prints the Lindblad relaxation rate summary. Should not be called directly.

summary_rlx_nott.m - prints the Nottingham DNP relaxation rate summary. Should not be called directly.

summary_rlx_t1_t2.m - prints the T1 and T2 relaxation rate summary. Should not be called directly.

summary_rlx_weiz.m - prints the Weizmann DNP relaxation rate summary. Should not be called directly.

summary_symmetry.m - prints the permutation symmetry summary. Should not be called directly.

summary_zeeman.m - prints the Zeeman interaction tensor summary. 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.

validate_sym.m - validates user-declared permutation symmetry against the interaction data. 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.

load_vstore.m - loads the parallel pool ValueStore from a MAT file.

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.

save_vstore.m - saves the parallel pool ValueStore into a MAT file.

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

Retrieved from "https://spindynamics.org/wiki/index.php?title=Kernel_utilities&oldid=10358"