ksepi.e: EPI sequence

Data Structures
struct	KSEPI_SEQUENCE
struct	KSEPI_FLEET_SEQUENCE
struct	KSEPI_METADATA

Macros
#define	KSEPI_MINHNOVER   8 /* N.B. overscans below about 16-24 should be avoided for long TE */
#define	KSEPI_MAXRBW_NORAMPSAMPLING   125.0
#define	KSEPI_DEFAULT_SSI_TIME_ICEHARDWARE   100
#define	KSEPI_DEFAULT_SSI_TIME   1500
#define	PLAY_FLEET   ((int) (!KS_3D_SELECTED && oparc && opaccel_ph_stride > 1)) /* conditions when to play FLEET */
#define	OPUSER_PSDVERSION   opuser0
#define	SHOW_RHRECON   use0
#define	OPUSER_KYNOVER   opuser1
#define	SHOW_KYNOVER   use1
#define	OPUSER_BLIPSIGN   opuser2
#define	SHOW_BLIPSIGN   use2
#define	OPUSER_EPIREADOUTMODE   opuser4
#define	SHOW_EPIREADOUTMODE   use4
#define	OPUSER_FLEET_EPIREADOUTMODE   opuser5
#define	SHOW_FLEET_EPIREADOUTMODE   use5
#define	OPUSER6_DIFF_RETURNMODE   opuser6 /* opuser6 is checked in recon_ksepi2, so don't chance this */
#define	SHOW_DIFF_RETURNMODE   use6
#define	OPUSER7_SWI_RETURNMODE   opuser7 /* opuser7 is checked in recon_ksepi2, so don't chance this */
#define	SHOW_SWI_READOUTMODE   use7
#define	OPUSER_REFLINES   opuser9
#define	SHOW_REFLINES   use9
#define	OPUSER_KZACSLINES   opuser15
#define	SHOW_KZACSLINES   use15
#define	KSEPI_INIT_SEQUENCE   {KS_INIT_SEQ_CONTROL, KS_INIT_EPI, KS_INIT_EPI, KS_INIT_TRAP, KS_INIT_SELRF, KS_INIT_SELRF, {KS_INIT_TRAP}, KS_INIT_WAIT, KS_INIT_WAIT, KS_INIT_TRAP, KS_INIT_TRAP}
#define	KSEPI_FLEET_INIT_SEQUENCE   {KS_INIT_SEQ_CONTROL, KS_INIT_EPI, KS_INIT_TRAP, KS_INIT_SELRF, KS_INIT_WAIT, KS_INIT_WAIT}
#define	KSEPI_INIT_METADATA   {KSEPI_SEQINDEX_MAIN, 0, 0, 0, 0, 0, 0, 0, 0, 0, KSEPI_SEQPART_EPITRAIN, KS_NOTSET, KS_NOTSET, 1}
#define	KSEPI_PHASEENCODING_MEMORYPOOL_SIZE   25000
#define	MAX_DIFFSCHEME_LENGTH   512
#define	KSEPI_DIFFUSION_MAXBVALS   10
#define	KSEPI_DIFFUSION_MAXBVALUE   20000

Enumerations
enum	KSEPI_SEQINDICES { KSEPI_SEQINDEX_MAIN, KSEPI_SEQINDEX_FLEET, KSEPI_SEQINDEX_MAIN_SPLITODDEVEN, KSEPI_SEQINDEX_FLEET_SPLITODDEVEN }
enum	KSEPI_SEQPARTS { KSEPI_SEQPART_EPITRAIN, KSEPI_SEQPART_DYNREFTRAIN, KSEPI_SEQPART_FIDNAV }
enum	ksepi_diffusion_return {   DIFFRETURN_ALL = 0, DIFFRETURN_ACQUIRED = 1, DIFFRETURN_B0 = 2, DIFFRETURN_MEANDWI = 4,   DIFFRETURN_MEANADC = 8, DIFFRETURN_EXPATT = 16, DIFFRETURN_FA = 32, DIFFRETURN_CFA = 64 }

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 ("EPI [KSFoundation]")
	psdname ("ksepi")
STATUS	ksepi_eval_flowcomp_phase (KS_TRAP *fcphase, const KS_EPI *epi, const char *desc)
STATUS	ksepi_pg (int start_time)
KS_CORESLICETIME	ksepi_scan_irslice (const SCAN_INFO *slice_pos, KS_DYNAMIC_STATE *dynamic)
KS_CORESLICETIME	ksepi_scan_coreslice (const SCAN_INFO *slice_pos, KS_DYNAMIC_STATE *dynamic)
KS_CORESLICETIME	ksepi_scan_coreslicegroup (const SCAN_INFO *slice_pos, KS_DYNAMIC_STATE *dynamic)
KS_CORESLICETIME	ksepi_scan_fleet_coreslice (const SCAN_INFO *slice_pos, KS_DYNAMIC_STATE *dynamic)
void	ksepi_scan_attach_metadata (KSEPI_SEQUENCE *seq, const KS_DYNAMIC_STATE *dynamic, uint8_t sequence_group)
void	ksepi_dump_metadata (KSEPI_METADATA *metadata, const KS_DYNAMIC_STATE *dynamic)
STATUS	ksepi_set_loop_control_design (KSSCAN_LOOP_CONTROL_DESIGN *loop_design, const KS_EPI *epitrain)
STATUS	ksepi_scan_seqstate (SCAN_INFO slice_pos, KS_PHASEENCODING_COORD starting_coord, ks_enum_epiblipsign blipsign)
s64	ksepi_scan_scanloop ()
const KSSCAN_LOOP_CONTROL *	ksepi_get_loop_ctrl ()
void	ksepi_init_imagingoptions (void)
STATUS	ksepi_init_UI (void)
STATUS	ksepi_eval_UI ()
STATUS	ksepi_eval_setuprf ()
STATUS	ksepi_eval_setupfleet ()
STATUS	ksepi_eval_setupobjects ()
STATUS	ksepi_eval_TErange ()
void	ksepi_set_kspace_design_forsat (KS_KSPACE_DESIGN *kdesign)
void	ksepi_set_slicetiming_design (KS_SLICETIMING_DESIGN *slicetiming_design)
STATUS	ksepi_set_inversion_loop_control_design (KSINV_LOOP_CONTROL_DESIGN *invloopctrl_design, const KS_EPI *epitrain)
STATUS	ksepi_eval_inversion (KS_SEQ_COLLECTION *seqcollection)
STATUS	ksepi_eval_sat (KS_SEQ_COLLECTION *seqcollection)
STATUS	ksepi_gradheat_play (const INT max_encode_mode, int nargs, void **args)
STATUS	ksepi_eval_loops (KS_SEQ_COLLECTION *seqcollection)
int	ksepi_eval_ssitime ()
STATUS	ksepi_eval_scantime (KS_SEQ_COLLECTION *seqcollection)
STATUS	ksepi_update_UI ()
STATUS	ksepi_predownload_plot (KS_SEQ_COLLECTION *seqcollection)
STATUS	ksepi_predownload_setrecon ()
STATUS	ksepi_pg_fleet (int start_time)
STATUS	ksepi_fleet_scan_seqstate (const SCAN_INFO *slice_pos, KS_PHASEENCODING_COORD starting_coord, ks_enum_epiblipsign blipsign)
void	ksepi_scan_rf_off ()
void	ksepi_scan_attach_metadata (KS_EPI *epitrain, KS_EPI *dynreftrain, const KS_DYNAMIC_STATE *dynamic, uint8_t sequence_group)
STATUS	ksepi_scan_init (void)
STATUS	ksepi_scan_prescanloop (int nloops, int dda)
STATUS	ksepi_diffusion_init_UI ()
void	SolveCubic (double a, double b, double c, double d, int *nsol, double *x)
STATUS	ksepi_diffusion_calcTE (double *TE_s, int exciso2end, int crsh1_half180, int half180_crsh2, int readout2echo, int ramptime, float G, int bval_desired)
STATUS	ksepi_diffusion_eval_gradients_TE (KSEPI_SEQUENCE *epi, const KSDIFF_CONTROL *diff_ctrl)
STATUS	ksepi_eval_diffusion (KSDIFF_CONTROL *diff_ctrl)
STATUS	ksepi_diffusion_pg (KSEPI_SEQUENCE *epi, int TE)

Variables
KS_SEQ_COLLECTION	seqcollection
float	ksepi_excthickness = 0
float	ksepi_gscalerfexc = 0.9 with {0.1, 3.0, 0.9, VIS, "Excitation slice thk scaling (< 1.0 thicker slice)",}
int	ksepi_slicecheck = 0 with {0, 1, 0, VIS, "move readout to z axis for slice thickness test",}
float	ksepi_spoilerarea = 3000.0 with {0.0, 10000.0, 3000.0, VIS, "ksepi ksepi.spoiler gradient area",}
int	ksepi_rfspoiling = 1 with {0, 1, 1, VIS, "Enable RF spoiling 1:on 0:off",}
int	ksepi_fse90 = 0 with {0, 1, 0, VIS, "Use FSE90 instead of SPSP for non-fatsat",}
float	ksepi_kissoff_factor = 0.04 with {0, 1, 0.04, VIS, "Slice oversampling fraction on each side (3D)",}
float	ksepi_rfstretch_exc = 1.0 with {0.1,10.0, 1.0, VIS, "RF excitation stretch factor"}
int	ksepi_fastexc3D = TRUE with {FALSE, TRUE, TRUE, VIS, "Sel. RF exc (3D) 0:EXC_SPSP_3D 1:EXC_FAST_SPSP_3D",}
float	ksepi_crusher_dephasing = 6.0 with { 0.0, 100.0, 6.0, VIS, "crusher dephasing over slice [cycles]",}
float	ksepi_gscalerfref = 0.9 with {0.1, 3.0, 0.9, VIS, "Refocusing slice thk scaling (< 1.0 thicker slice)",}
float	ksepi_rfstretch_ref = 1.0 with {0.1,10.0, 1.0, VIS, "RF refocusing stretch factor",}
int	ksepi_bridgecrushers = FALSE with {FALSE, TRUE, FALSE, VIS, "Bridge RF ref crushers",}
int	ksepi_t1value_to_null = T1_FAT_3T with {0, 5s, T1_FAT_3T, VIS, "T1 value to NULL [us]",}
int	ksepi_rampsampling = 1 with {0, 1, 1, VIS, "Rampsampling [0:OFF 1:ON]",}
int	ksepi_readlobegap = 0 with {0, 10ms, 0, VIS, "extra gap between readout lobes [us]",}
int	ksepi_echogap = 0 with {0, 100ms, 0, VIS, "extra gap between EPI echoes [us]",}
int	ksepi_readsign = 1 with { -1, 1, 1, VIS, "Readout polarity: +1/-1",}
float	ksepi_readampmax = 3.0 with {0.0, 5.0, 3.0, VIS, "Max grad amp for EPI readout lobes",}
float	ksepi_sr = 0.01 with {0.0, , 0.01, VIS, "EPI SR: amp/ramp [(G/cm) / us]",}
int	ksepi_esp = 0 with {0, 1000000, 0, VIS, "View-only: Echo spacing in [us]",}
int	ksepi_blipsign = KS_EPI_POSBLIPS with {KS_EPI_NEGBLIPS, KS_EPI_POSBLIPS, KS_EPI_POSBLIPS, VIS, "Blip polarity: +1/-1",}
int	ksepi_echotime_shifting = 1 with {0, 1, 1, VIS, "Enable echo time shifting for multi shot",}
int	ksepi_kynover = 24 with {KSEPI_MINHNOVER, 512, 24, VIS, "#extralines for MinTE",}
int	ksepi_kznover = 0 with {0, 512, 0, VIS, "#extralines in kz",}
int	ksepi_kz_nacslines = 8 with {0, 64, 8, VIS, "#acslines in kz",}
int	ksepi_caipi = 0 with {0, 512, 0, VIS, "CAIPIRINHA shift (affects 3D epi only. Set 0 for no CAIPI)",}
int	ksepi_readout_mode = KS_EPI_BIPOLAR with {KS_EPI_BIPOLAR, KS_EPI_FLYBACK, KS_EPI_BIPOLAR, VIS, "EPI readout mode 0: bipolar 1:splitoddeven 2:flyback",}
int	ksepi_fcy = 1 with {0, 1, 0, VIS, "Flowcomp Y when opfcomp"}
int	ksepi_fcz = 1 with {0, 1, 0, VIS, "Flowcomp Z when opfcomp"}
int	ksepi_fleet = 0 with {0, 1, 0, VIS, "FLEET calibration volume [0:OFF 1:ON]",}
int	ksepi_echotime_shifting_fleet = 1 with {0, 1, 1, VIS, "Enable echo time shifting for multi shot FLEET",}
float	ksepi_fleet_flip = 5.0 with {1.0, 90.0, 5.0, VIS, "FLEET flip angle [deg]",}
int	ksepi_fleet_dda = 3 with {1, 200, 3, VIS, "Dummies for FLEET module",}
int	ksepi_fleet_num_ky = 48 with {32, 256, 48, VIS, "Number of ky encodes for FLEET module",}
int	ksepi_fleet_readout_mode = KS_EPI_SPLITODDEVEN with {KS_EPI_BIPOLAR, KS_EPI_FLYBACK, KS_EPI_SPLITODDEVEN, VIS, "FLEET EPI readout mode 0: bipolar 1:splitoddeven 2:flyback",}
int	ksepi_fleet_nshots = 3 with {1, 128, 3, VIS, "# shots for FLEET",}
int	ksepi_reflines = 0 with {0, 96, 0, VIS, "Number of phase reference lines per shot",}
int	ksepi_swi_returnmode = 0 with {0, 7, 0, VIS, "SWI recon 0:Off 1:Acq 2:SWI 4:SWIphase",}
int	ksepi_pos_start = KS_RFSSP_PRETIME with {0, , KS_RFSSP_PRETIME, INVIS, "us from start until the first waveform begins",}
int	ksepi_ssi_time = KSEPI_DEFAULT_SSI_TIME with {32, , KSEPI_DEFAULT_SSI_TIME, VIS, "time from eos to ssi in intern trig",}
int	ksepi_dda = 1 with {1, 200, 1, VIS, "Number of dummy scans for steady state",}
int	ksepi_debug = 1 with {0, 100, 1, VIS, "Write out e.g. plot files (unless scan on HW)"}
int	ksepi_imsize = KS_IMSIZE_POW2 with {KS_IMSIZE_NATIVE, KS_IMSIZE_MIN256, KS_IMSIZE_POW2, VIS, "img. upsamp. [0:native 1:pow2 2:min256]"}
int	ksepi_abort_on_kserror = FALSE with {0, 1, 0, VIS, "Hard program abort on ks_error [0:OFF 1:ON]",}
int	ksepi_ref_nsegments = 1 with {1, 512, 1, VIS, "Number of kz segments in reference volume",}
float	ksepi_epiqfact = 1.0 with {1.0, 10.0, 1.0, VIS, "Quietness factor for the EPI readout only",}
int	ksepi_recvgain_mode = RG_CAL_MODE_HIGH_FIXED with {RG_CAL_MODE_MIN, RG_CAL_MODE_MAX, RG_CAL_MODE_HIGH_FIXED, VIS, "RecvGain - 0:Measured 1:8 2:5 3:Max",}
int	ksepi_metadump = 0
KSEPI_SEQUENCE	ksepi = KSEPI_INIT_SEQUENCE
KSSCAN_LOOP_CONTROL	ksepi_loopctrl = KSSCAN_INIT_LOOP_CONTROL
KSDIFF_CONTROL	ksepi_diffctrl = KSDIFF_INIT_CONTROL
KSEPI_FLEET_SEQUENCE	ksepi_fleetseq = KSEPI_FLEET_INIT_SEQUENCE
KSSCAN_LOOP_CONTROL	ksepi_fleet_loopctrl = KSSCAN_INIT_LOOP_CONTROL
KSINV_MODULE	ksepi_inv = KSINV_INIT_MODULE
KSINV_LOOP_CONTROL	ksepi_inv_loopctrl = KSINV_INIT_LOOP_CONTROL
KS_PHASEENCODING_COORD	ksepi_phaseencoding_memorypool [KSEPI_PHASEENCODING_MEMORYPOOL_SIZE] = {KS_INIT_PHASEENCODING_COORD}
int	ksepi_interechotime = 0
float	ksepi_echotime_shifting_shotdelay = 0.0
float	ksepi_echotime_shifting_shotdelay_fleet = 0.0
int	ksepi_echotime_shifting_sumdelay = 0
int	ksepi_echotime_shifting_sumdelay_fleet = 0
KS_KSPACE_ACQ	kacq = KS_INIT_KSPACE_ACQ
int	sequence_iopts []
int	rfspoiling_phase_counter = 0
float	ksepi_diffusion_amp_scale = 1.0 with {0.0, 1.0, 1.0, VIS, "Cap for scaling factor of diffusion gradient amplitude", }
int	ksepi_diffusion_heat_avg = 1 with {0, 1, 1, VIS, "Root mean sqared averaging diffusion amplitudes heat calculations", }
float	ksepi_diffusion_scaleX_heatcal = 1 with {0, 1, 1, VIS, "View-only: x diffusion gradient amplitude for heating calculations", }
float	ksepi_diffusion_scaleY_heatcal = 1 with {0, 1, 1, VIS, "View-only: y diffusion gradient amplitude for heating calculations", }
float	ksepi_diffusion_scaleZ_heatcal = 1 with {0, 1, 1, VIS, "View-only: z diffusion gradient amplitude for heating calculations", }
int	ksepi_diffusion_echotime = 0 with {0, , 0, VIS, "View-only: Echo time necessary to meet the desired b-value", }
int	ksepi_diffusion_returnmode = DIFFRETURN_ALL with {DIFFRETURN_ALL, 128, DIFFRETURN_ALL, VIS, "Diff maps All:0 Acq:1 b0:2 DWI:4 ADC:8 Exp:16 FA:32 cFA:64",}
int	ksepi_diffusion_minramptime = 1ms with {0, 20ms, 1ms, VIS, "Minimum diffusion ramp time. If 0: syslimits used",}

Detailed Description

MR-contrasts supported

• Diffusion weighting
• T2*-w (2D & 3D)

Features

• GE-EPI
• SE-EPI
• DW-EPI (multi-shell (b-value with ALL (3 dirs) and TENSOR)))
• Spatial (Graphical) Sat
• 2D & 3D data acquisition

Macro Definition Documentation

KSEPI_MINHNOVER

#define KSEPI_MINHNOVER   8 /* N.B. overscans below about 16-24 should be avoided for long TE */

KSEPI_MAXRBW_NORAMPSAMPLING

#define KSEPI_MAXRBW_NORAMPSAMPLING   125.0

KSEPI_DEFAULT_SSI_TIME_ICEHARDWARE

#define KSEPI_DEFAULT_SSI_TIME_ICEHARDWARE   100

KSEPI_DEFAULT_SSI_TIME

#define KSEPI_DEFAULT_SSI_TIME   1500

PLAY_FLEET

#define PLAY_FLEET   ((int) (!KS_3D_SELECTED && oparc && opaccel_ph_stride > 1)) /* conditions when to play FLEET */

OPUSER_PSDVERSION

#define OPUSER_PSDVERSION   opuser0

SHOW_RHRECON

#define SHOW_RHRECON   use0

OPUSER_KYNOVER

#define OPUSER_KYNOVER   opuser1

SHOW_KYNOVER

#define SHOW_KYNOVER   use1

OPUSER_BLIPSIGN

#define OPUSER_BLIPSIGN   opuser2

SHOW_BLIPSIGN

#define SHOW_BLIPSIGN   use2

OPUSER_EPIREADOUTMODE

#define OPUSER_EPIREADOUTMODE   opuser4

SHOW_EPIREADOUTMODE

#define SHOW_EPIREADOUTMODE   use4

OPUSER_FLEET_EPIREADOUTMODE

#define OPUSER_FLEET_EPIREADOUTMODE   opuser5

SHOW_FLEET_EPIREADOUTMODE

#define SHOW_FLEET_EPIREADOUTMODE   use5

OPUSER6_DIFF_RETURNMODE

#define OPUSER6_DIFF_RETURNMODE   opuser6 /* opuser6 is checked in recon_ksepi2, so don't chance this */

SHOW_DIFF_RETURNMODE

#define SHOW_DIFF_RETURNMODE   use6

OPUSER7_SWI_RETURNMODE

#define OPUSER7_SWI_RETURNMODE   opuser7 /* opuser7 is checked in recon_ksepi2, so don't chance this */

SHOW_SWI_READOUTMODE

#define SHOW_SWI_READOUTMODE   use7

OPUSER_REFLINES

#define OPUSER_REFLINES   opuser9

SHOW_REFLINES

#define SHOW_REFLINES   use9

OPUSER_KZACSLINES

#define OPUSER_KZACSLINES   opuser15

SHOW_KZACSLINES

#define SHOW_KZACSLINES   use15

KSEPI_INIT_SEQUENCE

#define KSEPI_INIT_SEQUENCE   {KS_INIT_SEQ_CONTROL, KS_INIT_EPI, KS_INIT_EPI, KS_INIT_TRAP, KS_INIT_SELRF, KS_INIT_SELRF, {KS_INIT_TRAP}, KS_INIT_WAIT, KS_INIT_WAIT, KS_INIT_TRAP, KS_INIT_TRAP}

KSEPI_FLEET_INIT_SEQUENCE

#define KSEPI_FLEET_INIT_SEQUENCE   {KS_INIT_SEQ_CONTROL, KS_INIT_EPI, KS_INIT_TRAP, KS_INIT_SELRF, KS_INIT_WAIT, KS_INIT_WAIT}

KSEPI_INIT_METADATA

#define KSEPI_INIT_METADATA   {KSEPI_SEQINDEX_MAIN, 0, 0, 0, 0, 0, 0, 0, 0, 0, KSEPI_SEQPART_EPITRAIN, KS_NOTSET, KS_NOTSET, 1}

initialization values for KSEPI_METADATA

KSEPI_PHASEENCODING_MEMORYPOOL_SIZE

#define KSEPI_PHASEENCODING_MEMORYPOOL_SIZE   25000

num elements allocated for unique phase encodes. For EPI, only the blipphaser's ky value goes in there (first ky line in EPI train)

MAX_DIFFSCHEME_LENGTH

#define MAX_DIFFSCHEME_LENGTH   512

Maximum 512 diffusion directions (including b=0)

KSEPI_DIFFUSION_MAXBVALS

#define KSEPI_DIFFUSION_MAXBVALS   10

10 different b-values > 0

KSEPI_DIFFUSION_MAXBVALUE

#define KSEPI_DIFFUSION_MAXBVALUE   20000

Enumeration Type Documentation

KSEPI_SEQINDICES

enum KSEPI_SEQINDICES

Enumerator
KSEPI_SEQINDEX_MAIN
KSEPI_SEQINDEX_FLEET
KSEPI_SEQINDEX_MAIN_SPLITODDEVEN
KSEPI_SEQINDEX_FLEET_SPLITODDEVEN

{KSEPI_SEQINDEX_MAIN, KSEPI_SEQINDEX_FLEET, KSEPI_SEQINDEX_MAIN_SPLITODDEVEN, KSEPI_SEQINDEX_FLEET_SPLITODDEVEN} KSEPI_SEQINDICES; 

