Sequence-independent looping functions (ksscan.h)

Data Structures
struct	KS_SLICETIMING_DESIGN
struct	KS_SLICETIMING
struct	KS_CORESLICETIME
struct	KS_PHASEENCODING_PLAN_DESIGN
struct	KSSCAN_LOOP_CONTROL
struct	KSSCAN_LOOP_CONTROL_DESIGN

Macros
#define	KS_MAX_RF_SCANINFO   256
#define	KS_INIT_SLICETIMING_DESIGN   {KS_INITVALUE(SLTAB_MAX, DEFAULT_AXIAL_SCAN_INFO), KS_NOTSET, 0, 1, 1, 2, 0, 0}
#define	KS_INIT_SLICETIMING   {KS_INITVALUE(KS_MAX_RF_SCANINFO, DEFAULT_AXIAL_SCAN_INFO), KS_INIT_SLICEPLAN, KS_NOTSET, KS_NOTSET, 0, 1, 0, SMS_SLICE_ENCODING_DIRECTION_NEG}
#define	KS_INIT_CORESLICETIME   {0, KS_NOTSET};
#define	KS_INIT_PHASEENCODING_PLAN_DESIGN   {KS_INIT_DESC, KS_INIT_KSPACE_ACQ, {CARTESIAN_COORD, CARTESIAN_COORD}, 1, KS_NOTSET, MTF_Y, Y_Z, SPLIT_SHOTS_LCPO, KS_INIT_PHASEENCODING_REPEAT_DESIGN}
#define	KSSCAN_INIT_LOOP_CONTROL   {0, 0, 0, 0, 0, KS_INIT_PHASEENCODING_PLAN, KS_INIT_PHASEENCODING_PLAN, KS_INIT_SLICETIMING}
#define	KSSCAN_INIT_LOOP_CONTROL_DESIGN   {0, 1, 1, 1, 0, KS_INIT_PHASEENCODING_PLAN_DESIGN, KS_INIT_PHASEENCODING_PLAN_DESIGN, KS_INIT_SLICETIMING_DESIGN}

Enumerations
enum	SMS_SLICE_ENCODING_DIRECTION { SMS_SLICE_ENCODING_DIRECTION_POS, SMS_SLICE_ENCODING_DIRECTION_NEG }

Functions
STATUS	ksscan_validate_slicetimingdesign (const KS_SLICETIMING_DESIGN *design)
STATUS	ksscan_slicetiming_eval_design (KS_SLICETIMING *slicetiming, KS_SEQ_CONTROL *sequence_to_inflate, KS_CORESLICETIME coreslice(const SCAN_INFO *slice_pos, KS_DYNAMIC_STATE *dynamic), const KS_SLICETIMING_DESIGN *slicetiming_design)
void	ksscan_copy_slices (KS_SLICETIMING_DESIGN *slicetiming_design, const SCAN_INFO *slice_pos)
STATUS	ksscan_eval_setup_rf_slices (KS_SLICETIMING *slicetiming, const KS_SLICETIMING_DESIGN *slicetiming_design, int is2D)
STATUS	ksscan_phaseencoding_plan_eval_design (KS_PHASEENCODING_PLAN *pe_plan, const KS_PHASEENCODING_PLAN_DESIGN *design)
STATUS	ksscan_loop_control_eval_design (KSSCAN_LOOP_CONTROL *loop_control, KS_SEQ_CONTROL *sequence_to_inflate, KS_CORESLICETIME coreslice(const SCAN_INFO *slice_pos, KS_DYNAMIC_STATE *dynamic), const KSSCAN_LOOP_CONTROL_DESIGN *design)
s64	ksscan_sliceloop (const KSSCAN_LOOP_CONTROL *loop_control, KS_DYNAMIC_STATE *dynamic, KS_CORESLICETIME coreslice(const SCAN_INFO *slice_pos, KS_DYNAMIC_STATE *dynamic))
s64	ksscan_acqloop (const KSSCAN_LOOP_CONTROL *loop_control, KS_DYNAMIC_STATE *dynamic, KS_CORESLICETIME coreslice(const SCAN_INFO *slice_pos, KS_DYNAMIC_STATE *dynamic))
void	ksscan_plotloop_shots (const KSSCAN_LOOP_CONTROL *loop_control, KS_CORESLICETIME coreslice(const SCAN_INFO *slice_pos, KS_DYNAMIC_STATE *dynamic))
void	ksscan_plotloop_slices (const KSSCAN_LOOP_CONTROL *loop_control, KS_CORESLICETIME coreslice(const SCAN_INFO *slice_pos, KS_DYNAMIC_STATE *dynamic))
s64	ksscan_scanloop (const KSSCAN_LOOP_CONTROL *orig_loop_control, KS_DYNAMIC_STATE *dynamic, KS_CORESLICETIME coreslice(const SCAN_INFO *slice_pos, KS_DYNAMIC_STATE *dynamic))
void	ksscan_prescanloop (const KSSCAN_LOOP_CONTROL *loop_control, KS_CORESLICETIME coreslice(const SCAN_INFO *slice_pos, KS_DYNAMIC_STATE *dynamic), int nloops, int dda)
void	ksscan_init_loopcontrol (KSSCAN_LOOP_CONTROL *loop_control)
void	ksscan_init_slicetiming (KS_SLICETIMING *slicetiming)
void	ks_plot_psd (const KS_SEQ_CONTROL *ctrl, const KSSCAN_LOOP_CONTROL *loopctrl)

