Difference between revisions of "Step.m"

From Spinach Documentation Wiki
Jump to: navigation, search
(Sync syntax/arguments/outputs with current Spinach source)
(Update function See also links and function index membership)
 
(6 intermediate revisions by the same user not shown)
Line 1: Line 1:
 
{{DISPLAYTITLE:step.m}} __NOTOC__
 
{{DISPLAYTITLE:step.m}} __NOTOC__
 
+
Propagation step function. Computes the action by a matrix exponential without computing that exponential. Supports one-, two-, and three-point product quadratures.
Time propagation function optimised for ''one-off calls'', such as hard pulses or slices of shaped pulses. For trajectory calculation and detection periods of time-domain experiments, use [[evolution.m]] instead. In Liouville space, this function calculates the action by a matrix exponential on a vector without computing the matrix exponential. This is cheaper than matrix exponentiation, but only when it is performed once. If many time steps are required, it is cheaper to pre-compute the exponential, which is what [[evolution.m]] does.
 
  
 
==Syntax==
 
==Syntax==
  
rho=step(spin_system,L,rho,time_step)
+
    rho=step(spin_system,L,rho,time_step)
  
==Arguments==
+
==Parameters==
  
L          -  Liouvillian or Hamiltonian to be used for
 
                    propagation; centre point piecewise-constant
 
                    rule if one matrix is supplied, piecewise-
 
                    linear rule if two matrices {left, right}
 
                    are supplied, piecewise-quadratic if three
 
                    matrices {left, midpoint, right} are given.
 
  
                    State-dependent evolution generators are
 
                    supported: if L{1} is a function handle (see
 
                    iserstep.m documentation), L{2} is current
 
                    time, and L{3} is the method (see iserstep.m
 
                    documentation), the problem is routed to a
 
                    an appropriate Lie group solver.
 
 
      rho        -  state vector or density matrix to be propagated
 
  
 +
      L          -  Liouvillian or Hamiltonian to be used for propagation;
 +
                    centre point piecewise-constant rule if one matrix is
 +
                    supplied, piecewise-linear rule if two matrices {left,
 +
                    right} are supplied, and piecewise-quadratic rule if
 +
                    three matrices {left, midpoint, right} are supplied.
 +
                    State-dependent evolution generators are also supported:
 +
                    if L{1} is a function handle, L{2} is current time, and
 +
                    L{3} is the method, the problem is routed to iserstep.m
 +
 +
      rho        -  state vector or density matrix
 +
 
       time_step  -  length of the time step to take
 
       time_step  -  length of the time step to take
 
Note: we initially had a faithful implementation of the Krylov process
 
      here - subspace, orthogonalisation, projection, etc., but in all
 
      our testing it was much inferior to the reordered Taylor process
 
      that is currently implemented below.
 
 
Note: the peculiar sequence of algebraic operations in the code below
 
      is designed to minimise the memory footprint in large cases.
 
 
ilya.kuprov@weizmann.ac.il
 
ledwards@cbs.mpg.de
 
a.acharya@soton.ac.uk
 
c.musselwhite@soton.ac.uk
 
  
 
==Outputs==
 
==Outputs==
  
rho        -  state vector or density matrix
+
      rho        -  state vector or density matrix
  
 
==Examples==
 
==Examples==
 
 
A 90-degree pulse in X phase on protons:
 
A 90-degree pulse in X phase on protons:
  
Line 65: Line 47:
 
==Notes==
 
==Notes==
  
#The function is programmed with a rather peculiar order of algebraic operations. This was carefully optimised to ensure best possible performance under a variety of scenarios (parallelisation, GPUs, large sparse arrays) in Matlab.
+
 
#Only use this function for short one-off events where you do not expect to see the same Liouvillian again. Long-term propagation (trajectories, observables) under a static Liouvillian should be handled with [[evolution.m]] or [[krylov.m]] functions instead.
+
This function originally used a faithful Krylov process, but testing found it inferior to the reordered Taylor process now used in the implementation. The current algebraic operation order is designed to minimise memory footprint in large cases.
  
 
==See also==
 
==See also==
 
+
[[evolution.m]], [[krylov.m]], [[propagator.m]], [[shaped_pulse_xy.m]], [[shaped_pulse_af.m]], [[cosy.m]], [[hsqc.m]], [[isergen.m]], [[iserstep.m]], [[steady.m]], [[Kernel_functions]]
[[Kernel_functions#Time_evolution|Time evolution functions]], [[evolution.m]], [[krylov.m]], [[propagator.m]], [[shaped_pulse_xy.m]], [[shaped_pulse_af.m]]
 
 
 
  
 
''Version 2.8, authors: [[Ilya Kuprov]], [[Luke Edwards]], [[Anupama Acharya]]''
 
''Version 2.8, authors: [[Ilya Kuprov]], [[Luke Edwards]], [[Anupama Acharya]]''

Latest revision as of 19:41, 6 June 2026

Propagation step function. Computes the action by a matrix exponential without computing that exponential. Supports one-, two-, and three-point product quadratures.

Syntax

    rho=step(spin_system,L,rho,time_step)

Parameters

     L          -  Liouvillian or Hamiltonian to be used for propagation;
                   centre point piecewise-constant rule if one matrix is
                   supplied, piecewise-linear rule if two matrices {left,
                   right} are supplied, and piecewise-quadratic rule if
                   three matrices {left, midpoint, right} are supplied.
                   State-dependent evolution generators are also supported:
                   if L{1} is a function handle, L{2} is current time, and
                   L{3} is the method, the problem is routed to iserstep.m

     rho        -  state vector or density matrix

     time_step  -  length of the time step to take

Outputs

     rho        -  state vector or density matrix

Examples

A 90-degree pulse in X phase on protons:

   Lx=operator(spin_system,'Lx','1H');
   rho=step(spin_system,Lx,rho,pi/2);

A 1 millisecond evolution period under a Hamiltonian H:

   rho=step(spin_system,H,rho,1e-3);

A 45-degree pulse with a 60-degree phase on carbon:

   Lx=operator(spin_system,'Lx','13C');
   Ly=operator(spin_system,'Ly','13C');
   rho=step(spin_system,cosd(60)*Lx+sind(60)*Ly,rho,pi/4);

See also the source code of shaped_pulse_xy.m and most NMR pulse sequences (cosy.m, hsqc.m, and others) for examples of this function being used.

Notes

This function originally used a faithful Krylov process, but testing found it inferior to the reordered Taylor process now used in the implementation. The current algebraic operation order is designed to minimise memory footprint in large cases.

See also

evolution.m, krylov.m, propagator.m, shaped_pulse_xy.m, shaped_pulse_af.m, cosy.m, hsqc.m, isergen.m, iserstep.m, steady.m, Kernel_functions

Version 2.8, authors: Ilya Kuprov, Luke Edwards, Anupama Acharya