Difference between revisions of "Penalty.m"

From Spinach Documentation Wiki
Jump to: navigation, search
(basics of penalty.m (outdated))
(Created basic page for the penalty.m function)
Line 1: Line 1:
 
{{DISPLAYTITLE:penalty.m}}
 
{{DISPLAYTITLE:penalty.m}}
  
This describes penalty terms for pulse waveforms. Returns the penalty function and its gradient for the waveform, which should be supplied as row vector or a horizontal stack thereof. Syntax:
+
Penalty terms for the Optimal Control module. Returns the penalty function and its gradient for the waveform, which should be supplied as row vector or a horizontal stack thereof.  
  
    [penalty_term,penalty_grad,penalty_hess]=...
+
==Syntax==
          penalty(waveform,type,floor_bound,ceiling_bound);
 
  
If a stack of waveforms is supplied, individual rows of the stack are treated as independent and the penalties are summed together. The penalty terms are usually evaluated within the [[cost_function]] passed as a nested function with its handle to [[fminnewton.m]].
+
    [pen_term,pen_grad,pen_hess]=penalty(wf,type,fb,cb)
  
=Inputs=
+
==Description==
{| class="wikitable"
+
This function looks at the edges of the spectrum and subtracts anything that it finds there from the entire spectrum. The assumption is that anything that's reached as far as the edge must be a streak artefact that should be removed. This is often the case in 2D and 3D NMR spectra.
|<tt>'waveform'</tt>
 
|pulse waveform, supplied as row vector or a horizontal stack thereof.
 
|-
 
|type=<tt>'DNS'</tt>
 
|derivative norm square penalty term, designed to favour smooth waveforms over jagged ones.
 
|-
 
|type=<tt>'NS'</tt>
 
|norm square penalty term, designed to favour low‐power wave forms over high‐power ones.
 
|-
 
|type=<tt>'SNS'</tt>
 
|spillout norm square penalty term, NS penalty applied to any part of the waveform whose value is outside the floor and ceiling bounds.
 
|-
 
|<tt>'floor_bound'</tt>
 
|lower bound waveform used in the SNS penalty function.
 
|-
 
|<tt>'ceiling_bound'</tt>
 
|upper bound waveform used in the SNS penalty function.
 
|}
 
If a stack of waveforms is supplied, individual rows of the stack are treated as independent and the penalties are summed together. The waveforms on different channels are assumed to be stored in the rows of the input array. The Hessian elements correspond to the elements of the waveform array ordered as:
 
  
    [X1 Y1 Z1 X2 Y2 Z2 ... Xn Yn Zn]
+
==Arguments==
  
 +
    wf          - control sequence waveform.
 +
   
 +
    type        - string which identifies penalty type:
 +
                    'NS', 'DNS', 'SNS', 'SNC'.
 +
   
 +
    fb          - floor bound, the lower bound on waveform used in the
 +
                    'SNS' and 'SNC' penalty function.
 +
   
 +
    cb          - ceiling bound, the upper bound on waveform used in the
 +
                    'SNS' and 'SNC' penalty function.
 +
 +
 +
 +
==Returns==
 +
 +
    pen_term    - value of the penalty term.
 +
   
 +
    pen_grad    - gradient of the penalty term with respect to wf.
 +
   
 +
    pen_hess    - Hessian of the penalty term with respect to wf.
 +
 +
==Penalty types==
 +
 +
    type='NS'    - norm square, designed to favour low-power
 +
                    waveforms over high-power ones.
 +
   
 +
    type='DNS'  - derivative norm square, designed to favour
 +
                    smooth waveforms over jagged ones.
 +
   
 +
    type='SNS'  - spillout norm square, 'NS' applied to the
 +
                    part of the waveform with values outside the
 +
                    floor and ceiling bounds.
 +
   
 +
    type='SNC'  - spillout norm cube, similar to 'SNS' except
 +
                    the penalty is a cube, not square.
 +
   
 +
 +
==Notes==
 +
The waveforms on different channels are assumed to be stored in the rows of the input array. The Hessian elements correspond to the elements of the waveform array ordered as:
 +
<center>
 +
<math>\begin{bmatrix}X_1 & X_2 & \cdots & X_n\\ Y_1 & Y_2 & \cdots & Y_n\\ Z_1 & Z_2 & \cdots & Z_n\end{bmatrix}</math>
 +
</center>
 
where X,Y,Z are different control channels and the index enumerates the time discretization points. Gradient dimensions and element order are the same as the input waveform dimensions and element order.
 
where X,Y,Z are different control channels and the index enumerates the time discretization points. Gradient dimensions and element order are the same as the input waveform dimensions and element order.
  
=Outputs=
+
==See also==
{| class="wikitable"
+
[[grape.m]], [[krotov.m]]
|<tt>'penalty_term'</tt>
+
 
|value of the penalty term.
+
 
|-
+
''Revision 3399, authors: [[Ilya Kuprov]], [[David Goodwin]]''
|<tt>'penalty_grad'</tt>
 
|gradient of the penalty term with respect to the waveform vector.
 
|-
 
|<tt>'penalty_hess'</tt>
 
|Hessian of the penalty term with respect to the waveform vector.
 
|}
 

Revision as of 21:04, 1 September 2016


Penalty terms for the Optimal Control module. Returns the penalty function and its gradient for the waveform, which should be supplied as row vector or a horizontal stack thereof.

Syntax

    [pen_term,pen_grad,pen_hess]=penalty(wf,type,fb,cb)

Description

This function looks at the edges of the spectrum and subtracts anything that it finds there from the entire spectrum. The assumption is that anything that's reached as far as the edge must be a streak artefact that should be removed. This is often the case in 2D and 3D NMR spectra.

Arguments

    wf           - control sequence waveform.
    
    type         - string which identifies penalty type:
                   'NS', 'DNS', 'SNS', 'SNC'.
    
    fb           - floor bound, the lower bound on waveform used in the
                   'SNS' and 'SNC' penalty function.
    
    cb           - ceiling bound, the upper bound on waveform used in the
                   'SNS' and 'SNC' penalty function.


Returns

    pen_term     - value of the penalty term.
    
    pen_grad     - gradient of the penalty term with respect to wf.
    
    pen_hess     - Hessian of the penalty term with respect to wf.

Penalty types

    type='NS'    - norm square, designed to favour low-power 
                   waveforms over high-power ones.
    
    type='DNS'   - derivative norm square, designed to favour 
                   smooth waveforms over jagged ones.
    
    type='SNS'   - spillout norm square, 'NS' applied to the 
                   part of the waveform with values outside the 
                   floor and ceiling bounds.
    
    type='SNC'   - spillout norm cube, similar to 'SNS' except 
                   the penalty is a cube, not square.
    

Notes

The waveforms on different channels are assumed to be stored in the rows of the input array. The Hessian elements correspond to the elements of the waveform array ordered as:

[math]\begin{bmatrix}X_1 & X_2 & \cdots & X_n\\ Y_1 & Y_2 & \cdots & Y_n\\ Z_1 & Z_2 & \cdots & Z_n\end{bmatrix}[/math]

where X,Y,Z are different control channels and the index enumerates the time discretization points. Gradient dimensions and element order are the same as the input waveform dimensions and element order.

See also

grape.m, krotov.m


Revision 3399, authors: Ilya Kuprov, David Goodwin