Detailed Description

Macro Definition Documentation

KS_MAX_RF_SCANINFO

#define KS_MAX_RF_SCANINFO   256

max RF slices per sequence module (2D: num slices, 3D: 1)

KS_INIT_SLICETIMING_DESIGN

#define KS_INIT_SLICETIMING_DESIGN   {KS_INITVALUE(SLTAB_MAX, DEFAULT_AXIAL_SCAN_INFO), KS_NOTSET, 0, 1, 1, 2, 0, 0}

KS_INIT_SLICETIMING

#define KS_INIT_SLICETIMING   {KS_INITVALUE(KS_MAX_RF_SCANINFO, DEFAULT_AXIAL_SCAN_INFO), KS_INIT_SLICEPLAN, KS_NOTSET, KS_NOTSET, 0, 1, 0, SMS_SLICE_ENCODING_DIRECTION_NEG}

Default values for KS_SLICETIMING

KS_INIT_CORESLICETIME

#define KS_INIT_CORESLICETIME   {0, KS_NOTSET};

KS_INIT_PHASEENCODING_PLAN_DESIGN

#define KS_INIT_PHASEENCODING_PLAN_DESIGN   {KS_INIT_DESC, KS_INIT_KSPACE_ACQ, {CARTESIAN_COORD, CARTESIAN_COORD}, 1, KS_NOTSET, MTF_Y, Y_Z, SPLIT_SHOTS_LCPO, KS_INIT_PHASEENCODING_REPEAT_DESIGN}

KSSCAN_INIT_LOOP_CONTROL

#define KSSCAN_INIT_LOOP_CONTROL   {0, 0, 0, 0, 0, KS_INIT_PHASEENCODING_PLAN, KS_INIT_PHASEENCODING_PLAN, KS_INIT_SLICETIMING}

KSSCAN_INIT_LOOP_CONTROL_DESIGN

#define KSSCAN_INIT_LOOP_CONTROL_DESIGN   {0, 1, 1, 1, 0, KS_INIT_PHASEENCODING_PLAN_DESIGN, KS_INIT_PHASEENCODING_PLAN_DESIGN, KS_INIT_SLICETIMING_DESIGN}

Enumeration Type Documentation

SMS_SLICE_ENCODING_DIRECTION

enum SMS_SLICE_ENCODING_DIRECTION

Enumerator
SMS_SLICE_ENCODING_DIRECTION_POS
SMS_SLICE_ENCODING_DIRECTION_NEG

{SMS_SLICE_ENCODING_DIRECTION_POS, SMS_SLICE_ENCODING_DIRECTION_NEG} SMS_SLICE_ENCODING_DIRECTION; 

Function Documentation

ksscan_validate_slicetimingdesign()

STATUS ksscan_validate_slicetimingdesign

(

const KS_SLICETIMING_DESIGN *

design

)

Function that performs range checks for the fields in KS_SLICETIMING_DESIGN before it is used

Parameters

[in]

design

Pointer to KS_SLICETIMING_DESIGN

Return values

STATUS

SUCCESS or FAILURE

                                                                              {

  if (design->nslices < 1 || design->nslices > 512) {
    return KS_THROW("nslices (%d) must be in range [1,512]", design->nslices);
  }
  if (design->minacqs < 1 || design->minacqs > 512) {
    return KS_THROW("minacqs (%d) must be in range [1,512]", design->minacqs);
  }
  if (design->inpass_interleaves < 1 || design->inpass_interleaves > 16) {
    return KS_THROW("inpass_interleaves (%d) must be in range [1,16]", design->inpass_interleaves);
  }  

  if (design->minTR < 0) {
    return KS_THROW("minTR (%d) must be >= 0", design->minTR);
  }
  if (design->maxTR < 0) {
    return KS_THROW("maxTR (%d) must be >= 0", design->maxTR);
  }
  if (design->maxTR > 0 && (design->maxTR < design->minTR)) {
    return KS_THROW("maxTR (%d) must be >= .minTR (%d)", design->maxTR, design->minTR);
  }

  if (design->is3D) {
    if (design->minacqs != 1) {
      return KS_THROW("minacqs (%d) must be 1 in 3D mode", design->minacqs);
    }
  }

  if (design->nslices % design->sms_factor) {
    return KS_THROW("#slices (%d) must be divisible with the SMS factor (%d)", design->nslices, design->sms_factor);
  }

  return SUCCESS;

} /* ksscan_validate_slicetimingdesign() */

ksscan_slicetiming_eval_design()

STATUS ksscan_slicetiming_eval_design	(	KS_SLICETIMING *	slicetiming,
		KS_SEQ_CONTROL *	sequence_to_inflate,
		KS_CORESLICETIME	coresliceconst SCAN_INFO *slice_pos, KS_DYNAMIC_STATE *dynamic,
		const KS_SLICETIMING_DESIGN *	slicetiming_design
	)

