RF Pulses, Read-out and Gradient Pulses

Table of Contents

• RF Pulses
  • Simple Sinc Pulse
  • Selective Sinc Pulse
  • Preparation and Execution of the Pulse
  • Dynamic Pulses
• Read-out
• Gradient Pulses

RF Pulses

In our simple FLASH sequence, the only RF pulse is a selective sinc pulse, played at the beginning of the repetition, performing excitation of the magnetization. In msl, all RF pulses are defined by classes which inherit from msl::RFPulse : these can be concrete RF pulses (e.g. msl::rf_pulses::Sinc or msl::rf_pulses::External), or modifiers to other pulses (e.g. msl::rf_pulses::Selective). All pulses will share the API of msl::RFPulse, and some will add extra members, e.g. msl::rf_pulses::External which handles family of pulses.

Simple Sinc Pulse

The creation of a concrete sinc pulse requires creating the RF pulse in a default state and then modifying it. Note that it is possible to chain calls to the setters function.

Note

Most code snippets in this tutorial are self-contained to show the required include directives, both from IDEA and from msl

#include <MrProtSrv/Domain/MrProtData/MrProt/MrProt.h>
 
#include <msl/rf_pulses/Sinc.h>
 
void createSincPulse(MrProt & protocol)
{
    msl::rf_pulses::Sinc rfPulse;
    rfPulse.setIdent("exc").setType(msl::RFPulse::Excitation);
    rfPulse.setFlipAngle(protocol.flipAngle()).setAdditionalPhase(rfPhase);
    rfPulse.setDuration(2560).setTimeBandwidthProduct(2.70).setSamples(128);
    rfPulse
        .setStartTime(0)
        .setThickness(protocol.sliceSeries().aFront().thickness())
        .setSlice(slice);
}

Selective Sinc Pulse

The creation of a selective sinc pulse is very similar, and uses both the msl::rf_pulses::Selective modifier and the msl::rf_pulses::Sinc concrete pulse.

#include <MrProtSrv/Domain/MrProtData/MrProt/MrProt.h>
 
#include <msl/rf_pulses/Selective.h>
#include <msl/rf_pulses/Sinc.h>
 
void createSelectiveSincPulse(MrProt & protocol)
{
    msl::rf_pulses::Selective<msl::rf_pulses::Sinc> rfPulse;
    rfPulse.setIdent("exc").setType(msl::RFPulse::Excitation);
    rfPulse.setFlipAngle(protocol.flipAngle()).setAdditionalPhase(rfPhase);
    rfPulse.setRFDuration(2560).setSamples(128);
    rfPulse.rf().setTimeBandwidthProduct(2.70);
    rfPulse
        .setStartTime(0)
        .setThickness(protocol.sliceSeries().aFront().thickness())
        .setSlice(slice);
}

The two differences are:

• The duration of the selective pulse is defined by msl::rf_pulses::Selective::setRFDuration instead of msl::rf_pulses::Selective::setDuration. This is required as the total duration of the selective pulse also includes the ramp-up and ramp-down time of the slice-selection gradient, which itself only depends on the performance of the gradient system.
• The time-bandwidth product is not set on the selective pulse itself, but on its contained pulse, using msl::rf_pulses::Selective::rf. Since not all pulses provide a time-bandwidth product (e.g. msl::rf_pulses::External), it is necessary to recover the child pulse for these special access. The slice-selection gradient can also be accessed in a similar manner (msl::rf_pulses::Selective::gradient), more information about gradient pulses are given in the next section.

Preparation and Execution of the Pulse

Once the parameters of a pulse have been set, the RF pulse object can be prepared using, as in IDEA, the protocol, sequence limits and exports. The full set-up of the excitation pulse would then be:

#include <MrProtSrv/Domain/CoreNative/SeqLim.h>
#include <MrProtSrv/Domain/MrProtData/MrProt/MrProt.h>
#include <MrProtSrv/Domain/MrProtData/MrProt/SeqIF/SeqExpo.h>
 
#include <msl/rf_pulses/Selective.h>
#include <msl/rf_pulses/Sinc.h>
 
NLSStatus prepareExcitation(MrProt & protocol, SeqLim & limits, SeqExpo & exports)
{
    msl::rf_pulses::Selective<msl::rf_pulses::Sinc> rfPulse;
    rfPulse.setIdent("exc").setType(msl::RFPulse::Excitation);
    rfPulse.setFlipAngle(protocol.flipAngle()).setAdditionalPhase(rfPhase);
    rfPulse.setRFDuration(2560).setSamples(128);
    rfPulse.rf().setTimeBandwidthProduct(2.70);
    rfPulse
        .setStartTime(0)
        .setThickness(protocol.sliceSeries().aFront().thickness())
        .setSlice(slice);
    
    return rfPulse.prepare(protocol, limits, exports);
}