KSEPI_SEQPARTS

enum KSEPI_SEQPARTS

Enumerator
KSEPI_SEQPART_EPITRAIN
KSEPI_SEQPART_DYNREFTRAIN
KSEPI_SEQPART_FIDNAV

{KSEPI_SEQPART_EPITRAIN, KSEPI_SEQPART_DYNREFTRAIN, KSEPI_SEQPART_FIDNAV} KSEPI_SEQPARTS; 

ksepi_diffusion_return

enum ksepi_diffusion_return

Enumerator
DIFFRETURN_ALL
DIFFRETURN_ACQUIRED
DIFFRETURN_B0
DIFFRETURN_MEANDWI
DIFFRETURN_MEANADC
DIFFRETURN_EXPATT
DIFFRETURN_FA
DIFFRETURN_CFA

{DIFFRETURN_ALL = 0, DIFFRETURN_ACQUIRED = 1, DIFFRETURN_B0 = 2, DIFFRETURN_MEANDWI = 4, DIFFRETURN_MEANADC = 8, DIFFRETURN_EXPATT = 16, DIFFRETURN_FA = 32, DIFFRETURN_CFA = 64} ksepi_diffusion_return;

Function Documentation

cvinit()

STATUS cvinit

(

void

)

                    {
  STATUS status;

  obl_method = PSD_OBL_OPTIMAL;

  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 */
  ksepi_init_imagingoptions();

  /* Setup UI buttons */
  status = ksepi_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);

  /* Link the memory pool for the phase encoding plans */
  status = ks_phaseencoding_memorypool_init(ksepi_phaseencoding_memorypool,
                                            KSEPI_PHASEENCODING_MEMORYPOOL_SIZE);
  KS_RAISE(status);

  status = GEReq_cveval();
  KS_RAISE(status);

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

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

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

  status = ksepi_pg(ksepi_pos_start);
  KS_RAISE(status);

  status = ks_eval_addtoseqcollection(&seqcollection, &ksepi.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 -----------*/

  /* FLEET */
  if (ksepi_fleet) {
    status = ksepi_pg_fleet(ksepi_pos_start);
    KS_RAISE(status);

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

  /* Sat */
  status = ksepi_eval_sat(&seqcollection);
  KS_RAISE(status);

  /* Inversion */
  status = ksepi_eval_inversion(&seqcollection);
  KS_RAISE(status);


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


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

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

  /* scan time */
  status = ksepi_eval_scantime(&seqcollection);
  KS_RAISE(status);

  return SUCCESS;

} /* my_cveval() */

cvcheck()

STATUS cvcheck

(

void

)

                     {
  STATUS status;

  status = my_cveval();
  KS_RAISE(status);

  status = GEReq_cvcheck();
  KS_RAISE(status);

  status = ksepi_update_UI();
  KS_RAISE(status);

  abort_on_kserror = ksepi_abort_on_kserror;

  return SUCCESS;

} /* cvcheck() */

predownload()

STATUS predownload

(

void

)

                           {
  STATUS status;

  status = GEReq_predownload();
  KS_RAISE(status);

  const KSSCAN_LOOP_CONTROL *loop_control = ksepi_get_loop_ctrl(); /* returns the inversion or standard loop control depending on inversion*/

  status = GEReq_predownload_prescan_options((RG_CAL_MODE_E) ksepi_recvgain_mode);
  KS_RAISE(status);

  /* Set filter slot # for SCAN, APS2, MPS2 */
  GEReq_predownload_setfilter(&ksepi.epitrain.read.acq.filt);
  ksepi.dynreftrain.read.acq.filt.fslot = ksepi.epitrain.read.acq.filt.fslot;
  ksepi_fleetseq.epitrain.read.acq.filt.fslot = ksepi.epitrain.read.acq.filt.fslot;

  /* 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 */
  if (existcv(opslquant)) {
    if (opimode == PSD_2D) {
      status = GEReq_predownload_store_sliceplan(loop_control->slicetiming.slice_plan);
    } else {
      status = GEReq_predownload_store_sliceplan3D(opslquant, opvquant);
    }
    KS_RAISE(status);
  }

  /* generic rh-vars setup */
  rhnecho = opnecho + (ksepi_reflines > 0);
  status = GEReq_predownload_setrecon_epi(&ksepi.epitrain, opfphases, loop_control->slicetiming.slice_plan, ksepi_interechotime - ksepi.epitrain.duration, ksepi_blipsign, 0, 0, 0, ksepi_imsize);
  KS_RAISE(status);

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

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

  return SUCCESS;

} /* predownload() */

pulsegen()

STATUS pulsegen

(

void

)

                        {

  GEReq_pulsegenBegin();

  /* Link the memory pool for the phase encoding plans */
  ks_phaseencoding_memorypool_init(ksepi_phaseencoding_memorypool,
                                   KSEPI_PHASEENCODING_MEMORYPOOL_SIZE);


  /* Main Pulse Sequence */
  ksepi_pg(ksepi_pos_start);
  KS_SEQLENGTH(seqcore, ksepi.seqctrl);

  /* Sat */
  if (kssat.seqctrl.duration > 0) {
    kssat_pg(&kssat);
    KS_SEQLENGTH(seqsat, kssat.seqctrl);
  }

  /* Inversion sequence modules */
  if (ANYINVERSION) {
    ksinv_pg(&ksepi_inv);
    KS_SEQLENGTH(seqinv, ksepi_inv.seqctrl);
    KS_SEQLENGTH(seqtrfill, ksepi_inv_loopctrl.seqctrl_filltr); /* FLAIR BLOCK requires 2 sequence modules */
  }

  /* FLEET module */
  ksepi_pg_fleet(ksepi_pos_start);
  KS_SEQLENGTH(seqFLEET, ksepi_fleetseq.seqctrl);

  GEReq_pulsegenEnd();

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


  return SUCCESS;

} /* pulsegen() */

mps2()

STATUS mps2

(

void

)

                  {

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

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

  ksepi_scan_prescanloop(30000, ksepi_dda);

  rspexit();

 return SUCCESS;

} /* mps2() */

aps2()

STATUS aps2

(

void

)

                  {

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

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

  ksepi_scan_prescanloop(100, ksepi_dda);

  rspexit();

  return SUCCESS;

} /* aps2() */

scan()

STATUS scan

(

void

)

                  {

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

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

  ksepi_scan_scanloop();

  GEReq_endofscan();

  rspexit();

  return SUCCESS;

} /* scan() */

abstract()

abstract

(

"EPI "

[KSFoundation]

)

psdname()

psdname

(

"ksepi"

)

ksepi_eval_flowcomp_phase()

STATUS ksepi_eval_flowcomp_phase	(	KS_TRAP *	fcphase,
		const KS_EPI *	epi,
		const char *	desc
	)

Evaluates the flow compensation gradient on the phase encoding (Y) board

This function computes the flow compensation gradient for the phase encoding (Y) board based on the EPI readout struct

Parameters

[out]	fcphase	Pointer to the flow compensation KS_TRAP gradient on the Y board
[in]	epi	Pointer to the KS_EPI structure containing the EPI parameters
[in]	desc	Description of the flow compensation phase gradients

Return values

STATUS

SUCCESS or FAILURE

                                                                                        {

  /* set time origin at end of bipolar flow comp lobe/beginning of epi.blipphaser */
  float dummy1 = 0.0;
  float dummy2 = 0.0;
  float zeromomentsum = 0.0;
  float firstmomentsum = 0.0;
  int pulsepos = 0;
  int invertphase = 0;
  int pulsecnt;
  int epiesp = 0;

  epiesp = (epi->read.grad.duration + epi->read_spacing);

  /* compute moments for blips */
  pulsepos = epi->blipphaser.grad.duration + epiesp - epi->blip.duration / 2;

  int blips2cent = ((epi->blipphaser.nover != 0) ? (epi->blipphaser.nover / epi->blipphaser.R) : (epi->etl / 2)) - 1;

  for (pulsecnt = 0; pulsecnt < blips2cent; pulsecnt++) {
    /* N.B.: pulsepos is updated in rampmoments() */
    rampmoments(0.0,           epi->blip.amp, epi->blip.ramptime,    invertphase, &pulsepos, &dummy1, &dummy2, &zeromomentsum, &firstmomentsum);
    rampmoments(epi->blip.amp, epi->blip.amp, epi->blip.plateautime, invertphase, &pulsepos, &dummy1, &dummy2, &zeromomentsum, &firstmomentsum);
    rampmoments(epi->blip.amp, 0.0,           epi->blip.ramptime,    invertphase, &pulsepos, &dummy1, &dummy2, &zeromomentsum, &firstmomentsum);
    pulsepos += (epiesp - epi->blip.duration);
  }

  ks_init_trap(fcphase);

  if (!areSame(zeromomentsum, 0) && !areSame(firstmomentsum, 0)) {
    int fcramp, fcplateau, dummy;
    float fcamp;
    amppwygmn(zeromomentsum, firstmomentsum, epi->blipphaser.grad.ramptime, epi->blipphaser.grad.plateautime, epi->blipphaser.grad.ramptime, 
              0.0, 0.0, (double) ks_syslimits_ampmax(loggrd), (double) ks_syslimits_ramptimemax(loggrd), 0, 
              &fcramp, &fcplateau, &dummy, &fcamp);

    fcphase->amp = fcamp;
    fcphase->ramptime = fcramp;
    fcphase->plateautime = fcplateau;
    fcphase->duration = 2 * fcphase->ramptime + fcphase->plateautime;
    fcphase->area = fcphase->duration * ((float) fcphase->ramptime + fcphase->plateautime);
    sprintf(fcphase->description, desc);
  }

  return SUCCESS;

} /* ksepi_eval_flowcomp_phase() */

ksepi_pg()

STATUS ksepi_pg

(

int

start_time

)

The ksepi (main) pulse sequence generation

This is the main pulse sequence in ksepi.e using the sequence objects in KSEPI_SEQUENCE with the sequence module name "ksepimain" (= ksepi.seqctrl.description)

Return values

STATUS

SUCCESS or FAILURE

                                {

  STATUS status;
  KS_SEQLOC tmploc = KS_INIT_SEQLOC;
  int epi_startpos = KS_NOTSET;
  int epi_readout_startpos = KS_NOTSET;
  int fc_startpos = KS_NOTSET;
  int fcz_endpos = KS_NOTSET;
  int echo, board;

  if (start_time < KS_RFSSP_PRETIME) {
    return KS_THROW("1st arg (pos start) must be at least %d us", KS_RFSSP_PRETIME);
  }

#ifdef HOST_TGT
  if (opte < avminte) {
    /* we cannot proceed until TE is in range.
       Return a long seq duration and pretend all is good */
    ks_eval_seqctrl_setminduration(&ksepi.seqctrl, 1s);
    return SUCCESS;
  }
#endif


  /*******************************************************************************************************
   *  RF Excitation
   *******************************************************************************************************/
  tmploc.ampscale = 1.0;
  tmploc.pos = RUP_GRD(start_time + KS_RFSSP_PRETIME);
  tmploc.board = ZGRAD;

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

  /* forward to end of selrfexc.postgrad (works for when slice sel gradient is KS_TRAP or KS_WAVE as only
     one of them can have non-zero duration at a given time) */
  tmploc.pos += ksepi.selrfexc.pregrad.duration + ksepi.selrfexc.grad.duration + ksepi.selrfexc.gradwave.duration + ksepi.selrfexc.postgrad.duration;

  /*******************************************************************************************************
  *  Flow comp in slice dir
  *******************************************************************************************************/

  /* First flow comp gradient was already merged into selrf rephaser */
  /* Second flow comp gradient slice for slice excitation */
  status = ks_pg_trap(&ksepi.fcompslice, tmploc, &ksepi.seqctrl); /* N.B.: will return quietly if ksepi.fcompslice.duration = 0 (opfcomp = 0) */
  KS_RAISE(status);
  fcz_endpos = tmploc.pos + ksepi.fcompslice.duration;

  /*******************************************************************************************************
  *  EPI phase reference lines
  *******************************************************************************************************/
  tmploc.board = (ksepi_slicecheck) ? KS_FREQZ_PHASEY : KS_FREQX_PHASEY;
  tmploc.pos = fcz_endpos;
  if (ksepi_slicecheck == FALSE) { /* reflines dephaser may overlap with slice flow comp and selrf rephaser unless slicecheck mode */
    tmploc.pos -= IMin(2, ksepi.dynreftrain.readphaser.duration, ksepi.selrfexc.postgrad.duration + ksepi.fcompslice.duration);
  }
  tmploc.ampscale = ksepi_readsign;
  status = ks_pg_epi(&ksepi.dynreftrain, tmploc, &ksepi.seqctrl);
  KS_RAISE(status);

  /*******************************************************************************************************
  *  EPI trains: Begin   (> 1 only supported with offline recon)
  -------------------------------------------------------------------------------------------------------*/
  for (echo = 0; echo < opnecho; echo++) {

    if (acq_type == TYPSPIN) {
      if (opdiffuse && echo == 0) {
        status = ksepi_diffusion_pg(&ksepi, opte);
        KS_RAISE(status);
      } else {
        if (echo == 0) /* RF refocusing pulse for 1st EPI train at TE/2 */
          tmploc.pos = ksepi.seqctrl.momentstart + opte / 2 - ksepi.selrfref.rf.start2iso - ksepi.selrfref.grad.ramptime - ksepi.selrfref.pregrad.duration;
        else /* RF refocusing pulse between two EPI trains (2nd-Nth EPI train are played out as tight as possible when ksepi_echogap = 0). Use epi_startpos from previous echo index (see below) */
          tmploc.pos = epi_startpos + ksepi.epitrain.duration + KS_RFSSP_PRETIME + ksepi_echogap / 2;
        tmploc.board = ZGRAD;
        status = ks_pg_selrf(&ksepi.selrfref, tmploc, &ksepi.seqctrl);
        KS_RAISE(status);
      }
    } /* acq_type == TYPSPIN */

    epi_startpos = ksepi.seqctrl.momentstart + opte - ksepi.epitrain.time2center + (echo * ksepi_interechotime);
    epi_readout_startpos = epi_startpos + IMax(3, ksepi.epitrain.readphaser.duration,
                                                  ksepi.epitrain.blipphaser.grad.duration,
                                                  ksepi.epitrain.zphaser.grad.duration);

    /*******************************************************************************************************
    *  Flow comp in phase dir
    *******************************************************************************************************/
    fc_startpos = epi_readout_startpos - ksepi.epitrain.blipphaser.grad.duration - 2 * ksepi.fcompphase.duration;
    tmploc.board = YGRAD;
    tmploc.pos = fc_startpos;
    tmploc.ampscale = 1;
    status = ks_pg_trap(&ksepi.fcompphase, tmploc, &ksepi.seqctrl); /* instance #0. N.B.: will return quietly if ksepi.fcompphase.duration = 0 */
    KS_RAISE(status);

    tmploc.pos += ksepi.fcompphase.duration;
    tmploc.ampscale = -1;
    status = ks_pg_trap(&ksepi.fcompphase, tmploc, &ksepi.seqctrl); /* instance #1 */
    KS_RAISE(status);

    /*******************************************************************************************************
    *  EPI readout including de/rephasers on freq, phase and slice encoding axes (net zero moment on both axes)
    *******************************************************************************************************/
    tmploc.board = (ksepi_slicecheck) ? KS_FREQZ_PHASEY : KS_FREQX_PHASEY;
    tmploc.pos = epi_startpos;
    tmploc.ampscale = ksepi_readsign;
    status = ks_pg_epi(&ksepi.epitrain, tmploc, &ksepi.seqctrl);
    KS_RAISE(status);

    /*******************************************************************************************************
    *  EPI echo time shifting pre_delay (only before 1st EPI train "echo = 0")
    *******************************************************************************************************/
    if (ksepi_echotime_shifting == TRUE && echo == 0) {
      for (board = XGRAD; board <= SSP; board++) {
        tmploc.board = board;
        if (oppseq == PSD_SE) {
          /* 2D: SE-EPI or DW-EPI */
          tmploc.pos = epi_startpos - GRAD_UPDATE_TIME;
        } else {
          /* 2D/3D: GE-EPI
          Place wait pulses just before main epi train dephasers (incl flowcomp if present) */
            if ((board == XGRAD && ksepi_slicecheck == FALSE) || (board == ZGRAD && ksepi_slicecheck == TRUE)) {
            tmploc.pos = epi_readout_startpos - ksepi.epitrain.readphaser.duration - GRAD_UPDATE_TIME;
          } else if (board == YGRAD) {
            tmploc.pos = fc_startpos - GRAD_UPDATE_TIME;
          } else {
            tmploc.pos = epi_readout_startpos - ksepi.epitrain.zphaser.grad.duration - GRAD_UPDATE_TIME;
          }
        }
        status = ks_pg_wait(&ksepi.pre_delay, tmploc, &ksepi.seqctrl);
        KS_RAISE(status);
      }
    }

  } /* for echo (= EPItrain) */

  /*------------------------------------------------------------------------------------------------------
   *  EPI trains: End
   *******************************************************************************************************/

  /*******************************************************************************************************
   *  Gradient spoilers on Y and Z (at the same time)
   *******************************************************************************************************/
  tmploc.ampscale = 1.0;
  tmploc.pos = epi_startpos + ksepi.epitrain.duration;
  tmploc.board = YGRAD;
  status = ks_pg_trap(&ksepi.spoiler, tmploc, &ksepi.seqctrl);
  KS_RAISE(status);

  tmploc.board = ZGRAD;
  status = ks_pg_trap(&ksepi.spoiler, tmploc, &ksepi.seqctrl);
  KS_RAISE(status);

  tmploc.pos += ksepi.spoiler.duration;

  /*******************************************************************************************************
  *  EPI echo time shifting post_delay
  *******************************************************************************************************/
  if (ksepi_echotime_shifting == TRUE) {
    tmploc.pos += GRAD_UPDATE_TIME;
    tmploc.board = KS_ALL;
    status = ks_pg_wait(&ksepi.post_delay, tmploc, &ksepi.seqctrl);
    KS_RAISE(status);
    tmploc.pos += IMax(2, psd_grd_wait, psd_rf_wait) + GRAD_UPDATE_TIME;
    tmploc.pos += ksepi_echotime_shifting_sumdelay;
  }

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

  /* make sure we are divisible by GRAD_UPDATE_TIME (4us) */
  tmploc.pos = RUP_GRD(tmploc.pos);

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

  return SUCCESS;

} /* ksepi_pg() */

ksepi_scan_irslice()

KS_CORESLICETIME ksepi_scan_irslice	(	const SCAN_INFO *	slice_pos,
		KS_DYNAMIC_STATE *	dynamic
	)

Wrapper function to ksinv_scan_irslice() with ksepi_inv (global in this file) as argument

The inversion sequence's play function

Parameters

[in]	slice_pos	Position of the slice to be played out (one element in the global ks_scan_info[] array)
[in]	dynamic	Pointer to KS_DYNAMIC_STATE struct, which has elements being automatically updated by the scan looping functions

Returns

KS_CORESLICETIME Time taken in [us] to play out one inversion slice (.duration) and time to center of inversion pulse (.referencetimepoint)

                                                                                           {

  return ksinv_scan_irslice(&ksepi_inv, slice_pos, dynamic);

} /* ksepi_scan_irslice() */

ksepi_scan_coreslice()

KS_CORESLICETIME ksepi_scan_coreslice	(	const SCAN_INFO *	slice_pos,
		KS_DYNAMIC_STATE *	dynamic
	)

Plays out one slice for the ksepi sequence module in real time during scanning

The main EPI sequence's play function

This function updates the waveforms, and plays out, the ksepi sequence module. 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 += ...).

ks_scan_epi_loadecho() is called for data acquisition for each EPI readout.

After this, ksepi_scan_attach_metadata() adds additional data for each acqusition window for use in the recon_ksepi2.m Matlab script for sorting and reconstruction. To distinguish between the main and FLEET sequences, the sequence_group is here set to KSEPI_DATAGROUP_MAIN.

After each call to ks_scan_playsequence(), ks_plot_slicetime() is called to add slice-timing information for later HTML plotting 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).

Common for all coreslice functions for any psd is the return of a KS_CORESLICETIME struct, which contains the time take to play out one slice (.duration) and the time from the start of the coreslice to the (.referencetimepoint) used to define the excitation location of the coreslice. Here this is simply ksepi.seqctrl.momentstart as there are no other embedded sequence modules played out inside this function. If any sequence module is added inside this function before/after ks_scan_playsequence(&ksepi.seqctrl), the KS_CORESLICETIME struct needs be updated accordingly.

Parameters

[in]	slice_pos	Position of the slice to be played out (one element in the global ks_scan_info[] array)
	dynamic	Pointer to KS_DYNAMIC_STATE struct, which has elements being automatically updated by the scan looping functions

Return values

coreslicetime

KS_CORESLICETIME containing the time taken in [us] to play out one slice and the moment start of the slice

                                                                                             {
  int echo;
  float tloc = 0.0;
  int i;
  KS_PHASEENCODING_COORD fake_coord = KS_INIT_PHASEENCODING_COORD;
  SCAN_INFO slice_pos_updated;

  /* coord to first line of EPI train, same for all echoes */
  const KS_PHASEENCODING_COORD starting_coord = dynamic->shot_coords.entries == NULL ?
    fake_coord : dynamic->shot_coords.entries[0];

  /* Turn off blips during dummies */
  const ks_enum_epiblipsign blipsign = (starting_coord.ky < 0) ? KS_EPI_NOBLIPS : (ks_enum_epiblipsign) ksepi_blipsign;

  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(dynamic->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, dynamic->Mphysical, dynamic->Mlogical);
    tloc = slice_pos_updated.optloc;

    /* modify sequence for next playout */
    ksepi_scan_seqstate(slice_pos_updated, starting_coord, blipsign);
  } else {
    /* false slice, shut off RF */
    ksepi_scan_rf_off();
  }

  /* Scale diffusion gradients */
  for (i=0; i<3; ++i) {
    ks_scan_trap_ampscale(&ksepi.diffgrads[i], INSTRALL, dynamic->diff_amp[i]);
  }

  int dabslice = dynamic->sltimeinpass;
  if (ksepi.epitrain.zphaser.res > 1) {
    if (dynamic->slloc_offset) {
      dabslice = dynamic->slloc_offset - starting_coord.kz;
    } else {
      dabslice = starting_coord.kz;
    }
  }

  dynamic->force_acq = TRUE; /* always acquire data, also during dummies when the blips are off (for Nyquist ghost correction in recon_ksepi2.m) */
  for (echo = 0; echo < opnecho; echo++) {
    ks_scan_epi_loadecho(&ksepi.epitrain, echo, echo, dabslice, starting_coord, blipsign, dynamic);
  }
  if (ksepi_reflines > 0) {
    /* store phase reference lines as opnecho:th echo */
    /* ky of -2 will result in a view of -1 */
    /* See ksepi2_reconrules.txt for sorting info regarding shot and kyview */
    const KS_PHASEENCODING_COORD dynref_coord = {KS_NOTSET-1, KS_NOTSET};
    ks_scan_epi_loadecho(&ksepi.dynreftrain, 0, opnecho, dabslice, dynref_coord, KS_EPI_NOBLIPS, dynamic);
  }

  /* attach metadata to all EPI readout windows */
  uint8_t sequence_group = (uint8_t) (ksepi.epitrain.epi_readout_mode == KS_EPI_SPLITODDEVEN) ? KSEPI_SEQINDEX_MAIN_SPLITODDEVEN : KSEPI_SEQINDEX_MAIN;
  ksepi_scan_attach_metadata(&ksepi.epitrain, &ksepi.dynreftrain, dynamic, sequence_group);

  KS_CORESLICETIME slicetime = KS_INIT_CORESLICETIME;

  slicetime.referencetimepoint = ksepi.seqctrl.momentstart;
  slicetime.duration += ks_scan_playsequence(&ksepi.seqctrl);

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

  return slicetime;

} /* ksepi_scan_coreslice() */