Calculate the number of slices/TR and TR padding time (no use of CVs or global variables)

This function calculates the number of slices that can fit in one TR based on the duration and occurences of the sequence modules and the requested design. This function is intended to be a better alternative to GERequired.e:GEReq_eval_TR(), as it does not use any global variables and can therefore be called more than once with different parameters without interference. This is useful when a sequence contains more than one slice loop with different parameters, for instance a calibration step followed by the main loop.

Parameters

[out]	slicetiming	Struct containing all information for looping through the slices
[in,out]	sequence_to_inflate	The sequence control for the module of choice to inflate (i.e. increase it .duration field) to meet the desired TR
[in]	coreslice	Function pointer to a coreslice function playing one or more modules representing the kernel that is repeated within a TR for each slice location
[in]	slicetiming_design	Design parameters for the calculation of

Return values

STATUS

SUCCESS or FAILURE

                                                                                       {

  if (sequence_to_inflate->duration == 0) {
    ksscan_init_slicetiming(slicetiming);
    return SUCCESS;
  }

  STATUS status;
  int numacqs = 0;
  int minacqs = KS_NOTSET;
  int i;
  int TR_for_thismanyslices = KS_NOTSET;
  int TR_for_shortest_scantime = KS_NOTSET;
  int nslices_perTR = KS_NOTSET;
  int nslices_shortest_scantime = KS_NOTSET;
  int shortest_scantime = KS_NOTSET;
  int singleslice_time = KS_NOTSET;
  int autoTR = KS_NOTSET;

  /* Copy fields */
  slicetiming->is3D = slicetiming_design->is3D;

  /* Calculate the offset to the slice location for 3D scans */
  slicetiming->slloc_offset = 0;
  if (slicetiming_design->is3D &&
      slicetiming_design->scan_info[1].optloc > slicetiming_design->scan_info[0].optloc) {
    slicetiming->slloc_offset = slicetiming_design->nslices - 1;
  }

  status = ksscan_eval_setup_rf_slices(slicetiming, slicetiming_design, !slicetiming_design->is3D);
  KS_RAISE(status);

  /* N.B.: For the purpose of finding how many slices that can fit within one TR,
     the terms 'per acqs', 'per pass', and 'per TR' are used synonymously here (and elsewhere) */

  if ((slicetiming_design->maxTR > 0) && (slicetiming_design->maxTR < slicetiming_design->minTR)) {
    return KS_THROW(".maxTR (%.1f) must be >= .minTR (%.1f) , or KS_NOTSET (disabled)", slicetiming_design->maxTR / 100.0, slicetiming_design->minTR / 100.0);
  }

  /* time for a single slice */
  singleslice_time = _play_loop(1, coreslice);
  if (singleslice_time <= 0) return KS_THROW("negative core slice duration (%d us)", singleslice_time);

  if ((slicetiming_design->maxTR > 0) && (slicetiming_design->maxTR < singleslice_time)) {
    if (slicetiming_design->maxTR == slicetiming_design->minTR) {
      return KS_THROW("TR (%.1f) must be > %.1f ms",  slicetiming_design->maxTR / 1000.0, singleslice_time / 1000.0);
    } else {
      return KS_THROW("Max TR (%.1f) must be > %.1f ms",  slicetiming_design->maxTR / 1000.0, singleslice_time / 1000.0);
    }
  }
  if ((slicetiming_design->minTR > 0) && (slicetiming_design->minTR < singleslice_time)) {
    return KS_THROW("Min TR (%.1f) must be > %.1f ms",  slicetiming_design->minTR / 1000.0, singleslice_time / 1000.0);
  }
  if ((slicetiming_design->maxTR > 0) && (slicetiming_design->minTR > 0) && 
     ((slicetiming_design->maxTR > slicetiming_design->minTR)) && ((slicetiming_design->maxTR - slicetiming_design->minTR) < singleslice_time)) {
    return KS_THROW("The [design.minTR (%.1f), design.maxTR (%.1f)]  interval must be > %.1f ms (or 0 for manual TR)",  slicetiming_design->minTR / 1000.0,  slicetiming_design->maxTR / 1000.0, singleslice_time / 1000.0);
  }
  if ((slicetiming_design->maxTR >= singleslice_time) && (slicetiming_design->maxTR == slicetiming_design->minTR)) {
    autoTR = FALSE;
  } else {
    autoTR = TRUE;
  }

  /* #acqs cannot exceed #slices. If sequential scanning, #acqs = #slices */
  minacqs = slicetiming_design->minacqs;
  if (minacqs < 1) {
    minacqs = 1;
  } else if (minacqs >= slicetiming->slice_plan.nslices) {
    minacqs = slicetiming->slice_plan.nslices;
  }

  int requested_maxslices_perTR = CEIL_DIV(slicetiming->slice_plan.nslices, minacqs);
  int TR_for_requested_maxslices = _play_loop(requested_maxslices_perTR, coreslice);

  if (autoTR) {

    if (slicetiming_design->maxTR > 0) { /* in-range autoTR */

      /* Check which combination that results in the lowest scan time, and max/min # slices in range */
      for (i = 1; i <= slicetiming->slice_plan.nslices; i++) {
        numacqs = CEIL_DIV(slicetiming->slice_plan.nslices, i);
        TR_for_thismanyslices = _play_loop(i, coreslice);
        if ((TR_for_thismanyslices >= slicetiming_design->minTR) && (slicetiming_design->maxTR == 0 || TR_for_thismanyslices <= slicetiming_design->maxTR) && (numacqs >= minacqs)) {
          /* if in TR range and numacqs >= minacqs */
          if (shortest_scantime == KS_NOTSET) {
            nslices_shortest_scantime = i;
            shortest_scantime = TR_for_thismanyslices * numacqs;
            TR_for_shortest_scantime = TR_for_thismanyslices;
          } else if (TR_for_thismanyslices * numacqs <= shortest_scantime * 1.01) {
            /* 1.01 to avoid round-off effects of TR_for_thismanyslices and to slightly favor fewer acqs and longer TRs
            when the scantime is nearly identical */
            nslices_shortest_scantime = i;
            shortest_scantime = TR_for_thismanyslices * numacqs;
            TR_for_shortest_scantime = TR_for_thismanyslices;
          }
        }
      }

      if (shortest_scantime == KS_NOTSET && slicetiming_design->minTR > 0) {
        /* failed to find solution within the interval, the range is probably too high for the set
            of slices. Need to add padding to reach slicetiming_design->minTR */
        if (TR_for_requested_maxslices < slicetiming_design->minTR) {
          nslices_perTR = requested_maxslices_perTR;
          slicetiming->TR = slicetiming_design->minTR;
        } else {
          return KS_THROW("Programming error");
        }
      } else {
        nslices_perTR = nslices_shortest_scantime;
        slicetiming->TR = TR_for_shortest_scantime;
      }

    } else { /* minimum TR (using requested_minacqs) */

      nslices_perTR = requested_maxslices_perTR;
      slicetiming->TR = IMax(2, TR_for_requested_maxslices, slicetiming_design->minTR);

    }

    /* .maxslices_per_TR corresponds to .design.maxTR so we know how many we COULD have fit in */
    if (minacqs == slicetiming->slice_plan.nslices) {
      slicetiming->maxslices_per_TR = 1; /* looks better for sequential */
    } else if (slicetiming_design->maxTR == 0) {
      slicetiming->maxslices_per_TR = 2048; /* GEs normal slice max value */
    } else {
      slicetiming->maxslices_per_TR = _maxslicespertr(slicetiming_design->maxTR, coreslice);
    }



  } else { /* Manual TR (based on user input: slicetiming_design->minTR == slicetiming_design->maxTR, both > 0) */

    /* how many slices COULD we fit in this fixed TR (=.minTR=.maxTR) ? */
    if (minacqs == slicetiming->slice_plan.nslices) { /* sequential */
      nslices_perTR = 1;
      slicetiming->maxslices_per_TR = 1;
    } else {
      slicetiming->maxslices_per_TR = _maxslicespertr(slicetiming_design->maxTR /* same here as .minTR */, coreslice);
      /* requested_maxslices_perTR: max slices the user wants per TR in order to get at least 'minacqs' number of passes
         slicetiming->maxslices_per_TR: how many slices that can fit in the fixed TR
         Take the minimum of these two to get number of slices to actually play per TR
       */
      nslices_perTR = IMin(2, slicetiming->maxslices_per_TR, requested_maxslices_perTR);

    }
    slicetiming->TR = slicetiming_design->minTR;

  } /* Auto/Manual TR */

  /* If SMS, check that nslices_perTR is an odd number (can some times be helped by adjusting #interleaves) */
  int inpass_interleaves = slicetiming_design->inpass_interleaves;
  status = ks_sms_check_divisibility(&inpass_interleaves, slicetiming_design->sms_factor, nslices_perTR, slicetiming->slice_plan.nslices);
  KS_RAISE(status);

  /* setup the slice plan for the sequence */
  ks_calc_sliceplan_interleaved(&slicetiming->slice_plan, slicetiming->slice_plan.nslices, nslices_perTR, inpass_interleaves);

  /* Update the number of instances of the sequence to be inflated given 'slicetiming->slice_plan.nslices_per_pass' number of slices
     time [us] for one sequence playout incl. the SSI time and necessary dead time to
     make up the expected TR. To be used in KS_SEQLENGTH() in pulsegen() */
  sequence_to_inflate->nseqinstances = 0;
  int timetoadd_perTR = slicetiming->TR - _play_loop(slicetiming->slice_plan.nslices_per_pass, coreslice);

  if (timetoadd_perTR < 0) {
    return KS_THROW("Programming error");
  }

  /* inflate the sequence to meet TR. If we have a non-standard sequence module to inflate during TR, which may not be executed
     'slicetiming->slice_plan.nslices_per_pass' time for that many slices, we divide here instead with 'sequence_to_inflate->nseqinstances'
     that just got the right value thanks to being reset to zero followed by _play_loop() a few lines above */
  if (sequence_to_inflate->nseqinstances > 0) {
    sequence_to_inflate->duration = RUP_GRD(sequence_to_inflate->duration + CEIL_DIV(timetoadd_perTR, sequence_to_inflate->nseqinstances));
  } else {
    return KS_THROW("the sequence to inflate (%s) not played in scan, cannot adjust duration for TR", sequence_to_inflate->description);
  }


  return SUCCESS;

} /* ksscan_slicetiming_eval_design() */

