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,diag_data]=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.

Arguments

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

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

    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 solu-
                          tion box, in Angstrom

    parameters.box_size - size of the source box in X, Y, and Z directi-
                          ons, 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.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 greater than 10.

    lambda              - Tikhonov regularization parameter.

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.

    diag_data   - the first element is the least squares error
                  in ppm^2, the second element is the entropy
                  penalty in the error functional, the third
                  element is the Tikhonov penalty in the error
                  functional.

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