ksepi_scan_coreslicegroup()

KS_CORESLICETIME ksepi_scan_coreslicegroup	(	const SCAN_INFO *	slice_pos,
		KS_DYNAMIC_STATE *	dynamic
	)

Function to run for scan to execute one slice of the ksepi sequence module with optional sat module

The main EPI sequence + potential other modules' play function

With the use of generic scan loops (ksscan.cc:ksscan_scanloop()) performing the actual scan in ksepi_scan_scanloop(), using

• KSSCAN_LOOP_CONTROL (ksepi_loopctrl)
• KS_DYNAMIC_STATE (dynamic)
• KS_CORESLICETIME (coreslice)

one needs to create the psd-specific function in this file to play out one slice of one or more sequence modules This is that function, which must take (const SCAN_INFO *slice_pos, KS_DYNAMIC_STATE *dynamic) as the two input arguments, and return a KS_CORESLICETIME struct. This to match the various ksscan_****loop() functions in ksscan.cc, used to run the scan.

Unlike ksepi_scan_coreslice(), which only plays the main sequence (ksepi), this function also plays other sequence modules. For now, this is only the kssat sequence module, which is played out before the main sequence, if active.

Parameters

[in]	slice_pos	Pointer to the SCAN_INFO struct corresponding to the current slice to be played out
	dynamic	Pointer to KS_DYNAMIC_STATE struct, which has elements being automatically updated by the scan looping functions

Returns

coreslicetime KS_CORESLICETIME containing the time taken in [us] to play out one slice and the moment start of the slice

                                                                                                  {
  KS_CORESLICETIME coreslicetime = KS_INIT_CORESLICETIME;
  int premainseq_duration = 0;
  
  /* Sat */
  premainseq_duration += kssat_scan(slice_pos, dynamic, &kssat);

  /* Main */
  coreslicetime = ksepi_scan_coreslice(slice_pos, dynamic);

  coreslicetime.duration += premainseq_duration;
  coreslicetime.referencetimepoint += premainseq_duration;

  return coreslicetime;

} /* ksepi_scan_coreslicegroup() */

ksepi_scan_fleet_coreslice()

KS_CORESLICETIME ksepi_scan_fleet_coreslice	(	const SCAN_INFO *	slice_pos,
		KS_DYNAMIC_STATE *	dynamic
	)

Plays out one slice for the ksepi_fleetseq sequence module in real time during scanning

The FLEET EPI sequence's play function

This function updates the waveforms, and plays out, the ksepi_fleetseq sequence module. It is quite similar to ksepi_scan_coreslice(), but with the FLEET sequence module instead of the main EPI sequence. In this function, sequence_group = KSEPI_DATAGROUP_FLEET, while it is KSEPI_DATAGROUP_MAIN in ksepi_scan_coreslice(), to let recon detect which readout windows are FLEET vs MAIN.

Parameters

[in]	slice_pos	Position of the slice to be played out (one element in the global ks_scan_info[] array)
	dynamic	Pointer to KS_DYNAMIC_STATE struct, which has elements being automatically updated by the scan looping functions

Returns

coreslicetime KS_CORESLICETIME containing the time taken in [us] to play out one slice and the moment start of the slice

                                                                                                   {
  float tloc = 0.0;
  KS_PHASEENCODING_COORD fake_coord = KS_INIT_PHASEENCODING_COORD;
  KS_CORESLICETIME slicetime = KS_INIT_CORESLICETIME;

  if (ksepi_fleetseq.seqctrl.duration == 0) {
    return slicetime;
  }

  /* coord to first line of EPI train */
  const KS_PHASEENCODING_COORD starting_coord = dynamic->shot_coords.entries == NULL ?
    fake_coord : dynamic->shot_coords.entries[0];

  /* Turn off blips during dummies */
  const ks_enum_epiblipsign blipsign = (starting_coord.ky < 0) ? KS_EPI_NOBLIPS : (ks_enum_epiblipsign) ksepi_blipsign;

  ksepi_fleet_scan_seqstate(slice_pos, starting_coord, blipsign);

  int dabslice = dynamic->sltimeinpass;
  if (ksepi_fleetseq.epitrain.zphaser.res > 1) {
    if (dynamic->slloc_offset) {
      dabslice = dynamic->slloc_offset - starting_coord.kz;
    } else {
      dabslice = starting_coord.kz;
    }
  }

  dynamic->force_acq = TRUE; /* always acquire the FLEET data, also during dummies when the blips are off (for Nyquist ghost correction in recon_ksepi2.m) */
  ks_scan_epi_loadecho(&ksepi_fleetseq.epitrain, 0, 0, dabslice, starting_coord, blipsign, dynamic);

  /* attach metadata to all EPI readout windows */
  uint8_t sequence_group = (uint8_t) (ksepi_fleetseq.epitrain.epi_readout_mode == KS_EPI_SPLITODDEVEN) ? KSEPI_SEQINDEX_FLEET_SPLITODDEVEN : KSEPI_SEQINDEX_FLEET;
  ksepi_scan_attach_metadata(&ksepi_fleetseq.epitrain, NULL, dynamic, sequence_group);

  slicetime.referencetimepoint = ksepi_fleetseq.seqctrl.momentstart;
  slicetime.duration += ks_scan_playsequence(&ksepi_fleetseq.seqctrl);

  tloc = (slice_pos != NULL) ? slice_pos->optloc : 0.0;
  ks_plot_slicetime(&ksepi_fleetseq.seqctrl, 1, &tloc, ksepi_fleetseq.selrfexc.slthick,
                    slice_pos == NULL ? KS_PLOT_NO_EXCITATION : KS_PLOT_STANDARD);

  return slicetime;

} /* ksepi_scan_fleet_coreslice() */

ksepi_scan_attach_metadata() [1/2]

void ksepi_scan_attach_metadata	(	KSEPI_SEQUENCE *	seq,
		const KS_DYNAMIC_STATE *	dynamic,
		uint8_t	sequence_group
	)

ksepi_dump_metadata()

void ksepi_dump_metadata	(	KSEPI_METADATA *	metadata,
		const KS_DYNAMIC_STATE *	dynamic
	)

Write out a textfile of the metadata created in ksepi_scan_attach_metadata() (WTools only)

This debugging function can be used to find errors in the datastore tags of this sequence, created in ksepi_scan_attach_metadata(). Alternatively, this can be done graphically in Matlab (recon_ksepi2.m -> recon_ksepi2_splitdata.m)

Parameters

metadata	Pointer to KSEPI_METADATA
dynamic	Pointer to KS_DYNAMIC_STATE

Returns

void

                                                                                    {
  (void) metadata;
  (void) dynamic;

#ifdef SIM
  /* in simulation (WTools) only */

  if (dynamic->slloc != 0) { /* only show for one slice */
    return;
  }

  FILE *fp;
  fp = fopen("ksepi_metadump.txt","a");

  char str[200] = "00000";
  static char laststr[200] = "1234";

  float bscale = \
  dynamic->diff_amp[XGRAD] * dynamic->diff_amp[XGRAD] + \
  dynamic->diff_amp[YGRAD] * dynamic->diff_amp[YGRAD] + \
  dynamic->diff_amp[ZGRAD] * dynamic->diff_amp[ZGRAD];

  char tmpstr[40];

  switch (metadata->sequence_group) {
    case KSEPI_SEQINDEX_MAIN:
      strcpy(tmpstr, "MAIN       ");
      break;
    case KSEPI_SEQINDEX_FLEET:
      strcpy(tmpstr, "FLEET      ");
      break;
    case KSEPI_SEQINDEX_MAIN_SPLITODDEVEN:
      strcpy(tmpstr, "MAIN_SPLIT ");
      break;
    case KSEPI_SEQINDEX_FLEET_SPLITODDEVEN:
      strcpy(tmpstr, "FLEET_SPLIT");
      break;                  
  }
  sprintf(str, "%s ", tmpstr);

  switch (metadata->seqpart) {
    case KSEPI_SEQPART_EPITRAIN:
      strcpy(tmpstr, "EPITRAIN   ");
      break;
    case KSEPI_SEQPART_DYNREFTRAIN:
      strcpy(tmpstr, "DYNREFTRAIN");
      break;
    case KSEPI_SEQPART_FIDNAV:
      strcpy(tmpstr, "FIDNAV     ");
      break;               
  }
  sprintf(str, "%s%s ", str, tmpstr);

  sprintf(str, "%sv%d ", str, metadata->vol_rep);
  sprintf(str, "%ssh%+d ", str, metadata->shot);
  sprintf(str, "%sish%+d ", str, metadata->inner_shot);
  sprintf(str, "%sa%d ", str, metadata->average);
  sprintf(str, "%srp%+d ", str, metadata->readpolarity);
  sprintf(str, "%sDx%+.1f ", str, dynamic->diff_amp[XGRAD]);
  sprintf(str, "%sDy%+.1f ", str, dynamic->diff_amp[YGRAD]);
  sprintf(str, "%sDz%+.1f ", str, dynamic->diff_amp[ZGRAD]);
  sprintf(str, "%sb%d ", str, (int) (bscale * opbval + 0.5));
  sprintf(str, "%s\n", str);

  if (1 || strcmp(str, laststr)) {
    fprintf(fp, "%s", str);
    strcpy(laststr, str);
  }

  fclose(fp);

#endif

} /* ksepi_dump_metadata() */

ksepi_set_loop_control_design()

STATUS ksepi_set_loop_control_design	(	KSSCAN_LOOP_CONTROL_DESIGN *	loop_design,
		const KS_EPI *	epitrain
	)

Setup of a KSSCAN_LOOP_CONTROL_DESIGN with desired k-space coordinates, averages, volumes, etc.

This function creates a KSSCAN_LOOP_CONTROL_DESIGN struct, with fields .dda: Number of dummy scans .naverages: Number of averages .nvols: Number of volumes .phaseenc_design: KS_PHASEENCODING_DESIGN (containing coordinates and other phase encoding info) .slicetiming_design: KS_SLICETIMING_DESIGN (containing slice timing info)

This function is called from ksepi_eval_loops() to produce a KSSCAN_LOOP_CONTROL_DESIGN, which is then used in part to create a KSSCAN_LOOP_CONTROL struct used in scan

Note that all design structs are short-lived and are set up as a receipe for other structures to be used in pulsegen and scan

Parameters

[out]	loop_design	KSSCAN_LOOP_CONTROL_DESIGN to be created
[in]	epitrain	KS_EPI struct with .blipphaser and .zphaser fields steering the set of k-space coordinates to reach

Return values

STATUS

SUCCESS or FAILURE

                                                                                                      {

  if (optr >= 1s) {
    ksepi_dda = 1;
  } else if (optr > 350ms) {
    ksepi_dda = 2;
  } else {
    ksepi_dda = 4;
  }

  loop_design->dda = IMax(2, 1, ksepi_dda); /* safety net to ensure at least one dummy (for Nyquist ghost correction in recon_ksepi2.m) */
  /* NEX usage for diffusion (opdiffuse): ksdiffusion.cc:ksdiff_schemeloop() uses
     - ksepi_loopctrl.naverages (next line) for b0 NEX
     - ksepi_diffctrl.multib_nex[bvalue_idx] as NEX for each b-value */
  loop_design->naverages = opdiffuse ? opdifnext2 /* NEX for b0s */ : ceil(opnex); 
  loop_design->nvols = opfphases;

  /* Generate the k-space coordinate list */
  STATUS s = ks_generate_3d_coords_epi(&kacq,
                                       epitrain,
                                       (ks_enum_epiblipsign) ksepi_blipsign,
                                       epitrain->R_ky,
                                       0 /* caipi */);
  KS_RAISE(s);

  /* Phase encoding */
  loop_design->phaseenc_design.encodes_per_shot = opnecho;
  loop_design->phaseenc_design.center_encode = 0;
  loop_design->phaseenc_design.kacq = kacq;
  loop_design->phaseenc_design.encode_shot_assignment_order = Z_Y; /* shot order. image ghosting occurs if Y_Z, important for SWI // HR */
  loop_design->phaseenc_design.repeat.num_repeats = opnecho;
  loop_design->phaseenc_design.repeat.mode = INTERLEAVED_LONGER_SHOTS;
  ks_create_suffixed_description(loop_design->phaseenc_design.description, ksepi.seqctrl.description, " - phase encoding plan");


  ksepi_set_slicetiming_design(&loop_design->slicetiming_design);

  return SUCCESS;

} /* ksepi_set_loop_control_design() */

ksepi_scan_seqstate()

STATUS ksepi_scan_seqstate	(	SCAN_INFO	slice_pos,
		KS_PHASEENCODING_COORD	starting_coord,
		ks_enum_epiblipsign	blipsign
	)

Sets the current state of all ksepi sequence objects at every ksepi playout in scan

This function sets the current state of all ksepi sequence objects being part of KSEPI_SEQUENCE, incl. gradient amplitude changes, RF freq/phases and receive freq/phase based on current slice position and phase encoding indices for a given sequence playout in ksepi_scan_coreslice() during scan.

Note that starting_coord is the first line in the EPI train.

Parameters

[in]	slice_pos	Position of the slice to be played out (one element in the ks_scan_info[] array)
[in]	starting_coord	KS_PHASEENCODING_COORD holding the .ky and .kz coordinates of the first line in the EPI train
[in]	blipsign	Sign of the EPI blips: [-1]:Negative (k-space top-down) [1]:Positive (k-space bottom-up) [0]:No blips

Return values

STATUS

SUCCESS or FAILURE

                                                                                                                     {
  int echo;
  float exc_rfphase;

  /* RF frequency & phase */
  if (ksepi_rfspoiling) {
    exc_rfphase = ks_scan_rf_phase_spoiling(rfspoiling_phase_counter);
    rfspoiling_phase_counter++;
  } else {
    exc_rfphase = 0;
  }

  ks_scan_rotate(slice_pos);

  ks_scan_rf_on(&ksepi.selrfexc.rf, INSTRALL);
  ks_scan_rf_on(&ksepi.selrfref.rf, INSTRALL);

  ks_scan_selrf_setfreqphase(&ksepi.selrfexc, 0,        slice_pos, exc_rfphase);
  ks_scan_selrf_setfreqphase(&ksepi.selrfref, INSTRALL, slice_pos, exc_rfphase+90);

  /* Echo time shifting */
  if (ksepi_echotime_shifting) {
    int pre_delay = ksepi.pre_delay.pg_duration;
    int post_delay = ksepi.post_delay.pg_duration;
    int kyshot = starting_coord.ky % ksepi.epitrain.blipphaser.R;
    int epiesp = ksepi.epitrain.read.grad.duration + ksepi.epitrain.read_spacing;
    float delta_t = (float) epiesp / (float) ksepi.epitrain.blipphaser.R;

    if (kyshot >= 0) {
      if (blipsign == KS_EPI_POSBLIPS) {
        pre_delay = RUP_GRD((int) (delta_t * (ksepi.epitrain.blipphaser.R-1-kyshot)));
      } else if (blipsign == KS_EPI_NEGBLIPS) {
        pre_delay = RUP_GRD((int) (delta_t * kyshot));
      }
    }
    ks_scan_wait(&ksepi.pre_delay, pre_delay);
    post_delay = ksepi_echotime_shifting_sumdelay - pre_delay;
    ks_scan_wait(&ksepi.post_delay, post_delay);
  } /* echotime shifting */

  /* EPI echoes (i.e. EPI trains) */
  for (echo = 0; echo < opnecho; echo++) {
    ks_scan_epi_shotcontrol(&ksepi.epitrain, echo, slice_pos, starting_coord, blipsign, exc_rfphase);
  } /* opnecho */

  KS_PHASEENCODING_COORD fake_coord = {KS_NOTSET, KS_NOTSET};
  ks_scan_epi_shotcontrol(&ksepi.dynreftrain, 0, slice_pos, fake_coord, KS_EPI_NOBLIPS, exc_rfphase);

  return SUCCESS;

} /* ksepi_scan_seqstate() */

ksepi_scan_scanloop()

s64 ksepi_scan_scanloop

(

)

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

This function is called from ksepi.e:scan(), which corresponds to the actual SCAN button press in the UI.

This function first completes the FLEET scan, for 2D imaging with parallel imaging, where the FLEET scan is used in recon for motion robust GRAPPA calibration.

If inversion is used, the function calls ksinv_scan_scanloop(), where ksepi_inv_loopctrl is used to control the the scan looping. For non-inversion scans, depending on if diffusion is used, either ksdiff_schemeloop() or ksscan_scanloop() is called, where ksepi_loopctrl is used to control the scan looping in both cases. ksscan_scanloop() and ksdiff_schemeloop() differ only on the outer volumne loop, but share the same inner looping from ksscan_acqloop(). While ksscan_scanloop() goes through volume indices like fMRI, ksdiff_schemeloop() goes through diffusion directions and b-values as different volumes.

Returns

scantime Total scan time in [us]

                          {
  s64 time = 0;

#ifdef SIM
  /* empty local file in simulation (see ksepi_dump_metadata()) */
  FILE *fp = fopen("ksepi_metadump.txt","w"); fclose(fp);
#endif

  if (ksepi_fleet) {
    time += ksscan_scanloop(&ksepi_fleet_loopctrl, NULL, ksepi_scan_fleet_coreslice);
  }

  KS_DYNAMIC_STATE dynamic = KS_INIT_DYNAMIC_STATE;

  if (!ANYINVERSION) {
    if (opdiffuse) {
      time += ksdiff_schemeloop(&ksepi_diffctrl, &ksepi_loopctrl, &dynamic, ksepi_scan_coreslicegroup);
    } else {
      time += ksscan_scanloop(&ksepi_loopctrl, &dynamic, ksepi_scan_coreslicegroup);
    }
  } else {
    time += ksinv_scan_scanloop(&ksepi_inv_loopctrl, &dynamic, ksepi_scan_coreslicegroup, ksepi_scan_irslice);
  }

  return time; /* in [us] */

} /* ksepi_scan_scanloop() */

ksepi_get_loop_ctrl()

const KSSCAN_LOOP_CONTROL * ksepi_get_loop_ctrl

(

)

Function to automatically switch between inverision and standard loop control

To save if statments in the code, this function returns the loop control in use depending on inversion is on or off.

Return values

STATUS

SUCCESS or FAILURE

                                                 {
  return ANYINVERSION ?
    &ksepi_inv_loopctrl.loopctrl : &ksepi_loopctrl;

} /* ksepi_get_loop_ctrl() */

ksepi_init_imagingoptions()

void ksepi_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)
  */


  cvset(opptsize, 2, 4, 4, ""); /* EDR */
  set_required_disabled_option(PSD_IOPT_EDR); /* always use EDR, don't change */

  /* Do not allow 3D multislab to be selected until supported by the PSD */
  cvmax(opimode, PSD_3D);

  /* Button accept control */
  cvmax(opflair, OPFLAIR_GROUP); /* allow T2-FLAIR */
  cvmax(opepi, 1);
  cvdef(opepi, 1);
  cvmax(opmph, 1);
  cvmax(opdiffuse, 1);

  /* Exlude different inversion types */
  set_incompatible(PSD_IOPT_T2FLAIR, PSD_IOPT_T1FLAIR);
  set_incompatible(PSD_IOPT_IR_PREP, PSD_IOPT_T1FLAIR);
  set_incompatible(PSD_IOPT_T2FLAIR, PSD_IOPT_IR_PREP);

  if (KS_3D_SELECTED) {
    deactivate_ioption(PSD_IOPT_IR_PREP);
  } 

  /* flow comp only for GE-EPI */
  if (exist(oppseq) == PSD_SE) {
    deactivate_ioption(PSD_IOPT_FLOW_COMP);
  }


  if (opdiffuse) {
    deactivate_ioption(PSD_IOPT_SEQUENTIAL);
    deactivate_ioption(PSD_IOPT_MPH);
    deactivate_ioption(PSD_IOPT_IR_PREP);
  }

#ifdef SIM
  opepi = !KS_3D_SELECTED;
  setexist(opepi, PSD_ON);
  opirmode = PSD_OFF; /* default interleaved slices */
  setexist(opirmode, PSD_ON);
#endif

  /* GERequired.e:GEReq_cvinit() sets ks_qfact (acoustic reduction) when
     ART (opsilent) has been selected. For medium/high ART, ks_qfact is set to 8/20.
     However, for EPI, the geometric distortions becomes too severe so can no
     reduce the slewrate for EPI as much (and hence the amount of acoustic reduction). 

     Also the SPSP RF pulse uses a gradwave that cannot be derated.
     If we use SPSP RF exc (opfat == FALSE), we set ks_qfact = 1.0.
     With opfat ks_qfact will be set by GEReq_cvinit() and the sequence will run quieter
     In all cases, the EPI readout gradients are controlled by ksepi_epiqfact */

  if (opsilent) {

    if (opfat == FALSE) { 
      /* SPectral-SPatial RF. Cannot derate excitation waveform */
      ks_qfact = 1.0; /* for all gradients except the EPI readout */
      GEReq_init_gradspecs(&loggrd, &phygrd, ks_srfact / ks_qfact);
    }

    if (opsilentlevel == 1) {
      /* moderate ART (small acoustic reduction) */
      ksepi_epiqfact = 3.0;
    } else {
      /* high ART (moderate acoustic reduction) */
      ksepi_epiqfact = 6.0; /* for the EPI readout */
    }
  } else {
    ksepi_epiqfact = 1.0;
  }

  pipure = PSD_PURE_COMPATIBLE_2; /* or maybe PSD_PURE_COMPATIBLE_1 ? */

  /* RF Drive mode (default to 'Quadrature') */
  cvdef(opdrivemode, 2);
  opdrivemode = _opdrivemode.defval;

  ks_plot_kstmp = TRUE; /* save plots to kstmp */

  /* default receive gain (LOW/HIGH for 3D/2D). No APS2 prescan with ksepi_recvgain_mode > 0 */
  ksepi_recvgain_mode = (KS_3D_SELECTED) ? RG_CAL_MODE_LOW_FIXED : RG_CAL_MODE_HIGH_FIXED;

} /* ksepi_init_imagingoptions() */

ksepi_init_UI()

STATUS ksepi_init_UI

(

void

)

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

Return values

STATUS