ksscan_copy_slices()

void ksscan_copy_slices	(	KS_SLICETIMING_DESIGN *	slicetiming_design,
		const SCAN_INFO *	slice_pos
	)

Copying of the graphical slice prescription in the UI (scan_info[]) and opslquant to the KS_SLICETIMING_DESIGN structure

Parameters

[in,out]	slicetiming_design	Pointer to KS_SLICETIMING. Fields design.nslices, design.scan_info and state.rf_scan_info set by this function from UI variables
[in]	slice_pos	Position of the slice to be played out (one element in the ks_scan_info[] array)

Returns

void

                                                                                               {

  memcpy(slicetiming_design->scan_info, scan_info, slicetiming_design->nslices * sizeof(SCAN_INFO));

} /* ksscan_copy_slices() */

ksscan_eval_setup_rf_slices()

STATUS ksscan_eval_setup_rf_slices	(	KS_SLICETIMING *	slicetiming,
		const KS_SLICETIMING_DESIGN *	slicetiming_design,
		int	is2D
	)

Setup the slice offsets that will be actually be used

Internal use*

Parameters

[in,out]	slicetiming	Pointer to KS_SLICETIMING
[in]	slicetiming_design	Pointer to KS_SLICETIMING. Fields design.nslices, design.scan_info and state.rf_scan_info set by this function from UI variables
[in]	is2D	Boolean indicator for 2D

Return values

STATUS

SUCCESS or FAILURE

                                                                                              {

  STATUS status = SUCCESS;

  if (slicetiming_design->nslices <= 0) {
    return KS_THROW("slicetiming_design.nslices must be >= 1");
  }

  slicetiming->sms_factor = slicetiming_design->sms_factor;

  if (is2D) {

    if (slicetiming_design->sms_factor > 1) { /* SMS */

      /* memcopy of design.scan_info into state.rf_scaninfo is done in ks_eval_sms_rf_scan_info */
      slicetiming->slice_plan.nslices = ks_eval_sms_rf_scan_info(slicetiming->rf_scan_info,
                                                                 slicetiming_design->scan_info,
                                                                 slicetiming_design->sms_factor,
                                                                 slicetiming_design->nslices);
      if (slicetiming->slice_plan.nslices < 1) {
        return KS_THROW("ks_eval_sms_rf_scan_info has failed");
      }

      /* set sms_slice_encoding_direction */
      slicetiming->sms_slice_encoding_direction = (0 < (slicetiming->rf_scan_info[1].optloc - slicetiming->rf_scan_info[0].optloc)) ? SMS_SLICE_ENCODING_DIRECTION_POS : SMS_SLICE_ENCODING_DIRECTION_NEG;

    } else { /* Normal 2D */

      slicetiming->slice_plan.nslices = slicetiming_design->nslices;
      memcpy(slicetiming->rf_scan_info, slicetiming_design->scan_info, slicetiming->slice_plan.nslices * sizeof(SCAN_INFO));

    }

  } else { /* 3D mode */

    SCAN_INFO centerposition = slicetiming_design->scan_info[0];
    /* SCAN_INFO centre_slices[opvquant]; used for multislab; TODO: figure out how multi-slab works*/
    int centerslice = slicetiming_design->nslices/2;
    slicetiming->slice_plan.nslices = 1;
    /* for future 3D multislab support, let passindx update centerposition */
    if (slicetiming_design->nslices == 1) {
      centerposition.optloc = slicetiming_design->scan_info[0].optloc;
    } else {
      centerposition.optloc = (slicetiming_design->scan_info[centerslice-1].optloc +
                             slicetiming_design->scan_info[centerslice].optloc)/2.0;

    }
    slicetiming->rf_scan_info[0] = centerposition;

  }

  return status;

} /* ksscan_eval_setup_rf_slices() */

ksscan_phaseencoding_plan_eval_design()

STATUS ksscan_phaseencoding_plan_eval_design	(	KS_PHASEENCODING_PLAN *	pe_plan,
		const KS_PHASEENCODING_PLAN_DESIGN *	design
	)

Generates a phase encodin plan according to design

This function is a wrapper for ks_generate_peplan_from_kcoords using a design struct instead of separated arguments.

Parameters

[out]	pe_plan	Phase encoding plan to be generated
[in]	design	Design of the phase encoding plan

Return values

STATUS

