Difference between revisions of "Grape.m"

From Spinach Documentation Wiki
Jump to: navigation, search
(basics of grape.m (outdated))
(Updated to the current doc style and updated to current syntax + options)
Line 1: Line 1:
 
{{DISPLAYTITLE:grape.m}}
 
{{DISPLAYTITLE:grape.m}}
  
Gradient Ascent Pulse Engineering (GRAPE) objective function and gradient. 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 with respect to amplitudes of all operators in every step of the shaped pulse.
+
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.  
  
    [diag_data,total_objective,total_grad,total_hess]=...
+
==Syntax==
          [[grape]](spin_system,drift,controls,waveform,time_step,nsteps,...
 
          initial_state_array,target_state_array,power_level)
 
  
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.
+
    [diag_data,fidelity,total_grad,total_hess]=grape(spin_sys,ctrl_sys,drift,waveform)
  
=Inputs=
+
==Description==
{| class="wikitable"
+
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..
|'spin_system'
 
|A spin system created with Spinach should always be passed to the grape optimal control module.
 
|-
 
|'drift'
 
|the "drift" Liouvillian: couplings, relaxation and other things that continue operating while the pulse is being executed.
 
|-
 
|'controls'
 
|a cell array of commutation superoperators whose coefficients are getting modulated by the pulse, e.g. {Lx,Ly}.
 
|-
 
|'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.
 
|-
 
|'time_step'
 
|waveform time step, in seconds.
 
|-
 
|'nsteps'
 
|number of time steps in the waveform.
 
|-
 
|'initial_state_array'
 
|cell array of initial state vectors (if multiple sources and targets are supplied, the resulting objective function and the gradient are sums over these source‐target pairs).
 
|-
 
|'target_state_array'
 
|a cell array of target state vectors (if multiple sources and targets are supplied, the resulting objective function and the gradient are sums over these source‐target pairs).
 
|-
 
|'power_level'
 
|nominal power level, in units of angular frequency. The waveform values should be specified as fractions of this power level.
 
|}
 
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.
 
  
=Outputs=
+
==Arguments==
{| class="wikitable"
 
|'total_objective'
 
|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 when
 
using the Newton‐Raphson method.
 
|-
 
|'diag_data'
 
|diagnostics data structure, containing complete information about the calculation. It has the following self‐explanatory fields:
 
  
diag_data.initial_state_array
+
    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.
  
diag_data.target_state_array
 
  
diag_data.total_objective
+
==Returns==
  
diag_data.spin_system  
+
    diag_data      - diagnostics data structure, containing complete information about
 +
                      the calculation. It has the following self‐explanatory fields:
 +
                              diag_data.current_state
 +
                              diag_data.rho
 +
                              diag_data.target
 +
                              diag_data.total_objective
 +
                              diag_data.spin_system
 +
                              diag_data.power_level
 +
                              diag_data.trajectory
 +
                              diag_data.total_grad
 +
                              diag_data.total_hess
 +
                              diag_data.dt
 +
                              diag_data.controls
 +
                              diag_data.waveform
 +
                              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.
  
diag_data.power_level
 
  
diag_data.trajectory
+
==Notes==
  
diag_data.total_grad
 
  
diag_data.total_hess
+
==See also==
 +
[[dirdiff.m]], [[step.m]], [[control_sys.m]]
  
diag_data.time_step
 
  
diag_data.controls
+
''Revision 3399, authors: [[Ilya Kuprov]], [[David Goodwin]]''
 
 
diag_data.waveform
 
 
 
diag_data.nsteps
 
 
 
diag_data.drift
 
|}
 

Revision as of 11:55, 2 September 2016


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

    [diag_data,fidelity,total_grad,total_hess]=grape(spin_sys,ctrl_sys,drift,waveform)

Description

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 system
    
    drift          - Drift 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.


Returns

    diag_data      - diagnostics data structure, containing complete information about 
                     the calculation. It has the following self‐explanatory fields:
                             diag_data.current_state
                             diag_data.rho
                             diag_data.target
                             diag_data.total_objective
                             diag_data.spin_system
                             diag_data.power_level
                             diag_data.trajectory
                             diag_data.total_grad
                             diag_data.total_hess
                             diag_data.dt
                             diag_data.controls
                             diag_data.waveform
                             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

See also

dirdiff.m, step.m, control_sys.m


Revision 3399, authors: Ilya Kuprov, David Goodwin