Note

In IDEA, some prepare-like return a boolean, some return a status. In msl, all such functions will return a status.

Once the pulse is prepared, it can be run in a similar way. This must happen in a real-time events block, here opened and closed explicitely. In addition to setting the current slice object (which varies across runs), we also set the phase of the RF pulse, e.g. for RF spoiling.

#include <MrMeasSrv/SeqIF/libRT/sSLICE_POS.h>
 
#include <MrProtSrv/Domain/CoreNative/SeqLim.h>
#include <MrProtSrv/Domain/MrProtData/MrProt/MrProt.h>
#include <MrProtSrv/Domain/MrProtData/MrProt/SeqIF/SeqExpo.h>
 
#include <msl/helpers.h>
#include <msl/RFPulse.h>
 
NLSStatus runExcitation(
    MrProt & protocol, SeqLim & limits, SeqExpo & exports, 
    msl::RFPulse & pulse, double rfPhase, sSLICE_POS const & slice)
{
    rfPulse.setAdditionalPhase(rfPhase).setSlice(slice);
    ON_ERROR_RETURN_STATUS(fRTEBInit(slice->getROT_MATRIX()));
    ON_ERROR_RETURN_STATUS(this->_excitation.run(protocol, limits, exports));
    ON_ERROR_RETURN_STATUS(fRTEBFinish());
    
    return MRI_SEQ_SEQU_NORMAL;
}

Note

The ON_ERROR_RETURN_STATUS macro checks the return code of its parameter and returns it if it is an error status (if it is a non-error status, the function continue).

Dynamic Pulses

In a more complex sequence, the user may choose between selective and non-selective (e.g. msl::rf_pulses::Rect) pulses: since all RF pulses are derived from the same base class, it is easy to switch between selective and non-selective pulses at run-time by using a pointer to msl::RFPulse. In the following example, a std::shared_ptr is used to avoir manual memory management.

#include <memory>
 
#include <MrProtSrv/Domain/MrProtData/MrProt/MrProt.h>
 
#include <msl/rf_pulses/Rect.h>
#include <msl/rf_pulses/Selective.h>
#include <msl/rf_pulses/Sinc.h>
#include <msl/RFPulse.h>
 
void createPulse(MrProt & protocol, long rfDuration)
{
    std::shared_ptr<msl::RFPulse> rfPulse;
    auto const excitationMode = protocol.getsTXSPEC().getucExcitMode();
    if(excitationMode == SEQ::EXCITATION_SLICE_SELECTIVE)
    {
        auto selective = std::make_shared<msl::rf_pulses::Selective<msl::rf_pulses::Sinc>>();
        (*selective)
            .setRFDuration(rfDuration)
            .setThickness(protocol.sliceSeries().aFront().thickness())
            .setSamples(500)
            .rf()
                .setTimeBandwidthProduct(6.);
        
        rfPulse = selective;
    }
    else if(excitationMode == SEQ::EXCITATION_VOLUME_SELECTIVE)
    {
        auto nonSelective = std::make_shared<msl::rf_pulses::Rect>();
        (*nonSelective)
            .setDuration(rfDuration)
            .setSamples(rfDuration / 10);
        rfPulse = nonSelective;
    }
    else
    {
        throw MrException("Invalid RF Pulse mode");
    }
}

Read-out

Our FLASH implementation uses Cartesian trajectories along the \(k_x\) direction of the k-space: this very common situation is handled by the msl::CartesianReadout class. This class handles the timing with respect to the echo times defined in the protocol, and only requires the user to define

• which portion of the k-space must be read (msl::CartesianReadout::setADCPosition, e.g. for asymmetric echo)
• which echo the readout targets (msl::CartesianReadout::setContrast)
• a way to compute the effective echo time, i.e. accounting for the time of the peak of the excitation pulse (msl::CartesianReadout::setTimeOffset)

If the phase of the RF pulse has been modified (e.g. for RF spoiling), then the readout object must also include this information.

The preparation and error handling are the same as for RF pulses.

#include <MrProtSrv/Domain/CoreNative/SeqLim.h>
#include <MrProtSrv/Domain/MrProtData/MrProt/MrProt.h>
#include <MrProtSrv/Domain/MrProtData/MrProt/SeqIF/SeqExpo.h>
 
#include <msl/CartesianReadout.h>
#include <msl/RFPulse.h>
 