SUCCESS or FAILURE

                           {
  STATUS status;

  /* Slice oversampling for 3D to avoid aliasing */
  if (KS_3D_SELECTED) {
    pislblank = ksepi_kissoff_factor * exist(opslquant);
  }

  /* Spin or Gradient Echo EPI */
  if (exist(oppseq) == PSD_SE || exist(oppseq) == PSD_IR) {
    acq_type = TYPSPIN; /* SE, FLAIR, or Diffusion EPI */
  } else {
    acq_type = TYPGRAD; /* GRE-EPI */
  }

  /* force flow comp off for non-GE-EPI */
  if (acq_type != TYPGRAD) {
    cvoverride(opfcomp, FALSE, PSD_FIX_ON, PSD_EXIST_ON);
  }

  /* rBW */
  float bw_3Dlimit = (cfgcoiltype == PSD_XRMW_COIL) ? 83.33 : 125.0;
  pidefrbw = (KS_3D_SELECTED) ? bw_3Dlimit : 250.0;
  cvset(oprbw, 15.625, pidefrbw, pidefrbw, "");
  pircbnub = (cfgcoiltype == PSD_XRMW_COIL) ? 4 : 5; /* number of variable bandwidth */
  pircb2nub = 0; /* no second bandwidth option */
  pircbval2 = 31.25;
  pircbval3 = 62.50;
  pircbval4 = (KS_3D_SELECTED) ? 83.33 : 125.0;
  pircbval5 = pidefrbw;

  /* NEX - never show. Partial Fourier in ky is done with opte = MINTE, not with NEX < 1 */
  cvdef(opnex, 1);
  opnex = _opnex.defval;
  cvmin(opnex, 1);
  cvmax(opnex, 1);
  opnex = 1;
  if (opdiffuse) {
    cvoverride(opnex, 1, PSD_FIX_OFF, PSD_EXIST_ON);
    pinexnub = 0;
  } else {
    pinexnub = 3;
  }
  pinexval2 = 1;
  pinexval3 = 1;
  pinexval4 = 1;
  pinexval5 = 1;
  pinexval6 = 1;

  /* FOV */
  opfov = 240;
  pifovnub = 5;
  pifovval2 = 200;
  pifovval3 = 220;
  pifovval4 = 240;
  pifovval5 = 260;
  pifovval6 = 280;

  /* phase FOV fraction */
  opphasefov = 1;
  piphasfovnub2 = 63;
  piphasfovval2 = 1.0;
  piphasfovval3 = 0.9;
  piphasfovval4 = 0.8;
  piphasfovval5 = 0.7;
  piphasfovval6 = 0.6;

  /* freq (x) resolution */
  cvmin(opxres, 16);

  /* phase (y) resolution */
  cvmin(opyres, 16);

  if (KS_3D_SELECTED) {
      /* assuming many shots for 3D */
      cvdef(opxres, 320);
      pixresnub = 63;
      pixresval2 = 192;
      pixresval3 = 256;
      pixresval4 = 288;
      pixresval5 = 320;
      pixresval6 = 384;

      cvdef(opyres, 320);
      piyresnub = 63;
      piyresval2 = 192;
      piyresval3 = 256;
      piyresval4 = 288;
      piyresval5 = 320;
      piyresval6 = 384;
  } else {
    cvdef(opxres, 64);
    cvdef(opyres, 64);
    if (opdiffuse) {
      pixresnub = 63;
      pixresval2 = 96;
      pixresval3 = 128;
      pixresval4 = 160;
      pixresval5 = 192;
      pixresval6 = 224;

      piyresnub = 63;
      piyresval2 = 96;
      piyresval3 = 128;
      piyresval4 = 160;
      piyresval5 = 192;
      piyresval6 = 224;
    } else {
      pixresnub = 63;
      pixresval2 = 32;
      pixresval3 = 64;
      pixresval4 = 96;
      pixresval5 = 128;
      pixresval6 = 160;

      piyresnub = 63;
      piyresval2 = 32;
      piyresval3 = 64;
      piyresval4 = 96;
      piyresval5 = 128;
      piyresval6 = 160;
    }
  }
  opxres = _opxres.defval;
  opyres = _opyres.defval;


  /* Num echoes */
  piechnub = 63;
  cvdef(opnecho, 1);
  cvmax(opnecho, 8);
  opnecho = _opnecho.defval;
  piechdefval = _opnecho.defval;
  piechval2 = 1;
  piechval3 = 2;
  piechval4 = 4;
  piechval5 = 6;
  piechval6 = 8;

  /* ETL */
  cvmax(opetl, 1024);
  pietlnub = 0;

  /* TE */
  avmaxte = 1s;
  avminte = 0;
  avminte2 = 0;
  pitetype = PSD_LABEL_TE_EFF; /* alt. PSD_LABEL_TE_EFF */
  cvdef(opte, 200ms);
  opte = _opte.defval;
  pite1nub = (opdiffuse) ? 6 : 63; /* 6: Only two menu choices MinTE & MinFullTE */
  pite1val2 = PSD_MINIMUMTE;
  pite1val3 = PSD_MINFULLTE;
  pite1val4 = 30ms;
  pite1val5 = 50ms;
  pite1val6 = 70ms;

  /* TE2 */
  /* pite2nub = 0; */

  /* TR */
  cvdef(optr, 2s);
  optr = _optr.defval;
  if (opfast == TRUE) {
    pitrnub = 0; /* '0': shown but greyed out (but only if opautotr = 1, otherwise TR menu is hidden) */
    cvoverride(opautotr, PSD_ON, PSD_FIX_OFF, PSD_EXIST_ON);
  } else {
    pitrnub = 2; /* '2': only one menu choice (Minimum = AutoTR) */
  }
  pitrval2 = PSD_MINIMUMTR;

  /* FA */
  if (acq_type == TYPSPIN) {
    cvdef(opflip, 180); /* refocusing RF: initialize with low FA to avoid gradrf complaints on load */
    pifanub = 0; /* can also be e.g. 2 to allow modification of refocusing flip angle */
    pifamode = PSD_FLIP_ANGLE_MODE_REFOCUS;
    pifaval2 = 180;
  } else {
    pifanub = 6;
    pifamode = PSD_FLIP_ANGLE_MODE_EXCITE;
    cvdef(opflip, 10);
    pifaval2 = 10;
    pifaval3 = 15;
    pifaval4 = 20;
    pifaval5 = 30;
    pifaval6 = 90;
  }
  opflip = _opflip.defval;


  /* slice thickness */
  pistnub = 5;
  if (!KS_3D_SELECTED) {
    cvdef(opslthick, 4);
    pistval2 = 3;
    pistval3 = 4;
    pistval4 = 5;
    pistval5 = 6;
    pistval6 = 10;
  } else {
    cvdef(opslthick, 2);
    pistval2 = 1.50;
    pistval3 = 1.75;
    pistval4 = 2.00;
    pistval5 = 2.25;
    pistval6 = 2.50;
  }
  opslthick = _opslthick.defval;

  /* slice spacing */
  cvdef(opslspace, 0);
  pi_neg_sp = FALSE;
  opslspace = _opslspace.defval;
  piisil = FALSE;
  piisnub = 0;
  piisval2 = 0;

  /* default # of slices */
  cvdef(opslquant, 30);

  /* 3D slice settings */
  if (KS_3D_SELECTED) {/* PSD_3D (=2) or PSD_3DM (=6) */

    if (opimode == PSD_3DM) {
      return KS_THROW("3D multislab mode not supported");
    }

    if (acq_type == TYPSPIN) {
      return KS_THROW("3D spin echo epi not supported");
    }

    pimultislab = 0; /* 0: forces only single slab, 1: allow multi-slab */
    pilocnub = 4;
    pilocval2 = 32;
    pilocval3 = 64;
    pilocval4 = 128;
    /* opslquant = #slices in slab. opvquant = #slabs */
    cvdef(opslquant, 32);
  }

  /* Multi phase (i.e. multi volumes) */
  if (opmph) {
    pimphscrn = 1;   /* display Multi-Phase Parameter screen */
    pifphasenub = 6;
    pifphaseval2 = 10;
    pifphaseval3 = 20;
    pifphaseval4 = 50;
    pifphaseval5 = 100;
    pifphaseval6 = 200;
    pisldelnub = 0;
    /*
    pisldelval3 = 1s;
    pisldelval4 = 2s;
    pisldelval5 = 5s;
    pisldelval6 = 10s;
    */
    piacqnub = 0;
    setexist(opacqo, 1);
    pihrepnub = 0;  /* no XRR gating */
  } else {
    if (!opdiffuse) {
      cvoverride(opfphases, 1, PSD_FIX_OFF, PSD_EXIST_OFF);
    }
    pimphscrn = 0;   /* do not display the Multi-Phase Parameter screen */
  }

  if (KS_3D_SELECTED) {
    pidefexcitemode = SELECTIVE;
    piexcitemodenub = 1 + 2 /* + 4 FOCUS */;
    cvdef(opexcitemode, SELECTIVE);
    cvmax(opexcitemode, NON_SELECTIVE);  /* 0=SELECTIVE, 1=NON_SELECTIVE */
  }


  /* Prescan buttons (autoshim). c.f. epic.h */
  pipscoptnub = 1; /* Bit map of number of Prescan option buttons. 0=none, 1=autoshim, 2=phase corr */

  /* OPUSER_PSDVERSION: show GIT revision (GITSHA) using REV variable from the Imakefile */
#ifdef REV
  char userstr[100];
  sprintf(userstr, "PSD version: %s", REV);
  cvset(OPUSER_PSDVERSION, 0, 0, 0, userstr);
  piuset |= SHOW_RHRECON;
#endif

  /* ksepi_nover defaults depend on application (overridden by OPUSER_KYNOVER)  */
  if (opdiffuse) {
    cvdef(ksepi_kynover,48); /* 48 lines drives up minTE, but results in better image quality for normal b-values */
  } else if (acq_type == TYPGRAD) {
    cvdef(ksepi_kynover,32); /* GE-EPI with long TE needs higher value to capture the less coherent k-space center (substantial image phase) */
  } else {
    cvdef(ksepi_kynover,16); /* SE-EPI has such distinct k-space peak with essentially no image phase, don't need many overscans */
  }
  /* OPUSER_KYNOVER: Number of overscans (extra kylines) for partial Fourier */
  cvset(OPUSER_KYNOVER, _ksepi_kynover.minval, _ksepi_kynover.maxval, _ksepi_kynover.defval, _ksepi_kynover.descr);
  piuset |= SHOW_KYNOVER;

  cvset(OPUSER_BLIPSIGN, _ksepi_blipsign.minval, _ksepi_blipsign.maxval, _ksepi_blipsign.defval, _ksepi_blipsign.descr);
  piuset |= SHOW_BLIPSIGN;

  cvset(OPUSER_EPIREADOUTMODE, _ksepi_readout_mode.minval, _ksepi_readout_mode.maxval, _ksepi_readout_mode.defval, _ksepi_readout_mode.descr);
  piuset |= SHOW_EPIREADOUTMODE;

  /* OPUSER_FLEET_EPIREADOUTMODE for FLEET (used for GRAPPA calibration) */
  cvset(OPUSER_FLEET_EPIREADOUTMODE, _ksepi_fleet_readout_mode.minval, _ksepi_fleet_readout_mode.maxval, _ksepi_fleet_readout_mode.defval, _ksepi_fleet_readout_mode.descr);
  if (oparc && opaccel_ph_stride > 1 && !KS_3D_SELECTED) {
    piuset |= SHOW_FLEET_EPIREADOUTMODE;
  } else {
    piuset &= ~SHOW_FLEET_EPIREADOUTMODE;
  }

  /* OPUSER6_DIFF_RETURNMODE. Used by recon to determine what DICOM images to write out (bitmask: All:0 Acq:1 b0:2 DWI:4 ADC:8 Exp:16 FA:32 cFA:64) */
  cvset(OPUSER6_DIFF_RETURNMODE, _ksepi_diffusion_returnmode.minval, _ksepi_diffusion_returnmode.maxval, _ksepi_diffusion_returnmode.defval, _ksepi_diffusion_returnmode.descr);
  if (opdiffuse) {
    piuset |= SHOW_DIFF_RETURNMODE;
  } else {
    piuset &= ~SHOW_DIFF_RETURNMODE;
  }

  /* OPUSER7_SWI_RETURNMODE. Used by recon to determine what DICOM images to write out (bitmask: 0:Off 1:Acq 2:SWI 4:SWIphase) */
  cvset(OPUSER7_SWI_RETURNMODE, _ksepi_swi_returnmode.minval, _ksepi_swi_returnmode.maxval, _ksepi_swi_returnmode.defval, _ksepi_swi_returnmode.descr);
  if (oppseq != PSD_SE && KS_3D_SELECTED) { /* show for GE variants (PSD_GE, PSD_SPGR, ...) */
   piuset |= SHOW_SWI_READOUTMODE;
  } else {
   piuset &= ~SHOW_SWI_READOUTMODE;
   cvoverride(ksepi_swi_returnmode, 0, PSD_FIX_OFF, PSD_EXIST_OFF);
  }

  /* OPUSER_REFLINES. Number of phase reference lines for ghost correction per shot */
  cvdef(ksepi_reflines, 0);
  ksepi_reflines = _ksepi_reflines.defval;
  cvset(OPUSER_REFLINES, _ksepi_reflines.minval, _ksepi_reflines.maxval, _ksepi_reflines.defval, _ksepi_reflines.descr);
  piuset |= SHOW_REFLINES;

  if (KS_3D_SELECTED) {
    cvset(OPUSER_KZACSLINES, _ksepi_kz_nacslines.minval, _ksepi_kz_nacslines.maxval, _ksepi_kz_nacslines.defval, _ksepi_kz_nacslines.descr);
    piuset |= SHOW_KZACSLINES;
  } else {
    piuset &= ~SHOW_KZACSLINES;
  }

  /*
     Reserved opusers:
     -----------------
     ksepi_diffusion_predownload_setrecon(): opuser20-25 (needed by GE's recon)
     GE reserves: opuser36-48 (epic.h)
   */


  /* Acceleration menu (max accel = 4). But we don't show ARC for 2D */
  GEReq_init_accelUI(KS_ACCELMENU_INT, 4);

  /* multi-shot button (see also ksepi_eval_UI()) */
  if (opdiffuse) {
    pishotnub = 0;
  } else {
    pishotnub = 63;
  }
  if (KS_3D_SELECTED) {
    pishotval2 = 8;
    pishotval3 = 12;
    pishotval4 = 16;
    pishotval5 = 24;
    pishotval6 = 32;
    cvdef(opnshots, 16);
} else {
    pishotval2 = 1;
    pishotval3 = 2;
    pishotval4 = 4;
    pishotval5 = 8;
    pishotval6 = 16;
    cvdef(opnshots, 1);
  }
  cvmin(opnshots, 1);
  cvmax(opnshots, 512);
  opnshots = _opnshots.defval;

  /* Make R/L freq encoding attempts */
  cvdef(opspf,1);
  if (existcv(opplane) && (KS_PLANE_AX || KS_PLANE_COR)) {
      piswapfc = 1;
      cvmin(opspf,1);
      if (existcv(opslquant) && existcv(opspf) && exist(opspf) == 0) {
        return KS_THROW("Must choose FreqDir = R/L");
      }
  } else {
      piswapfc = 0;
      cvmin(opspf,0);
  }

  /* Diffusion init */
  status = ksepi_diffusion_init_UI();
  KS_RAISE(status);

  return SUCCESS;

} /* ksepi_init_UI() */

ksepi_eval_UI()

STATUS ksepi_eval_UI

(

)

Gets the current UI and checks for valid inputs

Return values

STATUS

SUCCESS or FAILURE

                       {
  STATUS status;

  status = ksepi_init_UI();
  KS_RAISE(status);

  /*** Copy UserCVs to human readable CVs ***/
  if (existcv(opautote) && opautote == PSD_MINTE) {
    ksepi_kynover = (int) OPUSER_KYNOVER;
    if (ksepi_kynover < _ksepi_kynover.minval || ksepi_kynover > _ksepi_kynover.maxval)
      return KS_THROW("'#extralines for minTE' is out of range");
  }

  ksepi_blipsign = (int) OPUSER_BLIPSIGN;
  if (ksepi_blipsign != KS_EPI_POSBLIPS && ksepi_blipsign != KS_EPI_NEGBLIPS) {
    return KS_THROW("The EPI blip sign must be either +1 or -1"); /* User error */
  }

  ksepi_readout_mode = (int) OPUSER_EPIREADOUTMODE;
    if (ksepi_readout_mode < KS_EPI_BIPOLAR && ksepi_blipsign > KS_EPI_FLYBACK) {
    return KS_THROW("Readout mode must be in range 0-2"); /* User error */
  }

  ksepi_fleet_readout_mode = (int) OPUSER_FLEET_EPIREADOUTMODE;
    if (ksepi_fleet_readout_mode < KS_EPI_BIPOLAR && ksepi_blipsign > KS_EPI_FLYBACK) {
    return KS_THROW("FLEET readout mode must be in range 0-2"); /* User error */
  }

  /* Reserved opusers:
     -----------------
     ksepi_diffusion_predownload_setrecon(): opuser20-25 (needed by GE's recon)
     GE reserves: opuser36-48 (epic.h)
  */

  cvoverride(opasset, FALSE, _opasset.fixedflag, _opasset.existflag); /* force asset off, but keep exist/fixed status */
  piechnub = 63;

  ksepi_diffusion_returnmode = (int) OPUSER6_DIFF_RETURNMODE;

  ksepi_swi_returnmode = (int) OPUSER7_SWI_RETURNMODE;

  ksepi_fleet = PLAY_FLEET; /* PLAY_FLEET is = 1 for 2D ARC R>1, otherwise 0 */

  ksepi_reflines = (int) OPUSER_REFLINES;

  ksepi_kz_nacslines = (int) OPUSER_KZACSLINES;

  return SUCCESS;

} /* ksepi_eval_UI() */

ksepi_eval_setuprf()

STATUS ksepi_eval_setuprf

(

)

Setup of selective RF excitation and refocusing designs and make of corresponding KS_SELRF

This function initializes the local excdesign and refdesign structures with default values and modifies them based on various CVs. The function then calls ks_eval_design_selrfexc() and ks_eval_design_selrfref() functions to evaluate the designs and store the results in ksepi.selrfexc and ksepi.selrfref structures respectively for later use in ksepi_pg()

Return values

STATUS

SUCCESS or FAILURE

                            {

  STATUS status;

  KS_SELRF_DESIGN excdesign = KS_INIT_SELRF_EXCDESIGN; /* c.f. ksdesign.h */
  KS_SELRF_DESIGN refdesign = KS_INIT_SELRF_REFDESIGN; /* c.f. ksdesign.h */
  strcpy(excdesign.description, "ksepimain.selrfexc");
  strcpy(refdesign.description, "ksepimain.selrfref");

  ksepi_gscalerfexc = (KS_3D_SELECTED) ? 1.0 : 0.9;
  ksepi_gscalerfref = (KS_3D_SELECTED) ? 1.0 : 0.9;

  excdesign.slthick = (KS_3D_SELECTED) ? (exist(opslquant) - 2 * pislblank) * exist(opslthick) : exist(opslthick);
  excdesign.flip = (acq_type == TYPSPIN) ? 90 : opflip;
  excdesign.gscale = ksepi_gscalerfexc;
  excdesign.rfstretch = ksepi_rfstretch_exc;

  if (KS_3D_SELECTED) { /* 3D */
    if (existcv(opexcitemode) && (opexcitemode == SELECTIVE)) { /* Selective 3D */
      /* N.B.: Select opslquant * opslthick >= 100 mm to get optimized RF pulses for 3D, otherwise
         the RF selection falls back to SPSP for 2D (ksdesign.cc) */
      excdesign.rfpulse_choice = (ksepi_fastexc3D) ? EXC_FAST_SPSP_3D : EXC_SPSP_3D;
    } else { /* Non-selective 3D */
      excdesign.rfpulse_choice = EXC_HARD_LOWFAT;
      /* non-slice selective, set .slthick = 0 to have ks_**_selrf() produce a zero-amp gradient */
      excdesign.slthick = 0; /* Hard pulse w/o slice selection */
    }
  } else { /* 2D */
    excdesign.rfpulse_choice = (opfat) ? EXC_2D : EXC_SPSP;
  }

  status = ks_eval_design_selrfexc(&ksepi.selrfexc, excdesign); /* c.f. ksdesign.cc */
  KS_RAISE(status);


  /* selective RF refocusing */
  if (acq_type == TYPSPIN) {
    refdesign.slthick = exist(opslthick);
    refdesign.flip = opflip; /* pifamode = PSD_FLIP_ANGLE_MODE_REFOCUS when TYPSPIN */
    refdesign.gscale = ksepi_gscalerfref;
    refdesign.rfstretch = ksepi_rfstretch_ref;
    refdesign.rfpulse_choice = REF_SHARP_2D;
    refdesign.crusher_dephasing = ksepi_crusher_dephasing;
    refdesign.bridge_crushers = ksepi_bridgecrushers;

    status = ks_eval_design_selrfref(&ksepi.selrfref, refdesign); /* c.f. ksdesign.cc */
    KS_RAISE(status);

  } KS_RAISE(status);

  return SUCCESS;

} /* ksepi_eval_setuprf() */

ksepi_eval_setupfleet()

STATUS ksepi_eval_setupfleet

(

)

Setup the components of the FLEET sequence (KSEPI_FLEET_SEQUENCE ksepi_fleetseq)

Based on CVs and by copying the .epitrain from the main sequence, this function sets up the sequence components of the FLEET sequence. The FLEET sequence is used for GRAPPA calibration in the recon (recon_ksepi2.m) for 2D scans. See C macro PLAY_FLEET in this file

Return values

STATUS

SUCCESS or FAILURE

                               {
  STATUS status;

  if (ksepi_fleet == FALSE) {
    return SUCCESS;
  }

  ksepi_fleetseq.selrfexc = ksepi.selrfexc;
  ksepi_fleetseq.selrfexc.rf.flip = ksepi_fleet_flip;
  status = ks_eval_selrf1p(&ksepi_fleetseq.selrfexc, "fleetrfexc");
  KS_RAISE(status);

  /* EPI readout: First copy the EPI train from the main sequence */
  ksepi_fleetseq.epitrain = ksepi.epitrain; 

  const int nshots = IMin(2, ksepi_fleet_num_ky, ksepi_fleet_nshots * ((ksepi_fleet_readout_mode != KS_EPI_BIPOLAR) ? 2 : 1));
  const int yres = nshots * CEIL_DIV(ksepi_fleet_num_ky, nshots);
  ksepi_fleetseq.epitrain.blipphaser.R = nshots; /* this many EPI interleaves to fill k-space */
  ksepi_fleetseq.epitrain.R_ky = 1; /* no undersampling (acceleration) */
  ksepi_fleetseq.epitrain.blipphaser.res = yres;
  ksepi_fleetseq.epitrain.blipphaser.nover = 0; /* no partial Fourier for FLEET */
  ksepi_fleetseq.epitrain.epi_readout_mode = ksepi_fleet_readout_mode; /* KS_EPI_BIPOLAR, KS_EPI_FLYBACK, KS_EPI_SPLITODDEVEN */

  status = ks_eval_epi(&ksepi_fleetseq.epitrain, "epifleet", ks_qfact);
  KS_RAISE(status);

  ksepi_fleetseq.spoiler.area = ksepi_spoilerarea;
  status = ks_eval_trap(&ksepi_fleetseq.spoiler, "fleetspoiler");
  KS_RAISE(status);

  /* echo time shifting */
  ks_init_wait(&ksepi_fleetseq.pre_delay);
  ks_init_wait(&ksepi_fleetseq.post_delay);
  if (ksepi_echotime_shifting_fleet == TRUE) {
    /*** Set up a pair of wait objects that are used to shift back the RF up to the echospacing ***/
    int epiesp = ksepi_fleetseq.epitrain.read.grad.duration + ksepi_fleetseq.epitrain.read_spacing;
    ksepi_echotime_shifting_shotdelay_fleet = (float) epiesp / (float) ksepi_fleetseq.epitrain.blipphaser.R;
    ksepi_echotime_shifting_sumdelay_fleet = RUP_GRD((int) (ksepi_echotime_shifting_shotdelay_fleet * (ksepi_fleetseq.epitrain.blipphaser.R-1))) + GRAD_UPDATE_TIME;
    status = ks_eval_wait(&ksepi_fleetseq.pre_delay,"ksepi_fleet_wait_pre", GRAD_UPDATE_TIME, ksepi_echotime_shifting_sumdelay_fleet);
    KS_RAISE(status);
    status = ks_eval_wait(&ksepi_fleetseq.post_delay,"ksepi_fleet_wait_post", ksepi_echotime_shifting_sumdelay_fleet - GRAD_UPDATE_TIME, ksepi_echotime_shifting_sumdelay_fleet);
    KS_RAISE(status);
  }

  ks_init_seqcontrol(&ksepi_fleetseq.seqctrl);
  strcpy(ksepi_fleetseq.seqctrl.description, "ksepifleet");

  return SUCCESS;

} /* ksepi_eval_setupfleet() */

ksepi_eval_setupobjects()

STATUS ksepi_eval_setupobjects

(

)

Sets up all sequence objects for the main sequence module (KSEPI_SEQUENCE ksepi)

This function will set up all objects for the main sequence module (ksepi) via a mix of UI CVs and other CVs. This effectively sets the shape (amp, ramptimes & duration) of each trapezoid and waveform in the sequence for later placement in ksepi_pg().

Note that at the very end of this function, ksepi_eval_setupfleet() is called to also set up ksepi_fleetseq (KSEPI_FLEET_SEQUENCE) as well as ksepi (KSEPI_SEQUENCE) if ksepi_fleet is TRUE

Return values

STATUS

SUCCESS or FAILURE

                                 {
  STATUS status;

  /* All RF related setup in separate function */
  status = ksepi_eval_setuprf();
  KS_RAISE(status);


  /* EPI readout */
  ksepi.epitrain.read_spacing = ksepi_readlobegap;
  ksepi.epitrain.read.acq.rbw = oprbw;
  ksepi.epitrain.read.fov = opfov;
  ksepi.epitrain.read.res = RUP_FACTOR(opxres, 2); /* round up (RUP) to nearest multiple of 2 */
  ksepi.epitrain.read.rampsampling = ksepi_rampsampling;
  ksepi.epitrain.read.nover = 0; /* never partial Fourier in kx for EPI */
  ksepi.epitrain.blipphaser.fov = opfov * opphasefov;
  ksepi.epitrain.blipphaser.res = RUP_FACTOR((int) (opyres * opphasefov), 2); /* round up (RUP) to nearest multiple of 2 */
  ksepi.epitrain.blipphaser.nover = (opautote == PSD_MINTE) ? ksepi_kynover : 0; /* partial Fourier in ky */
  ksepi.epitrain.blipphaser.R = (opdiffuse || opnshots == 1) ? opaccel_ph_stride : opnshots; /* Number of shots to fully sample the desired part of k-space. opnshots hidden for diffusion */
  ksepi.epitrain.blipphaser.nacslines = 0; /* never have acs lines for EPI */
  ksepi.epitrain.R_ky = opaccel_ph_stride; /* actual acceleration is achieved by acquired a subset of shots */
  ksepi.epitrain.epi_readout_mode = ksepi_readout_mode; /* KS_EPI_BIPOLAR, KS_EPI_FLYBACK, KS_EPI_SPLITODDEVEN */


  /* z phase encoding gradient for the 3D case (one zphase enc. per TR, not real 3D EPI) */
  if (KS_3D_SELECTED) { /* PSD_3D or PSD_3DM */
    ksepi.epitrain.zphaser.fov = opvthick;
    ksepi.epitrain.zphaser.res = IMax(2, 1, opslquant);
    ksepi.epitrain.zphaser.nover = IMin(2, ksepi_kznover, ksepi.epitrain.zphaser.res/2);
    ksepi.epitrain.zphaser.R = opaccel_sl_stride;
    ksepi.epitrain.zphaser.nacslines = ksepi_kz_nacslines;
  } else {
    ksepi.epitrain.zphaser.res = KS_NOTSET; /* ks_eval_epi will clear zphaser if res <= 1 */
  }

  /* EPI readout train */
  status = ks_eval_epi(&ksepi.epitrain, "epi", ksepi_epiqfact);
  KS_RAISE(status);

  /* echo time shifting */
  ks_init_wait(&ksepi.pre_delay);
  ks_init_wait(&ksepi.post_delay);

  if (ksepi_echotime_shifting == TRUE) {
    /*** Set up a pair of wait objects that are used to shift back the RF up to the echospacing ***/
    int epiesp = ksepi.epitrain.read.grad.duration + ksepi.epitrain.read_spacing;
    ksepi_echotime_shifting_shotdelay = (float) epiesp / (float) ksepi.epitrain.blipphaser.R;
    ksepi_echotime_shifting_sumdelay = RUP_GRD((int) (ksepi_echotime_shifting_shotdelay * (ksepi.epitrain.blipphaser.R-1))) + GRAD_UPDATE_TIME;
    status = ks_eval_wait(&ksepi.pre_delay,"ksepi_wait_pre", GRAD_UPDATE_TIME, ksepi_echotime_shifting_sumdelay);
    KS_RAISE(status);
    status = ks_eval_wait(&ksepi.post_delay,"ksepi_wait_post", ksepi_echotime_shifting_sumdelay - GRAD_UPDATE_TIME, ksepi_echotime_shifting_sumdelay);
    KS_RAISE(status);
  }

  if (ksepi_reflines > 0) {
    ksepi.dynreftrain = ksepi.epitrain;
    ksepi.dynreftrain.blipphaser.nover = 0;
    ksepi.dynreftrain.blipphaser.res = ksepi_reflines * ksepi.dynreftrain.blipphaser.R;

    ksepi.dynreftrain.zphaser.res = KS_NOTSET; /* disable zphaser for reflines */

    status = ks_eval_epi(&ksepi.dynreftrain, "epireflines", ks_qfact);
    KS_RAISE(status);

    ks_init_phaser(&ksepi.dynreftrain.blipphaser); /* disable blipphaser for reflines */ 
    ks_init_trap(&ksepi.dynreftrain.blip); /* disable blips for reflines */
  }
  else {
    ks_init_epi(&ksepi.dynreftrain);
  }

  /* Flow comp */
  ks_init_trap(&ksepi.fcompphase);
  ks_init_trap(&ksepi.fcompslice);

  if (opfcomp == TRUE) {

    if (ksepi_fcy) {
      /* Y: Need two extra phase gradients for flowcomp */
      status = ksepi_eval_flowcomp_phase(&ksepi.fcompphase, &ksepi.epitrain, "fcompphase");
      KS_RAISE(status);
    }
    if (ksepi_fcz) {
      /* Z: Add second z rephaser to complete 0th and 1st moment nulling of slice selection */
      ksepi.fcompslice.area = -ksepi.selrfexc.postgrad.area;
      status = ks_eval_trap(&ksepi.fcompslice, "fcompslice2");
      KS_RAISE(status);

      /* Z: Now, make normal z rephaser twice as large */
      ksepi.selrfexc.postgrad.area *= 2;
      status = ks_eval_trap(&ksepi.selrfexc.postgrad, "rfexc.reph_fc1");
      KS_RAISE(status);
    }

  } /* opfcomp */


  /* It is useful to be able to see the current echo spacing in DisplayCV to determine distortion levels etc */
  cvoverride(ksepi_esp, ksepi.epitrain.read.grad.duration + ksepi.epitrain.read_spacing, PSD_FIX_ON, PSD_EXIST_ON);

  /* for consistency, set opetl to the actual one for the EPI train even though ETL menu should never be visible for EPI */
  cvoverride(opetl, ksepi.epitrain.etl, PSD_FIX_ON, PSD_EXIST_ON);


  /* protect against too long sequence. It appears that opnecho * ksepi.epitrain.etl cannot be >= 1024 */
  if (ksepi.epitrain.etl * opnecho >= 1024) {
    return KS_THROW("# readouts >= 1024. Please reduce echoes, phase res. or increase NumShots");
  }

  /* post-read ksepi.spoiler */
  ksepi.spoiler.area = ksepi_spoilerarea;
  status = ks_eval_trap(&ksepi.spoiler, "spoiler");
  KS_RAISE(status);

  /* Diffusion */
  ksepi_eval_diffusion(&ksepi_diffctrl);
  status = ksepi_diffusion_eval_gradients_TE(&ksepi, &ksepi_diffctrl);
  KS_RAISE(status);

  /* init seqctrl */
  ks_init_seqcontrol(&ksepi.seqctrl);
  strcpy(ksepi.seqctrl.description, "ksepimain");

  /* Setup FLEET sequence (returns early if ksepi_fleet = FALSE) */
  status = ksepi_eval_setupfleet();
  KS_RAISE(status);

  return SUCCESS;

} /* ksepi_eval_setupobjects() */

ksepi_eval_TErange()

STATUS ksepi_eval_TErange

(

)

Sets the min TE based on the durations of the sequence objects in KSEPI_SEQUENCE (ksepi)

This function handles the TE range for SE-EPI, GE-EPI and DW-EPI (opdiffuse).

Multiple EPI trains (opnecho > 1) are supported Time between the EPI readouts is controlled using ksepi_echogap, yielding a ksepi_interechotime variable used in ksepi_pg().

N.B.: The minTE (avminte) and maxTE (avmaxte) ensures TE (opte) to be in the valid range for this pulse sequence to be set up in ksepi_pg(). If the pulse sequence changes are made in ksepi_pg(), by adding/modifying/removing sequence objects in a way that affects the intended TE, this function needs to be updated too.

Return values

STATUS

SUCCESS or FAILURE

                            {
  int selrfend, min90_180, min180_echo;

  /* RF center to RF end */
  selrfend = ksepi.selrfexc.rf.iso2end + KS_RFSSP_POSTTIME + ksepi.selrfexc.grad.ramptime;

  if (acq_type == TYPSPIN) {

    /* minimum TE: Spin-Echo EPI case (also diffusion) */

    /*** minimum time needed between RF exc center to RF ref center ***/

    /* RF center to rephaser end */
    min90_180 = selrfend + ksepi.selrfexc.postgrad.duration;
    if (ksepi_slicecheck == FALSE) { /* reflines dephaser may overlap with selrf rephaser unless slicecheck mode */
      min90_180 -= IMin(2, ksepi.dynreftrain.readphaser.duration, ksepi.selrfexc.postgrad.duration);
    }
    min90_180 += ksepi.dynreftrain.duration; /* end of reftrain */

    int diffusion_duration = 0;
    int i = 0;
    for (; i<3; ++i) {
      diffusion_duration = IMax(2, diffusion_duration, ksepi.diffgrads[i].duration);
    }

    if (opdiffuse) {
      min90_180 += diffusion_duration;
    } else if (ksepi_slicecheck == FALSE) {
      min90_180 -= IMin(2, ksepi.dynreftrain.readphaser.duration,
                           ksepi.selrfref.grad2rf_start); /* reflines rephaser and selrefrf dephaser may overlap */
    }
    min90_180 += KS_RFSSP_PRETIME + ksepi.selrfref.grad2rf_start + ksepi.selrfref.rf.start2iso;

    /*** minimum time needed between RF ref center and echo center ***/
    min180_echo = ksepi.selrfref.rf.iso2end + ksepi.selrfref.rf2grad_end + KS_RFSSP_POSTTIME;
    min180_echo += diffusion_duration; /* zero if not opdiffuse  */
    min180_echo += ksepi.epitrain.time2center;

    if (ksepi_echotime_shifting == TRUE) {
      min180_echo += GRAD_UPDATE_TIME;
    }

    /* minimum TE is 2x the biggest of the two */
    avminte = IMax(2, min90_180, min180_echo) * 2;

  } else { /* GE-EPI */

    avminte = selrfend;

    if (ksepi_reflines > 0) {
      /* transports between selrf and reflines readout: */
      if (ksepi_slicecheck) {
        avminte += ksepi.selrfexc.postgrad.duration + ksepi.fcompslice.duration + ksepi.dynreftrain.readphaser.duration; /* Z */
      } else {
        avminte += IMax(2, ksepi.dynreftrain.readphaser.duration, /* X */
                           ksepi.selrfexc.postgrad.duration + ksepi.fcompslice.duration) /* Z */;
      }
      /* reflines readout: */
      avminte += ksepi.dynreftrain.duration - 2 * ksepi.dynreftrain.readphaser.duration;
      /* transports between reflines readout and main epi readout: */
      avminte += IMax(3, ksepi.dynreftrain.readphaser.duration + ksepi.epitrain.readphaser.duration, /* X */
                         2 * ksepi.fcompphase.duration + ksepi.epitrain.blipphaser.grad.duration, /* Y */
                         ksepi.epitrain.zphaser.grad.duration) /* Z */;
    } else { /* no reflines */
      /* transports between selrf and main epi readout: */
      if (ksepi_slicecheck) {
        avminte += IMax(3, ksepi.epitrain.zphaser.grad.duration, /* X */
                         2 * ksepi.fcompphase.duration + ksepi.epitrain.blipphaser.grad.duration, /* Y */
                         ksepi.selrfexc.postgrad.duration + ksepi.fcompslice.duration + ksepi.epitrain.readphaser.duration) /* Z */;
      } else {
        avminte += IMax(3, ksepi.epitrain.readphaser.duration, /* X */
                         2 * ksepi.fcompphase.duration + ksepi.epitrain.blipphaser.grad.duration, /* Y */
                         ksepi.selrfexc.postgrad.duration + ksepi.fcompslice.duration + ksepi.epitrain.zphaser.grad.duration) /* Z */;
      }
    }

    /* start of EPI readout */
    avminte -= IMax(3, ksepi.epitrain.readphaser.duration, /* X */
                       ksepi.epitrain.blipphaser.grad.duration, /* Y */
                       ksepi.epitrain.zphaser.grad.duration) /* Z */;
    /* start of EPI train */
    avminte += ksepi.epitrain.time2center; /* minimum TE ! */

    if (ksepi_echotime_shifting == TRUE) {
      avminte += GRAD_UPDATE_TIME;
    }
  }

  avminte += GRAD_UPDATE_TIME * 2; /* 8us extra margin */
  avminte = RUP_FACTOR(avminte, 8); /* round up to make time divisible by 8us */

  avmaxte = avminte; /* initialization only to avoid avmaxte = 0 */

  /* time offset between two EPI trains (up to 16 echoes = EPI trains) */
  ksepi_interechotime = ksepi.epitrain.duration + ksepi_echogap + (acq_type == TYPSPIN) * (KS_RFSSP_PRETIME + ksepi.selrfref.pregrad.duration + ksepi.selrfref.grad.duration + ksepi.selrfref.postgrad.duration + KS_RFSSP_POSTTIME);


  /* maximum TE */
  if (existcv(optr)) {
    if (opautotr) {
      /* TR = minTR, i.e. the current TE is also the maximum TE */
      if (opautote)
        avmaxte = avminte;
      else if (existcv(opte))
        avmaxte = opte;
      else
        avmaxte = avminte;
    } else {
      /* maximum TE dependent on the chosen TR */
      avmaxte = optr - ksepi.seqctrl.ssi_time; /* maximum sequence duration for this TR (implies one slice per TR) */
      avmaxte -= ksepi.spoiler.duration; /* subtract ksepi.spoiler time */
      avmaxte -= ksepi.epitrain.duration - ksepi.epitrain.time2center;
      if (opnecho > 1) {
        avmaxte -= (opnecho - 1) * ksepi_interechotime; /* for multi-echo */
      }
    }
  } else {
    avmaxte = 1s;
  }

  if (opnecho == 2) {
    /* for opnecho == 2, the TE2 button appears although we have greyed it out (pite2nub = 0).
       Make avminte2/opte2 contain the actual number */
    avminte2 = avminte + ksepi_interechotime;
    avmaxte2 = avmaxte + ksepi_interechotime;
    opte2 = opte       + ksepi_interechotime;
  }

  if (opautote) {
    setpopup(opte, PSD_OFF);
    cvoverride(opte, avminte, PSD_FIX_ON, PSD_EXIST_ON); /* AutoTE: force TE to minimum */
  } else if (existcv(opte)) {
    setpopup(opte, PSD_ON);
    if (opte < avminte)
      return KS_THROW("TE=%.1f too small. Please increase TE to %.1f", opte / 1000.0, avminte / 1000.0);
    if (opte > avmaxte)
      return KS_THROW("TE=%.1f too large. Please decrease to %.1f", opte / 1000.0, avmaxte / 1000.0);
  } else {
    /* default value might be too low */
    opte = avminte;
  }

  return SUCCESS;

} /* ksepi_eval_TErange() */

ksepi_set_kspace_design_forsat()

void ksepi_set_kspace_design_forsat

(

KS_KSPACE_DESIGN *

kdesign

)

Set the k-space design for use in the ksepi_eval_sat() function

ksepi_eval_sat()->kssat_setup_from_UI() (see ksmodules/kssat.e) needs a KS_KSPACE_DESIGN to get the FOV borders, why such struct is setup here. Ideally, this KS_KSPACE_DESIGN should also set up the proper fields of .epitrain field for the main sequence (ksepi), but this is for now still set up manually in ksepi_eval_setupobjects().

Note that all design structs are short-lived and are set up as a receipe for other structures to be used in pulsegen and scan

Parameters

[out]

kdesign

KS_KSPACE_DESIGN

Returns

void

                                                               {

  /* k-space design */  
  kdesign->res[XGRAD] = RUP_FACTOR(opxres, 2);
  kdesign->res[YGRAD] = RUP_FACTOR((int) (opyres * opphasefov), 2);

  kdesign->fov[XGRAD] = opfov;
  kdesign->fov[YGRAD] = opfov * opphasefov; 

  kdesign->R[YGRAD] = (opdiffuse || opnshots == 1) ? opaccel_ph_stride : opnshots; /* Number of shots to fully sample the desired part of k-space. opnshots hidden for diffusion */
  kdesign->R_epi_ky = opaccel_ph_stride; /* undersampling in ky. R[YGRAD] must be equal to R_epi_ky for diffusion */

  kdesign->rbw = oprbw;
  kdesign->override_R1 = 0; /* If non-zero, override the analog receive gain with this value */

  kdesign->nover[YGRAD] = (opautote == PSD_MINTE) ? ksepi_kynover : 0; /* partial Fourier in ky */
  kdesign->nover[ZGRAD] = 0; /* always full Fourier in kz */

  if (KS_3D_SELECTED) {
    kdesign->res[ZGRAD] = opslquant;
    kdesign->fov[ZGRAD] = opslthick * kdesign->res[ZGRAD]; /* round zFOV to exactly match .res */
    kdesign->R[ZGRAD] = opaccel_sl_stride;
  }

  /* rampsampling on for ART (opsilent) */
  kdesign->rampsampling = (opsilent) ? TRUE : FALSE;

} /* ksepi_set_kspace_design_forsat() */

ksepi_set_slicetiming_design()

void ksepi_set_slicetiming_design

(

KS_SLICETIMING_DESIGN *

slicetiming_design

)

Set up the number of slices, TR range, and min num acquisitions in KS_SLICETIMING_DESIGN

This function is called from ksepi_eval_loops()->ksepi_set_loop_control_design() to produce a KSSCAN_LOOP_CONTROL_DESIGN, which contains this KS_SLICETIMING_DESIGN struct steering how the final KS_SLICETIMING struct will be set up by ksscan_slicetiming_eval_design(), taking a KS_SLICETIMING_DESIGN as input

Note that all design structs are short-lived and are set up as a receipe for other structures to be used in pulsegen and scan

Parameters

[out]

slicetiming_design

KS_SLICETIMING_DESIGN to be created

Returns

void

                                                                             {

  /* interleaved slices in slice gap menu, force 2+ acqs */
  int minacqs = (opileave) ? 2 : 1;

  if (opslspace < 0) { /* Because we use overlap (pi_neg_sp) */
    minacqs = IMax(2, minacqs, ceil(opslthick / (opslthick - fabs(opslspace))));
  }

  slicetiming_design->is3D = KS_3D_SELECTED;
  slicetiming_design->nslices = opslquant;
  ksscan_copy_slices(slicetiming_design, ks_scan_info);

  slicetiming_design->minacqs = minacqs;
  if (opautotr) {
    slicetiming_design->minTR = 0;
    slicetiming_design->maxTR = 0;
  } else {
    slicetiming_design->minTR = optr;
    slicetiming_design->maxTR = optr;
  }

} /* ksepi_set_slicetiming_design() */

ksepi_set_inversion_loop_control_design()

STATUS ksepi_set_inversion_loop_control_design	(	KSINV_LOOP_CONTROL_DESIGN *	invloopctrl_design,
		const KS_EPI *	epitrain
	)

Setup of a KSINV_LOOP_CONTROL_DESIGN with inversion related parameters

This function creates a KSSCAN_LOOP_CONTROL_DESIGN struct, which contains the same KSSCAN_LOOP_CONTROL_DESIGN struct as ksepi_set_loop_control_design() in its .loopctrl_design field. This by calling ksepi_set_loop_control_design(&invloopctrl_design->loopctrl_design, epitrain) here.

In addition, inversion-recovery-related design info is set up in this function, including the type of inversion mode depending on the UI CVs opirprep, opt1flair, opt2flair.

The desired inversion timing is controlled by either the inversion time (TI) xor the T1 value of the tissue

• .T1value = ksepi_t1value_to_null, if the UI CV opautoti is TRUE (makes the final TI change automatically with TR)
• .TI = opti if the UI CV opautoti is FALSE (makes a fixed TI value set by the user)

Note that all design structs are short-lived and are set up as a receipe for other structures to be used in pulsegen and scan

Parameters

[out]	invloopctrl_design	KSINV_LOOP_CONTROL_DESIGN to be created
[in]	epitrain	KS_EPI struct with .blipphaser and .zphaser fields steering the set of k-space coordinates to reach

Return values

STATUS

SUCCESS or FAILURE

                                                                                                                      {

  if (!ANYINVERSION) {
    invloopctrl_design->irmode = KSINV_OFF;
    return SUCCESS;
  }

  if (exist(opautotr) == 0 && existcv(optr)) {
    return KS_THROW("MinimumTR (Auto) must be selected for FLAIR");
  }

  if ((opirprep + opt1flair + opt2flair) > 1) {
    return KS_THROW("Mutually exclusive opirprep/opt1flair/opt2flair");
  }

  STATUS s = ksepi_set_loop_control_design(&invloopctrl_design->loopctrl_design, epitrain);
  KS_RAISE(s);

  invloopctrl_design->irmode = KSINV_OFF;
  ksepi_t1value_to_null = (cffield == 30000) ? T1_CSF_3T : T1_CSF_1_5T; /* default value */

  if (opirprep) { /* IR prep */
    ksepi_t1value_to_null = (cffield == 30000) ? T1_FAT_3T : T1_FAT_1_5T; /* default value */
    invloopctrl_design->dosliceahead = 1; /* TODO */
    invloopctrl_design->irmode = KSINV_ON_INTERLEAVED;  
  }
  if (opt1flair) { /* interleaved IR */
    invloopctrl_design->dosliceahead = 1;
    invloopctrl_design->irmode = KSINV_ON_INTERLEAVED;  
    invloopctrl_design->loopctrl_design.slicetiming_design.minTR = KSINV_MINTR_T1FLAIR;
    invloopctrl_design->loopctrl_design.slicetiming_design.minTR = KSINV_MAXTR_T1FLAIR;
  }
  if (opt2flair) { /* FLAIR block */
    invloopctrl_design->irmode = KSINV_ON_FLAIR_BLOCK;
    invloopctrl_design->loopctrl_design.slicetiming_design.minTR = KSINV_MINTR_T2FLAIR;
  }

  if (opautoti) { /* use either TI or T1value (XOR). Must set the non-used one to KS_NOTSET */
    invloopctrl_design->TI = KS_NOTSET;
    invloopctrl_design->T1value = ksepi_t1value_to_null;
  } else {
    invloopctrl_design->TI = opti;
    invloopctrl_design->T1value = KS_NOTSET;
  }

  return SUCCESS;

} /* ksepi_set_inversion_loop_control_design() */

ksepi_eval_inversion()

STATUS ksepi_eval_inversion

(

KS_SEQ_COLLECTION *

seqcollection

)

Setup and evaluation of KSINV_DESIGN and the creation of a KSINV_MODULE module for inversion recovery

Note that all design structs are short-lived and are set up as a receipe for other structures to be used in pulsegen and scan. Here, the KSINV_DESIGN has local scope and is setup and used only by this function. What remains is the KSINV_MODULE ksepi_inv module, declaread in .

The KS_SEQ_COLLECTION is passed as a pointer to the function, to let the KSINV_MODULE to be registered in the collection for RF scaling, and heating calculations.

Parameters

[in,out]

seqcollection

Pointer to the KS_SEQ_COLLECTION struct holding all sequence modules

Return values

STATUS

SUCCESS or FAILURE

                                                              {

  STATUS status;

  KSINV_DESIGN inv_design = KSINV_INIT_DESIGN;

  ksinv_init_design(&inv_design, "inv"); /* e.g. STIR */
  if (opt1flair) {
    ksinv_init_design(&inv_design, "t1flair");
  }
  if (opt2flair) {
    ksinv_init_design(&inv_design, "t2flair");    
  }

  inv_design.invdesign.slthick = opslthick;
  inv_design.invdesign.flip = 180.0;
  inv_design.invdesign.rfpulse_choice = INV_ADIABATIC; /* TODO */
  inv_design.spoiler_area = ksepi_spoilerarea;
  inv_design.gscale_policy = KSINV_GSCALE_NONOVERLAP; /* TODO */
  inv_design.slice_gap = opslspace;
  inv_design.ssi_time = ksepi_ssi_time;

  const int minacqs = (opileave) ? 2 : 1;
  status = ksinv_eval_design(&ksepi_inv, &inv_design, minacqs, seqcollection);
  KS_RAISE(status);

  return SUCCESS;

} /* ksepi_eval_inversion() */

ksepi_eval_sat()

STATUS ksepi_eval_sat

(

KS_SEQ_COLLECTION *

seqcollection

)

Set up of the KSSAT_MODULE kssat for graphical saturation in the UI

As there can only be one global graphical saturation module that interacts with the UI, this function uses the global kssat struct (KSSAT_MODULE) in kssat.e, which is at the top of ksepi.e

seqcollection is passed as a pointer to the function, to register the KSSAT_MODULE in the collection for later RF scaling, and heating calculations.

Both design structs have local scope, and via ksepi_set_slicetiming_design(), the slice location info is used to control the location of the sat bands in kssat_setup_from_UI()

Parameters

[in,out]

seqcollection

Pointer to the KS_SEQ_COLLECTION struct holding all sequence modules

Return values

STATUS

SUCCESS or FAILURE

                                                        {

  STATUS status;

  KS_KSPACE_DESIGN kdesign = KS_INIT_KSPACE_2D_DESIGN;
  ksepi_set_kspace_design_forsat(&kdesign);

  KS_SLICETIMING_DESIGN slicetiming_design = KS_INIT_SLICETIMING_DESIGN;
  ksepi_set_slicetiming_design(&slicetiming_design);

  status = kssat_setup_from_UI(&kssat,
                               &kdesign,
                               &slicetiming_design,
                               opslthick,
                               seqcollection);
  KS_RAISE(status);

  return SUCCESS;

} /* ksepi_eval_sat() */

ksepi_gradheat_play()

STATUS ksepi_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 a set of sequence modules that collectively makes a test sequence that attempts to be a good approximation of the average and maxmimum power dissipation of the gradient system. This function is not used for any data collection.

This function first plays the saturation sequence (if kssat.seqctrl.duration > 0), then the inversion sequence (if any), then, if diffusion, scaled versions of the diffusion gradients are played (either .RMS_amp_scale or .max_power_amp_scale), with the main sequence based on the max_encode_mode.

It should be noted that the content of this function is manual work and needs to be updated if the content of ksepi_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.

This function 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.

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

Parameters

	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;

  int j;

  /* Sat */
  ks_scan_playsequence(&kssat.seqctrl);

  /* Inversion */
  if (ANYINVERSION) {
    ks_scan_playsequence(&ksepi_inv.seqctrl);
  }

  /* main */
  if (max_encode_mode == AVERAGE_POWER) {

    ks_scan_phaser_average(&ksepi.epitrain.blipphaser, INSTRALL);
    ks_scan_phaser_average(&ksepi.epitrain.zphaser, INSTRALL);

    /* RMS over all diffusion directions for each board */
    for (j = 0; j < 3; ++j) {
      ks_scan_trap_ampscale(&ksepi.diffgrads[j], INSTRALL, ksepi_diffctrl.RMS_amp_scale[j]);
    }
  } else { /* MAXIMUM_POWER */

    ks_scan_phaser_max(&ksepi.epitrain.blipphaser, INSTRALL);
    ks_scan_phaser_max(&ksepi.epitrain.zphaser, INSTRALL);

    /* X diffusion direction is usually the worst case */
    for (j = 0; j < 3; ++j) {
      ks_scan_trap_ampscale(&ksepi.diffgrads[j], INSTRALL, ksepi_diffctrl.max_power_amp_scale[j]);
    }
  }
  ks_scan_playsequence(&ksepi.seqctrl);

  return SUCCESS;

} /* ksepi_gradheat_play() */

ksepi_eval_loops()

STATUS ksepi_eval_loops

(

KS_SEQ_COLLECTION *

seqcollection

)

Setup of scan loop control structs (main and FLEET sequences) after heating calculations

This function performs the following tasks:

• Evaluates the SAR and gradient heating using ks_eval_hwlimits(...,ksepi_gradheat_play(),...) and returns newtime
• Increases the main sequence duration (ksepi.seqctrl.duration) if the newtime > time using ks_eval_seqctrl_setduration()
• Sets up
  • fleet_loopctrl_design, which is used together with the FLEET coreslice function (ksepi_scan_fleet_coreslice())
  • ksepi_fleet_loopctrl in ksscan_loop_control_eval_design() to control the scan loop for the FLEET sequence
  • loopctrl_design (for main sequence), which is used together with the coreslice function (ksepi_scan_coreslicegroup())
  • ksepi_loopctrl in ksscan_loop_control_eval_design() to control the scan loop for the main sequence
• If inversion is used, inv_loopctrl_design is used to create ksepi_inv_loopctrl, which controls the scan loop instead of ksepi_loopctrl when inversion is on.

Note that all design structs are short-lived and are set up as a receipe for other structures to be used in pulsegen and scan. Here this applies to the local variables fleet_loopctrl_design, loopctrl_design, and inv_loopctrl_design.

Parameters

[in,out]

seqcollection

Pointer to the KS_SEQ_COLLECTION struct holding all sequence modules

Return values

STATUS

SUCCESS or FAILURE

                                                          {

  STATUS status;

  /* SAR and gradient heating */
  const int time = ks_eval_getduration(seqcollection, ksepi_gradheat_play, 0, NULL);

  int newtime = 0;
  status = ks_eval_hwlimits(&newtime, seqcollection, &loggrd, ksepi_gradheat_play, 0, NULL);
  KS_RAISE(status);

  if (newtime > time) {
    ks_dbg("gradheat time: %d -> %d", time, newtime);
    ks_eval_seqctrl_setduration(&ksepi.seqctrl, ksepi.seqctrl.duration + newtime - time);
  }

  /* FLEET loop control */
  KSSCAN_LOOP_CONTROL_DESIGN fleet_loopctrl_design = KSSCAN_INIT_LOOP_CONTROL_DESIGN;
  /* ksepi_set_loop_control_design() as for main, but override some fields in the next few lines */
  status = ksepi_set_loop_control_design(&fleet_loopctrl_design, &ksepi_fleetseq.epitrain);
  KS_RAISE(status);
  fleet_loopctrl_design.dda = IMax(2, 1, ksepi_fleet_dda); /* safety net to ensure at least one dummy for FLEET (for Nyquist ghost correction in recon_ksepi2.m) */
  fleet_loopctrl_design.naverages = 1;
  fleet_loopctrl_design.nvols = 1;
  fleet_loopctrl_design.slicetiming_design.minacqs = fleet_loopctrl_design.slicetiming_design.nslices; /* Sequential */
  fleet_loopctrl_design.slicetiming_design.minTR = 0;
  fleet_loopctrl_design.slicetiming_design.maxTR = 0; 

  status = ksscan_loop_control_eval_design(&ksepi_fleet_loopctrl,
                                          &ksepi_fleetseq.seqctrl,
                                          &ksepi_scan_fleet_coreslice, 
                                          &fleet_loopctrl_design);
  KS_RAISE(status);


  /* Main or Inversion loop control */
  if (!ANYINVERSION) {
    KSSCAN_LOOP_CONTROL_DESIGN loopctrl_design = KSSCAN_INIT_LOOP_CONTROL_DESIGN;
    status = ksepi_set_loop_control_design(&loopctrl_design, &ksepi.epitrain);
    KS_RAISE(status);

    status = ksscan_loop_control_eval_design(&ksepi_loopctrl,
                                             &ksepi.seqctrl,
                                             ksepi_scan_coreslicegroup, 
                                             &loopctrl_design);
    KS_RAISE(status);
  } else {
    KSINV_LOOP_CONTROL_DESIGN inv_loopctrl_design = KSINV_INIT_LOOP_CONTROL_DESIGN;
    ksepi_set_inversion_loop_control_design(&inv_loopctrl_design, &ksepi.epitrain);

    status = ksinv_loop_control_eval_design(&ksepi_inv_loopctrl,
                                            ksepi_scan_irslice, &ksepi_inv.seqctrl,
                                            ksepi_scan_coreslicegroup, &ksepi.seqctrl,
                                            &inv_loopctrl_design,
                                            seqcollection);
    KS_RAISE(status);
  }

  /* Fill in the 'tmin' and 'tmin_total'. tmin_total is only like GEs use of the variable when TR = minTR */
  tmin = ksepi.seqctrl.min_duration;
  tmin_total = ksepi.seqctrl.duration;

  return SUCCESS;

} /* ksepi_eval_loops() */

ksepi_eval_ssitime()

int ksepi_eval_ssitime

(

)

The SSI time for the sequence

Returns

int SSI time in [us]

                         {

  /* SSI time CV:
     Empirical finding on how much SSI time we need to update.
     But, use a longer SSI time when we write out data to file in scan() */
  ksepi_ssi_time = RUP_GRD(IMax(2, 
                          ks_syslimits_hasICEhardware() ? KSEPI_DEFAULT_SSI_TIME_ICEHARDWARE : KSEPI_DEFAULT_SSI_TIME, 
                          _ksepi_ssi_time.minval));

  /* Copy SSI CV to seqctrl field used by setssitime() */
  ksepi.seqctrl.ssi_time = RUP_GRD(ksepi_ssi_time);
  ksepi_fleetseq.seqctrl.ssi_time = RUP_GRD(ksepi_ssi_time);

  /* SSI time one-sequence-off workaround:
     We set the hardware ssitime in ks_scan_playsequence(), but it acts on the next sequence module, hence
     we aren't doing this correctly when using multiple sequence modules (as KSChemSat etc).
     One option would be to add a short dummy sequence ks_scan_playsequence(), but need to investigate
     if there is a better way. For now, let's assume the the necessary update time is the longest for
     the main sequence (this function), and let the ssi time for all other sequence modules (KSChemSat etc)
     have the same ssi time as the main sequence. */
  kssat_ssi_time    = ksepi_ssi_time;

  return ksepi_ssi_time;

} /* ksepi_eval_ssitime() */

ksepi_eval_scantime()

STATUS ksepi_eval_scantime

(

KS_SEQ_COLLECTION *

seqcollection

)

Sets the scan time and SAR values in the UI and checks that the sequence is within hardware limits

pitscan is the UI variable for the scan clock shown in the top right corner on the MR scanner. The call to GEReq_eval_checkTR_SAR_calcs() also sets up the UI SAR annotation.

Return values

STATUS

SUCCESS or FAILURE

                                                             {

  STATUS status;

  /* Step 1: set all `seqctrl.nseqinstances` to 0 */
  ks_eval_seqcollection_resetninst(seqcollection);

  /* Step 2: run the scan loop to get total scan time */
  n64 scantime = ksepi_scan_scanloop();

  /* Step 3: Check that the entire sequence (across all sequence modules) is within SAR & hardware limits.
     Also sets up UI SAR annotation */
  status = GEReq_eval_checkTR_SAR_calcs(seqcollection, scantime);
  KS_RAISE(status);

  pitscan = (float) scantime; /* Scan time clock in UI */

  return SUCCESS;

} /* ksepi_eval_scantime() */

ksepi_update_UI()

STATUS ksepi_update_UI

(

)

Update variables for the UI and checks for out of bounds values

This function is called from cvcheck() to update the UI variables based largely on ksepi and ksepi_loopctrl after checks for some out-of-bounds values.

Return values

STATUS

SUCCESS or FAILURE

                         {

  /* Force the user to select the Echo Planar Imaging button. This error needs to be in cvcheck(), not in
     cvinit()/cveval() to avoid it to trigger also when Echo Planar Imaging has been selected.
     Without opepi = 1, the images won't show up correctly in the GE DB after the 1st volume */

  if (!KS_3D_SELECTED && opepi == PSD_OFF) {
    return KS_THROW("Please first select the 'Echo Planar Imaging' button");
  }

  if (existcv(opte) && existcv(opnex) && opautote == PSD_MINTE && opnex < 1.0) {
    return KS_THROW("TE = MinTE and NEX < 1 is not allowed");
  }

  if (ksepi_reflines > ksepi.epitrain.etl) {
    return KS_THROW("ksepi_reflines cannot be larger than echo train length");
  }

  if (existcv(opnshots) && (opasset == ASSET_SCAN) && (opnshots > 1)) {
    return KS_THROW("ASSET not compatible with multishot");
  }

  if (opasset != 0 && opasset != ASSET_SCAN) {
    return KS_THROW("ASSET flag must be either 0 (OFF) or 2 (ON)");
  }

  if (opdiffuse && oppseq == 2) {
    return KS_THROW("Select SpinEcho for Diffusion");
  }


  const KSSCAN_LOOP_CONTROL *loopctrl = ksepi_get_loop_ctrl();

  _optr.minval = 0;
  _optr.maxval = 60s;
  if (opautotr) {
    avmintr = loopctrl->slicetiming.TR;
    avmaxtr = loopctrl->slicetiming.TR;
  } else {
    avmintr = _optr.minval;
    avmaxtr = _optr.maxval;
  }
  (optr) = loopctrl->slicetiming.TR; /* ()-parentheses avoids fixedflag expansion */
  act_tr = loopctrl->slicetiming.TR;
  ihtr = optr; /* image header TR */

  /* show max slices/TR and # acqusitions */
  (avmaxslquant) = loopctrl->slicetiming.maxslices_per_TR;
  (avmaxacqs) = loopctrl->slicetiming.slice_plan.npasses;


  /* Pixel size in UI */
  piinplaneres = 1;
  ihinplanexres = opfov / ksepi.epitrain.read.res;
  ihinplaneyres = (opfov * opphasefov) / ksepi.epitrain.blipphaser.res;

  /* show echo spacing in UI */
  piesp = 1;
  ihesp = ksepi.epitrain.read.grad.duration / 1000.0;

  return SUCCESS;

} /* ksepi_update_UI() */

ksepi_predownload_plot()

STATUS ksepi_predownload_plot

(

KS_SEQ_COLLECTION *

seqcollection

)

Plotting of sequence modules and slice timing in HTML files

If a file /usr/g/research/bin/ksdonotplot exists, this function will return SUCCESS without plotting. This is a system-wide way of quickly disabling plotting for all sequences.

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 and FLEET sequence diagrams as HTML files, and lastly the sequence timing plot, showing slice location on the y-axis and time on the x-axis for all sequence modules at the same time.

The HTML plots will have a slider to show the dynamics of a psd. What is interesting to show dynamics for can vary between psds. If diffusion is on, only the diffusion scheme index should be changed by the slider, otherwise the shot index should be changed. To do this, this function must play the relevant changes that should be presented in the HTML plot slider and skip non-relevant changes such as change in slice location. One can think of this as recording something in a video, where only the relevant parts are recorded.

"Recording" is first reset by ks_eval_seqcollection_resetninst(). Then, for diffsion, a call to ksdiff_plotloop() is made to play a single slice and shot index for many diffusion scheme indices. For non-diffusion, the generic ksscan_plotloop_shots() is used to play a single slice for many shot indices.

Note that ksscan_plotloop_shots() internally copies the loop_control struct (arg 2) and overrides the number of slices in order to play a single slice.

Lastly, ks_plot_psd() is called to write out a JSON file, followed by a system call to the python script psdplot/psdplot.py to create the HTML plots. The HTML files can take 10-20 s to generate, so be patient.

The FLEET sequence is recorded using ksscan_plotloop_shots(), to show shot-to-shot variations with the HTML plot slider.

For the slicetiming plot, the three functions ks_plot_slicetime_begin();ksepi_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];

  /* System wide (psd independent) option to disable plotting, to e.g. speed up UX on a slow MR show system */
  if (existfile("/usr/g/research/bin/ksdonotplot")) {
    return SUCCESS;
  }


#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 ksepi_objects.txt instead */
  ks_print_selrf(ksepi.selrfexc, fp);
  ks_print_selrf(ksepi.selrfref, fp);
  int i = 0;
  for (; i<3; ++i) {
    ks_print_trap(ksepi.diffgrads[i], fp); /* opdiffuse = 1 */
  }
  ks_print_epi(ksepi.epitrain, fp);
  ks_print_epi(ksepi.dynreftrain, fp);
  ks_print_trap(ksepi.spoiler, fp);
  fclose(fp);


  ks_eval_seqcollection_resetninst(seqcollection);

  /* MAIN */
  if (opdiffuse) {
    ksdiff_schemeloop(&ksepi_diffctrl, ksepi_get_loop_ctrl(), NULL, ksepi_scan_coreslicegroup); /* HTML plot slider will change the diffusion scheme index */
    ksdiff_plotloop(&ksepi_diffctrl, ksepi_scan_coreslicegroup, NULL);
  } else {
    ksscan_plotloop_shots(ksepi_get_loop_ctrl(), ksepi_scan_coreslicegroup); /* HTML plot slider will change the shot index */
  }
  ks_plot_psd(&ksepi.seqctrl, ksepi_get_loop_ctrl());

  /* FLEET */
  ksscan_plotloop_shots(&ksepi_fleet_loopctrl, ksepi_scan_fleet_coreslice);
  ks_plot_psd(&ksepi_fleetseq.seqctrl, &ksepi_fleet_loopctrl);

  /* Saturation */
  ks_plot_host_seqctrl(&kssat.seqctrl, NULL);
  
  /* Sequence timing plot */
  ks_plot_slicetime_begin();
  ksepi_scan_scanloop();
  ks_plot_slicetime_end();

  return SUCCESS;

} /* ksepi_predownload_plot() */

ksepi_predownload_setrecon()

STATUS ksepi_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 ksepi.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. This function is called last in predownload()

The rhuser variables here are needed for the Matlab recon recon_ksepi2.m to work, so they should not be changed. Setting rhileaves here to 1, also for multi-shot EPI, is critical to make Nyquist ghost correction work in recon for multi-shot EPI.

The rhrecon is set to 961 to call /usr/g/bin/recon961 on the scanner, which is present when this PSD is bundled with a compiled version of the matlab recon has been installed from an RPM. rhrecon may be changed to any other number to call another recon script, possibly one that just copies the scan archive off the scanner, or compiled variants of the recon_ksepi2.m script for VRE recons.

Return values

STATUS

SUCCESS or FAILURE

                                    {

  /* These rhusers are read by epi2/recon_ksepi2.m
     epi/recon_epi.m cannot reconstruct this PSD */
  
  rhuser23 = (ksepi_reflines > 0) ? (float) (ksepi.dynreftrain.read.acq.pos[0] - ksepi.seqctrl.momentstart) : 0.0;
  rhuser25 = (ksepi_reflines > 0) ? (float) (ksepi.epitrain.read.acq.pos[0] - ksepi.seqctrl.momentstart - ksepi.pre_delay.pg_duration) : 0.0;


  /* FLEET */
  rhuser28 = (float) ksepi_fleetseq.epitrain.read.res; /* store num kx lines for FLEET */
  rhuser36 = (float) (ksepi_fleetseq.epitrain.read.grad.plateautime / 2) / 1.0e6; /* halfplateau time for FLEET [s] */
  rhuser37 = (float) (ksepi_fleetseq.epitrain.read.grad.ramptime)/ 1.0e6; /* attack/decay time for FLEET [s] */
  rhuser39 = (float) ksepi_fleetseq.epitrain.read.acq.filt.tsp; /* time between sample points [often 2us] */

  /* MAIN */
  rhuser31 = (float) ksepi.epitrain.R_ky; /* store for custom recon to know */

  /* GERequired.e uses: rhuser32-25 (VRGF) and rhuser48 (scantime) */
  rhuser45 = 1; /* flag for recon to indicate the existence of metadata.readpolarity (will be discontinued, and use .version instead) */;

  ihtr = optr;
  GEReq_predownload_setrecon_annotations_epi(&ksepi.epitrain, 0);

  /* This is only important for the recon header, we don't zerofill the ref lines and set it to one */
  cvoverride(rhileaves, 1, PSD_FIX_ON, PSD_EXIST_ON);

  rhrecon = 961; /* VRE recon using Matlab recon (recon_epi.m). See matlab/deploy/rpmbuild on how to make an RPM */

  return SUCCESS;

} /* ksepi_predownload_setrecon() */

