Difference between revisions of "Grape liouv.m"

From Spinach Documentation Wiki
Jump to: navigation, search
m
(sync with Spinach main 3975f139: trajectory cost terms)
 
(19 intermediate revisions by 2 users not shown)
Line 1: Line 1:
−
{{DISPLAYTITLE:grape.m}}
+
{{DISPLAYTITLE:grape_liouv.m}} __NOTOC__
−
 
+
Gradient Ascent Pulse Engineering (GRAPE) objective function, gradient, and Hessian. Propagates the system through a user-supplied shaped pulse from a given initial state and projects the result onto the given final state. The fidelity is returned, along with its gradient and Hessian with respect to amplitudes of all control operators at every time step of the shaped pulse. Uses Liouville-space formalism.
−
Gradient Ascent Pulse Engineering (GRAPE) fidelity, gradient and Hessian. Propagates the system through a user-supplied shaped pulse from a given initial state and projects the result onto the given final state. The real part of the projection is returned, along with its gradient and Hessian with respect to amplitudes of all operators in every time step of the shaped pulse.  
 
  
 
==Syntax==
 
==Syntax==
  
−
    [diag_data,fidelity,total_grad,total_hess]=grape(spin_sys,ctrl_sys,drift,waveform)
+
        [traj_data,fidelity,...
 +
        grad,hess]=grape_liouv(spin_system,drifts,controls,...
 +
                                waveform,rho_init,rho_targ,...
 +
                                fidelity_type)
  
−
==Description==
+
==Parameters==
−
Four derivative calculation methods are available: Hausdorff series, second order central finite difference, fourth order central finite difference and Sophie Schirmer's expm algorithm. The default (Sophie's algorithm) is fast and accurate to machine precision. Sophie Schirmer’s expm algorithm is the only option for the Newton‐Raphson method..
 
−
 
 
−
==Arguments==
 
−
 
 
−
    spin_sys      - spin system
 
−
   
 
−
    ctrl_sys      - [[control_sys.m|control system]]
 
−
   
 
−
    drift          - Drift [[Hamiltonian.m|Hamiltonian]]. The "drift" Liouvillian:
 
−
                      couplings, relaxation and other things that continue operating
 
−
                      while the pulse is being executed.
 
−
   
 
−
    waveform      - matrix of doubles with n_controls rows and n_steps columns,
 
−
                      where n_controls is the number of control operators  and n_steps
 
−
                      is the number of steps in the waveform. The waveform should be
 
−
                      specified as fractions of the total power level, which is
 
−
                      specified separately.
 
  
 +
  spin_system        - Spinach data object that has been through
 +
                        the [[optimcon.m]] problem setup function.
 +
 +
  drifts              - the drift Liouvillians: a cell array con-
 +
                        taining one matrix (for time-independent
 +
                        drift) or multiple matrices (one per time
 +
                        slice / point, for time-dependent drift).
 +
 +
  controls            - control operators in Liouville space (cell
 +
                        array of matrices).
 +
 +
  waveform            - control coefficients for each control ope-
 +
                        rator (in vertical dimension) at each time
 +
                        slice / point (horizonal dimension), rad/s
 +
 +
  rho_init            - initial state of the system as a vector in
 +
                        Liouville space, ignored in stroboscopic
 +
                        steady state optimisations.
 +
 +
  rho_targ            - target state of the system as a vector in
 +
                        Liouville space.
 +
 +
  fidelity_type      - 'real'  (real part of the overlap)
 +
                        'imag'  (imaginary part of the overlap)
 +
                        'square' (absolute square of the overlap)
  
 
==Returns==
 
==Returns==
  
−
    diag_data      - diagnostics data structure, containing complete information about
+
  fidelity            - fidelity of the control sequence
−
                      the calculation. It has the following self‐explanatory fields:
+
−
                              diag_data.current_state
+
  grad                - gradient of the fidelity with respect to
−
                              diag_data.rho
+
                        the control sequence
−
                              diag_data.target
+
−
                              diag_data.total_objective
+
  hess                - Hessian of the fidelity with respect to  
−
                              diag_data.spin_system
+
                        the control sequence, not available for
−
                              diag_data.power_level
+
                        piecewise-linear and stroboscopic stea-
−
                              diag_data.trajectory
+
                        dy state optimisations
−
                              diag_data.total_grad
+
−
                              diag_data.total_hess
+
  traj_data.forward  - forward trajectory from the initial con-
−
                              diag_data.dt
+
                        dition or stroboscopic steady state (a
−
                              diag_data.controls
+
                        stack of state vectors); this is returned
−
                              diag_data.waveform
+
                        only when requested by the control settings
−
                              diag_data.nsteps
 
−
                              diag_data.drift
 
−
   
 
−
    fidelity       - the value of the GRAPE objective function.
 
−
   
 
−
    total_grad    - the gradient of the objective function with respect to control amplitudes.
 
−
   
 
−
    total_hess    - the Hessian of the objective function with respect to control amplitudes.
 
−
 
 
  
 
==Notes==
 
==Notes==
 +
This is a low level function that is not designed to be called directly. Use [[grape_xy.m]], [[grape_phase.m]], or other wrapper functions instead.
  
 +
Trajectory cost terms are read from spin_system.control: when fid_type is 'average', the fidelity is averaged over the pulse nodes 1..N instead of being taken at the last node; traj_pen operators are summed, their expectation value is averaged over the same nodes and subtracted from the fidelity. Both terms use costates that ride on the backward sweep, the trajectory never leaves the worker. Hessians are not available with these terms.
  
 
==See also==
 
==See also==
−
[[dirdiff.m]], [[step.m]], [[control_sys.m]]
+
[[dirdiff.m]], [[step.m]], [[optimcon.m]], [[grape_xy.m]], [[grape_phase.m]], [[penalty.m]], [[grape_coop.m]], [[grape_curv.m]], [[grape_hilb.m]], [[tgrape.m]], [[Optimal_control_module]]
−
 
 
  
−
''Version 1.9, authors: [[Ilya Kuprov]], [[David Goodwin]]''
+
''Version 2.2, authors: [[Ilya Kuprov]], [[David Goodwin]], [[Uluk Rasulov]], [[Maxi Keitel]]''

Latest revision as of 10:59, 18 September 2026

Gradient Ascent Pulse Engineering (GRAPE) objective function, gradient, and Hessian. Propagates the system through a user-supplied shaped pulse from a given initial state and projects the result onto the given final state. The fidelity is returned, along with its gradient and Hessian with respect to amplitudes of all control operators at every time step of the shaped pulse. Uses Liouville-space formalism.

Syntax

       [traj_data,fidelity,...
        grad,hess]=grape_liouv(spin_system,drifts,controls,...
                               waveform,rho_init,rho_targ,...
                               fidelity_type)

Parameters

  spin_system         - Spinach data object that has been through 
                        the optimcon.m problem setup function.

  drifts              - the drift Liouvillians: a cell array con-
                        taining one matrix (for time-independent 
                        drift) or multiple matrices (one per time
                        slice / point, for time-dependent drift).

  controls            - control operators in Liouville space (cell 
                        array of matrices).

  waveform            - control coefficients for each control ope-
                        rator (in vertical dimension) at each time
                        slice / point (horizonal dimension), rad/s

  rho_init            - initial state of the system as a vector in
                        Liouville space, ignored in stroboscopic
                        steady state optimisations.

  rho_targ            - target state of the system as a vector in
                        Liouville space.

  fidelity_type       - 'real'   (real part of the overlap)
                        'imag'   (imaginary part of the overlap)
                        'square' (absolute square of the overlap)

Returns

  fidelity            - fidelity of the control sequence

  grad                - gradient of the fidelity with respect to
                        the control sequence

  hess                - Hessian of the fidelity with respect to 
                        the control sequence, not available for
                        piecewise-linear and stroboscopic stea-
                        dy state optimisations

  traj_data.forward   - forward trajectory from the initial con-
                        dition or stroboscopic steady state (a 
                        stack of state vectors); this is returned
                        only when requested by the control settings

Notes

This is a low level function that is not designed to be called directly. Use grape_xy.m, grape_phase.m, or other wrapper functions instead.

Trajectory cost terms are read from spin_system.control: when fid_type is 'average', the fidelity is averaged over the pulse nodes 1..N instead of being taken at the last node; traj_pen operators are summed, their expectation value is averaged over the same nodes and subtracted from the fidelity. Both terms use costates that ride on the backward sweep, the trajectory never leaves the worker. Hessians are not available with these terms.

See also

dirdiff.m, step.m, optimcon.m, grape_xy.m, grape_phase.m, penalty.m, grape_coop.m, grape_curv.m, grape_hilb.m, tgrape.m, Optimal_control_module

Version 2.2, authors: Ilya Kuprov, David Goodwin, Uluk Rasulov, Maxi Keitel

Retrieved from "https://spindynamics.org/wiki/index.php?title=Grape_liouv.m&oldid=10332"