NLSStatus prepareReadout(
    MrProt & protocol, SeqLim & limits, SeqExpo & exports,
    msl::RFPulse & excitation, double rfPhase)
{
    msl::CartesianReadout readout;
    readout
        .setADCPosition(-1, +1, protocol)
        .setContrast(0)
        .setTimeOffset(excitation.peakTime());
    // Our FLASH sequence includes RF spoiling: update the phase of the readout
    readout.setPhase(rfPhase);
    
    return readout.prepare(protocol, limits, exports);
}

Note

The names of getter and setters functions are always the same for all objects: for a property named something, the getter will be called something() and the setter setSomething(value). To follow the conventions of IDEA, class names and function names are camelCased.

Running the read-out is also similar to running an RF pulse. In addition to the RF phase and slice specification, the readout object also requires the coordinates of the current line, in the 2D \((k_y, k_z)\) space. More details about this index will be provided in the next part of the tutorial.

#include <MrProtSrv/Domain/CoreNative/SeqLim.h>
#include <MrProtSrv/Domain/MrProtData/MrProt/MrProt.h>
#include <MrProtSrv/Domain/MrProtData/MrProt/SeqIF/SeqExpo.h>
 
#include <msl/CartesianReadout.h>
#include <msl/RFPulse.h>
 
NLSStatus runReadout(
    MrProt & protocol, SeqLim & limits, SeqExpo & exports,
    msl::CartesianReadout & readout, double rfPhase, msl::Vector2d const & index,
    sSLICE_POS const & slice)
{
    readout.setPhase(rfPhase).setIndex(index).setSlice(this->slice());
    // TODO: don't forget to include all real time objects (RF pulses,
    //readouts, gradients, etc.) in a real-time block
    ON_ERROR_RETURN_STATUS(readout.run(protocol, limits, exports));
    
    return MRI_SEQ_SEQU_NORMAL;
}

Note

msl::Vector includes simple vector arithmetic for any type and any dimension.

Gradient Pulses

Both the RF pulse and the readout object include gradient pulses, automatically defined to match the k-space extent and per-pixel bandwidth. The FLASH sequence will require two additional gradient lobes:

• Moving from the k-space position at the end of the excitation pulse (i.e. including part of the slice-selection gradient) to the beginning of the trajectory
• Moving from the end of the trajectory back to the center of the k-space and spoiling

These two lobes will be tuned so that their duration is minimal, according to the k-space extents and the performance of the gradient system.

The msl::GradientPulse class handles a trapezoidal gradient pulse defined by a maximal amplitude on the \(x\), \(y\), and \(z\) axes, a symmetric ramp duration (i.e. ramp-up time is equal to ramp-down time) and a plateau duration. Although gradient pulses can be defined from these three values, it can be easier to use of the high-level functions.

Once created, the gradient area can be queried in a number of ways: total area, area between two times, area between start and specified time, area between specified time and end, etc.

The k-space vector of the to-begin lobe has two components

• a fixed component, depending on the readout object and on the slice-selection gradient
• a varying component, depending on the current k-space line being recorded,

The fixed component is designed so that the echo happens at the center of the k-space (i.e. -readout.areaBeforeEcho()), and that the area of the slice-selection which happens after the peak of the RF pulse is compensated (i.e. -excitation.gradient().areaFrom(peak)).

In the following example, the varying component is computed from the index on the trajectory in the discretized 2D \((k_y, k_z)\) k-space, with the continuous k-space vector obtained using the msl::KSpace object.

Regarding the timing, the gradient lobe is the shortest possible (msl::gradient_pulses::quickest) and ends when the readout begins (msl::GradientPulse::setEndTime and msl::GradientPulse::startTime).

void createToBegin(
    MrProt & protocol,
    msl::RFPulse const & excitation, msl::CartesianReadout const & readout,
    msl::Vector2l const & index)
{
    auto const postPeakSliceSelectionArea = 
        excitation.gradient().areaFrom(
            excitation.peakTime() - excitation.startTime());
    
    auto const fixed =
        // Move to begin on the readout axis
        - readout.areaBeforeEcho()
        // Compensate the gradient offset
        - postPeakSliceSelectionArea;
    
    msl::KSpace const kSpace(protocol);
    auto const point =
        msl::Vector3l{kSpace.nCenter()[0], index[0], index[1]
        - kSpace.nCenter();
    
    auto const gradientSpecs = msl::GradientSpecs::current(protocol);
    
    auto toBegin = msl::gradient_pulses::quickest(
        fixed+kSpace.k(point), gradientSpecs);
    toBegin.setEndTime(readout.startTime());
}