ksepi_pg_fleet()

STATUS ksepi_pg_fleet

(

int

start_time

)

The FLEET pulse sequence generation

This is the FLEET pulse sequence in ksepi.e using the sequence objects in KSEPI_FLEET_SEQUENCE with the sequence module name "ksepifleet" (= ksepi_fleet.seqctrl.description). The FLEET sequence module is needed for GRAPPA calibration in the recon (recon_ksepi2.m) for 2D scans

Return values

STATUS

SUCCESS or FAILURE

                                      {

  STATUS status;
  KS_SEQLOC tmploc = KS_INIT_SEQLOC;

  if (ksepi_fleet == FALSE) {
    return SUCCESS;
  }

  if (start_time < KS_RFSSP_PRETIME) {
    return KS_THROW("1st arg (pos start) must be at least %d us", KS_RFSSP_PRETIME);
  }

  /*******************************************************************************************************
   *  RF Excitation
   *******************************************************************************************************/
  tmploc.ampscale = 1.0;
  tmploc.pos = RUP_GRD(start_time + KS_RFSSP_PRETIME);
  tmploc.board = ZGRAD;

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

  tmploc.pos = ksepi_fleetseq.seqctrl.momentstart;
  tmploc.pos += KS_RFSSP_POSTTIME + ksepi_fleetseq.selrfexc.rf.iso2end + ksepi_fleetseq.selrfexc.grad.ramptime + ksepi_fleetseq.selrfexc.postgrad.duration;

  /*******************************************************************************************************
  *  EPI echo time shifting
  *******************************************************************************************************/
  if (ksepi_echotime_shifting_fleet == TRUE) {
    tmploc.board = KS_ALL;
    status = ks_pg_wait(&ksepi_fleetseq.pre_delay, tmploc, &ksepi_fleetseq.seqctrl);
    KS_RAISE(status);
    tmploc.pos += GRAD_UPDATE_TIME;
  }

  /*******************************************************************************************************
  *  EPI readout including de/rephasers on freq and phase encoding axes (net zero moment on both axes)
  *******************************************************************************************************/

  if (ksepi_slicecheck)
    tmploc.board = KS_FREQZ_PHASEY;
  else
    tmploc.board = KS_FREQX_PHASEY;
  tmploc.ampscale = ksepi_readsign;
  status = ks_pg_epi(&ksepi_fleetseq.epitrain, tmploc, &ksepi_fleetseq.seqctrl);
  KS_RAISE(status);
  tmploc.pos += ksepi_fleetseq.epitrain.duration; /* end of EPI (incl. x/y rephasers, but not zphaser) */

  /*******************************************************************************************************
   *  Gradient spoilers on Y and Z (at the same time)
   *******************************************************************************************************/
  tmploc.ampscale = 1.0;

  tmploc.board = YGRAD;
  status = ks_pg_trap(&ksepi_fleetseq.spoiler, tmploc, &ksepi_fleetseq.seqctrl);
  KS_RAISE(status);
  tmploc.board = ZGRAD;
  status = ks_pg_trap(&ksepi_fleetseq.spoiler, tmploc, &ksepi_fleetseq.seqctrl);
  KS_RAISE(status);

  tmploc.pos += ksepi_fleetseq.spoiler.duration;

  /*******************************************************************************************************
  *  EPI echo time shifting
  *******************************************************************************************************/
  if (ksepi_echotime_shifting_fleet == TRUE) {
    tmploc.pos += GRAD_UPDATE_TIME;
    tmploc.board = KS_ALL;
    status = ks_pg_wait(&ksepi_fleetseq.post_delay, tmploc, &ksepi.seqctrl);
    KS_RAISE(status);
    tmploc.pos += IMax(2, psd_grd_wait, psd_rf_wait) + GRAD_UPDATE_TIME;
    tmploc.pos += ksepi_echotime_shifting_sumdelay_fleet;
  }

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

  /* make sure we are divisible by GRAD_UPDATE_TIME (4us) */
  tmploc.pos = RUP_GRD(tmploc.pos);

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

  return SUCCESS;

} /* ksepi_pg_fleet() */

ksepi_fleet_scan_seqstate()

STATUS ksepi_fleet_scan_seqstate	(	const SCAN_INFO *	slice_pos,
		KS_PHASEENCODING_COORD	starting_coord,
		ks_enum_epiblipsign	blipsign
	)

Sets the current state of all FLEET sequence objects at every FLEET sequence playout in scan.

This function sets the current state of all FLEET sequence objects being part of KSEPI_FLEET_SEQUENCE, incl. gradient amplitude changes, RF freq/phases and receive freq/phase based on current slice position and phase encoding indices for a given sequence playout in ksepi_scan_fleet_coreslice() during scan.

Parameters

slice_pos	Pointer to the SCAN_INFO structure containing slice information.
starting_coord	The starting coordinate for the scan.
blipsign	The blip sign for the scan.

Return values

STATUS

SUCCESS or FAILURE

                                                                                                                                  {
  float exc_rfphase;

  /* RF frequency & phase */
  if (ksepi_rfspoiling) {
    exc_rfphase = ks_scan_rf_phase_spoiling(rfspoiling_phase_counter);
    rfspoiling_phase_counter++;
  } else {
    exc_rfphase = 0;
  }

  if (slice_pos != NULL) {
    ks_scan_rotate(*slice_pos);
    ks_scan_rf_on(&ksepi_fleetseq.selrfexc.rf, INSTRALL);
    ks_scan_selrf_setfreqphase(&ksepi_fleetseq.selrfexc, 0, *slice_pos, exc_rfphase);

    /* Echo time shifting */
    if (ksepi_echotime_shifting_fleet) {
      int pre_delay = ksepi_fleetseq.pre_delay.pg_duration;
      int post_delay = ksepi_fleetseq.post_delay.pg_duration;
      int kyshot = starting_coord.ky % ksepi_fleetseq.epitrain.blipphaser.R;
      int epiesp = ksepi_fleetseq.epitrain.read.grad.duration + ksepi_fleetseq.epitrain.read_spacing;
      float delta_t = (float) epiesp / (float) ksepi_fleetseq.epitrain.blipphaser.R;

      if (kyshot >= 0) {
        if (blipsign == KS_EPI_POSBLIPS) {
          pre_delay = RUP_GRD((int) (delta_t * (ksepi_fleetseq.epitrain.blipphaser.R-1-kyshot)));
        } else if (blipsign == KS_EPI_NEGBLIPS) {
          pre_delay = RUP_GRD((int) (delta_t * kyshot));
        }
      }
      ks_scan_wait(&ksepi_fleetseq.pre_delay, pre_delay);
      post_delay = ksepi_echotime_shifting_sumdelay_fleet - pre_delay;
      ks_scan_wait(&ksepi_fleetseq.post_delay, post_delay);
    } /* echotime shifting FLEET */

    ks_scan_epi_shotcontrol(&ksepi_fleetseq.epitrain, 0, *slice_pos, starting_coord, blipsign, exc_rfphase);
  } else {
    ks_scan_rf_off(&ksepi_fleetseq.selrfexc.rf, INSTRALL);
  }

  return SUCCESS;

} /* ksepi_fleet_scan_seqstate() */

ksepi_scan_rf_off()

void ksepi_scan_rf_off

(

)

Sets all RF pulse amplitudes to zero

Returns

void

                         {
  ks_scan_rf_off(&ksepi.selrfexc.rf, INSTRALL);
  ks_scan_rf_off(&ksepi.selrfref.rf, INSTRALL);

} /* ksepi_scan_rf_off() */

ksepi_scan_attach_metadata() [2/2]

void ksepi_scan_attach_metadata	(	KS_EPI *	epitrain,
		KS_EPI *	dynreftrain,
		const KS_DYNAMIC_STATE *	dynamic,
		uint8_t	sequence_group
	)

Copy selected elements in KS_DYNAMIC_STATE to KSEPI_METADATA for data tagging for recon

The elements in KS_DYNAMIC_STATE are set by the nested scan loop functions (for EPI that is in ksepi.cc). These elements are e.g. .average, .shot, .slloc. For more details see KS_DYNAMIC_STATE.

With a 22-byte size limit of additional data to each DAB packet (i.e. each readout lobe), the 22-byte KSEPI_METADATA struct will here be filled with selected information from the dynamic struct (which is too large to be passed on as DAB packets) as well as with static data (sequence_group). The selected content of information in KSEPI_METADATA is given in ksepi2.h, where for now some free fields are available for future use.

To reduce the byte usage, diff_ampX/Y/Z are converted from float to int16 and scaled by 32767.

Once the local KSEPI_METADATA metadata_out has been filled, it is passed to ks_loaddab() in this function.

Note that the sequence-independent KS_DYNAMIC_STATE can grow in the future with new fields to support more needs for various PSDs. In contrast, care needs to be taken not only to limit the number of bytes used in KSEPI_METADATA, and also to not shuffle the fields of KSEPI_METADATA for backwards compatibility of the Matlab recon ksepi2_recon.m, which uses dab_getinfo_ksepi2.m to parse each raw frame's additional bytes where the KSEPI_METADATA is stored.

Parameters

[in]	epitrain	Pointer to KS_EPI for the main EPI train
[in]	dynreftrain	Pointer to KS_EPI for the dynamic ref lines (may be NULL)
[in]	dynamic	Pointer to KS_DYNAMIC_STATE that stores nex, slice, shot, vol information
[in]	sequence_group	One of enums in KSEPI_SEQINDICES

Returns

void

                                                                                                                                {
  float readamp;
  int i;

  KSEPI_METADATA metadata = KSEPI_INIT_METADATA;

  metadata.sequence_group = sequence_group; /* enum KSEPI_SEQINDICES */

  metadata.average = (int8_t) dynamic->average; /* NEX */
  metadata.slloc = (int16_t) dynamic->slloc;
  metadata.shot = (int16_t) dynamic->shot;
  metadata.vol_rep = (int16_t) dynamic->vol;

  if (opdiffuse) {
    float logicalmax = FMax(3, loggrd.tx, loggrd.ty, loggrd.tz);
    metadata.diff_ampX = (int16_t) (dynamic->diff_amp[XGRAD] * loggrd.tx / logicalmax * MAX_PG_IAMP);
    metadata.diff_ampY = (int16_t) (dynamic->diff_amp[YGRAD] * loggrd.ty / logicalmax * MAX_PG_IAMP);
    metadata.diff_ampZ = (int16_t) (dynamic->diff_amp[ZGRAD] * loggrd.tz / logicalmax * MAX_PG_IAMP);
  } else {
    metadata.diff_ampX = (int16_t) 0;
    metadata.diff_ampY = (int16_t) 0;
    metadata.diff_ampZ = (int16_t) 0;
  }
  metadata.inner_shot = (int8_t) dynamic->inner_shot;

  /* Main EPI train(s) (KS_EPI) */
  for (i = 0; i < ks_numplaced(&epitrain->read.acq.base); i++) {
    readamp = ks_get_trapamp_instance(&epitrain->read.grad, i);
    metadata.readpolarity = (int8_t) areSame(readamp,0.0) ? 0 : ((readamp > 0.0) ? 1 : -1);
    metadata.seqpart = KSEPI_SEQPART_EPITRAIN; /* enum KSEPI_SEQPARTS */
    if (ksepi_metadump) { ksepi_dump_metadata(&metadata, dynamic); } 
    ks_loaddab(&epitrain->read.acq.echo[i], (char *) &metadata);
  }

  /* Dynamic ref lines (KS_EPI). ksepi_scan_coreslice_prep()->ks_scan_epi_loadecho(&seq->dynreftrain.... view # = -1 */
  if (dynreftrain != NULL) {
    for (i = 0; i < ks_numplaced(&dynreftrain->read.acq.base); i++) {
      readamp = ks_get_trapamp_instance(&dynreftrain->read.grad, i);
      metadata.readpolarity = (int8_t) areSame(readamp,0.0) ? 0 : ((readamp > 0.0) ? 1 : -1);
      metadata.seqpart = KSEPI_SEQPART_DYNREFTRAIN; /* enum KSEPI_SEQPARTS */
      if (ksepi_metadump) { ksepi_dump_metadata(&metadata, dynamic); } 
      ks_loaddab(&dynreftrain->read.acq.echo[i], (char *) &metadata);
    }
  }
  
} /* ksepi_scan_attach_metadata() */

ksepi_scan_init()

STATUS ksepi_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(&ksepi.seqctrl);  /* switch to main sequence */
  scopeon(&seqcore); /* Activate scope for core */
  syncon(&seqcore);  /* Activate sync for core */
  setssitime(ksepi.seqctrl.ssi_time / HW_GRAD_UPDATE_TIME);

  /* can we make these independent on global rsptrigger and rsprot in orderslice? */
  settriggerarray( (short) ksepi_get_loop_ctrl()->slicetiming.slice_plan.nslices_per_pass, rsptrigger);

  rfspoiling_phase_counter = 0;

  return SUCCESS;

} /* ksepi_scan_init() */

ksepi_scan_prescanloop()

STATUS ksepi_scan_prescanloop	(	int	nloops,
		int	dda
	)

Prescan loop called from both APS2 and MPS2 entry points

Return values

STATUS

SUCCESS or FAILURE

                                                   {

  if (!ANYINVERSION) {
    ksscan_prescanloop(&ksepi_loopctrl, ksepi_scan_coreslicegroup, nloops, dda);
  } else {
    ksinv_prescanloop(&ksepi_inv_loopctrl, ksepi_scan_coreslicegroup, ksepi_scan_irslice, nloops, dda);
  }

  return SUCCESS;

} /* ksepi_scan_prescanloop() */

ksepi_diffusion_init_UI()

STATUS ksepi_diffusion_init_UI

(

)

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

Return values

STATUS

SUCCESS or FAILURE

                                 {
    int i;

    if (opdiffuse != KS_EPI_DIFFUSION_ON) {
        return SUCCESS;
    }


   pidiffproctype = 0;/* Bitmask to show/hide automated DTI processing buttons */

    /* Optimize TE / super G check box */
#if EPIC_RELEASE >= 27    
    pimintediflabel = HAVE_PREMIER_GRADIENTS; /* Label indicator: 0 - Optimize TE, 1 - Super G */
    pimintedifvis = HAVE_PREMIER_GRADIENTS; /* Visibility of the "Optimize TE"/"Super G" button : 0 - invisible, 1 - visible */
#endif
    pimintedifnub = HAVE_PREMIER_GRADIENTS; /* Optimize TE button control in diffusion screen */
    pimintedifdef = 0; /* Default Optimize TE button control */
    cvset(opmintedif,0,1,0,""); /* Optimize TE button control */

    pinumsynbnub = 0; /* No synthetic b-values */
    pisynbvalstab = 0;
    piseparatesynbnub = 0;
    pidifrecnub = 0;
    pidifaxnub = 1;
    pidualspinechonub = 0; /* doesn't help, still checked when TENSOR is chosen */

    /* number of b-values */
    cvset(opnumbvals, 1, KSEPI_DIFFUSION_MAXBVALS, 1, "");
    pinumbnub = 63;
    pinumbval2 = 1;
    pinumbval3 = 2;
    pinumbval4 = 3;
    pinumbval5 = 4;
    pinumbval6 = KSEPI_DIFFUSION_MAXBVALS;

    /* b-value table */
    cvset(opbval, 0, KSEPI_DIFFUSION_MAXBVALUE, 1000, "");
    pibvalstab = 1; /* show bvalue table */
    avminbvalstab = 10.0;
    avmaxbvalstab = KSEPI_DIFFUSION_MAXBVALUE;
    if (existcv(opnumbvals) == FALSE) {
        /* until number of b-value has been selected, set up a range of b-values */
        for (i = 0; i < 10; i++)
            bvalstab[i] = 1000 + 500 * i;
    }

    pidifnextab = 1; /* Allow NEX input in table (and hide normal NEX) */
    avmindifnextab = 1;
    avmaxdifnextab = 10;

    /* Number of T2 menu (opdifnumt2) - DISABLED BY DEFAULT
      - produces this many .nb0 and .nb0neg volumes in recon (increases total # of DICOM images) */
    pidifnumt2defval = 1; 
    cvdef(opdifnumt2, pidifnumt2defval);
    opdifnumt2 = pidifnumt2defval;
    pidifnumt2nub = 0; /* Disable menu (use opdifnext2 for higher b0 SNR). Possible though to enable menu, recon will produce this many separate b0 vols */
    pidifnumt2val2 = 1;

    /* NEX for T2 (opdifnext2)
       - produces this many averages of .nb0 and .nb0neg volumes in recon without increasing the total # of DICOM images */
    cvset(opdifnext2, 1, 20, 1, "");
    pidifnext2nub = 63;
    pidifnext2val2 = 1;
    pidifnext2val3 = 2;
    pidifnext2val4 = 3;
    pidifnext2val5 = 4;
    pidifnext2val6 = 5;

    /* Number of diffusion directions menu (opdifnumdirs) */
    pidifnumdirsdefval = 6;     
    cvset(opdifnumdirs, 1, MAX_DIFFSCHEME_LENGTH, pidifnumdirsdefval, "");
    pidifnumdirsnub = 15;
    pidifnumdirsval2 = 6;
    pidifnumdirsval3 = 15;
    pidifnumdirsval4 = 25;


    /* Max diffusion amplitude to work with [G/cm] (based on trial and error) */
    if (HAVE_PREMIER_GRADIENTS) {
        if (opmintedif) { 
          /* 70 mT/m with longer TR */
          _ksepi_diffusion_amp_scale.defval = 1.0;
        } else {
          /* without increasing min TR for b < 1500, max diff amp seems to be ~50 mT/m (~70%) */
          _ksepi_diffusion_amp_scale.defval = 0.70;            
        }
    } else {
      /* by default, use 85% of physical max to allow for angled slices */
      _ksepi_diffusion_amp_scale.defval = 0.85;
    }
    ksepi_diffusion_amp_scale = _ksepi_diffusion_amp_scale.defval;

    return SUCCESS;

} /* ksepi_diffusion_init_UI() */

SolveCubic()

void SolveCubic	(	double	a,
		double	b,
		double	c,
		double	d,
		int *	nsol,
		double *	x
	)

Solve a third degree polynomial equation

Returns

void

{
  double    a1 = b/a, a2 = c/a, a3 = d/a;
  double    Q = (a1*a1 - 3.0*a2)/9.0;
  double    R = (2.0*a1*a1*a1 - 9.0*a1*a2 + 27.0*a3)/54.0;
  double    R2_Q3 = R*R - Q*Q*Q;
  double    theta;

  if (R2_Q3 <= 0){
    *nsol = 3;
    theta = acos(R/sqrt(Q*Q*Q));
    x[0] = -2.0 * sqrt(Q) * cos( theta/3.0) - a1/3.0;
    x[1] = -2.0 * sqrt(Q) * cos( (theta+2.0*PI)/3.0) - a1/3.0;
    x[2] = -2.0 * sqrt(Q) * cos( (theta+4.0*PI)/3.0) - a1/3.0;
  } else {
    *nsol = 1;
    x[0] = pow( sqrt(R2_Q3) + fabs(R), 1/3.0);
    x[0] += Q/x[0];
    x[0] *= (R < 0.0) ? 1 : -1;
    x[0] -= a1/3.0;
  }

} /* SolveCubic() */

ksepi_diffusion_calcTE()

STATUS ksepi_diffusion_calcTE	(	double *	TE_s,
		int	exciso2end,
		int	crsh1_half180,
		int	half180_crsh2,
		int	readout2echo,
		int	ramptime,
		float	G,
		int	bval_desired
	)

Calculate TE that will yield the desired b-value

Using a set of fixed times in the sequence as input arguments as well as the diffusion gradient amplitude and the desired b-value, this function calculates the echo time (TE) that will yield the desired b-value.

Parameters

[out]	TE_s	TE [s] that will yield the correct b-value
[in]	exciso2end	[us] RF excitation isocenter to end of exc rephaser
[in]	crsh1_half180	[us] left crusher start to RF isocenter of 1st/only 180
[in]	half180_crsh2	[us] RF isocenter to end of right crusher of 1st/only 180
[in]	readout2echo	[us] time from readout to echo
[in]	ramptime	[us] minimum ramp time
[in]	G	[G/cm] diffusion gradient amplitude
[in]	bval_desired	[s/mm^2] desired b-value

Return values

STATUS

SUCCESS or FAILURE

                                                                                                                                                                           {
    double exciso2end_s    = 1.0E-6 * RUP_GRD(exciso2end); /* [s] */
    double crsh1_half180_s = 1.0E-6 * RUP_GRD(crsh1_half180); /* [s] */
    double half180_crsh2_s = 1.0E-6 * RUP_GRD(half180_crsh2); /* [s] */
    double readout2echo_s  = 1.0E-6 * RUP_GRD(readout2echo); /* [s] */
    double ramptime_s      = 1.0E-6 * RUP_GRD(ramptime); /* [s] */
    double fixedtime_s;
    double gam_SI = (2 * PI * 42.58E6); /* [rad/(sT)] */
    double G_SI = G / 100.0; /* [G/cm] -> [T/m] */
    double sol[3];
    int nsol;
    double c0, c1, c2, c3, c0new;

    /* all double variables are in SI units (see genbvalcode.m for details on c0-c3 below) */

    fixedtime_s = FMax(2, exciso2end_s + crsh1_half180_s, half180_crsh2_s + readout2echo_s) + 2.0 * ramptime_s;

    c3 = 1.0 / 12.0;

    c2 = -(exciso2end_s + fixedtime_s - half180_crsh2_s - ramptime_s) / 4.0;

    c1 = exciso2end_s * fixedtime_s - fixedtime_s * half180_crsh2_s - exciso2end_s * ramptime_s + half180_crsh2_s * ramptime_s - ramptime_s * ramptime_s / 12.0;

    c0 = (fixedtime_s * fixedtime_s) * half180_crsh2_s - exciso2end_s * (fixedtime_s * fixedtime_s) - exciso2end_s * (ramptime_s * ramptime_s) +
      (7 * fixedtime_s * (ramptime_s * ramptime_s)) / 6 - (fixedtime_s * fixedtime_s) * ramptime_s + half180_crsh2_s * (ramptime_s * ramptime_s) +
      (fixedtime_s * fixedtime_s * fixedtime_s) / 3 - (7 * (ramptime_s * ramptime_s * ramptime_s)) / 15 + 2 * exciso2end_s * fixedtime_s * ramptime_s - 2 * fixedtime_s * half180_crsh2_s * ramptime_s;

    /* bval = 1.0E-6 * gam_SI * gam_SI * G_SI * G_SI * (c3 * pow(TE_s, 3.0) + c2 * pow(TE_s, 2.0) + c1 * TE_s + c0);  leading 1.0E-6 makes bval in s/mm^2 (e.g. b = 1000)
        where
            double gam_SI = (2 * PI * 42.58E6); [rad/(sT)]
            double G_SI = G [G/cm] / 100.0; [T/m]

        b(TE_s) = 1.0E-6 * gam_SI * gam_SI * G_SI * G_SI * (c3 * pow(TE_s, 3.0) + c2 * pow(TE_s, 2.0) + c1 * TE_s + c0);  [s/mm^2]
        desired b-value: bval_desired; [s/mm^2]
        F(TE_s) = b(TE_s) - bval_desired
        Find TE_s that gives F(TE_s) = 0   => TE_s that will yield the correct b-value
        F(TE_s) = 1.0E-6 * gam_SI * gam_SI * G_SI * G_SI * (c3 * pow(TE_s, 3.0) + c2 * pow(TE_s, 2.0) + c1 * TE_s + c0) - bval_desired = 0
        =>
        F(TE_s) = 1.0E-6 * gam_SI * gam_SI * G_SI * G_SI * (c3 * pow(TE_s, 3.0) + c2 * pow(TE_s, 2.0) + c1 * TE_s + (c0 - bval_desired/(1.0E-6 * gam_SI * gam_SI * G_SI * G_SI)))
        => [divide leading factors and make a new c0new = c0 - bval_desired/(1.0E-6 * gam_SI * gam_SI * G_SI * G_SI)
        Fnew(TE_s) = c3 * pow(TE_s, 3.0) + c2 * pow(TE_s, 2.0) + c1 * TE_s + c0new
        Put in c3, c2, c1, c0new into SolveCubic function to get TE_s where F(TE_s) = 0
    */
    c0new = c0 - (double) bval_desired / (1.0E-6 * gam_SI * gam_SI * G_SI * G_SI);

    /* Solve cubic function in TE */
    SolveCubic(c3, c2, c1, c0new, &nsol, sol);

    if (nsol == 3)
        *TE_s = FMax(3, sol[0], sol[1], sol[2]);
    else
        *TE_s = sol[0];


    return SUCCESS;

} /* ksepi_diffusion_calcTE() */

