KSFoundation  [April-2021]
A platform for simpler EPIC programming on GE MR systems
KS_WAVE Struct Reference

#include <KSFoundation.h>

Data Fields

KS_BASE base
KS_DESCRIPTION description
int res
int duration
KS_WAVEFORM waveform
int gradnum [3]
int gradwave_units
WF_PULSE ** wfpulse
float * rtscale

Detailed Description

Core sequence object making arbitrary waveforms on any board (using float data format)


The KS_WAVE sequence object contains a KS_WAVEFORM (float[KS_MAXWAVELEN]) to hold the waveform. The physical unit of the waveform in the KS_WAVE object depends the board on which it is placed in pulsegen(). For the

  • gradient boards (XGRAD, YGRAD, ZGRAD), the unit is [G/cm]
  • THETA board, the unit is [degrees]
  • RF and OMEGA boards, the units are arbitrary (c.f. ks_eval_rf() and ks_eval_wave())

Similar to the KS_TRAP sequence object, KS_WAVE is a core object used in other objects such as KS_RF. For RF pulse generation, direct use of KS_WAVE functions in e.g. cveval() or in the @pg section should be avoided as there is no mechanism to do the proper RF scaling. For RF, use instead KS_RF and KS_SELRF.

Placing out a KS_WAVE is done in the @pg section using ks_pg_wave(). A key feature with ks_pg_wave() is that all waveforms are double buffered. This allows replacing waveforms in run-time (scan()) from TR to TR. As ks_pg_wave() is used for all sequence objects dealing with waves, RF pulses, THETA, and OMEGA waveforms in the KS_RF objects are all double buffered as well. To replace a waveform in scan(), the function ks_scan_wave2hardware() is used.

The .gradnum[] field is modified by ks_pg_wave() on HOST to keep count of how many times the KS_WAVE has been placed in the @pg section. This information is used in ks_eval_gradrflimits() together with the sequence's common KS_SEQ_CONTROL object to calculate gradient heating limits for the sequence.

NOTE: Regardless of the order placed out in the @pg section, and on which boards (XGRAD, YGRAD, ZGRAD) the KS_WAVE object is placed, the instance number of the KS_WAVE is automatically sorted in time. If two instances of one KS_WAVE occur at the same time (.pos) on different boards, XGRAD comes before YGRAD, which comes before ZGRAD. These abstract, sorted, instance numbers are used by ks_scan_***() functions in scan() to refer to a specific instance of a KS_WAVE object in the sequence. However, unlike KS_TRAP, replacing e.g. a waveform in run-time for an instance of a KS_WAVE will affect all instances on the same board. This, since there is only one hardwave waveform per board for each KS_WAVE.

It is a requirement that there is a (sequence generating) function in the @pg section (containing the ks_pg_wave() call(s)) that can be run on both HOST and TGT. This function should be called exactly once in cveval() (after ks_eval_wave() and other ks_eval_***() functions). ks_pg_wave() will throw an error on TGT if this has not been done. See KS_SEQ_CONTROL for an example


@ipgexport (HOST)
cveval() {
ks_eval_wave(&mywave, "mywavedesc", res, duration, some_floatarray);
ks_eval_wave_file(&mywave, "mywavedesc", res, duration, "myfilename", "float"); // read from disk in float format (no header)
ks_eval_wave_file(&mywave, "mywavedesc", res, duration, "myfilename", "short"); // read from disk in short format (no header)
ks_eval_wave_file(&mywave, "mywavedesc", res, duration, "myfilename", "ge"); // read from disk in GE's external wave format
tmploc.pos = 10ms;
tmploc.board = XGRAD;
ks_pg_wave(&mywave, tmploc, &seqctrl); // Same wave object *can* be placed on multiple boards (but not recommended as the units differ between gradient and RF/OMEGA boards)
@rsp (TGT)
scan() {
...fill in mywave.wave[] with new content, then call...
ks_scan_wave2hardware(&mywave, 0); // updates hardware waveform on the board corresponding to instance 0 with new content in mywave.wave[]

Field Documentation

◆ base

KS_BASE base

Internal use

◆ description

KS_DESCRIPTION description

Descriptive string for the KS_WAVE object with maximum KS_DESCRIPTION_LENGTH characters

◆ res

int res

Number of sample points in wave

◆ duration

int duration

Duration in [us]. Must divisible with .res

◆ waveform

KS_WAVEFORM waveform

Waveform in [G/cm] (XGRAD, YGRAD, ZGRAD), [degrees] (THETA). Boards RHO and OMEGA have arbitrary units

◆ gradnum

int gradnum[3]

Internal use for gradient heating calculations

◆ gradwave_units

int gradwave_units

◆ locs

◆ wfpulse

WF_PULSE** wfpulse

Internal use

◆ wfi

Internal use

◆ rtscale

float* rtscale

Internal use

The documentation for this struct was generated from the following file: