ksgre_tutorial: Tutorial GRE sequence (2D)

Data Structures
struct	KSGRE_SEQUENCE

Macros
#define	KSGRE_DEFAULT_SSI_TIME   500
#define	KSGRE_INIT_SEQUENCE   {KS_INIT_SEQ_CONTROL, KS_INIT_READTRAP, KS_INIT_TRAP, KS_INIT_PHASER, KS_INIT_TRAP, KS_INIT_SELRF};

Functions
STATUS	cvinit (void)
STATUS	cveval (void)
STATUS	my_cveval (void)
STATUS	cvcheck (void)
STATUS	predownload (void)
STATUS	pulsegen (void)
STATUS	mps2 (void)
STATUS	aps2 (void)
STATUS	scan (void)
	abstract ("GRE Tutorial [KSFoundation]")
	psdname ("ksgre_tutorial")
int	ksgre_scan_sliceloop_nargs (int slperpass, int nargs, void **args)
float	ksgre_scan_acqloop (int passindx)
float	ksgre_scan_scanloop ()
STATUS	ksgre_scan_seqstate (SCAN_INFO slice_info, int kyview)
void	ksgre_init_imagingoptions (void)
STATUS	ksgre_init_UI (void)
STATUS	ksgre_eval_UI ()
STATUS	ksgre_eval_setupobjects ()
STATUS	ksgre_eval_TErange ()
STATUS	ksgre_gradheat_play (const INT max_encode_mode, int nargs, void **args)
STATUS	ksgre_eval_tr (KS_SEQ_COLLECTION *seqcollection)
STATUS	ksgre_check ()
STATUS	ksgre_update_UI ()
STATUS	ksgre_predownload_plot (KS_SEQ_COLLECTION *seqcollection)
STATUS	ksgre_predownload_setrecon ()
STATUS	ksgre_pg ()
int	ksgre_scan_coreslice (const SCAN_INFO *slice_pos, int dabslice, int kyindx, int exc)
int	ksgre_scan_sliceloop (int slperpass, int passindx, int kyindx, int exc)
STATUS	ksgre_scan_init (void)
STATUS	ksgre_scan_prescanloop (int nloops, int dda)

Variables
KS_SEQ_COLLECTION	seqcollection
float	ksgre_gscalerfexc = 0.9
float	ksgre_spoilerarea = 2000.0 with {0.0, 10000.0, 2000.0, VIS, "ksgre spoiler gradient area",}
int	ksgre_ssi_time = KSGRE_DEFAULT_SSI_TIME with {32, , KSGRE_DEFAULT_SSI_TIME, VIS, "time from eos to ssi in intern trig",}
int	ksgre_dda = 2 with {0, 200, 2, VIS, "Number of dummy scans for steady state",}
KSGRE_SEQUENCE	ksgre = KSGRE_INIT_SEQUENCE
int	sequence_iopts []
int	volindx
int	passindx

Detailed Description

Macro Definition Documentation

KSGRE_DEFAULT_SSI_TIME

#define KSGRE_DEFAULT_SSI_TIME   500

KSGRE_INIT_SEQUENCE

#define KSGRE_INIT_SEQUENCE   {KS_INIT_SEQ_CONTROL, KS_INIT_READTRAP, KS_INIT_TRAP, KS_INIT_PHASER, KS_INIT_TRAP, KS_INIT_SELRF};

Function Documentation

cvinit()

STATUS cvinit

(

void

)

                    {
  STATUS status;

  status = GEReq_cvinit();
  KS_RAISE(status);

  /* reset debug file ./ks_debug.txt (SIM) or /usr/g/mrraw/ks_debug.txt (HW) */
  ks_dbg_reset();

  /* Imaging Options buttons */
  ksgre_init_imagingoptions();

  /* Setup UI buttons */
  status = ksgre_init_UI();
  KS_RAISE(status);

  return SUCCESS;

} /* cvinit() */

cveval()

STATUS cveval

(

void

)

                    {

    /*
   cveval() is called 37+ times per UI button push on the MR system, while cvcheck() is only called once.
   For a faster execution we have a my_cveval() function that is called in cvcheck() instead
   */

  return SUCCESS;

} /* cveval() */

my_cveval()

STATUS my_cveval

(

void

)

                       {
  STATUS status;

  ks_init_seqcollection(&seqcollection);

  status = GEReq_cveval();
  KS_RAISE(status);

  /* User Interface updates & opuserCV sync */
  status = ksgre_eval_UI();
  KS_RAISE(status);

  /* Setup sequence objects */
  status = ksgre_eval_setupobjects();
   KS_RAISE(status);

  /* Calculate minimum (and maximum TE) */
  status = ksgre_eval_TErange();
  KS_RAISE(status);

  /* Run the sequence once (and only once after ksgre_eval_setupobjects()) in cveval() to
     get the sequence duration and the number of object instances (for grad/rf limits) */
  status = ksgre_pg();
  KS_RAISE(status);

  status = ks_eval_addtoseqcollection(&seqcollection, &ksgre.seqctrl);
  KS_RAISE(status);

  /* Add the passpacket seqctrl to the seqcollection */
  status = ks_eval_addtoseqcollection(&seqcollection, &seqctrl_passpack);
  KS_RAISE(status);

  /*--------- Begin: Additional sequence modules -----------*/



  /*--------- End: Additional sequence modules -----------*/


  /* Min TR, #slices per TR, RF/gradient heating & SAR */
  status = ksgre_eval_tr(&seqcollection);
  KS_RAISE(status);

  /* RF scaling across sequence modules */
  status = GEReq_eval_rfscaling(&seqcollection);
  KS_RAISE(status);

  /* scan time */
  pitscan = ksgre_scan_scanloop();

  return SUCCESS;

} /* my_cveval() */

cvcheck()

STATUS cvcheck

(

void

)

                     {
  STATUS status;

  status = my_cveval();
  KS_RAISE(status);

  status = GEReq_cvcheck();
  KS_RAISE(status);

  status = ksgre_check();
  KS_RAISE(status);

  status = ksgre_update_UI();
  KS_RAISE(status);
  
  return SUCCESS;

} /* cvcheck() */

predownload()

STATUS predownload

(

void

)

                           {
  STATUS status;

  status = GEReq_predownload();
  KS_RAISE(status);

  status = GEReq_predownload_prescan_options((RG_CAL_MODE_E) RG_CAL_MODE_LOW_FIXED);
  KS_RAISE(status);
  
  /* Set filter slot # for SCAN, APS2, MPS2 */
  GEReq_predownload_setfilter(&ksgre.read.acq.filt);

  /* slice ordering */
  /* The following GE globals must be set appropriately:
     data_acq_order[], rsp_info[], rsprot[], rsptrigger[]. This is a must for a main pulse sequence */
  status = GEReq_predownload_store_sliceplan(ks_slice_plan);
  KS_RAISE(status);

  /* generic rh-vars setup */
  GEReq_predownload_setrecon_readphase(&ksgre.read, &ksgre.phaseenc, NULL, KS_IMSIZE_MIN256, KS_GERECON * (rhrecon < 1000) /* online recon if rhrecon < 1000 */);
  GEReq_predownload_setrecon_annotations_readtrap(&ksgre.read, 0);
  GEReq_predownload_setrecon_voldata(opfphases, ks_slice_plan); /* opfphases = number of volumes */

  /* further sequence specific recon settings that have not been set correctly at this point */
  status = ksgre_predownload_setrecon();
  KS_RAISE(status);

  /* plotting of sequence modules and slice timing to disk */
  ksgre_predownload_plot(&seqcollection);

  return SUCCESS;

} /* predownload() */

pulsegen()

STATUS pulsegen

(

void

)

                        {

  GEReq_pulsegenBegin();

  /* Main Pulse Sequence */
  ksgre_pg();
  KS_SEQLENGTH(seqcore, ksgre.seqctrl);

  GEReq_pulsegenEnd();

  buildinstr(); /* load the sequencer memory */

  return SUCCESS;

} /* pulsegen() */

mps2()

STATUS mps2

(

void

)

                  {
  rspent = L_MPS2;
  strcpy(psdexitarg.text_arg, "mps2");

  if (ksgre_scan_init() == FAILURE)
    return rspexit();

 if (ksgre_scan_prescanloop(30000, ksgre_dda) == FAILURE)
   return rspexit();

  rspexit();

  return SUCCESS;

} /* mps2() */

aps2()

STATUS aps2

(

void

)

                  {

  rspent = L_APS2;
  strcpy(psdexitarg.text_arg, "aps2");

  if (ksgre_scan_init() == FAILURE)
    return rspexit();

  if (ksgre_scan_prescanloop(100, ksgre_dda) == FAILURE)
    return rspexit();

  rspexit();

  return SUCCESS;

} /* aps2() */

scan()

STATUS scan

(

void

)

                  {

  rspent = L_SCAN;
  strcpy(psdexitarg.text_arg, "scan");

  if (ksgre_scan_init() == FAILURE)
    return rspexit();

  /* Scan hierarchy:

    ksgre_scan_scanloop() - Data for the entire scan
        ksgre_scan_acqloop() - All data for one set of slices that fit within one TR (one acquisition)
            ksgre_scan_sliceloop() - One set of slices that fit within one TR played out for one shot
                 ksgre_scan_coreslice() - One slice playout, with optional other sequence modules
  */
  ksgre_scan_scanloop();

  GEReq_endofscan();

  /* So we can see the sequence in plotter after scan completes */
  ks_scan_switch_to_sequence(&ksgre.seqctrl);

  rspexit();

  return SUCCESS;

} /* scan() */

abstract()

abstract

(

"GRE Tutorial "

[KSFoundation]

)

psdname()

psdname

(

"ksgre_tutorial"

)

ksgre_scan_sliceloop_nargs()

int ksgre_scan_sliceloop_nargs	(	int	slperpass,
		int	nargs,
		void **	args
	)

Wrapper function to ksgre_scan_sliceloop() with standardized input arguments

For TR timing heat/SAR calculations of regular 2D multislice sequences, GEReq_eval_TR(), ks_eval_mintr() and GEReq_eval_checkTR_SAR() use a standardized function pointer with a fixed set of input arguments to call the sliceloop of the main sequence with different number of slices to check current slice loop duration. As different pulse sequences may need different number of input arguments (with different meaning) this ksgre_scan_sliceloop_nargs() wrapper function provides the argument translation for ksgre_scan_sliceloop().

The function pointer must have an integer corresponding to the number of slices to use as its first argument while the remaining input arguments (to ksgre_scan_sliceloop()) are stored in the generic void pointer array with nargs elements, which is then unpacked before calling ksgre_scan_sliceloop().

Parameters

[in]	slperpass	Number of slices to play in the slice loop
[in]	nargs	Number of extra input arguments to ksgre_scan_sliceloop() in range [0,4]
[in]	args	Void pointer array pointing to the variables containing the actual values needed for ksgre_scan_sliceloop()

Return values

slicelooptime

Time taken in [us] to play out slperpass slices

                                                                      {
  int passindx = 0;
  int kyindx = KS_NOTSET; /* off */
  int exc = 0;

  if (nargs < 0 || nargs > 3) {
    ks_error("%s: 3rd arg (void **) must contain up to 4 elements: passindx, kyindx, exc", __FUNCTION__);
    return -1;
  } else if (nargs > 0 && args == NULL) {
    ks_error("%s: 3rd arg (void **) cannot be NULL if nargs (2nd arg) != 0", __FUNCTION__);
    return -1;
  }

  if (nargs >= 1 && args[0] != NULL) {
    passindx = *((int *) args[0]);
  }
  if (nargs >= 2 && args[1] != NULL) {
    kyindx = *((int *) args[1]);
  }
  if (nargs >= 3 && args[2] != NULL) {
    exc = *((int *) args[2]);
  }

  return ksgre_scan_sliceloop(slperpass, passindx, kyindx, exc); /* in [us] */

} /* ksgre_scan_sliceloop_nargs() */

ksgre_scan_acqloop()

float ksgre_scan_acqloop

(

int

passindx

)

Plays out all phase encodes for all slices belonging to one pass

This function traverses through all phase encodes to be played out and runs the ksgre_scan_sliceloop() for each set of kyindx, and excitation. If ksgre_dda > 0, dummy scans will be played out before the phase encoding begins.

Parameters

[in]

passindx

0-based pass index in range [0, ks_slice_plan.npasses - 1]

Return values

passlooptime

Time taken in [us] to play out all phase encodes and excitations for slperpass slices. Note that the value is a float instead of int to avoid int overrange at 38 mins of scanning

                                       {
  float time = 0.0;
  int dda, kyindx, exc;

  /* dummy scans for steady state */
  for (dda = 0; dda < ksgre_dda; dda++) {
    time += (float) ksgre_scan_sliceloop(ks_slice_plan.nslices_per_pass, passindx, KS_NOTSET, KS_NOTSET);
    ks_plot_slicetime_endofslicegroup("ksgre dummy TR");
  }
  if (ksgre_dda > 0) {
    ks_plot_slicetime_endofpass(KS_PLOT_PASS_WAS_DUMMY);
  }

  for (kyindx = 0; kyindx < ksgre.phaseenc.numlinestoacq; kyindx++) {
    for (exc = 0; exc < (int) ceil(opnex); exc++) { /* ceil rounds up opnex < 1 (used for partial Fourier) to 1 */

      time += (float) ksgre_scan_sliceloop(ks_slice_plan.nslices_per_pass, passindx, kyindx, exc);

    } /* for exc */


    ks_plot_slicetime_endofslicegroup("ksgre line");

    /* save a frame of the main sequence */
    ks_plot_tgt_addframe(&ksgre.seqctrl);

  } /* for kyindx */

  ks_plot_slicetime_endofpass(KS_PLOT_PASS_WAS_STANDARD);

  return time; /* in [us] */

} /* ksgre_scan_acqloop() */

ksgre_scan_scanloop()

float ksgre_scan_scanloop

(

)

Plays out all passes of a single or multi-pass scan

This function traverses through all phase encodes to be played out, and runs the ksgre_scan_sliceloop() for each set of kyindx and excitation. If ksgre_dda > 0, dummy scans will be played out before the phase encoding begins.

Return values

scantime

Total scan time in [us] (float to avoid int overrange after 38 mins)

                            {
  float time = 0.0;

  for (volindx = 0; volindx < opfphases; volindx++) { /* opfphases is # volumes */

    for (passindx = 0; passindx < ks_slice_plan.npasses; passindx++) {

      time += ksgre_scan_acqloop(passindx);

#ifdef IPG
      GEReq_endofpass();
#endif

    } /* end: acqs (pass) loop */

  } /* end: volume loop */

  return time;

} /* ksgre_scan_scanloop() */

ksgre_scan_seqstate()

STATUS ksgre_scan_seqstate	(	SCAN_INFO	slice_info,
		int	kyview
	)

Sets the current state of all ksgre sequence objects being part of KSGRE_SEQUENCE

This function sets the current state of all ksgre sequence objects being part of KSGRE_SEQUENCE, incl. gradient amplitude changes, RF freq/phases and receive freq/phase based on current slice position and phase encoding indices.

The idea of having a 'seqstate' function is to be able to come back to a certain sequence state at any time and possibly play it out once more. This could for example be useful when certain lines or slices need to be rescanned due to image artifacts detected during scanning.

Parameters

[in]	slice_info	Position of the slice to be played out (one element in the ks_scan_info[] array)
[in]	kyview	Phase encoding index related to ksgre.phaseenc. A value outside of [0, ksgre.phaseenc.res-1] will set the phase encoding gradient amplitude to 0.

Return values

STATUS

SUCCESS or FAILURE

                                                             {
  float rfphase = 0;

  /* rotate the slice plane */
  ks_scan_rotate(slice_info);

  /* RF frequency & phase */
  ks_scan_rf_on(&ksgre.selrfexc.rf, INSTRALL);
  ks_scan_selrf_setfreqphase(&ksgre.selrfexc, 0 /* instance */, slice_info, rfphase);

  /* FOV offsets (by changing freq/phase of ksgre.read) */
  ks_scan_offsetfov(&ksgre.read, INSTRALL, slice_info, kyview, opphasefov, rfphase);

  /* phase enc amp */
  ks_scan_phaser_toline(&ksgre.phaseenc,   0, kyview); 

  return SUCCESS;

} /* ksgre_scan_seqstate() */

ksgre_init_imagingoptions()

void ksgre_init_imagingoptions

(

void

)

Initial handling of imaging options buttons and top-level CVs at the PSD type-in page

Returns

void

                                     {
  int numopts = sizeof(sequence_iopts) / sizeof(int);

  psd_init_iopt_activity();
  activate_iopt_list(numopts, sequence_iopts);
  enable_iopt_list(numopts, sequence_iopts);

  /* Imaging option control functions (using PSD_IOPT_ZIP_512 as example):
    - Make an option unchecked and not selectable: disable_ioption(PSD_IOPT_ZIP_512)
    - Make an option checked and not selectable:   set_required_disabled_option(PSD_IOPT_ZIP_512)
    - Remove the imaging option:                   deactivate_ioption(PSD_IOPT_ZIP_512)
  */

  /* default slice order is interleaved */
  cvdef(opirmode, 0); opirmode = 0;

  set_required_disabled_option(PSD_IOPT_EDR);


} /* ksgre_init_imagingoptions() */

ksgre_init_UI()

STATUS ksgre_init_UI

(

void

)

Initial setup of user interface (UI) with default values for menus and fields

Return values

STATUS

SUCCESS or FAILURE

                           {

  /* Menus and button content 
     See epic.h or ksgre.e for more pi*** CVs to use to set up the user menus and buttons */

  /* Note KSF C-macro: cvset(CV, min, max, default, descr). If desc="", then no update of desc */

  /* Gradient Echo Type of sequence */
  acq_type = TYPGRAD; /* loadrheader.e rheaderinit: sets eeff = 1 */

  /* slice spacing menu, make 0 gap the first menu choice */
  piisval2 = 0;

  /* show "Minimum" as 1st option in TR menu */
  pitrval2 = PSD_MINIMUMTR;

  /* show "MinimumFull" as 1st option in TE menu */
  pite1val2 = PSD_MINFULLTE;

  /* flip angle menu */
  pifanub = 6; /* 5 option + type-in */
  pifaval2 = 10;
  pifaval3 = 20;
  pifaval4 = 30;
  pifaval5 = 60;
  pifaval6 = 90;
  cvset(opflip, 1, 90, pifaval2, ""); /* allow opflip 1-90, with pifaval2 as default */

  /* receiver bandwidth menu */
  pircbnub  = 31; /* bitmask: 2^5 - 1. Makes 5 rows */
  pircbval2 = 31.25;
  pircbval3 = 41.67;
  pircbval4 = 50.0;
  pircbval5 = 62.50;
  pircbval6 = 125.0;
  cvset(oprbw, 4, 250, pircbval3, "");
  pidefrbw = pircbval3; /* Default menu choice (also makes oprbw to be initialized to this) */
  
  /* hide second bandwidth option */
  pircb2nub = 0;

  /* default low FA. cvset(CV, min, max, default, descr). If desc="", then no update of desc */
  cvset(opflip, 1, 90, 5, "");

  /* xres (freq) menu and opxres range (default value in UI not controllable from PSD) */
  pixresnub = 63;
  pixresval2 = 64;
  pixresval3 = 128;
  pixresval4 = 256;
  pixresval5 = 320;
  pixresval6 = 512;
  cvset(opxres, 32, 512, pixresval3, "");

  /* yres (phase) menu and opyres range (default value in UI not controllable from PSD) */
  piyresnub = 63;
  piyresval2 = 64;
  piyresval3 = 128;
  piyresval4 = 256;
  piyresval5 = 320;
  piyresval6 = 512;
  cvset(opyres, 32, 512, piyresval3, "");


  return SUCCESS;

} /* ksgre_init_UI() */

ksgre_eval_UI()

STATUS ksgre_eval_UI

(

)

Gets the current UI and checks for valid inputs

Return values

STATUS

SUCCESS or FAILURE

                       {

  if (ksgre_init_UI() == FAILURE)
    return FAILURE;

  /* add code here that is related to the user interface (i.e. scan parameter) changes */

  return SUCCESS;

} /* ksgre_eval_UI() */

ksgre_eval_setupobjects()

STATUS ksgre_eval_setupobjects

(

)

Sets up all sequence objects for the main sequence module (KSGRE_SEQUENCE ksgre)

Return values

STATUS

SUCCESS or FAILURE

                                 {
  STATUS status;

  /*******************************************************************************************************
   *  RF Excitation
   *******************************************************************************************************/

  /* RF pulse choice (KSFoundation_GERF.h) */
  ksgre.selrfexc.rf = exc_3dfgre;

  ksgre.selrfexc.rf.flip = opflip;
  ksgre.selrfexc.slthick = opslthick / ksgre_gscalerfexc;

  /* selective RF excitation */
  if (ks_eval_selrf(&ksgre.selrfexc, "rfexc") == FAILURE)
    return FAILURE;

  /*******************************************************************************************************
   *  Readout
   *******************************************************************************************************/

  ksgre.read.fov = opfov;
  ksgre.read.res = RUP_FACTOR(opxres, 2); /* round up (RUP) to nearest multiple of 2 */
  ksgre.read.acq.rbw = oprbw;
  status = ks_eval_readtrap(&ksgre.read, "read");
  KS_RAISE(status);

  /*******************************************************************************************************
   *  Readout dephaser
   *******************************************************************************************************/

  ksgre.readdephaser.area = -ksgre.read.area2center;
  status = ks_eval_trap(&ksgre.readdephaser, "readdephaser");
  KS_RAISE(status);

  /*******************************************************************************************************
  *  Phase encoding
  *******************************************************************************************************/

  ksgre.phaseenc.fov = opfov * opphasefov;
  ksgre.phaseenc.res = RUP_FACTOR((int) (opyres * opphasefov), 2); /* round up (RUP) to nearest multiple of 2 */

  if (ks_eval_phaser(&ksgre.phaseenc, "phaseenc") == FAILURE)
    return FAILURE;

  /*******************************************************************************************************
  *  Spoiler
  *******************************************************************************************************/

  ksgre.spoiler.area = ksgre_spoilerarea;
  if (ks_eval_trap(&ksgre.spoiler, "spoiler") == FAILURE)
    return FAILURE;

  /*******************************************************************************************************
   *  Init (reset) sequence control and set the SSI time
   *******************************************************************************************************/
  ks_init_seqcontrol(&ksgre.seqctrl);
  strcpy(ksgre.seqctrl.description, "ksgremain");
  /* Copy SSI CV to seqctrl field used by setssitime() */
  ksgre.seqctrl.ssi_time = RUP_GRD(ksgre_ssi_time);

  return SUCCESS;

} /* ksgre_eval_setupobjects() */