SUCCESS or FAILURE

                                                                                                                         {
  STATUS s;

  if (!design->kacq.coords) {
    return KS_THROW("coords is NULL");
  }

  strcpy(pe_plan->description, design->description);

  /* If repeated phase encoding plan is requested, change encodes_per_shot or center_encode */
  int encodes_per_shot = design->encodes_per_shot;
  int center_encode = design->center_encode;
  if (design->repeat.num_repeats > 1) {
    if (design->repeat.mode == INTERLEAVED_LONGER_SHOTS) { /* e.g. [1,3,2,4] -> [1, 1, 3, 3, 2, 2, 4, 4] */
      encodes_per_shot /= design->repeat.num_repeats;
      if (center_encode != KS_NOTSET) {
        center_encode /= design->repeat.num_repeats;
      }
    }
    /* TODO: Verify that other modes don't change encodes_per_shot and center_encode */
  }

  s = ks_generate_peplan_from_kcoords(&design->kacq,
                                      pe_plan,
                                      design->mtf_direction,
                                      design->encode_shot_assignment_order,
                                      design->mtf_profile,
                                      encodes_per_shot,
                                      center_encode,
                                      design->coord_type);
  KS_RAISE(s);

  pe_plan->coord_type[0] = design->coord_type[0];
  pe_plan->coord_type[1] = design->coord_type[1];

  s = ks_repeat_peplan(pe_plan, &design->repeat);
  KS_RAISE(s);

  return SUCCESS;

} /* ksscan_phaseencoding_plan_eval_design() */

ksscan_loop_control_eval_design()

STATUS ksscan_loop_control_eval_design	(	KSSCAN_LOOP_CONTROL *	loop_control,
		KS_SEQ_CONTROL *	sequence_to_inflate,
		KS_CORESLICETIME	coresliceconst SCAN_INFO *slice_pos, KS_DYNAMIC_STATE *dynamic,
		const KSSCAN_LOOP_CONTROL_DESIGN *	design
	)

Generates a loop control

This function should be the default way to generating a loop control.

Parameters

[out]	loop_control	Loop control to be generated. It contains all information needed for a standard scan loop
[in,out]	sequence_to_inflate	Control for the sequence that is to be inflated if needed to adjust the TR timing
[in]	coreslice	Function pointer to a coreslice function playing one or more modules representing the kernel that is repeated within a TR for each slice location
[in]	design	Design of the loop control

Return values

STATUS

SUCCESS or FAILURE

                                                                                 {

  STATUS s;

  if (sequence_to_inflate->duration == 0) {
    ksscan_init_loopcontrol(loop_control);
    return SUCCESS;
  }

  /* copy fields */
  loop_control->dda = design->dda;
  loop_control->nvols = design->nvols;
  loop_control->naverages = design->naverages;
  loop_control->play_endofpass = design->play_endofpass;
  loop_control->interleaved_snapshot = design->interleaved_snapshot;

  s = ksscan_phaseencoding_plan_eval_design(&loop_control->phaseenc_plan, &design->phaseenc_design);
  KS_RAISE(s);

  /* Only eval the dummy plan if there are coords */
  if (design->phaseenc_design_dummies.kacq.coords) {
    s = ksscan_phaseencoding_plan_eval_design(&loop_control->phaseenc_plan_dummies, &design->phaseenc_design_dummies);
    KS_RAISE(s);
  }

  s = ksscan_slicetiming_eval_design(&loop_control->slicetiming,
                                     sequence_to_inflate,
                                     coreslice,
                                     &design->slicetiming_design);
  KS_RAISE(s);

  return SUCCESS;
  
} /* ksscan_loop_control_eval_design() */

ksscan_sliceloop()

s64 ksscan_sliceloop	(	const KSSCAN_LOOP_CONTROL *	loop_control,
		KS_DYNAMIC_STATE *	dynamic,
		KS_CORESLICETIME	coresliceconst SCAN_INFO *slice_pos, KS_DYNAMIC_STATE *dynamic
	)

Executes all loops for a single TR

Usually it loops only over slices but, if the flag interleaved_snapshot is set, it loops over shots for each slice position.

Parameters

[in]	loop_control	Loop control containing all information needed for a standard scan loop
[in,out]	dynamic	Pointer to KS_DYNAMIC_STATE used to loop and ultimately set the state of the module(s) played
[in]	coreslice	Function pointer to a coreslice function playing one or more modules representing the kernel that is repeated within a TR for each slice location

Return values

s64	Duration of a single TR

                                                                                                        {
  s64 time = 0;
  const SCAN_INFO *current_slice = NULL;
  const int num_shots = loop_control->interleaved_snapshot ? loop_control->phaseenc_plan.num_shots : 1;

  for (dynamic->sltimeinpass = 0; dynamic->sltimeinpass < loop_control->slicetiming.slice_plan.nslices_per_pass; dynamic->sltimeinpass++) {
    for (dynamic->inner_shot = 0; dynamic->inner_shot < num_shots; dynamic->inner_shot++) {

      if (loop_control->interleaved_snapshot && dynamic->shot >= 0) {
        /*
          When running in interleaved snapshot mode, we need to use the inner shot index to retrieve the shot coordinates.
          Note that, we should not overwrite the shot coordinates for dummies so that the phasers will be turned off as
          expected. Hence, if shot index is negative shot_coords is not updated.
         */
        dynamic->shot_coords = ks_phaseencoding_get_shot(&loop_control->phaseenc_plan, dynamic->inner_shot);
      }

      if (loop_control->slicetiming.is3D) { /* 3D */
        dynamic->slloc = 0;
        /* Store the offset so that coreslice can get information about the slice stack's direction */
        dynamic->slloc_offset = loop_control->slicetiming.slloc_offset; 
      } else { /* 2D */
        /* slice location from slice plan */
        dynamic->slloc = ks_scan_getsliceloc(&loop_control->slicetiming.slice_plan, dynamic->pass, dynamic->sltimeinpass);
      }

      /* if dynamic->slloc = KS_NOTSET, pass in NULL as first argument to indicate 'false slice' */
      current_slice = (dynamic->slloc != KS_NOTSET) ?
        &loop_control->slicetiming.rf_scan_info[dynamic->slloc] : NULL;

      if (coreslice) {
        time += coreslice(current_slice, dynamic).duration;
      }

    } /* inner shot */
  } /* slice loop */

  return time; /* in [us] */

} /* ksscan_sliceloop() */

