last updated 3-Jun-1999

CCCP v. 1.1

Complete Calculation of Coherence Pathways

Alexej Jerschow
present address: C/O Pines Lab,
Department of Chemistry
University of California
Berkeley, CA 94720-1460

alexej@rabi.cchem.berkeley.edu

Description

This is a program for the efficient simulation of phase cycles and pulsed field gradient sequences and diffusion effects in nuclear magnetic resonance (NMR).

Basically, you input a phase cycle and a sequence of pulsed field gradients and the program will tell you which pathways are selected and to which extent they are attenuated, see example. The attenuation due to diffusion and pulses is also implemented.

For details please consult the full paper:

A. Jerschow and N. Müller, J. Magn. Reson. 134, 17-29 (1998).

Please reference this article when you use the CCCP program in publications. To refer to a special software version, please cite this www-page:

A. Jerschow and N. Müller, http://www.orc.uni-linz.ac.at/mueller/cccp/cccp.html


The abstract and the full text can be accessed via the IDEAL library.

The following paragraph applies to the preprint  version of this paper which is also available from our local server in Adobe Acrobatô (.pdf) or PostScript® (.ps) format:
 
 

This material has been published in the
Journal of Magnetic Resonance 134 (1998) 17-29,

the only definitive repository of the content that has been certified and accepted after
peer review. Copyright and all rights therein are retained by Academic Press. This material
may not be copied or reposted without explicit permission. The article is available in
electronic form from the IDEAL (International Digital Electronic Access Library) at
  http://www.idealibrary.com or http://www.europe.idealibrary.com.
preprint version on local server (situated in Europe/Austria):

Preprint in Acrobat format | Preprint in PostScript format



The program version 1.0 can be downloaded from
http://www.orc.uni-linz.ac.at/mueller/download/CCCP.tar

Version 1.1, which is the current recommended version is at:
http://www.orc.uni-linz.ac.at/mueller/download/CCCPv1.1.tar