ksgre_eval_TErange()

STATUS ksgre_eval_TErange

(

)

Sets the min TE based on the durations of the sequence objects in KSGRE_SEQUENCE (ksgre)

Return values

STATUS

SUCCESS or FAILURE

                            {

  /* Minimum TE */
  avminte = ksgre.selrfexc.rf.iso2end;
  avminte += IMax(3, \
        ksgre.readdephaser.duration + ksgre.read.acqdelay, \
        ksgre.phaseenc.grad.duration, \
        ksgre.selrfexc.grad.ramptime + ksgre.selrfexc.postgrad.duration);
  avminte += ksgre.read.time2center - ksgre.read.acqdelay; /* from start of acq win to k-space center */
  avminte = RUP_FACTOR(avminte + 8us, 8); /* add 8us margin and round up to make time divisible by 8us */

  if (opautote) {
    setpopup(opte, PSD_OFF);
    cvoverride(opte, avminte, PSD_FIX_ON, PSD_EXIST_ON); /* AutoTE: force TE to minimum */
  } else {
    setpopup(opte, PSD_ON);
    if (opte < avminte)
      opte = avminte;
  }

  return SUCCESS;

} /* ksgre_eval_TErange() */

ksgre_gradheat_play()

STATUS ksgre_gradheat_play	(	const INT	max_encode_mode,
		int	nargs,
		void **	args
	)

Play function of a test sequence used for gradient heating calculations

This function

• plays one or more (currently one) sequence modules that collective makes a test sequence that attempts to be a good approximation of the average and maxmimum power dissipation of the gradient system.
• is not used for any data collection.
• plays the main sequence based on the max_encode_mode (AVERAGE_POWER or MAXIMUM_POWER).
• is passed as an argument to ks_eval_getduration() to get the playout time and to ks_eval_hwlimits() to get the new minimum time due to hardware heating and SAR calculations.

It should be noted that the content of this function is manual work and needs to be updated if the content of ksgre_pg() or used sequence modules are changed for the gradient heating to be accurate. So if, for example, major dynamic changes of gradient amplitudes or which sequence modules that are used, this function should be updated accordingly.

As ks_eval_getduration() and ks_eval_hwlimits() are common for all sequences, this function has to have nargs and args as input arguments, but they are not used for this psd. See ksgre_eval_tr() for more details.

Parameters