ksscan_acqloop()

s64 ksscan_acqloop	(	const KSSCAN_LOOP_CONTROL *	loop_control,
		KS_DYNAMIC_STATE *	dynamic,
		KS_CORESLICETIME	coresliceconst SCAN_INFO *slice_pos, KS_DYNAMIC_STATE *dynamic
	)

Executes all loops for a single pass/acquisition

Parameters

[in]	loop_control	Loop control containing all information needed for a standard scan loop
[in,out]	dynamic	Pointer to KS_DYNAMIC_STATE used to loop and ultimately set the state of the module(s) played
[in]	coreslice	Function pointer that plays one or several modules representing the kernel that is repeated within a TR for each slice location

Return values

s64	Duration of a single pass/acquisition

                                                                                                      {
  s64 time = 0;
  char slicegroup_desc[256];

  /* shot < 0 means dummy scans */
  const int num_shots = loop_control->interleaved_snapshot ? 1 : loop_control->phaseenc_plan.num_shots;
  for (dynamic->shot = -loop_control->dda; dynamic->shot < num_shots; dynamic->shot++) {    

    const int naverages = dynamic->shot < 0 ? 1 : loop_control->naverages;
    dynamic->shot_coords = dynamic->shot >= 0 ? ks_phaseencoding_get_shot(&loop_control->phaseenc_plan,          dynamic->shot)
                                              : ks_phaseencoding_get_shot(&loop_control->phaseenc_plan_dummies, -dynamic->shot - 1);

    for (dynamic->average = 0; dynamic->average < naverages; dynamic->average++) {

      time += ksscan_sliceloop(loop_control, dynamic, coreslice);

      sprintf(slicegroup_desc, "%s - pass %d shot %d average %d",
              "Generic loop", /*seq->design.description,*/
              dynamic->pass, dynamic->shot, dynamic->average);
      ks_plot_slicetime_endofslicegroup_tagged(slicegroup_desc, (dynamic->shot < 0) ? KS_PLOT_SG_DUMMY : KS_PLOT_SG_ACQUISITION);
    } /* for average */

  } /* for shot */

  return time; /* in [us] */

} /* ksscan_acqloop() */

ksscan_plotloop_shots()

void ksscan_plotloop_shots	(	const KSSCAN_LOOP_CONTROL *	loop_control,
		KS_CORESLICETIME	coresliceconst SCAN_INFO *slice_pos, KS_DYNAMIC_STATE *dynamic
	)

Executes a single-slice single-pass scan loop used for plotting all shots states

Parameters

[in]	loop_control	Loop control containing all information needed for a standard scan loop
[in]	coreslice	Function pointer that plays one or more modules representing the kernel that is repeated within a TR for each slice location

Returns

void

                                                                                                              {
  KSSCAN_LOOP_CONTROL plot_control = *loop_control;
  plot_control.nvols = 1;
  plot_control.naverages = 1;
  plot_control.slicetiming.slice_plan.npasses = 1;
  plot_control.slicetiming.slice_plan.nslices_per_pass = 1;
  ksscan_scanloop(&plot_control, NULL, coreslice);

} /* ksscan_plotloop_shots() */

ksscan_plotloop_slices()

void ksscan_plotloop_slices	(	const KSSCAN_LOOP_CONTROL *	loop_control,
		KS_CORESLICETIME	coresliceconst SCAN_INFO *slice_pos, KS_DYNAMIC_STATE *dynamic
	)

Executes a single-shot single-pass scan loop used for plotting all slices states

Parameters

[in]	loop_control	Loop control containing all information needed for a standard scan loop
[in]	coreslice	Function pointer to a coreslice function playing one or more modules representing the kernel that is repeated within a TR for each slice location

Returns

void

                                                                                                               {
  KSSCAN_LOOP_CONTROL plot_control = *loop_control;
  plot_control.nvols = 1;
  plot_control.naverages = 1;
  plot_control.phaseenc_plan.num_shots = 1;
  ksscan_scanloop(&plot_control, NULL, coreslice);

} /* ksscan_plotloop_slices() */

ksscan_scanloop()

s64 ksscan_scanloop	(	const KSSCAN_LOOP_CONTROL *	orig_loop_control,
		KS_DYNAMIC_STATE *	dynamic,
		KS_CORESLICETIME	coresliceconst SCAN_INFO *slice_pos, KS_DYNAMIC_STATE *dynamic
	)

