PuleShaper 1.0 - (c) Guillermo Moyna, USIP - 2001

Welcome to the PulseShaper help/readme file. Here you will find a brief
description of the program, a Perl script for the generation of shaped pulse
profiles for use in selective excitation, as well as analysis of shaped pulse
frequency excitation profiles.

PulseShaper was originaly designed as a pulse profile generator for use with
pulse programs written for the Anazasi EFT-90 NMR spectrometer. Currently, the
program has 13 standard shapes, including square, triangle, trapezoid, Gaussian
and half-Gaussian, E-BURP, etc., a user-defined Fourier series shape, and also
has the capability of reading shape files from Bruker's ShapeTool and Varian's
Pandora's Box. The profile files from PulseShaper are simple, and have three
'header' lines. For a Gaussian pulse with 64 steps:

GAUSSIAN  (line 1)
NSTEPS 64 (line 2)
SUM 16.00 (line 3)
0.010 0
0.037 0
...
...
0.010 0   (line 67)

The first line is the name of the shape, the second is the number of steps
in the pulse, and the third is the sum of all the amplitudes. After the header,
each row has an amplitude value and a phase (0 or 180) to account for the sign
of the shape. These pulse profiles are read by the EFT-90 pulse programs and
converted into DANTE pulse trains with pulse width modulation. However, they
can be easily converted to other formats and used with other spectrometers.
To generate the pulse profiles, the user only has to select the desired shape
and enter the appropriate parameters, which will depend on the shape selected.

Soon it was realized that it would be nice to see the frequency excitation
profiles from the shaped pulses created by PulseShaper, and the first step
towards this was the incorporation of a FFT routine to calculate the FT of the
excitation profile. Using the number of steps of the shaped pulse, PulseShaper
calculates the next highest power of 2 (2^n) value and then zero fills to 16
times the resulting size. For example, if you have a 100 step pulse profile,
PulseShaper calculates the frequency profile by zero filling to 16 * 128,
because 128 is the closest power of 2 (2^n) to 100. The zero filling is done
to get a smooth frequency profile. The actual FFT is carried out using the
Perl Math::FFT module, and made life a whole lot easier.

Since for soft pulses the FT profile does not resemble the real excitation
profile, we decided to include a Bloch simulation routine. This routine starts
from the magnetization at equilibrium (M = [0,0,1]), and applies the pulse as
a series of square pulses with varying amplitude (varying gammaB1). After each
slice of the pulse is applied, M is recalculated by applying the analytical
solutions to the Bloch equation as found in: 

1) Liu, Weisz, and James, JMR-A 1993, 105, 184-192. (* See note below).
2) Lunati, Cofrancesco, Villa, Marzola, and Osculati, JMR 1998, 134, 223-235.

This is repeated sequentially for as many steps there are in the shaped pulse.
Before applying the 'cascade' of pulses, the program calculates an offset,
which is actually taken from the frequency range used in the FT analysis (i.e.,
the number of offsets will be 16 * [the closest power of 2 (2^n)], as described
above). The effective field is then computed using this offset and the gammaB1
for the step, whose amplitude varies with the pulse profile. The whole thing is
done in two nested loops.

The calculation of the frequency excitation profiles described above is done
after the shaped pulse has been generated. The user needs to supply a pulse
width (in mS) for the pulse, and a tip angle (in deg.), and the initial
condition of the magnetization (Mx, My, Mz) as a space separated list. The
program then does the FFT and Bloch analysis, and saves a frequency excitation
profile file as a text file whith the following tab-separated format:

Hz	Imaginary	Real	Power	Mx	My	Mz	Mx^2+My^2

'Hz' is the offset from the carrier, 'Imaginary', 'Real', and 'Power' are the
results from the FFT, and 'Mx', 'My', 'Mz', and 'Mx^2+My2' are the components
of the magnetization vector and the total transverse magnetization as a
function of the offset.

After the program saves the excitation profile, some additional information
for the pulse is printed out, including gamma * B1 and the excitation bandwidth
for the FT spectrum and the excitation spectrum. At this point, you can
reenter the frequency profile calculation stage and recalculate the profile for
a different pulse width, tip angle, and initial magnetization conditions, or go
back one more step and enter a different pulse shape.

As a final note, if you think that you have to convert/modify PulseShaper for
your particular application, please feel free to do so! The only thing I will
ask is that you send me an e-mail telling me what does your modified script
can do...

Enjoy, and send any comments/suggestions to g.moyna@usip.edu.

(*) This reference has a small error in the rotation matrix. The last 'My' in
equation [3], page 186, should be replaced by 'Mz'.

Updates
-------

1/29/2001 - Initial release.
2/01/2001 - Modified conversion routine to include Varian's Pandora's Box
            shaped files.
2/02/2001 - Included option that allows user to use initial magnetization
            conditions different from thermal equilibrium.
          - Modified excitation profile bandwidth calculation factor so that
            the bandwidth is calculated at 70.8% (3 dB drop) instead of 50%.
2/07/2001 - Made small modification on the indexes so that pulse profiles are
            perfectly symmetrical.