Difference between revisions of "Kernel contexts"
(Index the new Spinach 2.12 spin-boson functions and tutorial (PR 195)) |
|||
| (24 intermediate revisions by 2 users not shown) | |||
| Line 1: | Line 1: | ||
| − | A context is an intermediate layer between the kernel (which runs the mathematics) and the experiment (which is programmed as it would be on a spectrometer). Context functions are responsible for | + | A context is an intermediate layer between the kernel (which runs the mathematics) and the experiment (which is programmed as it would be on a spectrometer). Context functions are responsible for creating operators (evolution, kinetics, relaxation, diffusion, ''etc.'') and for running miscellaneous housekeeping (rotating frame transformations, transmitter offsets, powder averages, magic angle spinning, ''etc.''). |
| + | |||
| + | Most built-in pulse sequences in Spinach should be called via a context, for example: | ||
| + | |||
| + | fid=[[liquid.m|liquid]](spin_system,[[noesy.m|@noesy]],parameters,'nmr'); | ||
| + | |||
| + | This calls [[liquid.m]] context and tells it that [[noesy.m]] must be called. The parameters and the spin system are specified with the [[assume.m|assumptions]] set to liquid state NMR. The context function will build the Hamiltonian, the relaxation superoperator, the kinetics superoperator, apply the offsets and the rotating frame transformations, and pass the resulting operators to [[noesy.m]], which runs the simulation. | ||
| + | |||
| + | In this way, a lot of work is saved to whoever has to program the pulse sequence, particularly in situations when the operators and settings involved are complicated, ''e.g.'' gradients, diffusion and flow. ''Spinach'' contexts generate all of those in correct units and correct normalisation; the pulse sequence should simply treat them as a given. Because parameter lists of different pulse sequences are broadly similar, this allows rapid switching of the simulation context (for example, from liquid to powder) by simply calling the same experiment from a different context. | ||
| + | |||
| + | ==Available contexts== | ||
# [[crystal.m]] - single static orientation simulations. | # [[crystal.m]] - single static orientation simulations. | ||
| + | # [[device.m]] - spin-boson device simulations: spins together with cavity modes, phonon modes, and transmons declared in inter.modes. | ||
# [[doublerot.m]] - double rotation simulations using Fokker-Planck formalism for the rotation part and a spherical grid for the powder average operation. | # [[doublerot.m]] - double rotation simulations using Fokker-Planck formalism for the rotation part and a spherical grid for the powder average operation. | ||
# [[floquet.m]] - single rotation simulations using Floquet formalism for the rotation part and a spherical grid for the powder average operation. | # [[floquet.m]] - single rotation simulations using Floquet formalism for the rotation part and a spherical grid for the powder average operation. | ||
# [[gridfree.m]] - single rotation simulations using Fokker-Planck formalism for both the rotation part and the powder average operation. This module also supports stochastic Liouville equation formalism for spin relaxation theory. | # [[gridfree.m]] - single rotation simulations using Fokker-Planck formalism for both the rotation part and the powder average operation. This module also supports stochastic Liouville equation formalism for spin relaxation theory. | ||
| − | # [[imaging.m]] - | + | # [[imaging.m]] - imaging and spatial encoding simulations. |
# [[liquid.m]] - liquid state simulations. | # [[liquid.m]] - liquid state simulations. | ||
# [[powder.m]] - static powder simulations using a spherical grid for the powder average operation. | # [[powder.m]] - static powder simulations using a spherical grid for the powder average operation. | ||
| − | # [[ | + | # [[meshflow.m]] - microfluidic simulations where spin dynamics is accompanied by chemical reactions, diffusion, and flow. |
# [[singlerot.m]] - single rotation simulations using Fokker-Planck formalism for the rotation part and a spherical grid for the powder average operation. | # [[singlerot.m]] - single rotation simulations using Fokker-Planck formalism for the rotation part and a spherical grid for the powder average operation. | ||
| − | + | ==Call syntax for spectroscopy contexts== | |
| + | |||
| + | The following is a syntax example for a spectroscopy context (in this case DOR NMR): | ||
answer=doublerot(spin_system,pulse_sequence,parameters,assumptions); | answer=doublerot(spin_system,pulse_sequence,parameters,assumptions); | ||
| − | and | + | The first argument is the spin system object, the second is a function handle for the pulse sequence, the third is the parameter set expected by the sequence, and the last argument is the [[assume.m|assumption set]]. |
| + | |||
| + | All pulse sequences using a spectroscopy context must have the following call syntax: | ||
answer=pulse_sequence(spin_system,parameters,H,R,K); | answer=pulse_sequence(spin_system,parameters,H,R,K); | ||
| − | where H is the Hamiltonian commutation superoperator, R is the relaxation superoperator, and K is the kinetics superoperator. | + | where H is the Hamiltonian commutation superoperator, R is the relaxation superoperator, and K is the kinetics superoperator. |
| + | |||
| + | ==Call syntax for imaging and microfluidics contexts== | ||
The imaging context has a similar call: | The imaging context has a similar call: | ||
| Line 25: | Line 42: | ||
answer=imaging(spin_system,pulse_sequence,parameters) | answer=imaging(spin_system,pulse_sequence,parameters) | ||
| − | but the assumptions are set internally to 'nmr' | + | but the assumptions are set internally to 'nmr'. All pulse sequences using the imaging context must have the following syntax: |
answer=pulse_sequence(spin_system,parameters,H,R,K,G,F); | answer=pulse_sequence(spin_system,parameters,H,R,K,G,F); | ||
| − | where H is the Hamiltonian commutation superoperator, R is the relaxation superoperator, K is the kinetics superoperator, G is a cell array of three gradient operators | + | where H is the Hamiltonian commutation superoperator, R is the relaxation superoperator, K is the kinetics superoperator, G is a cell array of three gradient operators normalised to 1 Tesla/m, and F is the diffusion and flow superoperator. |
| + | |||
| + | ==Call syntax for the device context== | ||
| + | |||
| + | Devices containing bosonic modes - cavities, phonon modes, and transmons - are not molecules in magnets: the spin subsystem has an orientation, the modes do not. They are therefore run through [[device.m]] rather than through the spectroscopy contexts: | ||
| + | |||
| + | answer=device(spin_system,pulse_sequence,parameters,'cavity'); | ||
| + | |||
| + | The assumption set must be 'labframe', 'cavity', or 'spin-phonon'. In addition to the usual spin channel parameters, this context accepts parameters.mode_offset (detuning offsets for the bosonic modes, one per mode, in the transmitter sign convention) and supplies the thermal equilibrium state including Bose-Einstein mode populations when 'rho_eq' is requested in parameters.needs. | ||
| + | |||
| + | |||
| + | ''Version 2.8, authors: [[Ilya Kuprov]]'' | ||
Latest revision as of 05:42, 6 August 2026
A context is an intermediate layer between the kernel (which runs the mathematics) and the experiment (which is programmed as it would be on a spectrometer). Context functions are responsible for creating operators (evolution, kinetics, relaxation, diffusion, etc.) and for running miscellaneous housekeeping (rotating frame transformations, transmitter offsets, powder averages, magic angle spinning, etc.).
Most built-in pulse sequences in Spinach should be called via a context, for example:
fid=liquid(spin_system,@noesy,parameters,'nmr');
This calls liquid.m context and tells it that noesy.m must be called. The parameters and the spin system are specified with the assumptions set to liquid state NMR. The context function will build the Hamiltonian, the relaxation superoperator, the kinetics superoperator, apply the offsets and the rotating frame transformations, and pass the resulting operators to noesy.m, which runs the simulation.
In this way, a lot of work is saved to whoever has to program the pulse sequence, particularly in situations when the operators and settings involved are complicated, e.g. gradients, diffusion and flow. Spinach contexts generate all of those in correct units and correct normalisation; the pulse sequence should simply treat them as a given. Because parameter lists of different pulse sequences are broadly similar, this allows rapid switching of the simulation context (for example, from liquid to powder) by simply calling the same experiment from a different context.
Contents
Available contexts
- crystal.m - single static orientation simulations.
- device.m - spin-boson device simulations: spins together with cavity modes, phonon modes, and transmons declared in inter.modes.
- doublerot.m - double rotation simulations using Fokker-Planck formalism for the rotation part and a spherical grid for the powder average operation.
- floquet.m - single rotation simulations using Floquet formalism for the rotation part and a spherical grid for the powder average operation.
- gridfree.m - single rotation simulations using Fokker-Planck formalism for both the rotation part and the powder average operation. This module also supports stochastic Liouville equation formalism for spin relaxation theory.
- imaging.m - imaging and spatial encoding simulations.
- liquid.m - liquid state simulations.
- powder.m - static powder simulations using a spherical grid for the powder average operation.
- meshflow.m - microfluidic simulations where spin dynamics is accompanied by chemical reactions, diffusion, and flow.
- singlerot.m - single rotation simulations using Fokker-Planck formalism for the rotation part and a spherical grid for the powder average operation.
Call syntax for spectroscopy contexts
The following is a syntax example for a spectroscopy context (in this case DOR NMR):
answer=doublerot(spin_system,pulse_sequence,parameters,assumptions);
The first argument is the spin system object, the second is a function handle for the pulse sequence, the third is the parameter set expected by the sequence, and the last argument is the assumption set.
All pulse sequences using a spectroscopy context must have the following call syntax:
answer=pulse_sequence(spin_system,parameters,H,R,K);
where H is the Hamiltonian commutation superoperator, R is the relaxation superoperator, and K is the kinetics superoperator.
Call syntax for imaging and microfluidics contexts
The imaging context has a similar call:
answer=imaging(spin_system,pulse_sequence,parameters)
but the assumptions are set internally to 'nmr'. All pulse sequences using the imaging context must have the following syntax:
answer=pulse_sequence(spin_system,parameters,H,R,K,G,F);
where H is the Hamiltonian commutation superoperator, R is the relaxation superoperator, K is the kinetics superoperator, G is a cell array of three gradient operators normalised to 1 Tesla/m, and F is the diffusion and flow superoperator.
Call syntax for the device context
Devices containing bosonic modes - cavities, phonon modes, and transmons - are not molecules in magnets: the spin subsystem has an orientation, the modes do not. They are therefore run through device.m rather than through the spectroscopy contexts:
answer=device(spin_system,pulse_sequence,parameters,'cavity');
The assumption set must be 'labframe', 'cavity', or 'spin-phonon'. In addition to the usual spin channel parameters, this context accepts parameters.mode_offset (detuning offsets for the bosonic modes, one per mode, in the transmitter sign convention) and supplies the thermal equilibrium state including Bose-Einstein mode populations when 'rho_eq' is requested in parameters.needs.
Version 2.8, authors: Ilya Kuprov