[in]	max_encode_mode	The maximum encoding mode, which can be either AVERAGE_POWER or MAXIMUM_POWER.
[in]	nargs	(not used) Number of extra input arguments (# elements of void pointer array **args)
[in]	args	(not used) Void pointer array with nargs elements (may be NULL)

Return values

STATUS

SUCCESS or FAILURE

                                                                              {
  (void) nargs;
  (void) args;

  /* set seqstate... */

  if (max_encode_mode == AVERAGE_POWER) {
    ks_scan_phaser_average(&ksgre.phaseenc, INSTRALL);
  } else {
    ks_scan_phaser_max(&ksgre.phaseenc, INSTRALL);
  }

  ks_scan_playsequence(&ksgre.seqctrl);

  return SUCCESS;

} /* ksgre_gradheat_play() */

ksgre_eval_tr()

STATUS ksgre_eval_tr

(

KS_SEQ_COLLECTION *

seqcollection

)

Evaluation of number of slices / TR, set up of slice plan, TR validation and SAR checks

With the current sequence collection (see my_cveval()), and a function pointer to an argument-standardized wrapper function (ksgre_scan_sliceloop_nargs()) to the slice loop function (ksgre_scan_sliceloop(), this function calls GEReq_eval_TR(), where number of slices that can fit within one TR is determined by adding more slices as input argument to the slice loop function. For more details see GEReq_eval_TR().

With the number of slices/TR now known, a standard 2D slice plan is set up using ks_calc_sliceplan() and the duration of the main sequence is increased based on timetoadd_perTR, which was returned by GEReq_eval_TR(). timetoadd_perTR > 0 when optr > avmintr and when heat or SAR restrictions requires avmintr to be larger than the net sum of sequence modules in the slice loop.

At the end of this function, TR validation and heat/SAR checks are done using GEReq_eval_checkTR_SAR().

Parameters

[in]

seqcollection

Pointer to the KS_SEQ_COLLECTION struct holding all sequence modules

Return values

STATUS

SUCCESS or FAILURE

                                                       {
  int timetoadd_perTR;
  STATUS status;
  int slperpass, min_npasses;

  /* SAR and gradient heating */
  int newtime = 0;
  const int time = ks_eval_getduration(seqcollection, ksgre_gradheat_play, 0, NULL);
  status = ks_eval_hwlimits(&newtime, seqcollection, &loggrd, ksgre_gradheat_play, 0, NULL);
  KS_RAISE(status);

  if (newtime > time) {
    ks_eval_seqctrl_setduration(&ksgre.seqctrl, newtime);
  }

  /* interleaved slices in slice gap menu, force 2+ acqs */
  if (opileave)
    min_npasses = 2;
  else
    min_npasses = 1;

   /* Calculate # slices per TR, # acquisitions and how much spare time we have within the current TR by running the slice loop, honoring heating and SAR limits */
  status = GEReq_eval_TR(&slperpass, &timetoadd_perTR, min_npasses, seqcollection, ksgre_scan_sliceloop_nargs, 0, NULL);
  KS_RAISE(status);

  /* Calculate the slice plan (ordering) and passes (acqs). ks_slice_plan is passed to GEReq_predownload_store_sliceplan() in predownload() */
  ks_calc_sliceplan(&ks_slice_plan, exist(opslquant), slperpass);

  /* We spread the available timetoadd_perTR evenly, by increasing the .duration of each slice by timetoadd_perTR/slperpass */
  ksgre.seqctrl.duration = RUP_GRD(ksgre.seqctrl.duration + CEIL_DIV(timetoadd_perTR, ks_slice_plan.nslices_per_pass));

  /* Update SAR values in the UI (error will occur if the sum of sequence durations differs from optr) */
  status = GEReq_eval_checkTR_SAR(seqcollection, ks_slice_plan.nslices_per_pass, ksgre_scan_sliceloop_nargs, 0, NULL);
  KS_RAISE(status);

  return SUCCESS;

} /* ksgre_eval_tr() */

ksgre_check()

STATUS ksgre_check

(

)

Returns error of various parameter combinations that are not allowed for ksgre

Return values

STATUS

SUCCESS or FAILURE

                     {


  return SUCCESS;

} /* ksgre_check() */

ksgre_update_UI()

STATUS ksgre_update_UI

(

)

Update UI variables after evaluation

Return values

STATUS

SUCCESS or FAILURE

                         {

  /* Show resolution & BW per pixel in the UI */
  piinplaneres = 1;
  pirbwperpix = 1;
  ihinplanexres = ksgre.read.fov/ksgre.read.res;
  ihinplaneyres = ksgre.phaseenc.fov/ksgre.phaseenc.res;
  ihrbwperpix = (1000.0 * ksgre.read.acq.rbw * 2.0)/ksgre.read.res;

  return SUCCESS;

} /* ksgre_update_UI() */

ksgre_predownload_plot()

STATUS ksgre_predownload_plot

(

KS_SEQ_COLLECTION *

seqcollection

)

Plotting of sequence modules and slice timing in HTML files

Otherwise the function first prints out the textfile: <ks_psdname>_objects.txt, which contains the specs of most sequence components in the sequence.

The rest of the function is the plotting the main sequence diagram as HTML file, and lastly the sequence timing plot, showing slice location on the y-axis and time on the x-axis for all sequence modules (here only 1) at the same time.

For the slicetiming plot, the three functions ks_plot_slicetime_begin();ksgre_scan_scanloop();ks_plot_slicetime_end(); creates a corresponding JSON file, followed by a system call to the python script psdplot/psdplot_slicetime.py to create the HTML plot.

Return values

STATUS

SUCCESS or FAILURE

                                                                {
  char tmpstr[1000];

#ifdef PSD_HW
  sprintf(tmpstr, "/usr/g/mrraw/%s_objects.txt", ks_psdname);
#else
  sprintf(tmpstr, "./%s_objects.txt", ks_psdname);
#endif
  FILE *fp  = fopen(tmpstr, "w");

  /* Note: 'fp' can be replaced with 'stdout' or 'stderr' to get these
     values printed out in the WTools window in simulation. However,
     heavy printing may result in that the WTools window closes,
     why we here write to a file ksgre_objects.txt instead */
  ks_print_readtrap(ksgre.read, fp);
  ks_print_trap(ksgre.readdephaser, fp);
  ks_print_phaser(ksgre.phaseenc, fp);
  ks_print_trap(ksgre.spoiler, fp);
  ks_print_selrf(ksgre.selrfexc, fp);
  fclose(fp);


  /* ks_plot_host():
  Plot each sequence module as a separate file (PNG/SVG/PDF depending on ks_plot_filefmt (GERequired.e))
  See KS_PLOT_FILEFORMATS in KSFoundation.h for options.
  Note that the phase encoding amplitudes corresponds to the first shot, as set by the call to ksgre_scan_seqstate below */
  ksgre_scan_seqstate(ks_scan_info[0], 0);
  ks_plot_host(seqcollection, NULL);

  /* Sequence timing plot */
  ks_plot_slicetime_begin();
  ksgre_scan_scanloop();
  ks_plot_slicetime_end();

  return SUCCESS;

} /* ksgre_predownload_plot() */

ksgre_predownload_setrecon()

STATUS ksgre_predownload_setrecon

(

)

Last-resort function to override certain recon variables not set up correctly already

For most cases, the GEReq_predownload_*** functions in predownload() in ksgre.e set up the necessary rh*** variables for the reconstruction to work properly. However, if this sequence is customized, certain rh*** variables may need to be changed. Doing this here instead of in predownload() directly separates these changes from the standard behavior.

Return values

STATUS

SUCCESS or FAILURE

                                    {

  return SUCCESS;

} /* ksgre_predownload_setrecon() */

ksgre_pg()

STATUS ksgre_pg

(

)

The ksgre (main) pulse sequence

This is the main pulse sequence in ksgre.e using the sequence objects in KSGRE_SEQUENCE with the sequence module name "ksgremain" (= ksgre.seqctrl.description)

Return values

STATUS

SUCCESS or FAILURE

                  {
  KS_SEQLOC tmploc = KS_INIT_SEQLOC;
  int readstart_pos;
  STATUS status;


  /*******************************************************************************************************
   *  RF Excitation
   *******************************************************************************************************/
  tmploc.pos = RUP_GRD(KS_RFSSP_PRETIME);
  tmploc.board = ZGRAD;

  /* N.B.: ks_pg_selrf()->ks_pg_rf() detects that ksgre.selrfexc is an excitation pulse
     (ksgre.selrfexc.rf.role = KS_RF_ROLE_EXC) and will also set ksgre.seqctrl.momentstart
     to the absolute position in [us] of the isocenter of the RF excitation pulse */
  status = ks_pg_selrf(&ksgre.selrfexc, tmploc, &ksgre.seqctrl);
  KS_RAISE(status);

  /*******************************************************************************************************
  *  Readout timing
  *******************************************************************************************************/

  /* With ksgre.seqctrl.momentstart set by ks_pg_selrf(&ksgre.selrfexc, ...), the absolute readout position
     can be determined (for both full Fourier and partial Fourier readouts using ksgre.read.time2center) */
  readstart_pos = ksgre.seqctrl.momentstart + opte - ksgre.read.time2center;

  /*******************************************************************************************************
   *  Phase encoding
   *******************************************************************************************************/

  tmploc.pos = readstart_pos + RUP_GRD(ksgre.read.acqdelay) - ksgre.phaseenc.grad.duration;
  tmploc.board = YGRAD;

  status = ks_pg_phaser(&ksgre.phaseenc, tmploc, &ksgre.seqctrl);
  KS_RAISE(status);

  /* set phase encode amps to first ky view (for plotting & moment calcs in WTools) */
  ks_scan_phaser_toline(&ksgre.phaseenc, 0, 0);

  /*******************************************************************************************************
   *  Readout dephaser
   *******************************************************************************************************/

  tmploc.pos = readstart_pos - ksgre.readdephaser.duration;
  tmploc.board = XGRAD;

  status = ks_pg_trap(&ksgre.readdephaser, tmploc, &ksgre.seqctrl);
  KS_RAISE(status);

  /*******************************************************************************************************
   *  Readout
   *******************************************************************************************************/

  tmploc.pos = readstart_pos;
  tmploc.board = XGRAD;

  status = ks_pg_readtrap(&ksgre.read, tmploc, &ksgre.seqctrl);
  KS_RAISE(status);

  /*******************************************************************************************************
   *  Spoiler
   *******************************************************************************************************/

  tmploc.pos = readstart_pos + ksgre.read.grad.duration;
  tmploc.board = XGRAD;

  status = ks_pg_trap(&ksgre.spoiler, tmploc, &ksgre.seqctrl);
  KS_RAISE(status);

  /*******************************************************************************************************
   *  Set the minimal sequence duration (ksgre.seqctrl.min_duration) by calling
   *  ks_eval_seqctrl_setminduration()
   *******************************************************************************************************/

  tmploc.pos = RUP_GRD(tmploc.pos + ksgre.spoiler.duration);

#ifdef HOST_TGT
  /* On HOST only: Sequence duration (ksgre.seqctrl.ssi_time must be > 0 and is added to ksgre.seqctrl.min_duration in ks_eval_seqctrl_setminduration() */
  ks_eval_seqctrl_setminduration(&ksgre.seqctrl, tmploc.pos); /* tmploc.pos now corresponds to the end of last gradient in the sequence */
#endif

  return SUCCESS;

} /* ksgre_pg() */

ksgre_scan_coreslice()

int ksgre_scan_coreslice	(	const SCAN_INFO *	slice_pos,
		int	dabslice,
		int	kyindx,
		int	exc
	)

Plays out one slice in real time during scanning together with other active sequence modules

On TGT on the MR system (PSD_HW), this function sets up (ksgre_scan_seqstate()) and plays out the core ksgre sequence with optional sequence modules also called in this function. The low-level function call startseq(), which actually starts the realtime sequence playout is called from within ks_scan_playsequence(), which in addition also returns the time to play out that sequence module (see time += ...).

On HOST (in ksgre_eval_tr()) we call ksgre_scan_sliceloop_nargs(), which in turn calls this function that returns the total time in [us] taken to play out this core slice. These times are increasing in each parent function until ultimately ksgre_scan_scantime(), which returns the total time of the entire scan.

After each call to ks_scan_playsequence(), ks_plot_slicetime() is called to add slice-timing information on file for later PDF-generation of the sequence. As scanning is performed in real-time and may fail if interrupted, ks_plot_slicetime() will return quietly if it detects both IPG (TGT) and PSD_HW (on the MR scanner). See predownload() for the PNG/PDF generation.

Parameters

[in]	slice_pos	Position of the slice to be played out (one element in the global ks_scan_info[] array)
[in]	dabslice	0-based slice index for data storage
[in]	kyindx	Phase encoding index related to ksgre.phaseenc. A value outside of [0, ksgre.phaseenc.res-1] will set the phase encoding gradient amplitude to 0.
[in]	exc	Excitation index in range [0, NEX-1], where NEX = number of excitations (opnex)

Return values

coreslicetime

Time taken in [us] to play out one slice with potentially other sequence modules

                                                                                          {
  int echoindx;
  int dabop, dabview;
  TYPDAB_PACKETS acqflag;
  int time = 0;
  float tloc = 0.0;
  SCAN_INFO slice_pos_updated;
  KS_MAT4x4 Mphysical = KS_MAT4x4_IDENTITY;
  KS_MAT4x4 Mlogical = KS_MAT4x4_IDENTITY;

  if (slice_pos != NULL) {
    /* uncomment to make transformations in the logical read-phase-slice coordinate system, using your own
    logic (e.g. radial or propeller applications), here just rotating by 30 degrees in-plane
    float rotz = 30.0;
    ks_mat4_setgeometry(Mlogical, 0, 0, 0, 0, 0, rotz);
    Mphysical is useful for prospective motion correction implementations as it operates in X-Y-Z coords
    but should be left as the identity matrix otherwise
    */
    ks_scan_update_slice_location(&slice_pos_updated, *slice_pos, Mphysical, Mlogical);

    /* modify sequence for next playout */
    ksgre_scan_seqstate(slice_pos_updated, ksgre.phaseenc.linetoacq[kyindx]);
    tloc = slice_pos->optloc;
  } else {
    /* false slice, shut off RF */
    ks_scan_rf_off(&ksgre.selrfexc.rf, INSTRALL);
  }

  /* data acquisition control */
  acqflag = (kyindx >= 0 && slice_pos != NULL && dabslice >= 0) ? DABON : DABOFF; /* open or close data receiver */
  dabop = (exc <= 0) ? DABSTORE : DABADD; /* replace or add to data */
  dabview = (kyindx >= 0) ? ksgre.phaseenc.linetoacq[kyindx] : KS_NOTSET;

  for (echoindx = 0; echoindx < ksgre.read.acq.base.ngenerated; echoindx++) {
    loaddab(&ksgre.read.acq.echo[echoindx], dabslice, echoindx, dabop, dabview + 1, acqflag, PSD_LOAD_DAB_ALL);
  }

  time += ks_scan_playsequence(&ksgre.seqctrl);

  KS_PLOT_EXCITATION_MODE plottag = (slice_pos == NULL) ? KS_PLOT_NO_EXCITATION : KS_PLOT_STANDARD;
  ks_plot_slicetime(&ksgre.seqctrl, 1, &tloc, opslthick, plottag);

  return time; /* in [us] */

} /* ksgre_scan_coreslice() */

ksgre_scan_sliceloop()

int ksgre_scan_sliceloop	(	int	slperpass,
		int	passindx,
		int	kyindx,
		int	exc
	)

Plays out slperpass slices corresponding to one TR

This function gets a spatial slice location index based on the pass index and temporal position within current pass. It then calls ksgre_scan_coreslice() to play out one coreslice (i.e. the main ksgre main sequence + optional sequence modules, excluding inversion modules).

Parameters

[in]	slperpass	Number of slices to play in the slice loop
[in]	passindx	0-based pass index in range [0, ks_slice_plan.npasses - 1]
[in]	kyindx	Phase encoding index related to ksgre.phaseenc. A value outside of [0, ksgre.phaseenc.res-1] will set the phase encoding gradient amplitude to 0.
[in]	exc	Excitation index in range [0, NEX-1], where NEX = number of excitations (opnex)

Return values

slicelooptime

Time taken in [us] to play out slperpass slices

                                                                           {
  int time = 0;
  int slloc, sltimeinpass;

  for (sltimeinpass = 0; sltimeinpass < slperpass; sltimeinpass++) {

    /* slice location from slice plan (KS_NOTSET (= -1) means dummy slice) */
    slloc = ks_scan_getsliceloc(&ks_slice_plan, passindx, sltimeinpass);

    time += ksgre_scan_coreslice((slloc != KS_NOTSET) ? &ks_scan_info[slloc] : NULL, sltimeinpass, kyindx, exc);

  }

  return time; /* in [us] */

} /* ksgre_scan_sliceloop() */

ksgre_scan_init()

STATUS ksgre_scan_init

(

void

)

Common initialization for prescan entry points MPS2 and APS2 as well as the SCAN entry point

Return values

STATUS

SUCCESS or FAILURE

                             {

  GEReq_initRSP();

  /* Here goes code common for APS2, MPS2 and SCAN */

  ks_scan_switch_to_sequence(&ksgre.seqctrl);  /* switch to main sequence */
  scopeon(&seqcore); /* Activate scope for core */
  syncon(&seqcore);  /* Activate sync for core */
  setssitime(ksgre.seqctrl.ssi_time/HW_GRAD_UPDATE_TIME);

  /* can we make these independent on global rsptrigger and rsprot in orderslice? */
  settriggerarray( (short) ks_slice_plan.nslices_per_pass, rsptrigger);

  return SUCCESS;

} /* ksgre_scan_init() */

ksgre_scan_prescanloop()

STATUS ksgre_scan_prescanloop	(	int	nloops,
		int	dda
	)

Prescan loop called from both APS2 and MPS2 entry points

Return values

STATUS

SUCCESS or FAILURE

                                                   {
  int i, echoindx, sltimeinpass, slloc;

  /* turn off receivers for all echoes */
  for (echoindx = 0; echoindx < ksgre.read.acq.base.ngenerated; echoindx++) {
    loaddab(&ksgre.read.acq.echo[echoindx], 0, 0, DABSTORE, 0, DABOFF, PSD_LOAD_DAB_ALL);
  }

  /* play first 'dda' dummy scans to get into steady state before start acquiring data */
  for (i = -dda; i < nloops; i++) {

    /* loop over slices */
    for (sltimeinpass = 0; sltimeinpass < ks_slice_plan.nslices_per_pass; sltimeinpass++) {

      slloc = ks_scan_getsliceloc(&ks_slice_plan, 0, sltimeinpass);

      /* modify sequence for next playout */
      ksgre_scan_seqstate(ks_scan_info[slloc], KS_NOTSET); /* KS_NOTSET => no phase encoding */

      /* data routing control */
      if (i >= 0) {
        /* turn on receiver for 1st echo */
        if (ksgre.read.acq.base.ngenerated > 0)
          loaddab(&ksgre.read.acq.echo[0], 0, 0, DABSTORE, 0, DABON, PSD_LOAD_DAB_ALL);
      }

      ks_scan_playsequence(&ksgre.seqctrl);

    } /* for slices */

  } /* for nloops */

  return SUCCESS;

} /* ksgre_scan_prescanloop() */

Variable Documentation

seqcollection

KS_SEQ_COLLECTION seqcollection

ksgre_gscalerfexc

float ksgre_gscalerfexc = 0.9

ksgre_spoilerarea

float ksgre_spoilerarea = 2000.0 with {0.0, 10000.0, 2000.0, VIS, "ksgre spoiler gradient area",}

ksgre_ssi_time

int ksgre_ssi_time = KSGRE_DEFAULT_SSI_TIME with {32, , KSGRE_DEFAULT_SSI_TIME, VIS, "time from eos to ssi in intern trig",}

ksgre_dda

int ksgre_dda = 2 with {0, 200, 2, VIS, "Number of dummy scans for steady state",}

ksgre

KSGRE_SEQUENCE ksgre = KSGRE_INIT_SEQUENCE

sequence_iopts

int sequence_iopts[]

Initial value:

= {
  PSD_IOPT_EDR, 
  PSD_IOPT_SEQUENTIAL 














}

volindx

int volindx

passindx

int passindx