ksepi_diffusion_eval_gradients_TE()

STATUS ksepi_diffusion_eval_gradients_TE	(	KSEPI_SEQUENCE *	epi,
		const KSDIFF_CONTROL *	diff_ctrl
	)

Evaluate the diffusion gradients and TE

This function evaluates the diffusion gradients and TE based on the KSDIFF_CONTROL struct diff_ctrl and the KSEPI_SEQUENCE struct epi.

Parameters

[in,out]	epi	KSEPI_SEQUENCE struct
[in]	diff_ctrl	KSDIFF_CONTROL struct, with used fields .max_magnitude_amp and .bvalue

Return values

STATUS

SUCCESS or FAILURE

                                                                                               {

    STATUS status;
    int exciso2end    = epi->selrfexc.rf.iso2end + KS_RFSSP_POSTTIME + epi->selrfexc.grad.ramptime + epi->selrfexc.postgrad.duration; /* RF excitation isocenter to end of exc rephaser [us] */
    const int crsh1_half180 = KS_RFSSP_PRETIME + epi->selrfref.grad2rf_start + epi->selrfref.rf.start2iso; /* left crusher start to RF isocenter of 1st/only 180 [us] */
    const int half180_crsh2 = epi->selrfref.rf.iso2end + epi->selrfref.rf2grad_end + KS_RFSSP_POSTTIME; /*  RF isocenter to end of right crusher of 1st/only 180 [us] */
    int i;

    if (ksepi_reflines > 0) {
        exciso2end += epi->dynreftrain.duration;
        if (ksepi_slicecheck == FALSE) { /* reflines dephaser may overlap with selrf rephaser unless slicecheck mode */
            exciso2end -= IMin(2, epi->dynreftrain.readphaser.duration, epi->selrfexc.postgrad.duration);
        }
    }

    if (opdiffuse != KS_EPI_DIFFUSION_ON) {
        return SUCCESS;
    }

    /* Diffusion amplitude scaling to start out with. May decrease if b-value very small */
    float amp_scale = ksepi_diffusion_amp_scale;
    int plateautime = 0;

    const int ramptime = RUP_GRD(IMax(2, ks_syslimits_ramptimemax(loggrd), ksepi_diffusion_minramptime));
    const int fixedtime = RUP_GRD(IMax(2, exciso2end + crsh1_half180, half180_crsh2 + epi->pre_delay.pg_duration + epi->epitrain.time2center) + 2 * ramptime);

    int bvalue_validated = FALSE;
    const int max_attempts = 30;

    for (i=0; i < max_attempts; ++i) {

       double TE_s;
       status = ksepi_diffusion_calcTE(&TE_s, exciso2end /* [us] */, crsh1_half180 /* [us] */, half180_crsh2 /* [us] */,
                                        epi->epitrain.time2center /* [us] */,
                                        ramptime /* [us] */,
                                        amp_scale * diff_ctrl->max_magnitude_amp /* [G/cm] */,
                                        diff_ctrl->bvalue /* [s/mm^2] */);
        KS_RAISE(status);

        /* Save the TE found to the CV for later verification. ksepi_diffusion_echotime in [us] */
        cvoverride(ksepi_diffusion_echotime, (TE_s * 1E6), PSD_FIX_OFF, PSD_EXIST_OFF);
        ksepi_diffusion_echotime = RUP_GRD(ksepi_diffusion_echotime);

        /* Set diffusion plateau times based on found TE */
        plateautime = RDN_GRD(ksepi_diffusion_echotime / 2 - fixedtime);

        if (plateautime >= (2 * GRAD_UPDATE_TIME)) {
          bvalue_validated = TRUE;
          break;
        }

        /* Too low b-value or long ramptimes leading to negative plateau times?
           Reduce diffusion gradient amplitude and try again */
        amp_scale *= 0.95;
    }

    if (bvalue_validated == FALSE) {
      return KS_THROW("TE => negative diffusion gradient plateau time");
    }

    const char boards[] = "XYZ";
    const float diffgrad_amps[] = {loggrd.tx, loggrd.ty, loggrd.tz};
    for (i=0; i<3; ++i) {
      ks_init_trap(&epi->diffgrads[i]);

      /* Build up the trap object(s) manually, now that we know the plateau time(s) */
      epi->diffgrads[i].amp = diffgrad_amps[i] * amp_scale; /* [G/cm] */
      epi->diffgrads[i].ramptime = ramptime;
      epi->diffgrads[i].plateautime = plateautime;
      sprintf(epi->diffgrads[i].description, "diffgrad_%c", boards[i]);

      /* duration and area are consequences of the fields just set (N.B. all are initialized to zero by ks_init_trap()) */
      epi->diffgrads[i].duration  = epi->diffgrads[i].plateautime  + 2 * epi->diffgrads[i].ramptime;
      epi->diffgrads[i].area  = epi->diffgrads[i].amp  * (float) (epi->diffgrads[i].plateautime  + epi->diffgrads[i].ramptime);
    }

    return SUCCESS;

} /* ksepi_diffusion_eval_gradients_TE() */

ksepi_eval_diffusion()

STATUS ksepi_eval_diffusion

(

KSDIFF_CONTROL *

diff_ctrl

)

Creation of KSDIFF_CONTROL using a KSDIFF_CONTROL_DESIGN struct set by this function

The KSDIFF_CONTROL_DESIGN struct is set up mostly by UI CVs on the Diffusion tab. This is then used by ksdiff_eval_design() to create the KSDIFF_CONTROL struct ksepi_diffctrl, which is later used in ksepi_eval_setupobjects()->ksepi_diffusion_eval_gradients_TE() to control diffusion timing, gradients, and TE

Note that all design structs are short-lived and are set up as a receipe for other structures to be used in pulsegen and scan

Parameters

[out]

diff_ctrl

KSDIFF_CONTROL struct to be created

Return values

STATUS

SUCCESS or FAILURE

                                                       {

  STATUS status;

  KSDIFF_CONTROL_DESIGN diff_design = KSDIFF_INIT_CONTROL_DESIGN;

  if (opdiffuse) {
    /* diffusion design */
    diff_design.nb0 = opdifnumt2;
    diff_design.ndirs = opdifnumdirs;
    diff_design.numbvals = opnumbvals;

    diff_design.physical_bound_type = (HAVE_PREMIER_GRADIENTS) ? KSDIFF_ISO : KSDIFF_CUBOID;

    diff_design.coordinate_system = (diff_design.ndirs == 4) ?
      KSDIFF_PHYSICAL : /* tetrahedral case */
      KSDIFF_LOGICAL;

    int i = 0; 
    for (i = 0; i < diff_design.numbvals; i++) {
      /* 'difnextab' & 'bvalstab' are global UI arrays for the Diffusion screen */
      diff_design.bvalues[i] = bvalstab[i];
      diff_design.multib_nex[i] = difnextab[i];
    }
  } /* diffusion */

  status = ksdiff_eval_design(&ksepi_diffctrl, &diff_design);
  KS_RAISE(status);

  return SUCCESS;

} /* ksepi_eval_diffusion() */

ksepi_diffusion_pg()

STATUS ksepi_diffusion_pg	(	KSEPI_SEQUENCE *	epi,
		int	TE
	)

Diffusion part of the ksepi_pg() function, placing diffusion gradients and the refocusing RF pulse in between

Return values

STATUS

SUCCESS or FAILURE

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

    if (opdiffuse != KS_EPI_DIFFUSION_ON) {
      return SUCCESS;
    }

    /* First diffusion gradient right after the excitation and any reference lines */
    tmploc.ampscale = 1.0;
    tmploc.pos = epi->seqctrl.momentstart + epi->selrfexc.rf.iso2end + epi->selrfexc.grad.ramptime + epi->selrfexc.postgrad.duration;

    if (ksepi_slicecheck == FALSE) { /* reflines dephaser may overlap with selrf rephaser unless slicecheck mode */
      tmploc.pos -= IMin(2, epi->dynreftrain.readphaser.duration, epi->selrfexc.postgrad.duration);
    }   

    if (ksepi_reflines > 0) {
      tmploc.pos += epi->dynreftrain.duration;
    }

    for (i = XGRAD; i <= ZGRAD; i++) {
      tmploc.board = i;
      status = ks_pg_trap(&epi->diffgrads[i], tmploc, &epi->seqctrl);
      KS_RAISE(status);
    }

    /* Selective RF Refocus with left (pregrad.) and right (postgrad.) crushers */
    tmploc.pos = epi->seqctrl.momentstart + TE / 2 - (epi->selrfref.grad2rf_start + epi->selrfref.rf.start2iso);
    status = ks_pg_selrf(&epi->selrfref, tmploc, &epi->seqctrl);
    KS_RAISE(status);

    /* Second diffusion gradient after the refocusing pulse */
    tmploc.ampscale = 1.0;
    tmploc.pos += epi->selrfref.grad2rf_start + epi->selrfref.rf.start2iso + epi->selrfref.rf.iso2end + epi->selrfref.rf2grad_end;
    
    for (i = XGRAD; i <= ZGRAD; i++) {
      tmploc.board = i;
      status = ks_pg_trap(&epi->diffgrads[i], tmploc, &epi->seqctrl);
      KS_RAISE(status);
    }

    return SUCCESS;

} /* ksepi_diffusion_pg() */

Variable Documentation

seqcollection

KS_SEQ_COLLECTION seqcollection

ksepi_excthickness

float ksepi_excthickness = 0

ksepi_gscalerfexc

float ksepi_gscalerfexc = 0.9 with {0.1, 3.0, 0.9, VIS, "Excitation slice thk scaling (< 1.0 thicker slice)",}

ksepi_slicecheck

int ksepi_slicecheck = 0 with {0, 1, 0, VIS, "move readout to z axis for slice thickness test",}

ksepi_spoilerarea

float ksepi_spoilerarea = 3000.0 with {0.0, 10000.0, 3000.0, VIS, "ksepi ksepi.spoiler gradient area",}

ksepi_rfspoiling

int ksepi_rfspoiling = 1 with {0, 1, 1, VIS, "Enable RF spoiling 1:on 0:off",}

ksepi_fse90

int ksepi_fse90 = 0 with {0, 1, 0, VIS, "Use FSE90 instead of SPSP for non-fatsat",}

ksepi_kissoff_factor

float ksepi_kissoff_factor = 0.04 with {0, 1, 0.04, VIS, "Slice oversampling fraction on each side (3D)",}

ksepi_rfstretch_exc

float ksepi_rfstretch_exc = 1.0 with {0.1,10.0, 1.0, VIS, "RF excitation stretch factor"}

ksepi_fastexc3D

int ksepi_fastexc3D = TRUE with {FALSE, TRUE, TRUE, VIS, "Sel. RF exc (3D) 0:EXC_SPSP_3D 1:EXC_FAST_SPSP_3D",}

ksepi_crusher_dephasing

float ksepi_crusher_dephasing = 6.0 with { 0.0, 100.0, 6.0, VIS, "crusher dephasing over slice [cycles]",}

ksepi_gscalerfref

float ksepi_gscalerfref = 0.9 with {0.1, 3.0, 0.9, VIS, "Refocusing slice thk scaling (< 1.0 thicker slice)",}

ksepi_rfstretch_ref

float ksepi_rfstretch_ref = 1.0 with {0.1,10.0, 1.0, VIS, "RF refocusing stretch factor",}

ksepi_bridgecrushers

int ksepi_bridgecrushers = FALSE with {FALSE, TRUE, FALSE, VIS, "Bridge RF ref crushers",}

ksepi_t1value_to_null

int ksepi_t1value_to_null = T1_FAT_3T with {0, 5s, T1_FAT_3T, VIS, "T1 value to NULL [us]",}

ksepi_rampsampling

int ksepi_rampsampling = 1 with {0, 1, 1, VIS, "Rampsampling [0:OFF 1:ON]",}

ksepi_readlobegap

int ksepi_readlobegap = 0 with {0, 10ms, 0, VIS, "extra gap between readout lobes [us]",}

ksepi_echogap

int ksepi_echogap = 0 with {0, 100ms, 0, VIS, "extra gap between EPI echoes [us]",}

ksepi_readsign

int ksepi_readsign = 1 with { -1, 1, 1, VIS, "Readout polarity: +1/-1",}

ksepi_readampmax

float ksepi_readampmax = 3.0 with {0.0, 5.0, 3.0, VIS, "Max grad amp for EPI readout lobes",}

ksepi_sr

float ksepi_sr = 0.01 with {0.0, , 0.01, VIS, "EPI SR: amp/ramp [(G/cm) / us]",}

ksepi_esp

int ksepi_esp = 0 with {0, 1000000, 0, VIS, "View-only: Echo spacing in [us]",}

ksepi_blipsign

int ksepi_blipsign = KS_EPI_POSBLIPS with {KS_EPI_NEGBLIPS, KS_EPI_POSBLIPS, KS_EPI_POSBLIPS, VIS, "Blip polarity: +1/-1",}

ksepi_echotime_shifting

int ksepi_echotime_shifting = 1 with {0, 1, 1, VIS, "Enable echo time shifting for multi shot",}

ksepi_kynover

int ksepi_kynover = 24 with {KSEPI_MINHNOVER, 512, 24, VIS, "#extralines for MinTE",}

ksepi_kznover

int ksepi_kznover = 0 with {0, 512, 0, VIS, "#extralines in kz",}

ksepi_kz_nacslines

int ksepi_kz_nacslines = 8 with {0, 64, 8, VIS, "#acslines in kz",}

ksepi_caipi

int ksepi_caipi = 0 with {0, 512, 0, VIS, "CAIPIRINHA shift (affects 3D epi only. Set 0 for no CAIPI)",}

ksepi_readout_mode

int ksepi_readout_mode = KS_EPI_BIPOLAR with {KS_EPI_BIPOLAR, KS_EPI_FLYBACK, KS_EPI_BIPOLAR, VIS, "EPI readout mode 0: bipolar 1:splitoddeven 2:flyback",}

ksepi_fcy

int ksepi_fcy = 1 with {0, 1, 0, VIS, "Flowcomp Y when opfcomp"}

ksepi_fcz

int ksepi_fcz = 1 with {0, 1, 0, VIS, "Flowcomp Z when opfcomp"}

ksepi_fleet

int ksepi_fleet = 0 with {0, 1, 0, VIS, "FLEET calibration volume [0:OFF 1:ON]",}

ksepi_echotime_shifting_fleet

int ksepi_echotime_shifting_fleet = 1 with {0, 1, 1, VIS, "Enable echo time shifting for multi shot FLEET",}

ksepi_fleet_flip

float ksepi_fleet_flip = 5.0 with {1.0, 90.0, 5.0, VIS, "FLEET flip angle [deg]",}

ksepi_fleet_dda

int ksepi_fleet_dda = 3 with {1, 200, 3, VIS, "Dummies for FLEET module",}

ksepi_fleet_num_ky

int ksepi_fleet_num_ky = 48 with {32, 256, 48, VIS, "Number of ky encodes for FLEET module",}

ksepi_fleet_readout_mode

int ksepi_fleet_readout_mode = KS_EPI_SPLITODDEVEN with {KS_EPI_BIPOLAR, KS_EPI_FLYBACK, KS_EPI_SPLITODDEVEN, VIS, "FLEET EPI readout mode 0: bipolar 1:splitoddeven 2:flyback",}

ksepi_fleet_nshots

int ksepi_fleet_nshots = 3 with {1, 128, 3, VIS, "# shots for FLEET",}

ksepi_reflines

int ksepi_reflines = 0 with {0, 96, 0, VIS, "Number of phase reference lines per shot",}

ksepi_swi_returnmode

int ksepi_swi_returnmode = 0 with {0, 7, 0, VIS, "SWI recon 0:Off 1:Acq 2:SWI 4:SWIphase",}

ksepi_pos_start

int ksepi_pos_start = KS_RFSSP_PRETIME with {0, , KS_RFSSP_PRETIME, INVIS, "us from start until the first waveform begins",}

ksepi_ssi_time

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

ksepi_dda

int ksepi_dda = 1 with {1, 200, 1, VIS, "Number of dummy scans for steady state",}

ksepi_debug

int ksepi_debug = 1 with {0, 100, 1, VIS, "Write out e.g. plot files (unless scan on HW)"}

ksepi_imsize

int ksepi_imsize = KS_IMSIZE_POW2 with {KS_IMSIZE_NATIVE, KS_IMSIZE_MIN256, KS_IMSIZE_POW2, VIS, "img. upsamp. [0:native 1:pow2 2:min256]"}

ksepi_abort_on_kserror

int ksepi_abort_on_kserror = FALSE with {0, 1, 0, VIS, "Hard program abort on ks_error [0:OFF 1:ON]",}

ksepi_ref_nsegments

int ksepi_ref_nsegments = 1 with {1, 512, 1, VIS, "Number of kz segments in reference volume",}

ksepi_epiqfact

float ksepi_epiqfact = 1.0 with {1.0, 10.0, 1.0, VIS, "Quietness factor for the EPI readout only",}

ksepi_recvgain_mode

int ksepi_recvgain_mode = RG_CAL_MODE_HIGH_FIXED with {RG_CAL_MODE_MIN, RG_CAL_MODE_MAX, RG_CAL_MODE_HIGH_FIXED, VIS, "RecvGain - 0:Measured 1:8 2:5 3:Max",}

ksepi_metadump

int ksepi_metadump = 0

ksepi

KSEPI_SEQUENCE ksepi = KSEPI_INIT_SEQUENCE

Main EPI sequence (KSEPI_DATAGROUP_MAIN or KSEPI_DATAGROUP_MAIN_SPLITODDEVEN)

ksepi_loopctrl

KSSCAN_LOOP_CONTROL ksepi_loopctrl = KSSCAN_INIT_LOOP_CONTROL

Scan loop control for the ksepi sequence (without inversion)

ksepi_diffctrl

KSDIFF_CONTROL ksepi_diffctrl = KSDIFF_INIT_CONTROL

ksepi_fleetseq

KSEPI_FLEET_SEQUENCE ksepi_fleetseq = KSEPI_FLEET_INIT_SEQUENCE

FLEET calibation sequence for parallel imaging (KSEPI_DATAGROUP_FLEET or KSEPI_DATAGROUP_FLEET_SPLITODDEVEN)

ksepi_fleet_loopctrl

KSSCAN_LOOP_CONTROL ksepi_fleet_loopctrl = KSSCAN_INIT_LOOP_CONTROL

Scan loop control for the FLEET sequence

ksepi_inv

KSINV_MODULE ksepi_inv = KSINV_INIT_MODULE

Inversion module

ksepi_inv_loopctrl

KSINV_LOOP_CONTROL ksepi_inv_loopctrl = KSINV_INIT_LOOP_CONTROL

Scan loop control when using main sequence + inversion module

ksepi_phaseencoding_memorypool

KS_PHASEENCODING_COORD ksepi_phaseencoding_memorypool[KSEPI_PHASEENCODING_MEMORYPOOL_SIZE] = {KS_INIT_PHASEENCODING_COORD}

ksepi_interechotime

int ksepi_interechotime = 0

ksepi_echotime_shifting_shotdelay

float ksepi_echotime_shifting_shotdelay = 0.0

ksepi_echotime_shifting_shotdelay_fleet

float ksepi_echotime_shifting_shotdelay_fleet = 0.0

ksepi_echotime_shifting_sumdelay

int ksepi_echotime_shifting_sumdelay = 0

ksepi_echotime_shifting_sumdelay_fleet

int ksepi_echotime_shifting_sumdelay_fleet = 0

kacq

KS_KSPACE_ACQ kacq = KS_INIT_KSPACE_ACQ

sequence_iopts

int sequence_iopts[]

Initial value:

= {
  PSD_IOPT_ARC, 
  PSD_IOPT_MPH, 
  PSD_IOPT_EDR, 
  PSD_IOPT_ZIP_512, 
  PSD_IOPT_IR_PREP, 
  PSD_IOPT_MILDNOTE, 
  PSD_IOPT_FLOW_COMP, 
  PSD_IOPT_SEQUENTIAL, 





}

rfspoiling_phase_counter

int rfspoiling_phase_counter = 0

ksepi_diffusion_amp_scale

float ksepi_diffusion_amp_scale = 1.0 with {0.0, 1.0, 1.0, VIS, "Cap for scaling factor of diffusion gradient amplitude", }

ksepi_diffusion_heat_avg

int ksepi_diffusion_heat_avg = 1 with {0, 1, 1, VIS, "Root mean sqared averaging diffusion amplitudes heat calculations", }

ksepi_diffusion_scaleX_heatcal

float ksepi_diffusion_scaleX_heatcal = 1 with {0, 1, 1, VIS, "View-only: x diffusion gradient amplitude for heating calculations", }

ksepi_diffusion_scaleY_heatcal

float ksepi_diffusion_scaleY_heatcal = 1 with {0, 1, 1, VIS, "View-only: y diffusion gradient amplitude for heating calculations", }

ksepi_diffusion_scaleZ_heatcal

float ksepi_diffusion_scaleZ_heatcal = 1 with {0, 1, 1, VIS, "View-only: z diffusion gradient amplitude for heating calculations", }

ksepi_diffusion_echotime

int ksepi_diffusion_echotime = 0 with {0, , 0, VIS, "View-only: Echo time necessary to meet the desired b-value", }

ksepi_diffusion_returnmode

int ksepi_diffusion_returnmode = DIFFRETURN_ALL with {DIFFRETURN_ALL, 128, DIFFRETURN_ALL, VIS, "Diff maps All:0 Acq:1 b0:2 DWI:4 ADC:8 Exp:16 FA:32 cFA:64",}

ksepi_diffusion_minramptime

int ksepi_diffusion_minramptime = 1ms with {0, 20ms, 1ms, VIS, "Minimum diffusion ramp time. If 0: syslimits used",}