release notes:
  • BUG fixes:

  •   - does not exit with runtime error any more when all paths
        are cancelled by "too efficient" phase cycles, gradients, or diffusion
  • The documentation is no longer included in the tar file. Please use this web page as the documentation.

  • If you want to be updated about new developments please send a short message to: alexej@rabi.cchem.berkeley.edu (please put CCCP into the subject line)

    System requirements

    You need MATLAB 5.0x. Not tested on Mac/PC. It should be mentioned that long pulse sequences will require a high performance machine (both by memory and CPU).

    Files and usage

    The package consists of the following files

    CCCP.m
    calcord.m
    DispPaths.m
    cccp.ps (documentation in postscript format, no longer included as of v. 1.1, please use this html-page)

    example parameter files from the paper:

    pfgbp1.m, pfgbp2.m (bipolar gradient diffusion sequence)
    dqnoesy1.m, dqnoesy2.m, dqnoesy3.m (3D PFG DQ NOESY)
    hsqc.m (HSQC)

    Put all the files in one directory and issue CCCP('parf_name') on the command line. (parf_name contains the name of the parameter file without the '.m' suffix).

    You will be prompted for a filename where the pathway information should be stored (for later use). The file receives the extension .log. After that the pathways will be displayed. On the screen only the absolute and relative intensities are displayed, in the logfile you have:Sig - absolute signal intensity, Phase, PCdmp - damping due to phase cycle, Puldmp - damping due to pulses/spin system, Gdmp - damping due to gradients, Diffdmp - damping due to diffusion.

    If you have specified several nuclei the coherence pathways will be displayed separately for each of them in addition to the cumulative coherence order. In the logfile first the total coherence order is printed, then the partial one for all nuclei.

    CAVEAT: not tested with more than two nuclei.

    Parameters

    All experiment dependent parameters are input in a separate file which may have any name (look at the example files, and/or refer to the MATLAB manual).
    ph
    the phase cycle may be input conveniently as:
    ph{1}= [ 0 0 1 1 ];
    ph{2}= 1;
    ph{3}= 0;
    ph{4}= [ 2 2 3 3 0 0 1 1];
    phrec = [ 0 2 0 2 2 0 2 0 ];
    phrec is the receiver phase. The number of lines corresponds to the number of pulses (no index may be left out). In addition you have to specify the base of each cycle: base=4; recbase=4;. If base is a vector it allows to specify a different base for each pulse. recbase is the base of the receiver phases.
    pulses
    e.g.:
     pulses = [ [1 2 1 1]*.95*pi/2;...
      1 1 2 1 ]];
    The first line specifies the pulses in radians.

    The second line specifies on which nuclear species the pulse acts (the number of nuclear species is max(pulses(2,:))).

    gamma
    specifies the gyromagnetic ratio of all nuclear species (vector), e.g.: gamma=[2.67522e8 0.67283e8]; for 1H and 13C.
    allow_pahts
    allows the user to input empirical weighting factors as well as to restrict the number of possible pathways. Its size is (2pmax+ 1) * (n+1) where n is the number of pulses. The row index is the coherence order (from pmax to -pmax) and the column index specifies the evolution period. A number weighs the pathway accordingly (zero removes it). E.g.:
         allow_paths{1}=[0 0 1 1 1 1 1 0;...
                    0 1 1 1 1 1 1 0;...
                    1 1 1 1 1 1 1 0;...
                    0 1 1 1 1 1 1 1;...
                    0 0 1 1 1 1 1 0]
    here, we start with zero order (before the first pulse) and end with -1 for detection. allow_paths has to be specified for all nuclei separately (with an appropriate index in the braces). There can be, however, only one starting coherence order (otherwise only the first one is taken). Specifying coherence order restrictions (for a certain nucleus) for an evolution period after an rf-pulse acting on another nucleus has no effect. In the same way the ending (observed) coherence order has to be specified immediately after the last pulse on that nuclear species.
    grads
    specifies the gradients during the evolution period (starting with a gradient before the first pulse, e.g.
      gradunits=50e-2*1e-3;
      grads =[0 1 0.5 0 0]*gradunits;
      sampledim=.5e-2;
    Here, we have gradients of 0.5 T/m and 0.25 T/m for 1 ms duration (rectangular) after the first and second rf-pulses, respectively. Up to three lines can be specified in the matrix in order to account for multiple axis gradients.

    The first line is always the z direction. The following ones are x and y.

    sampledim specifies the sample extensions (cylinder height and diameter). In this example only the height is given since only z -gradients are considered.

    intergrad_dels
    specifies the intergradient delays in seconds (used for the calculation of diffusion damping).
    diffconst
    is the diffusion coefficient for which to calculate the diffusion weighting (in m2/s).
    epsilon
    threshold for the elimination of CTPs after the phase cycle.
    cutoff
    threshold for the elimination of CTPs after the gradient damping (and again after the diffusion damping).
    range
    specifies the range of the resulting CTPs to be displayed.
    spin_system
    leave blank if you don't want a density matrix calculation. Otherwise you may choose from the following systems: AX, AMX, AMXinv (the latter is a heteronuclear system with inverse detection, consisting of, say, two protons and one X).
    J
    coupling constants, one for AX, two for AMXinv (homonuclear JAM and heteronuclear JAX), and three for AMX ( JAM,JAX,JMX).
    del
    evolution delays necessary for density matrix calculation.
    abundance
    allows to specify the rel. abundance of the nuclear specii (currently has only effect together with spin_system='AMXinv').

    BUGS, TODO

    There are many parts of the program that can be considerably optimized. In particular the calculation of the phase cycle attenuation is currently implemented in a very inefficient way. The density matrix calculation needs probably further extensions and the displaying capabilities should be improved. Using long pulse sequences can cost a considerable amount of CPU time/memory, in particular with heteronuclear experiments.

    Advice: if it does not work for long pulse sequences try to address parts of the problem, by restricting the number of possible pathways by the allow_paths variable, or looking at parts of the pulse sequence separately.

    I hope to provide some improvement in the near future.

    miscellaneous bugs:

    Disclaimer

    CCCP v. 1.0 Complete Calculation of Coherence Pathways. Copyright © 1998 by Alexej Jerschow.
    CCCP v. 1.1 Complete Calculation of Coherence Pathways. Copyright © 1998 by Alexej Jerschow.

    This program is free software; you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation; either version 2 of the License, or (at your option) any later version.

    This program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details.

    If you have not received a copy of the GNU General Public License along with this program you can write to the

    Free Software Foundation, Inc., 59 Temple Place - Suite 330, Boston, MA 02111-1307, USA.

    Contact information

    Alexej Jerschow
    present address: C/O Pines Lab,
    Department of Chemistry
    University of California
    Berkeley, CA 94720-1460


    email: ajerscho@ico.unil.ch (please put CCCP into the subject line)

    The program can be downloaded from http://www.orc.uni-linz.ac.at/mueller/download/CCCP.tar(v. 1.0)
    Version 1.1, which is the current recommended version is at:

    http://www.orc.uni-linz.ac.at/mueller/download/CCCPv1.1.tar


    If you want to be updated about new developments please send a short message to: alexej@rabi.cchem.berkeley.edu (please put CCCP into the subject line)


    Alexej Jerschow and Norbert Müller, Oct. 1998