# penalty.m

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.

fd_opt       - finite difference options for 'DNS' penalty function.
Two element numeric array with first element being the
number of points in the finite difference stencil, and
the second element the order of the derivative required.


## Returns

    pen_term     - value of the penalty term.

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:

$\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}$

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.