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
KS_SEQLOC	locs [KS_MAXINSTANCES]
WF_PULSE **	wfpulse
KS_WFINSTANCE *	wfi
float *	rtscale

Detailed Description

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

KS_WAVE

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

Example

@ipgexport (HOST)
KS_WAVE mywave = KS_INIT_WAVE;
KS_SEQ_CONTROL seqctrl;

@host
cveval() {

  ks_eval_wave(&mywave, "mywavedesc", res, duration, some_floatarray);
  ...or...
  ks_eval_wave_file(&mywave, "mywavedesc", res, duration, "myfilename", "float"); // read from disk in float format (no header)
  ...or...
  ks_eval_wave_file(&mywave, "mywavedesc", res, duration, "myfilename", "short"); // read from disk in short format (no header)
  ...or...
  ks_eval_wave_file(&mywave, "mywavedesc", res, duration, "myfilename", "ge"); // read from disk in GE's external wave format

}

@pg
  KS_SEQLOC tmploc = KS_INIT_SEQLOC;

  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

KS_SEQLOC locs[KS_MAXINSTANCES]

wfpulse

WF_PULSE** wfpulse

Internal use

wfi

KS_WFINSTANCE* wfi

Internal use

rtscale

float* rtscale

Internal use

---

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

• KSFoundation.h