Ipcs.m

3D reconstruction of paramagnetic centre probability density from PCS data using Kuprov-Charnock equation (http://dx.doi.org/10.1039/C4CP03106G).

Syntax

    [source_cube,ranges,pred_pcs,err_ls,reg_a,reg_b]=ipcs(parameters,npoints,lambda)

Description

This function implements the three-dimensional paramagnetic centre probability density algorithm described in our forthcoming paper on the subject. The user needs to supply atomic coordinates and pseudocontact shifts. The algorithm uses Tikhonov regularisation. In the argument description below, "source" refers to the probability density of the paramagnetic centre that generates the pseudocontact shift, and "solution" refers to the pseudocontact shift itself.

Arguments

    parameters.xyz      - nuclear coordinates as [x y z] with multiple rows 
                          at which PCS has been measured, in Angstrom.

    parameters.xyz_all  - atomic coordinates as [x y z] with multiple rows 
                          for all atoms in the structure, in Angstrom.

    parameters.expt_pcs - pseudocontact shift in ppm at each nucleus.

    parameters.chi      - effective magnetic susceptibility tensor, in units
                          of Angstrom^3.

    parameters.margins  - a six-element vector specifying margins to take
                          around the bounding box of the nuclear coordina-
                          tes supplied, to eliminate the effects of the 
                          periodic boundary conditions.

    parameters.box_cent - Cartesian coordinates of the centre of the source
                          box, in Angstrom

    parameters.box_size - size of the source box in X, Y, and Z directions,
                          in Angstrom

    parameters.plot     - a cell array of strings specifying the plotting
                          options at each iteration:
                            
                            'diagnostics' - diagnostic output

                            'density'     - probability density
 
                            'molecule'    - molecular structure

                            'tightzoom'   - zooms the plot to the
                                            molecular bounding box

                            'box'         - source box

    parameters.confine  - source confinement radii (a two-element vector
                          in Angstrom). The density would only be varied
                          in points that are no closer than the first ra-
                          dius to any atom and no further away than the 
                          second radius from the nearest atom.

    parameters.sharpen  - source contrast control; leave at zero unless
                          you know what you are doing.

    parameters.guess    - optional initial guess for the source density.
                          If this is supplied on a different grid from 
                          the current one, it will be resampled by cubic
                          interpolation

    parameters.equation - 'poisson' to recover the right hand side of the
                          Poisson's equation, 'kuprov' to recover the
                          probability density.
 
    parameters.gpu      - set to 1 of you have an NVidia GPU, otherwise
                          set to 0.

    npoints             - number of grid points in each dimension of the
                          solution cube, a positive integer; at least 64
                          is recommended.

    lambda              - Tikhonov regularization parameter; start with 1,
                          then use lcurve.m function to determine it 
                          more precisely

Returns

    source_cube - source term cube with dimensions ordered as
                  [X Y Z].

    ranges      - Cartesian axis extents for the source cube as
                  [xmin xmax ymin ymax zmin zmax] in Angstroms.

    pred_pcs    - pseudocontact shifts produced by the source
                  cube returned in the first parameter.

    err_ls      - least squares penalty of the final source cube

    reg_a       - contrast penalty of the final source cube

    reg_b       - Tikhonov penalty of the final source cube

Examples

See the pseudocontact shift analysis tutorial and the examples in nmr_paramag directory of the standard example set supplied with Spinach.

Notes

For further information on the equations and algorithms used in this function see http://dx.doi.org/10.1039/C4CP03106G

See also

ppcs.m, kpcs.m, ippcs.m, ilpcs.m, lpcs.m

Version 1.9, authors: Elizaveta Suturina, Gareth Charnock, Ilya Kuprov