Difference between revisions of "Kernel utilities"

From Spinach Documentation Wiki
Jump to: navigation, search
(→‎Integration grids)
(Index entries for the functions added in Spinach 2.13)
 
(219 intermediate revisions by 3 users 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==
  
−
Multiplicities and magnetogyric ratios for most non-zero spin isotopes in the periodic table are available from [[spin.m]] function.
+
[[spin.m]] - multiplicities and magnetogyric ratios for most isotopes in the periodic table.
  
 
==Spin system editing==
 
==Spin system editing==
  
−
[[dilute.m]] – splits the spin system into several independent subsystems, each containing only one instance of a user specified isotope that is deemed "dilute". All spin system data is updated accordingly and basis set information, if found, is destroyed. Used in the simulation of NMR experiments with natural abundance of 13C, 15N and other naturally dilute isotopes.
+
[[chemshifts.m]] - returns chemical shifts for all spins.
  
−
[[kill_spin.m]] – removes the specified spins from the spin_system structure and updates all internal structures accordingly. If basis set information is found, it is destroyed.
+
[[cubic_lattice.m]] - generates a cubic lattice of spins.
  
−
[[shift_iso.m]] – replaces the isotropic parts of interaction tensors with user-supplied values. This is useful for correcting DFT calculations, where the anisotropy is usually satisfactory, but the isotropic part often is not.
+
[[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==
 
==Rotations==
  
−
See the section on [[rotation conventions]] for the details of how rotations are stored and manipulated inside Spinach kernel. The list of relevant Spinach and Matlab functions appears below.
+
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.
  
−
[[anax2dcm.m]] – converts angle-axis rotation parameters to directional cosine matrix. Angle should be in radians, axis is normalized by the function.
+
[[euler_equiv.m]] - Checks whether two Euler angle sets specify the same rotation.
  
−
[[anax2quat.m]] – converts angle-axis rotation parameters into a quaternion. Angle should be in radians, axis is normalized by the function.
+
[[euler_sup.m]] - Superposes two active ZYZ Euler rotations.
  
−
[[dcm2euler.m]] – converts a directional cosine matrix (DCM) representation of a rotation into Euler angles. This is mathematically an ill-defined procedure and numerous checks are implemented to stop the function if any loss of accuracy is likely to occur. It is not advisable to use the eigenvector matrix that comes out of a 3x3 interaction tensor diagonalization procedure as a DCM because of the intrinsic randomness that is associated with eigenvector directions and labels.
+
[[qter2dcm.m]] - Converts a unit quaternion into a directional cosine matrix.
  
−
[[dcm2quat.m]] – converts a directional cosine matrix representation of a rotation into a quaternion representation.
+
[[qter2euler.m]] - Converts a unit quaternion into Euler angles.
  
−
[[dcm2wigner.m]] – converts a directional cosine matrix (DCM) representation of a rotation into a Wigner matrix representation. Wigner matrices are ordered and signed to act on a vector of irreducible spherical tensor operator coefficients ordered as described in the function header. Numerous checks are implemented to stop the function if any loss of accuracy is likely to occur. It is not advisable to use the eigenvector matrix that comes out of a 3x3 interaction tensor diagonalization procedure as a DCM because of the intrinsic randomness that is associated with eigenvector directions and labels.
+
[[rotor_stack.m]] - Produces rotor stack of Liouvillians or Hamiltonians.
  
−
[[euler2dcm.m]] – converts Euler angles into the corresponding directional cosine matrix.
+
[[wigner.m]] - Converts Euler angles into Wigner rotation matrix.
  
−
[[wigner.m]] – converts Euler angles into the corresponding Wigner rotation matrix. Wigner matrices are ordered and signed to act on a vector of irreducible spherical tensor operator coefficients ordered as described in the function header.
+
[[qter2anax.m]] - Converts a quaternion into an angle-axis specification.
  
−
[[quat2anax.m]] – converts a quaternion rotation specification into an angle-axis specification.
+
[[rotmat_align.m]] - Rotation matrix aligning one vector with another vector.
  
−
[[quat2dcm.m]] – converts a quaternion representation of a rotation into a directional cosine matrix.
+
[[xyz2sph.m]] - Converts Cartesian into spherical coordinates.
  
 
==Interaction specification conventions==
 
==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.
 
[[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.
 
[[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.
 
[[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.
  
−
[[fract2cart.m]] – converts fractional crystallographic coordinates to Cartesian coordinates.
+
[[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.
 
[[gauss2mhz.m]] – converts hyperfine coupling tensors from Gauss to MHz.
  
 
[[hartree2joule.m]] – converts Hartree energy units to Joules.
 
[[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.
 
[[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.
 
[[xyz2dd.m]] – converts coordinates and periodic boundary conditions into 3x3 dipolar coupling matrices.
  
−
==SU(2) infrastructure==
+
[[zfs2mat.m]] - converts D and E zero-field splitting parameters into a diagonal 3x3 spin interaction matrix.
  
−
[[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.
+
==SU(2), SO(3), and other groups==
 +
[[add_spins.m]] - Reduces direct products of two su(2) irreps.
  
−
[[ist_product_table.m]] - structure coefficient tables for the associateive envelopes of su(mult) algebras.
+
[[cg_fast.m]] - fast but less accurate Clebsch-Gordan coefficient calculation.
  
−
[[pauli.m]] – generates Pauli matrices of a spin with user-specified multiplicity.
+
[[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.
  
−
[[p_superop.m]] – a general function returning user-specified right and left side product superoperators. Direct calls to this function are rarely necessary – please use operator.m unless the requested state is very exotic indeed. The function accepts operator specification in the internal Spinach notation: for each spin, identity state (or equivalently    spherical tensor operator) is numbered 0,  is numbered 1,  is numbered 2,  is numbered 3, and so on (Spinach supports all spin quantum numbers) -- irreducible spherical tensors are numbered by ascending ranks and within ranks by descending projection. The resulting sequence of integers is mapped by the kernel into the sequence of operators in the direct product. A call to [[p_superop.m]] with such a string as an argument would return a right or left side product superoperator corresponding to the direct product state specified.
+
[[hilb2liouv.m]] - Converts Hilbert space operators into Liouville space superoperators or state vectors.
  
−
==SO(3) infrastructure==
+
[[irr_sph_ten.m]] - Single-spin irreducible spherical tensor operators for a given spin multiplicity.
  
−
[[clebsch_gordan.m]] – computes Clebsch-Gordan coefficients using arbitrary-precision integer arithmetic. Indices in excess of 1,000 are handled without difficulty (a surprisingly non-trivial thing to achieve) and a fast analytical bypass is implemented for the coefficients encountered in the Stochastic Liouville Equation module.
+
[[ist_product_table.m]] - Structure coefficient tables for the associative envelopes of su(n) algebras.
  
−
[[perm_group.m]] – a database of common finite groups, including orders, classes and character tables. Used by the permutation symmetry module.
+
[[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: one rank 0 component, three rank 1 components and five rank 2 components to the total of nine independent components.
+
[[mat2sphten.m]] – translates 3x3 interaction tensors into irreducible spherical tensor coefficients.
  
−
[[sphten2mat.m]] – Converts the nine components of the irreducible spherical tensor representation of an interaction tensor into the Cartesian representation with a 3x3 matrix.
+
[[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.
 
[[spher_harmon.m]] – computes spherical harmonics.
  
−
[[wigner.m]] – computes Wigner matrices.
+
[[sphten2mat.m]] – irreducible spherical tensor coefficients into 3x3 matrix.
  
−
[[sle_operators.m]] - Wigner D function basis set and rotation generators.
+
[[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==
 
==Spatial dynamics infrastructure==
 +
 +
[[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 96: 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.
  
 
[[fpl2rho.m]] – partial trace with respect to spatial 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.
 
[[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.
 
[[phan2fpl.m]] – projects a phantom into the Fokker-Planck space.
  
−
[[corrfun.m]] – computes rotational correlation functions normalized to be correlation functions of second-rank Wigner functions. Handles isotropic, axial and fully anisotropic rotational diffusion. The 625 correlation functions possible with various index combinations in the latter case have been tested against a brute-force Monte-Carlo simulation of rotational diffusion. This function is used by the Redfield theory module.
+
[[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.
  
−
[[hydrodynamics.m]] - hydrodynamics infrastructure provider.
+
[[flow_gen.m]] - diffusion and flow generator builder.
  
 
==State space indexing and manipulation==
 
==State space indexing and manipulation==
  
−
[[absorb.m]] – designates specific states as "dark" -- any population reaching them would stay in them forever in a frozen state. This function is only available in sphten-liouv formalism.
+
[[adelim.m]] - adiabatic elimination
  
−
[[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.
+
[[coherence.m]] - coherence order selection
  
−
[[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.
+
[[correlation.m]] - correlation 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.
+
[[homospoil.m]] - transverse magnetisation removal
  
−
[[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.
+
[[human2opspec.m]] – converts human-readable operator specs into IST format
  
−
[[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
+
[[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==
  
−
[[slice_2d.m]] – displays slices of 2D spectra.
+
[[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_1d.m]] – 1D spectral plotting utility.
Line 150: Line 306:
 
[[plot_3d.m]] – 3D spectral plotting utility.
 
[[plot_3d.m]] – 3D spectral plotting utility.
  
−
[[volplot.m]] – volumetric ploting.
+
[[plot_uf.m]] - ultrafast NMR plotting utility.
  
−
[[molplot.m]] – stick plots of molecules.
+
[[pseudomodulation.m]] - Fourier-domain pseudomodulation of uniformly sampled spectra.
  
−
[[fprint.m]] – 2D spectrum fingerprinting utility.
+
[[slice_2d.m]] – displays slices of 2D spectra.
  
−
[[apodization.m]] – performs free induction decay apodization. Supports 1D, 2D and 3D FIDs.
+
[[stack_2d.m]] - stack plotting utility for 2D NMR spectra.
  
−
[[int_2d.m]] – 2D spectral integration utility.
+
[[mri_2d_plot.m]] - 2D MRI plotting utility.
  
 
[[sweep2ticks.m]] – converts spectral sweep width information into a vector of frequency axis ticks.
 
[[sweep2ticks.m]] – converts spectral sweep width information into a vector of frequency axis ticks.
  
−
[[tensor_analysis.m]] – returns basic diagnostic information about a 3x3 interaction tensor.
+
[[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==
 
== 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.
  
−
[[dirdiff.m]] – directional derivatives of matrix exponentials.
+
[[lorentzcon.m]] - Normalised Lorentzian function and its convolution with a triangular function.
  
−
[[expmint.m]] – matrix exponential integrals.
+
[[md5_hash.m]] - Returns MD5 hashes of matrices.
  
−
[[hdot.m]] – Hadamard matrix product, a full sum of an element-by-element product of two matrices. Used as a computationally efficient way of computing the trace of a product of two matrices.
+
[[mprealloc.m]] - Preallocates an operator in the current formalism and basis.
  
−
[[krondelta.m]] – Kronecker's delta symbol.
+
[[pink_noise.m]] - trajectories of a real random process with a 1/f power spectral density.
  
−
[[md5_hash.m]] – returns MD5 hashes of matrices.
+
[[remncomm.m]] - The part of the matrix that commutes with another matrix.
  
−
[[mprealloc.m]] – preallocates an operator in the current formalism and basis.
+
[[remtrace.m]] - Zeroes out the trace of a 3x3 interaction tensor.
  
−
[[unit_oper.m]] – returns a unit operator in the current formalism and basis.
+
[[rootmatch.m]] - Order-preserving root matching between three magnetic field root lists.
  
−
[[unit_state.m]] – returns a unit state in the current formalism and basis.
+
[[rspert.m]] - Rayleigh-Schrodinger perturbation theory to arbitrary order.
  
−
[[clean_up.m]] – sparse matrix clean-up utility. Drops all elements that are found to be smaller in absolute value than a user-specified threshold from the non-zero index of a sparse array. If a dense array is supplied as an input, it is returned unchanged. If the sparse array is found to have non-zero density above the Spinach threshold (spin_system.tols.dense_matrix), the array is converted into dense type. This utility is invoked after every sparse matrix-matrix multiplication in Spinach in order to remove inconsequential non-zeros and keep the memory footprint to a minimum. The functions that critically rely on array clean-up for efficiency are the matrix exponentiation and the Redfield theory module.
+
[[rspt_eig.m]] - Eigensystems of spin Hamiltonians and their derivatives.
  
−
[[statmerge.m]] – merges means and standard deviations for multiple sample sets.
+
[[sgolaydiff.m]] - Savitzky-Golay differentiation of noisy sampled signals.
  
−
[[symmetrize.m]] – symmetrises 3x3 interaction tensors. Antisymmetric (i.e. spherical tensor rank 1) parts of many spin interactions are inconsequential and best ignored in practical simulations.
+
[[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_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_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.
 
[[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==
 
==Housekeeping functions==
  
−
[[report.m]] – Spinach kernel user feedback function, should not be called directly.
+
[[banner.m]] - prints console banners.
  
−
[[pad.m]] – pads character strings with spaces.
+
[[cacheman.m]] - cache management heuristics for the scratch folder.
  
−
[[significant.m]] – returns true of the supplied object is significant to the specified tolerance.
+
[[compile_mex.m]] - MEX compilation utility.
  
−
[[negligible.m]] – returns true if the object supplied is negligible to the given tolerance.
+
[[dipolar.m]] - converts coordinates into dipolar coupling tensors. This function is called by Spinach kernel and should not be used directly.
  
−
[[summary.m]] – prints various summaries for Spinach kernel. Should not be called directly.
+
[[existentials.m]] - kernel integrity control, checks for function name collisions.
  
−
[[tolerances.m]] – tolerance information for Spinach kernel. Should not be called directly.
+
[[exorcise.m]] - enforces the house style on the ''Spinach'' code base.
  
−
[[existentials.m]] – kernel integrity control function. Should not be called directly.
+
[[forum.m]] - opens the Spinach support forum page.
  
−
[[dipolar.m]] – converts coordinates into dipolar coupling tensors. This function is called by Spinach kernel and should not be used directly.
+
[[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.
 
[[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]]''

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"