Executes all loops according to the provided loop control

Parameters

[in]	orig_loop_control	Loop control containing all information needed for a standard scan loop
[in,out]	dynamic	Pointer to KS_DYNAMIC_STATE used to loop and ultimately set the state of the module(s) played
[in]	coreslice	Function pointer to a coreslice function playing one or more modules representing the kernel that is repeated within a TR for each slice location

Return values

s64	Duration of the whole scan

                                                                                                       {
  s64 time = 0;
  KSSCAN_LOOP_CONTROL loop_control = *orig_loop_control;
  KS_DYNAMIC_STATE default_dynamic = KS_INIT_DYNAMIC_STATE;
  if (!dynamic) {
    dynamic = &default_dynamic;
  }

  for (dynamic->vol = 0; dynamic->vol < loop_control.nvols; dynamic->vol++) {
    for (dynamic->pass = 0; dynamic->pass < loop_control.slicetiming.slice_plan.npasses; dynamic->pass++) {

      /* In a single pass scan we should play dummies only once */
      loop_control.dda = loop_control.slicetiming.slice_plan.npasses == 1 ?
        (!dynamic->vol)*orig_loop_control->dda :
        orig_loop_control->dda;

      time += ksscan_acqloop(&loop_control, dynamic, coreslice);

      loop_control.dda = 0;
      if (loop_control.play_endofpass) {
        time += GEReq_endofpass();
      }
      ks_plot_slicetime_endofpass(KS_PLOT_PASS_WAS_STANDARD);
    } /* pass loop */
  } /* volume loop */

  return time; /* in [us] */

} /* ksscan_scanloop() */

ksscan_prescanloop()

void ksscan_prescanloop	(	const KSSCAN_LOOP_CONTROL *	loop_control,
		KS_CORESLICETIME	coresliceconst SCAN_INFO *slice_pos, KS_DYNAMIC_STATE *dynamic,
		int	nloops,
		int	dda
	)

Executes a prescan loop

It consist of of a number of dummies TRs equal to dda where dynamic.shot = KS_NOTSET followed by nloops TRs where dynamic.shot = 0 and dynamic.shot_coords = {0, NULL} to indicate to the coreslice to turn off all phase encoding. The flag dynamic.prescan is set so that the coreslice can turn off the data routing for all but the readout with the highest expected signal.

Parameters

[in]	loop_control	Loop control containing all information needed for a standard scan loop
[in]	coreslice	Function pointer to a coreslice function playing one or more modules representing the kernel that is repeated within a TR for each slice location
[in]	nloops	Number of repetitions to be scanned
[in]	dda	Number of dummy repetitions to be played before turning the data acquisition on

Return values

void	Executes a prescan loop

                                             {

  const KS_PHASEENCODING_SHOTCOORDS fake_shot = KS_INIT_PHASEENCODING_SHOTCOORDS;
  KS_DYNAMIC_STATE dynamic = KS_INIT_DYNAMIC_STATE;
  dynamic.prescan = 1;
  dynamic.shot_coords = fake_shot;

  int i;
  for (i = -dda; i < nloops; i++) {
    /* negative shot always closes data receiver during prescan */
    dynamic.shot = (dda < 0) * KS_NOTSET;
    ksscan_sliceloop(loop_control, &dynamic, coreslice);
  } /* for nloops */

} /* ksscan_prescanloop() */

ksscan_init_loopcontrol()

void ksscan_init_loopcontrol

(

KSSCAN_LOOP_CONTROL *

loop_control

)

Initialize a loop control

Parameters

[out]

loop_control

Loop control to be initialized

Returns

void

                                                                {
  KSSCAN_LOOP_CONTROL loop_init = KSSCAN_INIT_LOOP_CONTROL;
  *loop_control = loop_init;

} /* ksscan_init_loopcontrol() */

ksscan_init_slicetiming()

void ksscan_init_slicetiming

(

KS_SLICETIMING *

slicetiming

)

Initialize a slice timing

Parameters

[out]

slicetiming

Slice timing to be initialized

Returns

void

                                                          {
  KS_SLICETIMING slicetiming_init = KS_INIT_SLICETIMING;
  *slicetiming = slicetiming_init;

} /* ksscan_init_slicetiming() */

ks_plot_psd()

void ks_plot_psd	(	const KS_SEQ_CONTROL *	ctrl,
		const KSSCAN_LOOP_CONTROL *	loopctrl
	)

Wrapper function for plotting a module/sequence entry

It handles the cases where negative shots are also used for encoding

Parameters

ctrl	Control of the module to be plotted
loopctrl	Loop control, can be NULL.

Returns

void

                                                                                  {
  if (loopctrl) {
    const KS_PHASEENCODING_PLAN* plans[2] = {&loopctrl->phaseenc_plan, &loopctrl->phaseenc_plan_dummies};
    ks_plot_host_seqctrl_manyplans(ctrl, plans, loopctrl->phaseenc_plan_dummies.num_shots > 0 ? 2 : 1);
  } else {
    ks_plot_host_seqctrl(ctrl, NULL);
  }

} /* ks_plot_psd() */