KSFoundation.h File Reference

Data Structures
struct	KSEPI_DATATAG
struct	KS_DATASTORE_STRUCT_DYNAMIC
struct	KS_DATASTORE_STRUCT_INFO
struct	KS_DATASTORETAG
struct	KS_SEQLOC
struct	KS_WFINSTANCE
struct	KS_BASE
struct	KS_WAIT
struct	KS_ISIROT
struct	KS_TRAP
struct	KS_WAVE
struct	KS_READ
struct	KS_RF
struct	KS_GRADRFCTRL
struct	KS_SEQ_HANDLE
struct	KS_SEQ_CONTROL
struct	KS_SEQ_COLLECTION
struct	KS_SAR
struct	KS_SLICE_PLAN
struct	KS_SMS_INFO
struct	KS_SELRF
struct	KS_READTRAP
struct	KS_READWAVE
struct	KS_PHASER
struct	KS_PHASEENCODING_COORD
struct	KS_PHASEENCODING_PLAN
struct	KS_EPI
struct	KS_DIXON_ASYMREADWAVE
struct	KS_DIXON_DUALREADTRAP

Macros
#define	WARN_UNUSED_RESULT
#define	DEFAULT_SCAN_INFO_HEAD   0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 1.0, 1.0, 1.0
#define	DEFAULT_SCAN_INFO_TAIL
#define	DEFAULT_AXIAL_SCAN_INFO
#define	DEFAULT_AX_SCAN_INFO_FREQ_LR   DEFAULT_AXIAL_SCAN_INFO
#define	DEFAULT_AX_SCAN_INFO_FREQ_AP
#define	DEFAULT_SAG_SCAN_INFO_FREQ_SI
#define	DEFAULT_SAG_SCAN_INFO_FREQ_AP
#define	DEFAULT_COR_SCAN_INFO_FREQ_SI
#define	DEFAULT_COR_SCAN_INFO_FREQ_LR
#define	KS_NOTSET   -1
#define	KS_INFINITY   (1.0/0.0)
#define	_cvdesc(cv, string)
#define	areSame(a, b)   (fabs((a) - (b)) < 1e-5)
#define	isNotSet(a)   areSame((a), KS_NOTSET)
#define	isSet(a)   !isNotSet(a)
#define	KS_ISI_predelay   256
#define	KS_ISI_time   256
#define	KS_ISI_rotupdatetime   12
#define	KS_ISI_postdelay   256
#define	KS_MINPLATEAUTIME   8
#define	KS_DEFAULT_SSI_TIME   1500
#define	KS_DEFAULT_SSI_TIME_MR750w   500
#define	KS_DEFAULT_SSI_TIME_MR750   1000
#define	KS_DEFAULT_SSI_TIME_MR450W   500
#define	KS_DEFAULT_SSI_TIME_MR450   1000
#define	KS_DEFAULT_SSI_TIME_PREMIER   500
#define	KS_DEFAULT_SSI_TIME_ICE   200
#define	KS_DEFAULT_SSI_TIME_OTHERWISE   1500
#define	KS_RFSSP_PRETIME   64
#define	KS_RFSSP_POSTTIME   56
#define	KS_RF_STANDARD_CRUSHERAREA   2000.0
#define	KS_EPI_MIN_INTERTRAIN_SSPGAP   80
#define	L_REF   10
#define	PSD_HRMW_COIL   13
#define	HAVE_PREMIER_GRADIENTS   (cfgcoiltype == PSD_HRMW_COIL)
#define	HALF_KHZ_USEC   500.0
#define	KS_SAVEPFILES   RHXC_AUTO_LOCK
#define	KS_GERECON   (RHXC_AUTO_DISPLAY+RHXC_XFER_IM)
#define	KS_3D_SELECTED   (opimode == PSD_3D || opimode == PSD_3DM)
#define	KS_3D_SINGLESLAB_SELECTED   (opimode == PSD_3D)
#define	KS_3D_MULTISLAB_SELECTED   (opimode == PSD_3DM)
#define	KS_DESCRIPTION_LENGTH   128
#define	KS_MAXWAVELEN   10000
#define	KS_MAXUNIQUE_RF   20
#define	KS_MAXUNIQUE_TRAP   200
#define	KS_MAXUNIQUE_WAVE   200
#define	KS_MAXUNIQUE_SEQUENCES   200
#define	KS_MAX_PHASEDYN   2049
#define	KS_MAXUNIQUE_READ   500
#define	KS_MAXINSTANCES   500
#define	KS_EPI_MINBLIPAREA   100
#define	KS_INITZEROS(n)   {[0 ... (n-1)] = 0}
#define	KS_INITVALUE(n, a)   {[0 ... (n-1)] = a}
#define	KS_INIT_DESC   KS_INITZEROS(KS_DESCRIPTION_LENGTH)
#define	KS_INIT_SEQLOC   {KS_NOTSET, KS_NOTSET, 1.0, 1.0}
#define	KS_INIT_WFINSTANCE   {NULL, 0, NULL, {KS_INIT_SEQLOC}}
#define	KS_INIT_WAIT   {{0,0,NULL,sizeof(KS_WAIT)}, KS_INIT_DESC, 0, KS_INITVALUE(KS_MAXINSTANCES, KS_INIT_SEQLOC), NULL, NULL}
#define	KS_INIT_ISIROT   {KS_INIT_WAIT, KS_INIT_WAIT, NULL, 0, 0, 0, 0}
#define	KS_INIT_TRAP   {{0,0,NULL,sizeof(KS_TRAP)}, KS_INIT_DESC, 0.0, 0.0, 0, 0, 0, {0, 0, 0}, {0, 0, 0}, {1, 1, 1}, KS_INITVALUE(KS_MAXINSTANCES,KS_INIT_SEQLOC), NULL, NULL, NULL}
#define	KS_INIT_READ   {{0,0,NULL,sizeof(KS_READ)}, KS_INIT_DESC, 0, KS_NOTSET, {0.0, 0, 0.0, 0.0, KS_NOTSET, 0, 0, 0}, KS_INITVALUE(KS_MAXINSTANCES,KS_NOTSET), 0, NULL}
#define	KS_INIT_READ_EPI   {{0,0,NULL,sizeof(KS_READ)}, KS_INIT_DESC, 0, 250.0, {0.0, 0, 0.0, 0.0, KS_NOTSET, 0, 0, 0}, KS_INITVALUE(KS_MAXINSTANCES,KS_NOTSET), 0, NULL}
#define	KS_INIT_READTRAP   {KS_INIT_READ, 240.0, 256, 0, 0, 0, 0.0, 0.0, 0.0, 0, KS_INIT_TRAP, KS_INIT_TRAP}
#define	KS_INIT_READTRAP_EPI   {KS_INIT_READ_EPI, 240.0, 64, 0, 0, 0, 0.0, 0.0, 0.0, 0, KS_INIT_TRAP, KS_INIT_TRAP}
#define	KS_INIT_PHASEENCTABLE   KS_INITZEROS(KS_MAX_PHASEDYN)
#define	KS_INIT_PHASER   {KS_INIT_TRAP, 240.0, KS_NOTSET, 0, 1, 0, 0, 0.0, 0, KS_INIT_PHASEENCTABLE}
#define	KS_INIT_PHASEENCODING_COORD   {KS_NOTSET, KS_NOTSET}
#define	KS_INIT_PHASEENCODING_PLAN   {KS_NOTSET, KS_NOTSET, KS_INIT_DESC, NULL, NULL, NULL, FALSE}
#define	KS_INIT_PHASEENCODING_ALLEPIPLANS   KS_INITVALUE(KS_EPI_PEPLAN_NUMPLANS, KS_INIT_PHASEENCODING_PLAN)
#define	KS_INIT_PHASEENCODING_PLAN_16PTRS   KS_INITVALUE(16, NULL)
#define	KS_INIT_EPI   {KS_INIT_READTRAP_EPI, KS_INIT_TRAP, KS_INIT_TRAP, KS_INIT_PHASER, KS_INIT_PHASER, 1, 0, 0, 0, 0, 1.0, KS_EPI_MINBLIPAREA}
#define	KS_INIT_WAVEVALUE   0
#define	KS_INIT_WAVEFORM   KS_INITVALUE(KS_MAXWAVELEN, KS_INIT_WAVEVALUE)
#define	KS_INIT_WAVE   {{0,0,NULL,sizeof(KS_WAVE)}, KS_INIT_DESC, 0, 0, KS_INIT_WAVEFORM, {0,0,0}, KS_NOTSET, KS_INITVALUE(KS_MAXINSTANCES,KS_INIT_SEQLOC), NULL, NULL, NULL}
#define	KS_INIT_READWAVE   {KS_INITVALUE(3,KS_INIT_WAVE), KS_INIT_WAVE, KS_INIT_WAVE, KS_INIT_READ, KS_INITVALUE(3, 0), KS_INITVALUE(3, 0.0), 0.0, 0.0, 0, 0, 0}
#define	KS_INIT_DIXON_ASYMREADWAVE   {KS_INIT_READWAVE, KS_INIT_DESC, KS_INITVALUE(2,0), 0, 0.0, 0, 0.0, KS_INITVALUE(8,0.0)}
#define	KS_INIT_DIXON_DUALREADTRAP   {KS_INIT_READWAVE, KS_INIT_DESC, 0,0,0,0,0.0,0, KS_INITVALUE(2,0),0,0.0,0,0,0,0.0,0.0, KS_INITVALUE(4,0)}
#define	RX27_APPLY_HADAMARD
#define	KS_INIT_RFPULSE   {NULL, NULL, 0.0,0.0,0.0,0.0,0.0,0,0.0,0.0,0.0,0.0,NULL,0.0,0.0,0,0,-1,0.0,NULL,0,NULL RX27_APPLY_HADAMARD}
#define	KS_INIT_RF   {KS_RF_ROLE_NOTSET, KS_NOTSET, KS_NOTSET, 0.0, 0.0, KS_NOTSET, KS_NOTSET, KS_NOTSET, KS_INIT_DESC, KS_INIT_RFPULSE, KS_INIT_WAVE, KS_INIT_WAVE, KS_INIT_WAVE}
#define	KS_INIT_SELRF   {KS_INIT_RF, KS_NOTSET, 1.0, KS_INIT_TRAP, KS_INIT_TRAP, KS_INIT_TRAP, KS_INIT_WAVE, KS_INIT_SMS_INFO}
#define	KS_INIT_GRADRFCTRL   {KS_INITZEROS(KS_MAXUNIQUE_RF), 0, KS_INITZEROS(KS_MAXUNIQUE_TRAP), 0, KS_INITZEROS(KS_MAXUNIQUE_WAVE), 0, KS_INITZEROS(KS_MAXUNIQUE_READ), 0, FALSE /* is_cleared_on_tgt */ }
#define	KS_INIT_SEQ_HANDLE   {NULL, 0, NULL}
#define	KS_INIT_SEQ_CONTROL   {0, 0, KS_DEFAULT_SSI_TIME, 0, KS_NOTSET, FALSE, KS_INIT_DESC, KS_INIT_SEQ_HANDLE, KS_INIT_GRADRFCTRL}
#define	KS_INIT_SEQ_COLLECTION   {0, KS_SEQ_COLLECTION_ALLOWNEW, FALSE, KS_INITVALUE(KS_MAXUNIQUE_SEQUENCES, NULL)}
#define	KS_INIT_SAR   {0, 0, 0, 0}
#define	KS_INIT_SLICEPLAN   {0,0,0,{{0,0,0}}}
#define	KS_INIT_SMS_INFO   {1, 0, 0}
#define	KS_INIT_LOGGRD   {0,0,0,0,0,0,{0,0,0,0,0,0},{0,0,0,0},{0,0,0,0},{0,0,0,0},{0,0,0,0},{0,0,0,0},{0,0,0,0},0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0 }
#define	KS_INIT_PHYSGRD   { 0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0, 0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0 }
#define	KS_MAT3x3_IDENTITY   {1,0,0,0,1,0,0,0,1}
#define	KS_MAT4x4_IDENTITY   {1,0,0,0, 0,1,0,0, 0,0,1,0, 0,0,0,1}
#define	KS_CUSTOM_DATASTORE_LENGTH   22
#define	KSEPI_INIT_DATATAG   {0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0}
#define	KS_INIT_DATASTORE_STRUCT_DYNAMIC   {-1, -1, -1, -1, -1, {0.0}}
#define	KS_INIT_DATASTORE_STRUCT_INFO   {TRUE, 0}
#define	KS_INIT_DATASTORETAG   {KS_INIT_DATASTORE_STRUCT_DYNAMIC, KS_INIT_DATASTORE_STRUCT_INFO, KS_INITZEROS(KS_CUSTOM_DATASTORE_LENGTH), NULL}
#define	cvset(cv, min, max, def, desc)

Typedefs
typedef char	KS_DESCRIPTION[KS_DESCRIPTION_LENGTH]
typedef float	KS_WAVEFORM[KS_MAXWAVELEN]
typedef short	KS_IWAVE[KS_MAXWAVELEN]
typedef double	KS_MAT3x3[9]
typedef double	KS_MAT4x4[16]
typedef KS_PHASEENCODING_PLAN	KS_PHASEENCODING_ALLEPIPLANS[KS_EPI_PEPLAN_NUMPLANS]
typedef KS_PHASEENCODING_PLAN *	KS_PHASEENCODING_PLAN_16PTRS[16]

Enumerations
enum	KS_PLOT_FILEFORMATS { KS_PLOT_OFF, KS_PLOT_MAKEPDF, KS_PLOT_MAKESVG, KS_PLOT_MAKEPNG }
enum	KS_PLOT_EXCITATION_MODE { KS_PLOT_STANDARD, KS_PLOT_NO_EXCITATION }
enum	KS_PLOT_PASS_MODE { KS_PLOT_PASS_WAS_DUMMY, KS_PLOT_PASS_WAS_CALIBRATION, KS_PLOT_PASS_WAS_STANDARD }
enum	KS_PLOT_SLICEGROUP_MODE { KS_PLOT_SG_DUMMY, KS_PLOT_SG_CALIBRATION, KS_PLOT_SG_ACQUISITION, KS_PLOT_SG_NOTSET }
enum	ks_enum_pf_earlylate_te { KS_PF_EARLY_TE, KS_PF_LATE_TE }
enum	ks_enum_sweep_order { KS_SWEEP_ORDER_TOP_DOWN = 0, KS_SWEEP_ORDER_BOTTOM_UP = 1, KS_SWEEP_ORDER_CENTER_OUT = 2, KS_SWEEP_ORDER_OUTSIDE_IN = 3 }
enum	ks_snr_mode { KS_SNR_MEAS_OFF = 0, KS_SNR_MEAS_FREQUENCY = 1, KS_SNR_MEAS_PHASE = 2 }
enum	ks_enum_trapparts { G_ATTACK, G_PLATEAU, G_DECAY }
enum	ks_enum_boarddef {   KS_X = TYPXGRAD, KS_Y = TYPYGRAD, KS_Z = TYPZGRAD, KS_RHO = TYPRHO1,   KS_RHO2 = TYPRHO2, KS_THETA = TYPTHETA, KS_OMEGA = TYPOMEGA, KS_SSP = TYPSSP,   KS_FREQX_PHASEY, KS_FREQY_PHASEX, KS_FREQX_PHASEZ, KS_FREQZ_PHASEX,   KS_FREQY_PHASEZ, KS_FREQZ_PHASEY, KS_XYZ, KS_ALL }
enum	ks_enum_epiblipsign { KS_EPI_POSBLIPS = 1, KS_EPI_NOBLIPS = 0, KS_EPI_NEGBLIPS = -1 }
enum	ks_enum_epiplans {   KS_EPI_PEPLAN_EARLYTE_BOTTOMUP_UNDERSAMPLED, KS_EPI_PEPLAN_EARLYTE_BOTTOMUP_MULTISHOT, KS_EPI_PEPLAN_EARLYTE_TOPDOWN_UNDERSAMPLED, KS_EPI_PEPLAN_EARLYTE_TOPDOWN_MULTISHOT,   KS_EPI_PEPLAN_LATETE_BOTTOMUP_UNDERSAMPLED, KS_EPI_PEPLAN_LATETE_BOTTOMUP_MULTISHOT, KS_EPI_PEPLAN_LATETE_TOPDOWN_UNDERSAMPLED, KS_EPI_PEPLAN_LATETE_TOPDOWN_MULTISHOT,   KS_EPI_PEPLAN_NUMPLANS }
enum	ks_enum_diffusion { KS_EPI_DIFFUSION_OFF, KS_EPI_DIFFUSION_ON }
enum	ks_enum_imsize { KS_IMSIZE_NATIVE, KS_IMSIZE_POW2, KS_IMSIZE_MIN256 }
enum	ks_enum_datadestination { KS_DONT_SEND = -1, KS_SENDTOBAM = 0, KS_SENDTORTP = 1 }
enum	ks_enum_accelmenu { KS_ACCELMENU_FRACT, KS_ACCELMENU_INT }
enum	ks_enum_rfrole {   KS_RF_ROLE_NOTSET, KS_RF_ROLE_EXC, KS_RF_ROLE_REF, KS_RF_ROLE_CHEMSAT,   KS_RF_ROLE_SPSAT, KS_RF_ROLE_INV }
enum	ks_enum_sincwin {   KS_RF_SINCWIN_OFF, KS_RF_SINCWIN_HAMMING, KS_RF_SINCWIN_HANNING, KS_RF_SINCWIN_BLACKMAN,   KS_RF_SINCWIN_BARTLETT }
enum	ks_enum_wavebuf { KS_WF_MAIN, KS_WF_BUF1, KS_WF_BUF2, KS_WF_SIZE }
enum	ks_enum_smstype {   KS_SELRF_SMS_MB, KS_SELRF_SMS_PINS, KS_SELRF_SMS_PINS_DANTE, KS_SELRF_SMS_MULTI_PINS,   KS_SELRF_SMSTYPE_SIZE }
enum	ks_enum_sms_phase_mod {   KS_SELRF_SMS_PHAS_MOD_OFF, KS_SELRF_SMS_PHAS_MOD_PHAS, KS_SELRF_SMS_PHAS_MOD_AMPL, KS_SELRF_SMS_PHAS_MOD_QUAD,   KS_SELRF_SMS_PHAS_MOD_SIZE }
enum	{ KS_SEQ_COLLECTION_ALLOWNEW, KS_SEQ_COLLECTION_LOCKED }
enum	ks_enum_grad_scaling_policy { KS_GRADWAVE_ABSOLUTE, KS_GRADWAVE_RELATIVE }

Functions
int	isNaN (float a)
void	ks_init_read (KS_READ *read)
void	ks_init_trap (KS_TRAP *trap)
void	ks_init_wait (KS_WAIT *wait)
void	ks_init_wave (KS_WAVE *wave)
void	ks_init_rf (KS_RF *rf)
void	ks_init_sms_info (KS_SMS_INFO *sms_info)
void	ks_init_selrf (KS_SELRF *selrf)
void	ks_init_readtrap (KS_READTRAP *readtrap)
void	ks_init_phaser (KS_PHASER *phaser)
void	ks_init_epi (KS_EPI *epi)
void	ks_init_dixon_asymreadwave (KS_DIXON_ASYMREADWAVE *asymreadwave)
void	ks_init_dixon_dualreadtrap (KS_DIXON_DUALREADTRAP *dual_readtrap)
void	ks_init_gradrfctrl (KS_GRADRFCTRL *gradrfctrl)
void	ks_init_seqcontrol (KS_SEQ_CONTROL *seqcontrol)
void	ks_init_seqcollection (KS_SEQ_COLLECTION *seqcollection)
STATUS	ks_init_slewratecontrol (LOG_GRAD *loggrd, PHYS_GRAD *phygrd, float srfact) WARN_UNUSED_RESULT
STATUS	ks_eval_addtoseqcollection (KS_SEQ_COLLECTION *seqcollection, KS_SEQ_CONTROL *seqctrl) WARN_UNUSED_RESULT
STATUS	ks_eval_seqcollection_isadded (KS_SEQ_COLLECTION *seqcollection, KS_SEQ_CONTROL *seqctrl)
STATUS	ks_eval_addtraptogradrfctrl (KS_GRADRFCTRL *gradrfctrl, KS_TRAP *trap) WARN_UNUSED_RESULT
STATUS	ks_eval_addwavetogradrfctrl (KS_GRADRFCTRL *gradrfctrl, KS_WAVE *wave) WARN_UNUSED_RESULT
STATUS	ks_eval_addrftogradrfctrl (KS_GRADRFCTRL *gradrfctrl, KS_RF *rf) WARN_UNUSED_RESULT
STATUS	ks_eval_addreadtogradrfctrl (KS_GRADRFCTRL *gradrfctrl, KS_READ *read) WARN_UNUSED_RESULT
STATUS	ks_eval_wait (KS_WAIT *wait, const char *const desc, int maxduration) WARN_UNUSED_RESULT
STATUS	ks_eval_isirot (KS_ISIROT *isirot, const char *const desc, int isinumber) WARN_UNUSED_RESULT
STATUS	ks_eval_read (KS_READ *read, const char *const desc) WARN_UNUSED_RESULT
STATUS	ks_eval_trap_constrained (KS_TRAP *trap, const char *const desc, float ampmax, float slewrate, int minduration) WARN_UNUSED_RESULT
STATUS	ks_eval_trap (KS_TRAP *trap, const char *const desc) WARN_UNUSED_RESULT
STATUS	ks_eval_trap2 (KS_TRAP *trap, const char *const desc) WARN_UNUSED_RESULT
STATUS	ks_eval_trap1 (KS_TRAP *trap, const char *const desc) WARN_UNUSED_RESULT
STATUS	ks_eval_trap_constrained_time_maxarea (KS_TRAP *trap, const char *const desc, float ampmax, float slewrate, float maxarea, int derate_slewrate) WARN_UNUSED_RESULT
STATUS	ks_eval_set_asym_padding (KS_READTRAP *readtrap, float wanted_paddingarea_pre, float wanted_paddingarea_post) WARN_UNUSED_RESULT
STATUS	ks_eval_trap1p (KS_TRAP *trap, const char *const desc) WARN_UNUSED_RESULT
STATUS	ks_eval_readtrap_constrained (KS_READTRAP *readtrap, const char *const desc, float ampmax, float slewrate) WARN_UNUSED_RESULT
STATUS	ks_eval_readtrap (KS_READTRAP *readtrap, const char *const desc) WARN_UNUSED_RESULT
STATUS	ks_eval_readtrap2 (KS_READTRAP *readtrap, const char *const desc) WARN_UNUSED_RESULT
STATUS	ks_eval_readtrap1 (KS_READTRAP *readtrap, const char *const desc) WARN_UNUSED_RESULT
STATUS	ks_eval_readtrap_constrained_sample_duration (KS_READTRAP *readtrap, const char *const desc, const float ampmax, const float slewrate, const int t_A, const int sample_duration, const float area_post, const float area_total) WARN_UNUSED_RESULT
STATUS	ks_eval_dixon_wang (struct _dixon_dualreadtrap_s *dual_read, const char *const desc, const float PF, float M)
STATUS	ks_eval_dixon_dualreadtrap (struct _dixon_dualreadtrap_s *dual_read, const char *const desc, int flip)
STATUS	ks_verify_dualreadtrap_setup (struct _dixon_dualreadtrap_s *dual_read)
STATUS	ks_eval_dixon_dualreadtrap_slim (struct _dixon_dualreadtrap_s *dual_read, const char *const desc, int flip)
STATUS	ks_eval_dixon_asymtriangle_padded (struct _dixon_asymreadwave_s *asym_readwave, const char *const desc, const int tas, const int time2center, const float area_pre, const float area_acq, const float fov, const int duration) WARN_UNUSED_RESULT
STATUS	ks_eval_dixon_asymspline_padded (struct _dixon_asymreadwave_s *asym_readwave, const char *const desc, const int tas, const int time2center, const int tae, const float Apre, const float Aacq, const float Apost, const float fov, const int duration) WARN_UNUSED_RESULT
STATUS	ks_eval_dixon_asymspline (struct _dixon_asymreadwave_s *asym_readwave, const char *const desc, const int time2center, const float area, const float fov, const int duration, const float paddingarea) WARN_UNUSED_RESULT
STATUS	ks_eval_dixon_asymtriangle (struct _dixon_asymreadwave_s *asym_readwave, const char *const desc, const int ttc, const float area, const float fov, const int duration, const float paddingarea) WARN_UNUSED_RESULT
STATUS	ks_eval_readtrap1p (KS_READTRAP *readtrap, const char *const desc) WARN_UNUSED_RESULT
int	ks_eval_kynover_fromnex (int yres, float nex, int minkynover)
void	ks_eval_phaseviewtable (KS_PHASER *phaser)
STATUS	ks_eval_phaser_adjustres (KS_PHASER *phaser, const char *const desc) WARN_UNUSED_RESULT
STATUS	ks_eval_phaser_setaccel (KS_PHASER *phaser, int min_acslines, float R) WARN_UNUSED_RESULT
STATUS	ks_eval_phaser_constrained (KS_PHASER *phaser, const char *const desc, float ampmax, float slewrate, int minplateautime) WARN_UNUSED_RESULT
STATUS	ks_eval_phaser (KS_PHASER *phaser, const char *const desc) WARN_UNUSED_RESULT
STATUS	ks_eval_phaser2 (KS_PHASER *phaser, const char *const desc) WARN_UNUSED_RESULT
STATUS	ks_eval_phaser1 (KS_PHASER *phaser, const char *const desc) WARN_UNUSED_RESULT
STATUS	ks_eval_phaser1p (KS_PHASER *phaser, const char *const desc) WARN_UNUSED_RESULT
STATUS	ks_eval_wave (KS_WAVE *wave, const char *const desc, int res, int duration, KS_WAVEFORM waveform) WARN_UNUSED_RESULT
STATUS	ks_eval_mirrorwave (KS_WAVE *wave)
STATUS	ks_eval_wave_file (KS_WAVE *wave, const char *const desc, int res, int duration, const char *const filename, const char *const format) WARN_UNUSED_RESULT
STATUS	ks_eval_rf_sinc (KS_RF *rf, const char *const desc, double bw, double tbw, float flip, int wintype) WARN_UNUSED_RESULT
STATUS	ks_eval_rf_secant (KS_RF *rf, const char *const desc, float A0, float tbw, float bw)
STATUS	ks_eval_rf_hard (KS_RF *rf, const char *const desc, int duration, float flip) WARN_UNUSED_RESULT
STATUS	ks_eval_rf_hard_optimal_duration (KS_RF *rf, const char *const desc, int order, float flip, float offsetFreq) WARN_UNUSED_RESULT
STATUS	ks_eval_rf_binomial (KS_RF *rf, const char *const desc, int offResExc, int nPulses, float flip, float offsetFreq) WARN_UNUSED_RESULT
STATUS	ks_eval_rfstat (KS_RF *rf) WARN_UNUSED_RESULT
STATUS	ks_eval_rf (KS_RF *rf, const char *const desc) WARN_UNUSED_RESULT
void	ks_eval_rf_relink (KS_RF *rf)
STATUS	ks_eval_stretch_rf (KS_RF *rf, float stretch_factor)
STATUS	ks_eval_seltrap (KS_TRAP *trap, const char *const desc, float slewrate, float slthick, float bw, int rfduration) WARN_UNUSED_RESULT
STATUS	ks_eval_selrf_constrained (KS_SELRF *selrf, const char *const desc, float ampmax, float slewrate) WARN_UNUSED_RESULT
STATUS	ks_eval_selrf (KS_SELRF *selrf, const char *const desc) WARN_UNUSED_RESULT
STATUS	ks_eval_selrf2 (KS_SELRF *selrf, const char *const desc) WARN_UNUSED_RESULT
STATUS	ks_eval_selrf1 (KS_SELRF *selrf, const char *const desc) WARN_UNUSED_RESULT
STATUS	ks_eval_selrf1p (KS_SELRF *selrf, const char *const desc) WARN_UNUSED_RESULT
STATUS	ks_eval_sms_get_phase_modulation (float *sms_phase_modulation, const int sms_multiband_factor, const int sms_phase_modulation_mode) WARN_UNUSED_RESULT
float	ks_eval_findb1 (KS_SELRF *selrf, float max_b1, double scaleFactor, int sms_multiband_factor, int sms_phase_modulation_mode, float sms_slice_gap)
void	ks_eval_transient_SPGR_FA_train_recursive (float *FA_train, float *MZ_train, int N, float E1, float target_MT, int n)
void	ks_eval_transient_SPGR_FA_train_binary_search (float *FA_train, float *MZ_train, int N, float E1, float MTlo, float MThi, float total_FA)
STATUS	ks_eval_check_FA_train (int N, float *FA_train, float *MZ_train, float total_FA)
STATUS	ks_eval_transient_SPGR_FA_train (float *FA_train, int N, float TR, float T1, float total_FA)
STATUS	ks_eval_sms_make_multiband (KS_SELRF *selrfMB, const KS_SELRF *selrf, const int sms_multiband_factor, const int sms_phase_modulation_mode, const float sms_slice_gap, int debug) WARN_UNUSED_RESULT
float	ks_eval_sms_calc_slice_gap (int sms_multiband_factor, const SCAN_INFO *org_slice_positions, int nslices, float slthick, float slspace)
float	ks_eval_sms_calc_caipi_area (int caipi_fov_shift, float sms_slice_gap)
STATUS	ks_eval_sms_make_pins (KS_SELRF *selrfPINS, const KS_SELRF *selrf, float sms_slice_gap)
STATUS	ks_eval_sms_make_pins_dante (KS_SELRF *selrfPINS, const KS_SELRF *selrf, float sms_slice_gap)
int	ks_eval_findNearestNeighbourIndex (float value, const float *x, int length)
void	ks_eval_linear_interp1 (const float *x, int x_length, const float *y, const float *xx, int xx_length, float *yy)
STATUS	ks_eval_trap2wave (KS_WAVE *wave, const KS_TRAP *trap) WARN_UNUSED_RESULT
STATUS	ks_eval_append_two_waves (KS_WAVE *first_wave, KS_WAVE *second_wave) WARN_UNUSED_RESULT
STATUS	ks_eval_concatenate_waves (int num_waves, KS_WAVE *target_wave, KS_WAVE **waves_to_append) WARN_UNUSED_RESULT
STATUS	ks_eval_epi_constrained (KS_EPI *epi, const char *const desc, float ampmax, float slewrate) WARN_UNUSED_RESULT
STATUS	ks_eval_epi_setinfo (KS_EPI *epi)
STATUS	ks_eval_epi_maxamp_slewrate (float *ampmax, float *slewrate, int xres, float quietnessfactor)
STATUS	ks_eval_epi (KS_EPI *epi, const char *const desc, float quietnessfactor) WARN_UNUSED_RESULT
int	ks_eval_gradrflimits (KS_SAR *sar, KS_SEQ_COLLECTION *seqcollection, float gheatfact)
int	ks_eval_mintr (int nslices, KS_SEQ_COLLECTION *seqcollection, float gheatfact, int(*play_loop)(int, int, void **), int nargs, void **args)
int	ks_eval_maxslicespertr (int TR, KS_SEQ_COLLECTION *seqcollection, float gheatfact, int(*play_loop)(int, int, void **), int nargs, void **args)
STATUS	ks_eval_seqctrl_setminduration (KS_SEQ_CONTROL *seqctrl, int mindur)
STATUS	ks_eval_seqctrl_setduration (KS_SEQ_CONTROL *seqctrl, int dur)
STATUS	ks_eval_seqcollection_durations_setminimum (KS_SEQ_COLLECTION *seqcollection) WARN_UNUSED_RESULT
STATUS	ks_eval_seqcollection_durations_atleastminimum (KS_SEQ_COLLECTION *seqcollection) WARN_UNUSED_RESULT
void	ks_eval_seqcollection_resetninst (KS_SEQ_COLLECTION *seqcollection)
void	ks_print_seqcollection (KS_SEQ_COLLECTION *seqcollection, FILE *fp)
void	ks_print_scaninfo (const SCAN_INFO *scan_info, int nslices, const char *desc, FILE *fp)
int	ks_eval_seqcollection_gettotalduration (KS_SEQ_COLLECTION *seqcollection)
int	ks_eval_seqcollection_gettotalminduration (KS_SEQ_COLLECTION *seqcollection)
STATUS	ks_eval_seqcollection2rfpulse (RF_PULSE *rfpulse, KS_SEQ_COLLECTION *seqcollection)
GRAD_PULSE	ks_eval_makegradpulse (KS_TRAP *trp, int gradchoice)
void	ks_read_header_pool (int *exam_number, int *series_number, int *run_number)
unsigned int	ks_calc_nextpow2 (unsigned int x)
int	ks_calc_roundupms (int time)
STATUS	ks_calc_filter (FILTER_INFO *echo_filter, int tsp, int duration) WARN_UNUSED_RESULT
int	ks_calc_bw2tsp (float bw)
float	ks_calc_tsp2bw (int tsp)
int	ks_calc_trap_time2area (KS_TRAP *trap, float area)
float	ks_calc_nearestbw (float bw)
float	ks_calc_lower_rbw (float rbw)
float	ks_calc_higher_rbw (float rbw)
float	ks_calc_max_rbw (float ampmax, float fov)
float	ks_calc_minfov (float ampmax, int tsp)
float	ks_calc_minslthick (float bw)
int	ks_calc_mintsp (float ampmax, float fov)
float	ks_calc_fov2gradareapixel (float fov)
int	ks_calc_dixon_times_within_one_period (float t1, float t2, float B0)
float	ks_calc_dixon_fat_nsa_2p (float t1, float t2, float B0, float F)
float	ks_calc_dixon_water_nsa_2p (float t1, float t2, float B0, float W)
double	ks_calc_dixon_cond_2p (double t1, double t2, double B0)
float	ks_calc_dixon_mean_nsa_2p_ss (float t1, float t2, float B0)
float	ks_calc_dixon_mean_nsa_2p_ss_weighted (float t1, float t2, float B0, float w1, float w2)
void	ks_phaseencoding_init_tgt (KS_PHASEENCODING_PLAN *phaseenc_plan_ptr)
KS_PHASEENCODING_COORD	ks_phaseencoding_get (const KS_PHASEENCODING_PLAN *phaseenc_plan_ptr, int echo, int shot)
void	ks_phaseencoding_set (KS_PHASEENCODING_PLAN *phaseenc_plan_ptr, int echo, int shot, int ky, int kz)
void	ks_phaseencoding_print (const KS_PHASEENCODING_PLAN *phaseenc_plan_ptr)
STATUS	ks_phaseencoding_resize (KS_PHASEENCODING_PLAN *phaseenc_plan_ptr, int etl, int num_shots)
STATUS	ks_phaseencoding_generate_simple (KS_PHASEENCODING_PLAN *phaseenc_plan_ptr, const char *const desc, KS_PHASER *phaser, KS_PHASER *zphaser)
STATUS	ks_phaseencoding_generate_simple_ellipse (KS_PHASEENCODING_PLAN *phaseenc_plan_ptr, const char *const desc, KS_PHASER *phaser, KS_PHASER *zphaser)
STATUS	ks_fse_calcecho (double *bestecho, double *optecho, int *nacqlines_to_kspacecenter, KS_PHASER *pe, ks_enum_pf_earlylate_te pf_direction, int TE, int etl, int esp)
STATUS	ks_phaseencoding_generate_2Dfse (KS_PHASEENCODING_PLAN *phaseenc_plan_ptr, const char *const desc, KS_PHASER *phaser, KS_PHASER *zphaser, ks_enum_pf_earlylate_te pf_direction, int TE, int etl, int esp)
STATUS	ks_phaseencoding_generate_epi (KS_PHASEENCODING_PLAN *phaseenc_plan_ptr, const char *const desc, const KS_EPI *epitrain, const ks_enum_epiblipsign blipsign, const ks_enum_pf_earlylate_te pf_direction, const int numileavestoacq, ks_enum_sweep_order sweep_order, int numsegments, const int caipi_delta)
STATUS	ks_phaseencoding_generate_allepiplans (KS_PHASEENCODING_ALLEPIPLANS phaseenc_plans, const char *const desc, const KS_EPI *epitrain, const int caipi_delta)
STATUS	ks_phaseencoding_allepiplans_setechoes (KS_PHASEENCODING_PLAN_16PTRS peplan_echoes, KS_PHASEENCODING_ALLEPIPLANS allepiplans, int nechoes, int multishot_flag, int min1stTE, int mirrorTE, ks_enum_epiblipsign blipsign)
STATUS	ks_calc_sliceplan (KS_SLICE_PLAN *slice_plan, int nslices, int slperpass)
STATUS	ks_calc_sliceplan_interleaved (KS_SLICE_PLAN *slice_plan, int nslices, int slperpass, int inpass_interleaves)
STATUS	ks_calc_sliceplan_sms (KS_SLICE_PLAN *slice_plan, int nslices, int slperpass, int multiband_factor)
int	ks_calc_slice_acquisition_order_smssingleacq (DATA_ACQ_ORDER *dacq, int nslices)
int	ks_calc_sms_min_gap (DATA_ACQ_ORDER *dacq, int nslices)
void	ks_print_sliceplan (const KS_SLICE_PLAN slice_plan, FILE *fp)
void	ks_print_waveform (const KS_WAVEFORM waveform, const char *filename, int res)
void	ks_print_read (KS_READ read, FILE *fp)
void	ks_print_trap (KS_TRAP trap, FILE *fp)
void	ks_print_readtrap (KS_READTRAP readtrap, FILE *fp)
void	ks_print_phaser (KS_PHASER phaser, FILE *fp)
void	ks_print_epi (KS_EPI epi, FILE *fp)
void	ks_print_rf (KS_RF rf, FILE *fp)
void	ks_print_rfpulse (RF_PULSE rfpulse, FILE *fp)
void	ks_print_selrf (KS_SELRF selrf, FILE *fp)
void	ks_print_gradrfctrl (KS_GRADRFCTRL gradrfctrl, FILE *fp)
STATUS	ks_error (const char *format,...) __attribute__((format(printf
STATUS STATUS	ks_dbg (const char *format,...) __attribute__((format(printf
STATUS STATUS STATUS	existfile (const char *fname)
int	ks_syslimits_hasICEhardware ()
void	ks_dbg_reset ()
float	ks_syslimits_ampmax (LOG_GRAD loggrd)
float	ks_syslimits_ampmax2 (LOG_GRAD loggrd)
float	ks_syslimits_ampmax1 (LOG_GRAD loggrd)
float	ks_syslimits_ampmax1p (LOG_GRAD loggrd)
int	ks_syslimits_ramptimemax (LOG_GRAD loggrd)
float	ks_syslimits_slewrate (LOG_GRAD loggrd)
float	ks_syslimits_slewrate2 (LOG_GRAD loggrd)
float	ks_syslimits_slewrate1 (LOG_GRAD loggrd)
float	ks_syslimits_slewrate1p (LOG_GRAD loggrd)
float	ks_syslimits_gradtarget (LOG_GRAD loggrd, int board)
float	ks_syslimits_ampmax_phys ()
int	ks_syslimits_ramptimemax_phys ()
float	ks_syslimits_slewrate_phys ()
short	ks_phase_radians2hw (float radphase)
short	ks_phase_degrees2hw (float degphase)
float	ks_calc_selgradamp (float rfbw, float slthick)
int	ks_wave_res (const KS_WAVE *wave)
float	ks_waveform_max (const KS_WAVEFORM waveform, int res)
float	ks_wave_max (const KS_WAVE *wave)
float	ks_waveform_min (const KS_WAVEFORM waveform, int res)
float	ks_wave_min (const KS_WAVE *wave)
float	ks_waveform_absmax (const KS_WAVEFORM waveform, int res)
float	ks_waveform_maxslew (const KS_WAVEFORM waveform, int res, int duration)
float	ks_wave_maxslew (const KS_WAVE *wave)
short	ks_iwave_absmax (const KS_IWAVE waveform, int res)
float	ks_wave_absmax (const KS_WAVE *wave)
float	ks_waveform_area (const KS_WAVEFORM waveform, int start, int end, int dwelltime)
float	ks_wave_area (const KS_WAVE *wave, int start, int end)
float	ks_waveform_sum (const KS_WAVEFORM waveform, int res)
float	ks_wave_sum (const KS_WAVE *wave)
float	ks_waveform_norm (const KS_WAVEFORM waveform, int res)
float	ks_wave_norm (const KS_WAVE *wave)
void	ks_waveform_cumsum (KS_WAVEFORM cumsumwaveform, const KS_WAVEFORM waveform, int res)
void	ks_wave_cumsum (KS_WAVE *cumsumwave, const KS_WAVE *wave)
void	ks_waveform_multiply (KS_WAVEFORM waveform_mod, const KS_WAVEFORM waveform, int res)
void	ks_wave_multiply (KS_WAVE *wave_mod, const KS_WAVE *wave)
void	ks_waveform_add (KS_WAVEFORM waveform_mod, const KS_WAVEFORM waveform, int res)
void	ks_wave_add (KS_WAVE *wave_mod, const KS_WAVE *wave)
void	ks_waveform_multiplyval (KS_WAVEFORM waveform, float val, int res)
void	ks_wave_multiplyval (KS_WAVE *wave, float val)
void	ks_waveform_addval (KS_WAVEFORM waveform, float val, int res)
void	ks_wave_addval (KS_WAVE *wave, float val)
STATUS	ks_waveform2iwave (KS_IWAVE iwave, const KS_WAVEFORM waveform, int res, int board) WARN_UNUSED_RESULT
STATUS	ks_wave2iwave (KS_IWAVE iwave, const KS_WAVE *wave, int board) WARN_UNUSED_RESULT
WF_PULSE *	ks_pg_echossp (WF_PULSE *echo, const char *suffix)
STATUS	ks_pg_trap (KS_TRAP *trap, KS_SEQLOC loc, KS_SEQ_CONTROL *ctrl) WARN_UNUSED_RESULT
STATUS	ks_pg_read (KS_READ *read, int pos, KS_SEQ_CONTROL *ctrl) WARN_UNUSED_RESULT
STATUS	ks_pg_phaser (KS_PHASER *phaser, KS_SEQLOC loc, KS_SEQ_CONTROL *ctrl) WARN_UNUSED_RESULT
STATUS	ks_pg_readtrap (KS_READTRAP *readtrap, KS_SEQLOC loc, KS_SEQ_CONTROL *ctrl) WARN_UNUSED_RESULT
STATUS	ks_pg_wave (KS_WAVE *wave, KS_SEQLOC loc, KS_SEQ_CONTROL *ctrl) WARN_UNUSED_RESULT
STATUS	ks_pg_rf (KS_RF *rf, KS_SEQLOC loc, KS_SEQ_CONTROL *ctrl) WARN_UNUSED_RESULT
STATUS	ks_pg_selrf (KS_SELRF *selrf, KS_SEQLOC loc, KS_SEQ_CONTROL *ctrl) WARN_UNUSED_RESULT
STATUS	ks_pg_wait (KS_WAIT *wait, KS_SEQLOC loc, KS_SEQ_CONTROL *ctrl) WARN_UNUSED_RESULT
STATUS	ks_pg_isirot (KS_ISIROT *isirot, SCAN_INFO scan_info, int pos, void(*rotfun)(), KS_SEQ_CONTROL *ctrl) WARN_UNUSED_RESULT
STATUS	ks_pg_epi_dephasers (KS_EPI *epi, KS_SEQLOC loc, KS_SEQ_CONTROL *ctrl) WARN_UNUSED_RESULT
STATUS	ks_pg_epi_rephasers (KS_EPI *epi, KS_SEQLOC loc, KS_SEQ_CONTROL *ctrl) WARN_UNUSED_RESULT
STATUS	ks_pg_epi_echo (KS_EPI *epi, KS_SEQLOC loc, KS_SEQ_CONTROL *ctrl) WARN_UNUSED_RESULT
STATUS	ks_pg_epi (KS_EPI *epi, KS_SEQLOC loc, KS_SEQ_CONTROL *ctrl) WARN_UNUSED_RESULT
void	ks_mat4_zero (KS_MAT4x4 m)
void	ks_mat4_identity (KS_MAT4x4 m)
void	ks_mat4_print (const KS_MAT4x4 m)
void	ks_mat4_multiply (KS_MAT4x4 lhs, const KS_MAT4x4 rhs_left, const KS_MAT4x4 rhs_right)
void	ks_mat4_invert (KS_MAT4x4 lhs, const KS_MAT4x4 rhs)
void	ks_mat4_setgeometry (KS_MAT4x4 lhs, float x, float y, float z, float xr, float yr, float zr)
void	ks_mat4_setrotation1axis (KS_MAT4x4 rhs, float rot, char axis)
void	ks_mat4_extractrotation (KS_MAT3x3 R, const KS_MAT4x4 M)
void	ks_mat4_extracttranslation (double *T, const KS_MAT4x4 M)
void	ks_mat3_identity (KS_MAT3x3 m)
void	ks_mat3_multiply (KS_MAT3x3 lhs, const KS_MAT3x3 rhs_left, const KS_MAT3x3 rhs_right)
void	ks_mat3_print (const KS_MAT3x3 m)
void	ks_mat3_apply (double *w, const KS_MAT3x3 R, const double *v)
void	ks_mat3_invapply (double *w, const KS_MAT3x3 R, const double *v)
void	ks_scan_update_slice_location (SCAN_INFO *new_loc, const SCAN_INFO orig_loc, const KS_MAT4x4 M_physical, const KS_MAT4x4 M_logical)
void	ks_scan_rotate (SCAN_INFO slice_info)
void	ks_scan_isirotate (KS_ISIROT *isirot)
STATUS	ks_pg_fse_flip_angle_taperoff (double *flip_angles, int etl, double flip1, double flip2, double flip3, double target_flip, int start_middle)
void	ks_pg_mod_fse_rfpulse_structs (KS_SELRF *rf1, KS_SELRF *rf2, KS_SELRF *rf3, const double *flip_angles, const int etl)
void	ks_instancereset_trap (KS_TRAP *trap)
void	ks_instancereset_wait (KS_WAIT *wait)
void	ks_instancereset_phaser (KS_PHASER *phaser)
void	ks_instancereset_readtrap (KS_READTRAP *readtrap)
void	ks_instancereset_rf (KS_RF *rf)
void	ks_instancereset_selrf (KS_SELRF *selrf)
void	ks_instancereset_epi (KS_EPI *epi)
int	ks_compare_wfi_by_timeboard (const KS_WFINSTANCE *a, const KS_WFINSTANCE *b)
int	ks_compare_wfi_by_boardtime (const KS_WFINSTANCE *a, const KS_WFINSTANCE *b)
int	ks_compare_wfp_by_time (const WF_PULSE *a, const WF_PULSE *b)
int	ks_compare_pint (const void *v1, const void *v2)
int	ks_compare_pshort (const void *v1, const void *v2)
int	ks_compare_pfloat (const void *v1, const void *v2)
int	ks_compare_int (const void *v1, const void *v2)
int	ks_compare_short (const void *v1, const void *v2)
int	ks_compare_float (const void *v1, const void *v2)
void	ks_sort_getsortedindx (int *sortedindx, int *array, int n)
void	ks_sort_getsortedindx_s (int *sortedindx, short *array, int n)
void	ks_sort_getsortedindx_f (int *sortedindx, float *array, int n)
void	ks_sort_wfi_by_timeboard (KS_WFINSTANCE *a, int nitems)
void	ks_sort_wfi_by_boardtime (KS_WFINSTANCE *a, int nitems)
void	ks_sort_wfp_by_time (WF_PULSE *a, int nitems)
int	ks_file_exist (char *filename)
void	ks_plot_host_slicetime_delete ()
void	ks_plot_slicetime_begin ()
void	ks_plot_slicetime (KS_SEQ_CONTROL *ctrl, int nslices, float *slicepos_mm, float slthick_mm, KS_PLOT_EXCITATION_MODE exctype)
void	ks_plot_slicetime_endofslicegroup (const char *desc)
void	ks_plot_slicetime_endofslicegroup_tagged (const char *desc, const KS_PLOT_SLICEGROUP_MODE tag)
void	ks_plot_slicetime_endofpass (KS_PLOT_PASS_MODE)
void	ks_plot_slicetime_end ()
void	ks_plot_host_slicetime_begin ()
void	ks_plot_host_slicetime (KS_SEQ_CONTROL *ctrl, int nslices, float *slicepos_mm, float slthick_mm, KS_PLOT_EXCITATION_MODE exctype)
void	ks_plot_host_slicetime_endofslicegroup (const char *desc, const KS_PLOT_SLICEGROUP_MODE tag)
void	ks_plot_host_slicetime_endofpass (KS_PLOT_PASS_MODE)
void	ks_plot_host_slicetime_end ()
void	ks_plot_host (KS_SEQ_COLLECTION *seqcollection, KS_PHASEENCODING_PLAN *plan)
void	ks_plot_host_seqctrl (KS_SEQ_CONTROL *ctrl, KS_PHASEENCODING_PLAN *plan)
void	ks_plot_host_seqctrl_manyplans (KS_SEQ_CONTROL *ctrl, KS_PHASEENCODING_PLAN **plan, const int num_plans)
void	ks_plot_tgt_reset (KS_SEQ_CONTROL *ctrl)
void	ks_plot_tgt_addframe (KS_SEQ_CONTROL *ctrl)
void	ks_scan_rf_ampscale (KS_RF *rf, int instanceno, float ampscale)
void	ks_scan_rf_on (KS_RF *rf, int instanceno)
void	ks_scan_rf_on_chop (KS_RF *rf, int instanceno)
void	ks_scan_rf_off (KS_RF *rf, int instanceno)
void	ks_scan_selrf_setfreqphase (KS_SELRF *selrf, int instanceno, SCAN_INFO sliceinfo, float rfphase)
void	ks_scan_selrf_setfreqphase_pins (KS_SELRF *selrf, int instanceno, SCAN_INFO sliceinfo, int sms_multiband_factor, float sms_slice_gap, float rfphase)
void	ks_scan_rf_setphase (KS_RF *rf, int instanceno, float rfphase)
void	ks_scan_wave2hardware (KS_WAVE *wave, const KS_WAVEFORM newwave)
void	ks_scan_offsetfov_iso (KS_READTRAP *readtrap, int instanceno, SCAN_INFO sliceinfo, double ky, double kz, double rcvphase)
void	ks_scan_offsetfov (KS_READTRAP *readtrap, int instanceno, SCAN_INFO sliceinfo, float view, float phasefovratio, float rcvphase)
void	ks_scan_offsetfov3D (KS_READTRAP *readtrap, int instanceno, SCAN_INFO sliceinfo, float kyview, float phasefovratio, float kzview, float zphasefovratio, float rcvphase)
void	ks_scan_offsetfov_readwave (KS_READWAVE *readwave, int instanceno, SCAN_INFO sliceinfo, float kyview, float phasefovratio, float rcvphase)
void	ks_scan_omegatrap_hz (KS_TRAP *trap, int instanceno, float Hz)
void	ks_scan_omegawave_hz (KS_WAVE *wave, int instanceno, float Hz)
void	ks_scan_wait (KS_WAIT *wait, int waitperiod)
void	ks_scan_trap_ampscale (KS_TRAP *trap, int instanceno, float ampscale)
void	ks_scan_trap_ampscale_slice (KS_TRAP *trap, int start, int skip, int count, float ampscale)
void	ks_scan_phaser_kmove (KS_PHASER *phaser, int instanceno, double pixelunits)
void	ks_scan_phaser_toline (KS_PHASER *phaser, int instanceno, int view)
void	ks_scan_phaser_fromline (KS_PHASER *phaser, int instanceno, int view)
int	ks_scan_getsliceloc (const KS_SLICE_PLAN *slice_plan, int passindx, int sltimeinpass)
int	ks_scan_getslicetime (const KS_SLICE_PLAN *slice_plan, int passindx, int slloc)
ks_enum_epiblipsign	ks_scan_epi_verify_phaseenc_plan (KS_EPI *epi, KS_PHASEENCODING_PLAN *phaseenc_plan, int shot)
void	ks_scan_epi_shotcontrol (KS_EPI *epi, int echo, SCAN_INFO sliceinfo, KS_PHASEENCODING_PLAN *phaseenc_plan, int shot, int exc, float rcvphase)
void	ks_scan_epi_loadecho_with_tag (KS_EPI *epi, int echo, int storeecho, int slice, KS_PHASEENCODING_PLAN *phaseenc_plan, int shot, KSEPI_DATATAG *datatag, KS_DATASTORETAG *datastoretag)
void	ks_scan_epi_loadecho_with_datastoretag (KS_EPI *epi, int echo, int storeecho, int slice, KS_PHASEENCODING_PLAN *phaseenc_plan, int shot, KS_DATASTORETAG *datastoretag)
void	ks_scan_epi_loadecho_with_epidatatag (KS_EPI *epi, int echo, int storeecho, int slice, KS_PHASEENCODING_PLAN *phaseenc_plan, int shot, KSEPI_DATATAG *datatag)
void	ks_scan_epi_loadecho (KS_EPI *epi, int echo, int storeecho, int slice, KS_PHASEENCODING_PLAN *phaseenc_plan, int shot)
void	ks_loaddab (WF_PULSE_ADDR echo, char *dab_array)
void	ks_loaddab_datastoretag (WF_PULSE_ADDR echo, KS_DATASTORETAG *datastoretag)
void	ks_scan_acq_to_rtp (KS_READ *read, TYPDAB_PACKETS dabacqctrl, float fatoffset)
void	ks_scan_switch_to_sequence (KS_SEQ_CONTROL *ctrl)
int	ks_scan_playsequence (KS_SEQ_CONTROL *ctrl)
STATUS	ks_scan_loaddabwithindices (WF_PULSE_ADDR pulse, LONG slice, LONG echo, LONG view, uint8_t acq, uint8_t vol, TYPDAB_PACKETS acqon_flag)
STATUS	ks_scan_loaddabwithindices_nex (WF_PULSE_ADDR pulse, LONG slice, LONG echo, LONG view, uint8_t acq, uint8_t vol, LONG operation, TYPDAB_PACKETS acqon_flag)
int	ks_scan_wait_for_rtp (void *rtpmsg, int maxmsgsize, int maxwait, KS_SEQ_CONTROL *waitctrl)
void	ks_copy_and_reset_obj (void *pobj)
void	ks_show_clock (FLOAT scantime)
float	ks_scan_rf_phase_spoiling (int counter)
void	ks_tgt_reset_gradrfctrl (KS_GRADRFCTRL *gradrfctrl)
int	ks_eval_clear_readwave (KS_READWAVE *readwave)
int	ks_eval_clear_dualreadtrap (KS_DIXON_DUALREADTRAP *dual_read)
void	ks_polyval (const double *coeffs, const int order, const float *x, const int numx, float *values)

Variables
int	abort_on_kserror
int	ks_rhoboard
LOG_GRAD	loggrd
PHYS_GRAD	phygrd
int	pscR1
int	rspent

Detailed Description

This file contains the most documentation, and contains all definitions, sequence objects (typedef structs) and function prototypes for KSFoundation. @inline this file in the main sequence.

Macro Definition Documentation

WARN_UNUSED_RESULT

#define WARN_UNUSED_RESULT

Compiler flag for DV25 and higher, causing a compiler error if the returned function value is not used by the calling function

DEFAULT_SCAN_INFO_HEAD

#define DEFAULT_SCAN_INFO_HEAD   0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 1.0, 1.0, 1.0

DEFAULT_SCAN_INFO_TAIL

#define DEFAULT_SCAN_INFO_TAIL

DEFAULT_AXIAL_SCAN_INFO

#define DEFAULT_AXIAL_SCAN_INFO

Value:

{ DEFAULT_SCAN_INFO_HEAD, {1.0, 0.0, 0.0, \
                                                           0.0, 1.0, 0.0, \
                                                           0.0, 0.0, 1.0}, DEFAULT_SCAN_INFO_TAIL}

DEFAULT_AX_SCAN_INFO_FREQ_LR

#define DEFAULT_AX_SCAN_INFO_FREQ_LR   DEFAULT_AXIAL_SCAN_INFO

DEFAULT_AX_SCAN_INFO_FREQ_AP

#define DEFAULT_AX_SCAN_INFO_FREQ_AP

Value:

{ DEFAULT_SCAN_INFO_HEAD, {0.0, 1.0, 0.0, \
                                                               -1.0, 0.0, 0.0, \
                                                                0.0, 0.0, 1.0}, DEFAULT_SCAN_INFO_TAIL}

DEFAULT_SAG_SCAN_INFO_FREQ_SI

#define DEFAULT_SAG_SCAN_INFO_FREQ_SI

Value:

{ DEFAULT_SCAN_INFO_HEAD, {0.0, 0.0, 1.0, \
                                                                 0.0, 1.0, 0.0, \
                                                                -1.0, 0.0, 0.0}, DEFAULT_SCAN_INFO_TAIL}

DEFAULT_SAG_SCAN_INFO_FREQ_AP

#define DEFAULT_SAG_SCAN_INFO_FREQ_AP

Value:

{ DEFAULT_SCAN_INFO_HEAD, {0.0, 0.0, 1.0, \
                                                                 1.0, 0.0, 0.0, \
                                                                 0.0, 1.0, 0.0}, DEFAULT_SCAN_INFO_TAIL}

DEFAULT_COR_SCAN_INFO_FREQ_SI

#define DEFAULT_COR_SCAN_INFO_FREQ_SI

Value:

{ DEFAULT_SCAN_INFO_HEAD, {0.0, 1.0, 0.0, \
                                                                 0.0, 0.0, 1.0, \
                                                                 1.0, 0.0, 0.0}, DEFAULT_SCAN_INFO_TAIL}

DEFAULT_COR_SCAN_INFO_FREQ_LR

#define DEFAULT_COR_SCAN_INFO_FREQ_LR

Value:

{ DEFAULT_SCAN_INFO_HEAD, {-1.0, 0.0, 0.0, \
                                                                  0.0, 0.0, 1.0, \
                                                                  0.0, 1.0, 0.0}, DEFAULT_SCAN_INFO_TAIL}

KS_NOTSET

#define KS_NOTSET   -1

Unrealistic value used on some variables to trigger errors

KS_INFINITY

#define KS_INFINITY   (1.0/0.0)

Infinity

_cvdesc

#define _cvdesc	(		cv,
			string
	)

Value:

{\
    if( NULL != string ) {\
        if( FALSE == (cv)->staticdescrflag ) {\
            free( (void *)((cv)->descr) );\
        }\
        (cv)->descr = strdup( string );\
        (cv)->staticdescrflag = FALSE;\
    }\
}

areSame

#define areSame	(		a,
			b
	)		(fabs((a) - (b)) < 1e-5)

isNotSet

#define isNotSet

(

a

)

areSame((a), KS_NOTSET)

isSet

#define isSet

(

a

)

!isNotSet(a)

KS_ISI_predelay

#define KS_ISI_predelay   256

KS_ISI_time

#define KS_ISI_time   256

KS_ISI_rotupdatetime

#define KS_ISI_rotupdatetime   12

KS_ISI_postdelay

#define KS_ISI_postdelay   256

KS_MINPLATEAUTIME

#define KS_MINPLATEAUTIME   8

Shortest plateautime of a trapezoid (KS_TRAP)

KS_DEFAULT_SSI_TIME

#define KS_DEFAULT_SSI_TIME   1500

KS_DEFAULT_SSI_TIME_MR750w

#define KS_DEFAULT_SSI_TIME_MR750w   500

KS_DEFAULT_SSI_TIME_MR750

#define KS_DEFAULT_SSI_TIME_MR750   1000

KS_DEFAULT_SSI_TIME_MR450W

#define KS_DEFAULT_SSI_TIME_MR450W   500

KS_DEFAULT_SSI_TIME_MR450

#define KS_DEFAULT_SSI_TIME_MR450   1000

KS_DEFAULT_SSI_TIME_PREMIER

#define KS_DEFAULT_SSI_TIME_PREMIER   500

KS_DEFAULT_SSI_TIME_ICE

#define KS_DEFAULT_SSI_TIME_ICE   200

KS_DEFAULT_SSI_TIME_OTHERWISE

#define KS_DEFAULT_SSI_TIME_OTHERWISE   1500

KS_RFSSP_PRETIME

#define KS_RFSSP_PRETIME   64

Time in [us] before an RF pulse that is needed for SSP packets. May sometimes be taken into account

KS_RFSSP_POSTTIME

#define KS_RFSSP_POSTTIME   56

Time in [us] after an RF pulse that is needed for SSP packets. May sometimes be taken into account

KS_RF_STANDARD_CRUSHERAREA

#define KS_RF_STANDARD_CRUSHERAREA   2000.0

KS_EPI_MIN_INTERTRAIN_SSPGAP

#define KS_EPI_MIN_INTERTRAIN_SSPGAP   80

EXPERIMENTAL. Check how the SSP packets in the beginning/end of the EPI train can be packed to minimize this one for all possible acq. parameters

L_REF

#define L_REF   10

PSD_HRMW_COIL

#define PSD_HRMW_COIL   13

HAVE_PREMIER_GRADIENTS

#define HAVE_PREMIER_GRADIENTS   (cfgcoiltype == PSD_HRMW_COIL)

HALF_KHZ_USEC

#define HALF_KHZ_USEC   500.0

KS_SAVEPFILES

#define KS_SAVEPFILES   RHXC_AUTO_LOCK

Bit for rhexecctrl to dump Pfiles

KS_GERECON

#define KS_GERECON   (RHXC_AUTO_DISPLAY+RHXC_XFER_IM)

Bit for rhexecctrl for GE product image reconstruction

KS_3D_SELECTED

#define KS_3D_SELECTED   (opimode == PSD_3D || opimode == PSD_3DM)

KS_3D_SINGLESLAB_SELECTED

#define KS_3D_SINGLESLAB_SELECTED   (opimode == PSD_3D)

KS_3D_MULTISLAB_SELECTED

#define KS_3D_MULTISLAB_SELECTED   (opimode == PSD_3DM)

KS_DESCRIPTION_LENGTH

#define KS_DESCRIPTION_LENGTH   128

Max # of characters in the description of the various sequence objects

KS_MAXWAVELEN

#define KS_MAXWAVELEN   10000

KS_MAXWAVELEN (10000) sample points

KS_MAXUNIQUE_RF

#define KS_MAXUNIQUE_RF   20

Maximum number of different RF pulses in the sequence (c.f. also grad_rf_empty**.h)

KS_MAXUNIQUE_TRAP

#define KS_MAXUNIQUE_TRAP   200

Maximum number of different KS_TRAPs in the sequence

KS_MAXUNIQUE_WAVE

#define KS_MAXUNIQUE_WAVE   200

Maximum number of different KS_WAVEs in the sequence

KS_MAXUNIQUE_SEQUENCES

#define KS_MAXUNIQUE_SEQUENCES   200

Maximum number of pulses sequence modules, including core, (i.e. with own SEQLENGTH/bofffset()) in this pulse sequence

KS_MAX_PHASEDYN

#define KS_MAX_PHASEDYN   2049

Maximum number of phase encoding steps in a KS_PHASER sequence object

KS_MAXUNIQUE_READ

#define KS_MAXUNIQUE_READ   500

Maximum number of readout instances

KS_MAXINSTANCES

#define KS_MAXINSTANCES   500

KS_EPI_MINBLIPAREA

#define KS_EPI_MINBLIPAREA   100

Default value of lowest EPI blip area until blip is made wider to avoid discretization errors

KS_INITZEROS

#define KS_INITZEROS

(

n

)

{[0 ... (n-1)] = 0}

C macro to initialize arrays with zeros at declaration

KS_INITVALUE

#define KS_INITVALUE	(		n,
			a
	)		{[0 ... (n-1)] = a}

C macro to initialize each element in an array with a number at declaration

KS_INIT_DESC

#define KS_INIT_DESC   KS_INITZEROS(KS_DESCRIPTION_LENGTH)

Default values for KS_DESCRIPTION strings

KS_INIT_SEQLOC

#define KS_INIT_SEQLOC   {KS_NOTSET, KS_NOTSET, 1.0, 1.0}

Default values for KS_SEQLOC structs

KS_INIT_WFINSTANCE

#define KS_INIT_WFINSTANCE   {NULL, 0, NULL, {KS_INIT_SEQLOC}}

Default values for KS_WFINSTANCE structs (internal use)

KS_INIT_WAIT

#define KS_INIT_WAIT   {{0,0,NULL,sizeof(KS_WAIT)}, KS_INIT_DESC, 0, KS_INITVALUE(KS_MAXINSTANCES, KS_INIT_SEQLOC), NULL, NULL}

Default values for KS_WAIT sequence objects

KS_INIT_ISIROT

#define KS_INIT_ISIROT   {KS_INIT_WAIT, KS_INIT_WAIT, NULL, 0, 0, 0, 0}

KS_INIT_TRAP

#define KS_INIT_TRAP   {{0,0,NULL,sizeof(KS_TRAP)}, KS_INIT_DESC, 0.0, 0.0, 0, 0, 0, {0, 0, 0}, {0, 0, 0}, {1, 1, 1}, KS_INITVALUE(KS_MAXINSTANCES,KS_INIT_SEQLOC), NULL, NULL, NULL}

Default values for KS_TRAP sequence objects

KS_INIT_READ

#define KS_INIT_READ   {{0,0,NULL,sizeof(KS_READ)}, KS_INIT_DESC, 0, KS_NOTSET, {0.0, 0, 0.0, 0.0, KS_NOTSET, 0, 0, 0}, KS_INITVALUE(KS_MAXINSTANCES,KS_NOTSET), 0, NULL}

Default values for KS_READ sequence objects

KS_INIT_READ_EPI

#define KS_INIT_READ_EPI   {{0,0,NULL,sizeof(KS_READ)}, KS_INIT_DESC, 0, 250.0, {0.0, 0, 0.0, 0.0, KS_NOTSET, 0, 0, 0}, KS_INITVALUE(KS_MAXINSTANCES,KS_NOTSET), 0, NULL}

Default values for KS_READ sequence objects in KS_EPI

KS_INIT_READTRAP

#define KS_INIT_READTRAP   {KS_INIT_READ, 240.0, 256, 0, 0, 0, 0.0, 0.0, 0.0, 0, KS_INIT_TRAP, KS_INIT_TRAP}

Default values for KS_READTRAP sequence objects

KS_INIT_READTRAP_EPI

#define KS_INIT_READTRAP_EPI   {KS_INIT_READ_EPI, 240.0, 64, 0, 0, 0, 0.0, 0.0, 0.0, 0, KS_INIT_TRAP, KS_INIT_TRAP}

Default values for the KS_READTRAP sequence objects in KS_EPI

KS_INIT_PHASEENCTABLE

#define KS_INIT_PHASEENCTABLE   KS_INITZEROS(KS_MAX_PHASEDYN)

Default values for the phase encoding table *.linetoacq* in the KS_PHASER sequence object

KS_INIT_PHASER

#define KS_INIT_PHASER   {KS_INIT_TRAP, 240.0, KS_NOTSET, 0, 1, 0, 0, 0.0, 0, KS_INIT_PHASEENCTABLE}

Default values for KS_PHASER sequence objects

KS_INIT_PHASEENCODING_COORD

#define KS_INIT_PHASEENCODING_COORD   {KS_NOTSET, KS_NOTSET}

KS_INIT_PHASEENCODING_PLAN

#define KS_INIT_PHASEENCODING_PLAN   {KS_NOTSET, KS_NOTSET, KS_INIT_DESC, NULL, NULL, NULL, FALSE}

KS_INIT_PHASEENCODING_ALLEPIPLANS

#define KS_INIT_PHASEENCODING_ALLEPIPLANS   KS_INITVALUE(KS_EPI_PEPLAN_NUMPLANS, KS_INIT_PHASEENCODING_PLAN)

KS_INIT_PHASEENCODING_PLAN_16PTRS

#define KS_INIT_PHASEENCODING_PLAN_16PTRS   KS_INITVALUE(16, NULL)

KS_INIT_EPI

#define KS_INIT_EPI   {KS_INIT_READTRAP_EPI, KS_INIT_TRAP, KS_INIT_TRAP, KS_INIT_PHASER, KS_INIT_PHASER, 1, 0, 0, 0, 0, 1.0, KS_EPI_MINBLIPAREA}

Default values for KS_EPI sequence objects

KS_INIT_WAVEVALUE

#define KS_INIT_WAVEVALUE   0

Default value for one element in a KS_WAVEFORM

KS_INIT_WAVEFORM

#define KS_INIT_WAVEFORM   KS_INITVALUE(KS_MAXWAVELEN, KS_INIT_WAVEVALUE)

Default values for KS_WAVEFORM

KS_INIT_WAVE

#define KS_INIT_WAVE   {{0,0,NULL,sizeof(KS_WAVE)}, KS_INIT_DESC, 0, 0, KS_INIT_WAVEFORM, {0,0,0}, KS_NOTSET, KS_INITVALUE(KS_MAXINSTANCES,KS_INIT_SEQLOC), NULL, NULL, NULL}

Default values for KS_WAVE sequence objects

KS_INIT_READWAVE

#define KS_INIT_READWAVE   {KS_INITVALUE(3,KS_INIT_WAVE), KS_INIT_WAVE, KS_INIT_WAVE, KS_INIT_READ, KS_INITVALUE(3, 0), KS_INITVALUE(3, 0.0), 0.0, 0.0, 0, 0, 0}

KS_INIT_DIXON_ASYMREADWAVE

#define KS_INIT_DIXON_ASYMREADWAVE   {KS_INIT_READWAVE, KS_INIT_DESC, KS_INITVALUE(2,0), 0, 0.0, 0, 0.0, KS_INITVALUE(8,0.0)}

KS_INIT_DIXON_DUALREADTRAP

#define KS_INIT_DIXON_DUALREADTRAP   {KS_INIT_READWAVE, KS_INIT_DESC, 0,0,0,0,0.0,0, KS_INITVALUE(2,0),0,0.0,0,0,0,0.0,0.0, KS_INITVALUE(4,0)}

Default values for KS_DIXON_DUALREADTRAP sequence objects

RX27_APPLY_HADAMARD

#define RX27_APPLY_HADAMARD

KS_INIT_RFPULSE

#define KS_INIT_RFPULSE   {NULL, NULL, 0.0,0.0,0.0,0.0,0.0,0,0.0,0.0,0.0,0.0,NULL,0.0,0.0,0,0,-1,0.0,NULL,0,NULL RX27_APPLY_HADAMARD}

Default values for GE's RF_PULSE structure

KS_INIT_RF

#define KS_INIT_RF   {KS_RF_ROLE_NOTSET, KS_NOTSET, KS_NOTSET, 0.0, 0.0, KS_NOTSET, KS_NOTSET, KS_NOTSET, KS_INIT_DESC, KS_INIT_RFPULSE, KS_INIT_WAVE, KS_INIT_WAVE, KS_INIT_WAVE}

Default values for KS_RF sequence objects

KS_INIT_SELRF

#define KS_INIT_SELRF   {KS_INIT_RF, KS_NOTSET, 1.0, KS_INIT_TRAP, KS_INIT_TRAP, KS_INIT_TRAP, KS_INIT_WAVE, KS_INIT_SMS_INFO}

Default values for KS_SELRF sequence objects

KS_INIT_GRADRFCTRL

#define KS_INIT_GRADRFCTRL   {KS_INITZEROS(KS_MAXUNIQUE_RF), 0, KS_INITZEROS(KS_MAXUNIQUE_TRAP), 0, KS_INITZEROS(KS_MAXUNIQUE_WAVE), 0, KS_INITZEROS(KS_MAXUNIQUE_READ), 0, FALSE /* is_cleared_on_tgt */ }

Default values for KS_GRADRFCTRL control handler

KS_INIT_SEQ_HANDLE

#define KS_INIT_SEQ_HANDLE   {NULL, 0, NULL}

Default values for the KS_SEQ_HANDLE struct

KS_INIT_SEQ_CONTROL

#define KS_INIT_SEQ_CONTROL   {0, 0, KS_DEFAULT_SSI_TIME, 0, KS_NOTSET, FALSE, KS_INIT_DESC, KS_INIT_SEQ_HANDLE, KS_INIT_GRADRFCTRL}

Default values for the KS_SEQ_CONTROL struct

KS_INIT_SEQ_COLLECTION

#define KS_INIT_SEQ_COLLECTION   {0, KS_SEQ_COLLECTION_ALLOWNEW, FALSE, KS_INITVALUE(KS_MAXUNIQUE_SEQUENCES, NULL)}

Default values for the KS_SEQ_CONTROL struct

KS_INIT_SAR

#define KS_INIT_SAR   {0, 0, 0, 0}

Default values for the KS_SAR struct

KS_INIT_SLICEPLAN

#define KS_INIT_SLICEPLAN   {0,0,0,{{0,0,0}}}

Default values for the KS_SLICE_PLAN struct

KS_INIT_SMS_INFO

#define KS_INIT_SMS_INFO   {1, 0, 0}

Default values for the KS_INIT_SMS_INFO struct

KS_INIT_LOGGRD

#define KS_INIT_LOGGRD   {0,0,0,0,0,0,{0,0,0,0,0,0},{0,0,0,0},{0,0,0,0},{0,0,0,0},{0,0,0,0},{0,0,0,0},{0,0,0,0},0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0 }

Default values for GE's loggrd struct

KS_INIT_PHYSGRD

#define KS_INIT_PHYSGRD   { 0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0, 0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0 }

Default values for GE's phygrd struct

KS_MAT3x3_IDENTITY

#define KS_MAT3x3_IDENTITY   {1,0,0,0,1,0,0,0,1}

Identity matrix initialization for KS_MAT3x3

KS_MAT4x4_IDENTITY

#define KS_MAT4x4_IDENTITY   {1,0,0,0, 0,1,0,0, 0,0,1,0, 0,0,0,1}

Identity matrix initialization for KS_MAT4x4

KS_CUSTOM_DATASTORE_LENGTH

#define KS_CUSTOM_DATASTORE_LENGTH   22

KSEPI_INIT_DATATAG

#define KSEPI_INIT_DATATAG   {0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0}

KS_INIT_DATASTORE_STRUCT_DYNAMIC

#define KS_INIT_DATASTORE_STRUCT_DYNAMIC   {-1, -1, -1, -1, -1, {0.0}}

KS_INIT_DATASTORE_STRUCT_INFO

#define KS_INIT_DATASTORE_STRUCT_INFO   {TRUE, 0}

KS_INIT_DATASTORETAG

#define KS_INIT_DATASTORETAG   {KS_INIT_DATASTORE_STRUCT_DYNAMIC, KS_INIT_DATASTORE_STRUCT_INFO, KS_INITZEROS(KS_CUSTOM_DATASTORE_LENGTH), NULL}

cvset

#define cvset	(		cv,
			min,
			max,
			def,
			desc
	)

Value:

cvmin(cv,min);\
    cvmax(cv,max);\
    cvdef(cv,def);\
    if (strcmp(desc,"")) {cvdesc(cv,desc)};\
    errornum(cv,0);\
    errorstring(cv,"");\
    if (CONCAT2(_,cv).fixedflag == 0) { cv = CONCAT2(_,cv).defval; }

Macro to set CVs directly with min/max/def

Typedef Documentation

KS_DESCRIPTION

typedef char KS_DESCRIPTION[KS_DESCRIPTION_LENGTH]

Char array used in all KS_**** sequence objects

KS_WAVEFORM

typedef float KS_WAVEFORM[KS_MAXWAVELEN]

Waveform array for RF, Theta or custom gradients

KS_IWAVE

typedef short KS_IWAVE[KS_MAXWAVELEN]

Interim short integer array to copy to hardware (internal use)

KS_MAT3x3

typedef double KS_MAT3x3[9]

Array to store a row major 3x3 matrix

KS_MAT4x4

typedef double KS_MAT4x4[16]

Array to store a row major 4x4 matrix

KS_PHASEENCODING_ALLEPIPLANS

typedef KS_PHASEENCODING_PLAN KS_PHASEENCODING_ALLEPIPLANS[KS_EPI_PEPLAN_NUMPLANS]

Readable names KS

KS_PHASEENCODING_PLAN_16PTRS

typedef KS_PHASEENCODING_PLAN* KS_PHASEENCODING_PLAN_16PTRS[16]

KS_PHASEENCODING_PLAN array containing all 8 possible phase encoding plans for EPI

Enumeration Type Documentation

KS_PLOT_FILEFORMATS

enum KS_PLOT_FILEFORMATS

Enumerator
KS_PLOT_OFF
KS_PLOT_MAKEPDF
KS_PLOT_MAKESVG
KS_PLOT_MAKEPNG

             {
  KS_PLOT_OFF,
  KS_PLOT_MAKEPDF,
  KS_PLOT_MAKESVG,
  KS_PLOT_MAKEPNG
} KS_PLOT_FILEFORMATS;

KS_PLOT_EXCITATION_MODE

enum KS_PLOT_EXCITATION_MODE

Enumerator
KS_PLOT_STANDARD
KS_PLOT_NO_EXCITATION

             {
  KS_PLOT_STANDARD,
  KS_PLOT_NO_EXCITATION
} KS_PLOT_EXCITATION_MODE;

KS_PLOT_PASS_MODE

enum KS_PLOT_PASS_MODE

Enumerator
KS_PLOT_PASS_WAS_DUMMY
KS_PLOT_PASS_WAS_CALIBRATION
KS_PLOT_PASS_WAS_STANDARD

             {
  KS_PLOT_PASS_WAS_DUMMY,
  KS_PLOT_PASS_WAS_CALIBRATION,
  KS_PLOT_PASS_WAS_STANDARD
} KS_PLOT_PASS_MODE;

KS_PLOT_SLICEGROUP_MODE

enum KS_PLOT_SLICEGROUP_MODE

Enumerator
KS_PLOT_SG_DUMMY
KS_PLOT_SG_CALIBRATION
KS_PLOT_SG_ACQUISITION
KS_PLOT_SG_NOTSET

             {
  KS_PLOT_SG_DUMMY,
  KS_PLOT_SG_CALIBRATION,
  KS_PLOT_SG_ACQUISITION,
  KS_PLOT_SG_NOTSET
} KS_PLOT_SLICEGROUP_MODE;

ks_enum_pf_earlylate_te

enum ks_enum_pf_earlylate_te

Enumerator
KS_PF_EARLY_TE
KS_PF_LATE_TE

{KS_PF_EARLY_TE, KS_PF_LATE_TE} ks_enum_pf_earlylate_te;

ks_enum_sweep_order

enum ks_enum_sweep_order

Enumerator
KS_SWEEP_ORDER_TOP_DOWN
KS_SWEEP_ORDER_BOTTOM_UP
KS_SWEEP_ORDER_CENTER_OUT
KS_SWEEP_ORDER_OUTSIDE_IN

             {KS_SWEEP_ORDER_TOP_DOWN = 0,
              KS_SWEEP_ORDER_BOTTOM_UP = 1,
              KS_SWEEP_ORDER_CENTER_OUT = 2,
              KS_SWEEP_ORDER_OUTSIDE_IN = 3} ks_enum_sweep_order;

ks_snr_mode

enum ks_snr_mode

Enumerator
KS_SNR_MEAS_OFF
KS_SNR_MEAS_FREQUENCY
KS_SNR_MEAS_PHASE

{KS_SNR_MEAS_OFF = 0, KS_SNR_MEAS_FREQUENCY = 1, KS_SNR_MEAS_PHASE = 2};

ks_enum_trapparts

enum ks_enum_trapparts

Enumerator
G_ATTACK
G_PLATEAU
G_DECAY

{G_ATTACK, G_PLATEAU, G_DECAY};

ks_enum_boarddef

enum ks_enum_boarddef

Enumerator
KS_X
KS_Y
KS_Z
KS_RHO
KS_RHO2
KS_THETA
KS_OMEGA
KS_SSP
KS_FREQX_PHASEY
KS_FREQY_PHASEX
KS_FREQX_PHASEZ
KS_FREQZ_PHASEX
KS_FREQY_PHASEZ
KS_FREQZ_PHASEY
KS_XYZ
KS_ALL

                      {KS_X = TYPXGRAD,
                       KS_Y = TYPYGRAD,
                       KS_Z = TYPZGRAD,
                       KS_RHO = TYPRHO1,
                       KS_RHO2 = TYPRHO2,
                       KS_THETA = TYPTHETA,
                       KS_OMEGA = TYPOMEGA,
                       KS_SSP = TYPSSP,
                       KS_FREQX_PHASEY,
                       KS_FREQY_PHASEX,
                       KS_FREQX_PHASEZ,
                       KS_FREQZ_PHASEX,
                       KS_FREQY_PHASEZ,
                       KS_FREQZ_PHASEY,
                       KS_XYZ,
                       KS_ALL};

ks_enum_epiblipsign

enum ks_enum_epiblipsign

Enumerator
KS_EPI_POSBLIPS
KS_EPI_NOBLIPS
KS_EPI_NEGBLIPS

{KS_EPI_POSBLIPS = 1, KS_EPI_NOBLIPS = 0, KS_EPI_NEGBLIPS = -1} ks_enum_epiblipsign; /* positive or negative blips. Don't change the enum values (+1, -1)! */

ks_enum_epiplans

enum ks_enum_epiplans

Enumerator
KS_EPI_PEPLAN_EARLYTE_BOTTOMUP_UNDERSAMPLED
KS_EPI_PEPLAN_EARLYTE_BOTTOMUP_MULTISHOT
KS_EPI_PEPLAN_EARLYTE_TOPDOWN_UNDERSAMPLED
KS_EPI_PEPLAN_EARLYTE_TOPDOWN_MULTISHOT
KS_EPI_PEPLAN_LATETE_BOTTOMUP_UNDERSAMPLED
KS_EPI_PEPLAN_LATETE_BOTTOMUP_MULTISHOT
KS_EPI_PEPLAN_LATETE_TOPDOWN_UNDERSAMPLED
KS_EPI_PEPLAN_LATETE_TOPDOWN_MULTISHOT
KS_EPI_PEPLAN_NUMPLANS

             {
  KS_EPI_PEPLAN_EARLYTE_BOTTOMUP_UNDERSAMPLED, /* 0 */
  KS_EPI_PEPLAN_EARLYTE_BOTTOMUP_MULTISHOT, /* 1 */
  KS_EPI_PEPLAN_EARLYTE_TOPDOWN_UNDERSAMPLED, /* 2 */
  KS_EPI_PEPLAN_EARLYTE_TOPDOWN_MULTISHOT, /* 3 */
  KS_EPI_PEPLAN_LATETE_BOTTOMUP_UNDERSAMPLED, /* 4 */
  KS_EPI_PEPLAN_LATETE_BOTTOMUP_MULTISHOT, /* 5 */
  KS_EPI_PEPLAN_LATETE_TOPDOWN_UNDERSAMPLED, /* 6 */
  KS_EPI_PEPLAN_LATETE_TOPDOWN_MULTISHOT, /* 7 */
  KS_EPI_PEPLAN_NUMPLANS /* 8 */
} ks_enum_epiplans; 

ks_enum_diffusion

enum ks_enum_diffusion

KS_PHASEENCODING_PLAN Array of 16 pointers to KS_PHASEENCODING_PLANS for multi-echo use

Enumerator
KS_EPI_DIFFUSION_OFF
KS_EPI_DIFFUSION_ON

{KS_EPI_DIFFUSION_OFF, KS_EPI_DIFFUSION_ON};

ks_enum_imsize

enum ks_enum_imsize

Enumerator
KS_IMSIZE_NATIVE
KS_IMSIZE_POW2
KS_IMSIZE_MIN256

{KS_IMSIZE_NATIVE, KS_IMSIZE_POW2, KS_IMSIZE_MIN256};

ks_enum_datadestination

enum ks_enum_datadestination

Enumerator
KS_DONT_SEND
KS_SENDTOBAM
KS_SENDTORTP

{KS_DONT_SEND = -1, KS_SENDTOBAM = 0, KS_SENDTORTP = 1};

ks_enum_accelmenu

enum ks_enum_accelmenu

Enumerator
KS_ACCELMENU_FRACT
KS_ACCELMENU_INT

{KS_ACCELMENU_FRACT, KS_ACCELMENU_INT};

ks_enum_rfrole

enum ks_enum_rfrole

Enumerator
KS_RF_ROLE_NOTSET
KS_RF_ROLE_EXC
KS_RF_ROLE_REF
KS_RF_ROLE_CHEMSAT
KS_RF_ROLE_SPSAT
KS_RF_ROLE_INV

{KS_RF_ROLE_NOTSET, KS_RF_ROLE_EXC, KS_RF_ROLE_REF, KS_RF_ROLE_CHEMSAT, KS_RF_ROLE_SPSAT, KS_RF_ROLE_INV};

ks_enum_sincwin

enum ks_enum_sincwin

Enumerator
KS_RF_SINCWIN_OFF
KS_RF_SINCWIN_HAMMING
KS_RF_SINCWIN_HANNING
KS_RF_SINCWIN_BLACKMAN
KS_RF_SINCWIN_BARTLETT

{KS_RF_SINCWIN_OFF, KS_RF_SINCWIN_HAMMING, KS_RF_SINCWIN_HANNING, KS_RF_SINCWIN_BLACKMAN, KS_RF_SINCWIN_BARTLETT};

ks_enum_wavebuf

enum ks_enum_wavebuf

Enumerator
KS_WF_MAIN
KS_WF_BUF1
KS_WF_BUF2
KS_WF_SIZE

{KS_WF_MAIN, KS_WF_BUF1, KS_WF_BUF2, KS_WF_SIZE};

ks_enum_smstype

enum ks_enum_smstype

Enumerator
KS_SELRF_SMS_MB
KS_SELRF_SMS_PINS
KS_SELRF_SMS_PINS_DANTE
KS_SELRF_SMS_MULTI_PINS
KS_SELRF_SMSTYPE_SIZE

                     {
  KS_SELRF_SMS_MB,
  KS_SELRF_SMS_PINS,
  KS_SELRF_SMS_PINS_DANTE,
  KS_SELRF_SMS_MULTI_PINS,
  KS_SELRF_SMSTYPE_SIZE};

ks_enum_sms_phase_mod

enum ks_enum_sms_phase_mod

Enumerator
KS_SELRF_SMS_PHAS_MOD_OFF
KS_SELRF_SMS_PHAS_MOD_PHAS
KS_SELRF_SMS_PHAS_MOD_AMPL
KS_SELRF_SMS_PHAS_MOD_QUAD
KS_SELRF_SMS_PHAS_MOD_SIZE

                           {
  KS_SELRF_SMS_PHAS_MOD_OFF,
  KS_SELRF_SMS_PHAS_MOD_PHAS,
  KS_SELRF_SMS_PHAS_MOD_AMPL,
  KS_SELRF_SMS_PHAS_MOD_QUAD,
  KS_SELRF_SMS_PHAS_MOD_SIZE};

anonymous enum

anonymous enum

Enumerator
KS_SEQ_COLLECTION_ALLOWNEW
KS_SEQ_COLLECTION_LOCKED

{KS_SEQ_COLLECTION_ALLOWNEW, KS_SEQ_COLLECTION_LOCKED};

ks_enum_grad_scaling_policy

enum ks_enum_grad_scaling_policy

Enumerator
KS_GRADWAVE_ABSOLUTE
KS_GRADWAVE_RELATIVE

{KS_GRADWAVE_ABSOLUTE, KS_GRADWAVE_RELATIVE};

Function Documentation

isNaN()

int isNaN

(

float

a

)

                   {
  return a != a;
}

ks_init_read()

void ks_init_read

(

KS_READ *

read

)

Resets a KS_READ sequence object to its default value (KS_INIT_READ)

Parameters

[out]

read

Pointer to KS_READ

Returns

void

                                 {
  KS_READ defacq = KS_INIT_READ;
  *read = defacq;
}

ks_init_trap()

void ks_init_trap

(

KS_TRAP *

trap

)

Resets a KS_TRAP sequence object to its default value (KS_INIT_TRAP)

Parameters

[out]

trap

Pointer to KS_TRAP

Returns

void

                                 {
  KS_TRAP deftrap = KS_INIT_TRAP;
  *trap = deftrap;
}

ks_init_wait()

void ks_init_wait

(

KS_WAIT *

wait

)

Resets a KS_WAIT sequence object to its default value (KS_INIT_WAIT)

Parameters

[out]

wait

Pointer to KS_WAIT

Returns

void

                                 {
  KS_WAIT defwait = KS_INIT_WAIT;
  *wait = defwait;
}

ks_init_wave()

void ks_init_wave

(

KS_WAVE *

wave

)

Resets a KS_WAVE sequence object to its default value (KS_INIT_WAVE)

Parameters

[out]

wave

Pointer to KS_WAVE

Returns

void

                                 {
  KS_WAVE defwave = KS_INIT_WAVE;
  *wave = defwave;
}

ks_init_rf()

void ks_init_rf

(

KS_RF *

rf

)

Resets a KS_RF sequence object to its default value (KS_INIT_RF)

Parameters

[out]

rf

Pointer to KS_RF

Returns

void

                           {
  KS_RF defrf = KS_INIT_RF;
  *rf = defrf;
}

ks_init_sms_info()

void ks_init_sms_info

(

KS_SMS_INFO *

sms_info

)

Resets a KS_SMS_INFO sequence object to its default value (KS_INIT_SMS_INFO)

Parameters

[out]

sms_info

Pointer to KS_SMS_INFO

Returns

void

                                             {
  KS_SMS_INFO defsms_info = KS_INIT_SMS_INFO;
  *sms_info = defsms_info;
}

ks_init_selrf()

void ks_init_selrf

(

KS_SELRF *

selrf

)

Resets a KS_SELRF sequence object to its default value (KS_INIT_SELRF)

Parameters

[out]

selrf

Pointer to KS_SELRF

Returns

void

                                    {
  KS_SELRF defselrf = KS_INIT_SELRF;
  *selrf = defselrf;
}

ks_init_readtrap()

void ks_init_readtrap

(

KS_READTRAP *

readtrap

)

Resets a KS_READTRAP sequence object to its default value (KS_INIT_READTRAP)

Parameters

[out]

readtrap

Pointer to KS_READTRAP

Returns

void

                                             {
  KS_READTRAP defread = KS_INIT_READTRAP;
  *readtrap = defread;
}

ks_init_phaser()

void ks_init_phaser

(

KS_PHASER *

phaser

)

Resets a KS_PHASER sequence object to its default value (KS_INIT_PHASER)

Parameters

[out]

phaser

Pointer to KS_PHASER

Returns

void

                                       {
  KS_PHASER defphaser = KS_INIT_PHASER;
  *phaser = defphaser;
}

ks_init_epi()

void ks_init_epi

(

KS_EPI *

epi

)

Resets a KS_EPI sequence object to its default value (KS_INIT_EPI)

Parameters

[out]

epi

Pointer to KS_EPI

Returns

void

                              {
  KS_EPI defepi = KS_INIT_EPI;
  *epi = defepi;
}

ks_init_dixon_asymreadwave()

void ks_init_dixon_asymreadwave

(

KS_DIXON_ASYMREADWAVE *

asymreadwave

)

Resets a KS_DIXON_ASYMREADWAVE sequence object to its default value (KS_INIT_DIXON_ASYMREADWAVE)

Parameters

[in,out]

asymreadwave

Pointer to KS_DIXON_ASYMREADWAVE

Returns

void

                                                                     {
  KS_DIXON_ASYMREADWAVE def_asymreadwave = KS_INIT_DIXON_ASYMREADWAVE;
  *asymreadwave = def_asymreadwave;
}

ks_init_dixon_dualreadtrap()

void ks_init_dixon_dualreadtrap

(

KS_DIXON_DUALREADTRAP *

dual_readtrap

)

Resets a KS_DIXON_DUALREADTRAP sequence object to its default value (KS_INIT_DIXON_DUALREADTRAP)

Parameters

[in,out]

dual_readtrap

Pointer to KS_DIXON_DUALREADTRAP

Returns

void

                                                                      {
  KS_DIXON_DUALREADTRAP def_dual_readtrap = KS_INIT_DIXON_DUALREADTRAP;
  *dual_readtrap = def_dual_readtrap;
}

ks_init_gradrfctrl()

void ks_init_gradrfctrl

(

KS_GRADRFCTRL *

gradrfctrl

)

Resets KS_GRADRFCTRL to its default value (KS_INIT_GRADRFCTRL)

Parameters

[out]

gradrfctrl

Pointer to KS_GRADRFCTRL

Returns

void

                                                   {
  KS_GRADRFCTRL defgradrf = KS_INIT_GRADRFCTRL;
  *gradrfctrl = defgradrf;
}

ks_init_seqcontrol()

void ks_init_seqcontrol

(

KS_SEQ_CONTROL *

seqcontrol

)

Resets KS_SEQ_CONTROL to its default value (KS_INIT_SEQ_CONTROL)

Parameters

[out]

seqcontrol

Pointer to KS_INIT_SEQ_CONTROL

Returns

void

                                                    {
  KS_SEQ_CONTROL defseqcontrol = KS_INIT_SEQ_CONTROL;
  *seqcontrol = defseqcontrol;
}

ks_init_seqcollection()

void ks_init_seqcollection

(

KS_SEQ_COLLECTION *

seqcollection

)

Resets KS_SEQ_COLLECTION to its default value (KS_INIT_SEQ_COLLECTION)

Parameters

[out]

seqcollection

Pointer to KS_INIT_SEQ_COLLECTION

Returns

void

                                                             {
  KS_SEQ_COLLECTION defseqcollection = KS_INIT_SEQ_COLLECTION;
  *seqcollection = defseqcollection;
}

ks_init_slewratecontrol()

STATUS ks_init_slewratecontrol	(	LOG_GRAD *	loggrd,
		PHYS_GRAD *	phygrd,
		float	srfact
	)

Changes existing (globally used) loggrd and phygrd structs (set up by inittargets() in e.g. GEReq_init_gradspecs())

If srfact < 1.0, both phygrd and loggrd are updated, and the gradients will be switched propotionally slower. This can be used to make the acquistion quieter. If srfact > 1.0, only loggrd will be updated. This could be used as an attempt to switch the gradients faster, but should be used with care as the risk for peripheral nerve stimulation (PNS) increases and the gradients may trip.

Parameters

[in,out]	loggrd	Pointer to LOG_GRAD
[in,out]	phygrd	Pointer to PHYS_GRAD
[in]	srfact	Slewrate factor (< 1.0 means less acquistic noise and reduced risk for PNS)

Returns

void

                                                                                  {

  if (fabs(srfact) < FLT_EPSILON) {
    return ks_error("%s: slewrate factor can not be zero", __FUNCTION__);
  }

  if (srfact < 1.0 && phygrd != NULL) {
    phygrd->xrt = (int) ((float) phygrd->xrt / srfact);
    phygrd->yrt = (int) ((float) phygrd->yrt / srfact);
    phygrd->zrt = (int) ((float) phygrd->zrt / srfact);
  }

  if (loggrd != NULL) {
    loggrd->xrt = (int) ((float) loggrd->xrt / srfact);
    loggrd->yrt = (int) ((float) loggrd->yrt / srfact);
    loggrd->zrt = (int) ((float) loggrd->zrt / srfact);
  }

  return SUCCESS;
}

ks_eval_addtoseqcollection()

STATUS ks_eval_addtoseqcollection	(	KS_SEQ_COLLECTION *	seqcollection,
		KS_SEQ_CONTROL *	seqctrl
	)

Adds a sequence module (KS_SEQ_CONTROL) to the KS_SEQ_COLLECTION struct for later RF scaling and SAR calculations

The KS_SEQ_CONTROL object will be ignored if added previously or if its .duration field is zero. A zero duration of a KS_SEQ_CONTROL indicates that this sequence module should not be used with the current settings

Parameters

[in,out]	seqcollection	Pointer to the KS_SEQ_COLLECTION for the sequence
[in]	seqctrl	Pointer to KS_SEQ_CONTROL

Return values

STATUS

SUCCESS or FAILURE

                                                                                             {
  int i;

  if (seqcollection == NULL) {
    return ks_error("%s: seqcollection is NULL", __FUNCTION__);
  }

  if (seqctrl->duration == 0) {
    /* Return early if seqctrl.duration = 0 so we are not adding sequence modules with zero duration to the collection.
       This is in concert with:
       - not performing createseq() in KS_SEQLENGTH if seqctrl.duration = 0
       - not playing sequence modules in scan() using ks_scan_playsequence() if seqctrl.duration = 0

       It is the task of the PG function (e.g. <seqmodule>_pg()) of the current sequence module to set seqctrl.duration > 0 based on the waveform content in that module
       and <seqmodule>_pg() should therefore be called before this function.
       Preferred method is to add the following to the end of <seqmodule>_pg():
       #ifndef IPG
        // HOST only:
        ks_eval_seqctrl_setminduration(&seqctrl, tmploc.pos); // tmploc.pos now corresponds to the end of last gradient in the sequence
       #endif
    */
    return SUCCESS;
  }

  if (seqcollection->numseq > KS_MAXUNIQUE_SEQUENCES) {
    return ks_error("%s: Number of sequence modules has been exceeded (max: %d)", __FUNCTION__, KS_MAXUNIQUE_SEQUENCES);
  }

  if (seqcollection->mode == KS_SEQ_COLLECTION_LOCKED) {
    return ks_error("%s - (%s): seqcollection.mode = KS_SEQ_COLLECTION_LOCKED. Module must be added before GEReq_eval_TR(), GEReq_eval_rfscaling(), and GEReq_eval_checkTR_SAR()", __FUNCTION__, seqctrl->description);
  }

   /* check for previous registrations of this sequence module.  If found, return */
  if (seqcollection->numseq > 0) {
    for (i = 0; i < seqcollection->numseq; i++) {
      if (seqcollection->seqctrlptr[i] == seqctrl)
        return SUCCESS;
    }
  }

  /* register the sequence module */
  seqcollection->seqctrlptr[seqcollection->numseq++] = seqctrl;

  return SUCCESS;
}

ks_eval_seqcollection_isadded()

STATUS ks_eval_seqcollection_isadded	(	KS_SEQ_COLLECTION *	seqcollection,
		KS_SEQ_CONTROL *	seqctrl
	)

Checks whether a sequence module (KS_SEQ_CONTROL) is a part of the KS_SEQ_COLLECTION struct

Parameters

[in]	seqcollection	Pointer to the KS_SEQ_COLLECTION for the sequence
[in]	seqctrl	Pointer to KS_SEQ_CONTROL

Return values

STATUS

SUCCESS or FAILURE

                                                                                                {
  int i;
  
  if (seqctrl->duration == 0) {
    return SUCCESS; /* it is not added, but we should still not complain as .duration = 0
                       means that it won't be used anyway */
  }

  /* check for previous registrations of this sequence module.  If found, return */
  if (seqcollection->numseq > 0) {
    for (i = 0; i < seqcollection->numseq; i++) {
      if (seqcollection->seqctrlptr[i] == seqctrl)
        return SUCCESS;
    }
  }

  return FAILURE;

}

ks_eval_addtraptogradrfctrl()

STATUS ks_eval_addtraptogradrfctrl	(	KS_GRADRFCTRL *	gradrfctrl,
		KS_TRAP *	trap
	)

*Internal use*. Adds a trapezoid (KS_TRAP) to the KS_GRADRFCTRL struct for later gradient heating calculations in ks_eval_gradrflimits()

The KS_TRAP object will be ignored if added previously

Parameters

[in,out]	gradrfctrl	Pointer to the KS_GRADRFCTRL for the sequence
[in]	trap	Pointer to KS_TRAP

Return values

STATUS

SUCCESS or FAILURE

                                                                             {
  int i;
  if (trap == NULL) return SUCCESS;

  if (gradrfctrl == NULL) {
    return ks_error("%s: gradrfctrl is NULL", __FUNCTION__);
  }

  if (gradrfctrl->numtrap >= KS_MAXUNIQUE_TRAP) {
    return ks_error("%s: ERROR - too many unique KS_TRAP in sequence", __FUNCTION__);
  }

  /* check for previous registrations of this trap's memory address.  If found, return */
  if (gradrfctrl->numtrap > 0) {
    for (i = 0; i < gradrfctrl->numtrap; i++) {
      if (gradrfctrl->trapptr[i] == trap)
        return SUCCESS;
    }
  }

  gradrfctrl->trapptr[gradrfctrl->numtrap++] = trap;

  return SUCCESS;
}

ks_eval_addwavetogradrfctrl()

STATUS ks_eval_addwavetogradrfctrl	(	KS_GRADRFCTRL *	gradrfctrl,
		KS_WAVE *	wave
	)

*Internal use*. Adds a wave (KS_WAVE) - if it is not a part of a KS_RF object - to the KS_GRADRFCTRL struct for later gradient heating calculations in ks_eval_gradrflimits()

The KS_WAVE object will be ignored if added previously

Parameters

[in,out]	gradrfctrl	Pointer to the KS_GRADRFCTRL for the sequence
[in]	wave	Pointer to KS_WAVE

Return values

STATUS

SUCCESS or FAILURE

                                                                             {
  int i;
  if (wave == NULL) return SUCCESS;

  if (gradrfctrl == NULL) {
    return ks_error("%s: gradrfctrl is NULL", __FUNCTION__);
  }

  if (gradrfctrl->numwave >= KS_MAXUNIQUE_WAVE) {
    return ks_error("%s: ERROR - too many unique KS_WAVE in sequence", __FUNCTION__);
  }

  /* check for previous registrations of this trap's memory address.  If found, return */
  if (gradrfctrl->numwave > 0) {
    for (i = 0; i < gradrfctrl->numwave; i++) {
      if (gradrfctrl->waveptr[i] == wave)
        return SUCCESS;
    }
  }

  /* check also for previous waves in KS_RF (rfwave, omegawave, thetawave). If found, return */
  if (gradrfctrl->numrf > 0) {
    for (i = 0; i < gradrfctrl->numrf; i++) {
      if (&(gradrfctrl->rfptr[i]->rfwave) == wave || &(gradrfctrl->rfptr[i]->omegawave) == wave || &(gradrfctrl->rfptr[i]->thetawave) == wave)
        return SUCCESS;
    }
  }

  gradrfctrl->waveptr[gradrfctrl->numwave++] = wave;

  return SUCCESS;
}

ks_eval_addrftogradrfctrl()

STATUS ks_eval_addrftogradrfctrl	(	KS_GRADRFCTRL *	gradrfctrl,
		KS_RF *	rf
	)

*Internal use*. Adds an RF pulse to the KS_GRADRFCTRL struct for later SAR & RF power calculations in ks_eval_gradrflimits()

The RF object will be ignored if added previously

Parameters

[in,out]	gradrfctrl	Pointer to the KS_GRADRFCTRL for the sequence
[in]	rf	Pointer to KS_RF

Return values

STATUS

SUCCESS or FAILURE

                                                                       {
  int i;
  if (rf == NULL) return SUCCESS;

  if (gradrfctrl == NULL) {
    return ks_error("%s: gradrfctrl is NULL", __FUNCTION__);
  }

  if (gradrfctrl->numrf >= KS_MAXUNIQUE_RF) {
    return ks_error("%s: ERROR - too many unique KS_RF in sequence", __FUNCTION__);
  }

  /* check for previous registrations of this rf's memory address. If found, return */
  if (gradrfctrl->numrf > 0) {
    for (i = 0; i < gradrfctrl->numrf; i++) {
      if (gradrfctrl->rfptr[i] == rf)
        return SUCCESS;
    }
  }

  gradrfctrl->rfptr[gradrfctrl->numrf++] = rf;

  return SUCCESS;
}

ks_eval_addreadtogradrfctrl()

STATUS ks_eval_addreadtogradrfctrl	(	KS_GRADRFCTRL *	gradrfctrl,
		KS_READ *	read
	)

*Internal use*. Adds an acquisition to the KS_GRADRFCTRL struct. Used for plotting

Parameters

[in,out]	gradrfctrl	Pointer to the KS_GRADRFCTRL for the sequence
[in]	read	Pointer to acquisition object.

Return values

STATUS

SUCCESS or FAILURE

                                                                             {
  int i;
  if (read == NULL) return SUCCESS;

  if (gradrfctrl == NULL) {
    return ks_error("%s: gradrfctrl is NULL", __FUNCTION__);
  }

  if (gradrfctrl->numacq >= KS_MAXUNIQUE_READ) {
    return ks_error("%s: ERROR - too many readouts in sequence", __FUNCTION__);
  }

  /* check for previous registrations of the pointer. If found, return */
  if (gradrfctrl->numacq > 0) {
    for (i = 0; i < gradrfctrl->numacq; i++) {
      if (gradrfctrl->readptr[i] == read)
        return SUCCESS;
    }
  }

  gradrfctrl->readptr[gradrfctrl->numacq++] = read;

  return SUCCESS;
}

ks_eval_wait()

STATUS ks_eval_wait	(	KS_WAIT *	wait,
		const char *const	desc,
		int	maxduration
	)

Sets up a wait pulse using a KS_WAIT sequence object

This function should be called in cveval() and defines a wait pulse whose duration can be changed at scan-time up to .duration [us].

If ks_eval_wait() returns FAILURE, one must also make sure cveval() returns FAILURE, otherwise an error message created in ks_eval_wait() will not be seen in the UI.

Parameters

[out]	wait	Pointer to the KS_WAIT object to be set up
[in]	desc	A description (text string) of the KS_WAIT object. This description is used for pulse sequence generation (seen in the file generated by TimeHist in MGD Sim/WTools)
[in]	maxduration	The desired maximum duration in [us] of the KS_WAIT object

Return values

STATUS

SUCCESS or FAILURE

                                                                          {

  ks_init_wait(wait);

  if (desc == NULL || desc[0] == ' ') {
    return ks_error("ks_eval_wait desc (2nd arg) cannot be NULL or begin with a space");
  } else {
    strncpy(wait->description, desc, KS_DESCRIPTION_LENGTH - 1);
  }


  wait->duration = duration;

  /* initialize counters to 0 */
  wait->base.ninst = 0;
  wait->base.ngenerated = 0;
  wait->base.next = NULL;

  return SUCCESS;
}

ks_eval_isirot()

STATUS ks_eval_isirot	(	KS_ISIROT *	isirot,
		const char *const	desc,
		int	isinumber
	)

Sets up a KS_ISIROT object to be used for real-time coordinate rotations

See also ks_pg_isirot() and ks_scan_isirotate().

Parameters

[out]	isirot	Pointer to the KS_ISIROT object to be set up
[in]	desc	A description (text string) of the KS_ISIROT object
[in]	isinumber	A free ISI interrupt number in range [4,7]

Return values

STATUS

SUCCESS or FAILURE

                                                                                 {
  STATUS status;
  char tmpdesc[KS_DESCRIPTION_LENGTH];

  if ((isinumber < 4) || (isinumber > 7)) {
    return ks_error("%s: ISI number out of range (should be 4-7)", __FUNCTION__);
  }

  sprintf(tmpdesc, "%s_isirotfun", desc);
  status = ks_eval_wait(&isirot->waitfun, tmpdesc, RUP_GRD(KS_ISI_time));
  if (status != SUCCESS) return status;

  sprintf(tmpdesc, "%s_isirotupdate", desc);
  status = ks_eval_wait(&isirot->waitrot, tmpdesc, RUP_GRD(KS_ISI_rotupdatetime));
  if (status != SUCCESS) return status;

  isirot->isinumber = isinumber;
  isirot->duration = isirot->waitfun.duration + isirot->waitrot.duration;
  isirot->counter = 0;
  isirot->numinstances = 0;

  return SUCCESS;
}

ks_eval_read()

STATUS ks_eval_read	(	KS_READ *	read,
		const char *const	desc
	)

Sets up a data acquisition window using a KS_READ sequence object

This function should be called in cveval() and defines a data acquisition window of a certain duration with some receiver bandwidth. Before calling this function, the following fields in the KS_READ object must be set:

• .rbw: The desired receiver bandwidth / FOV in [kHz] (max: 250)
• .duration: The duration in [us]

ks_eval_read() will validate the desired rBW and round it to the nearest valid value. Also the duration will be rounded up to fit a whole number of samples in the acquisition window.

To use an acquisition window with a gradient, see KS_READTRAP and ks_eval_readtrap()

If ks_eval_read() returns FAILURE, one must also make sure cveval() returns FAILURE, otherwise an error message created in ks_eval_read() will not be seen in the UI.

Parameters

[in,out]	read	Pointer to the KS_READ object to be set up
[in]	desc	A description (text string) of the KS_READ object. This description is used for pulse sequence generation (seen in the file generated by TimeHist in MGD Sim/WTools)

Return values

STATUS

SUCCESS or FAILURE

                                                            {
  char tmpdesc[KS_DESCRIPTION_LENGTH];
  int duration;
  float rbw;
  int tsp;
  int override_R1;
  int noutputs;

  /* store desired inputs before resetting */
  duration = read->duration;
  rbw = read->rbw;
  override_R1 = read->override_R1;
  strcpy(tmpdesc, desc); /* copy in case the read->description has been passed in before ks_init_read wipes it */

  /* Reset all fields (after saving the desired info) */
  ks_init_read(read);

  /* put back the input fields */
  read->duration = duration;
  read->rbw = ks_calc_nearestbw(rbw);  /* round to nearest valid rBW */
  read->override_R1 = override_R1;
  tsp = ks_calc_bw2tsp(read->rbw);
  strncpy(read->description, tmpdesc, KS_DESCRIPTION_LENGTH - 1);
  read->description[KS_DESCRIPTION_LENGTH - 1] = 0;

  /* don't allow empty description or a description with leading space */
  if (read->description == NULL || read->description[0] == ' ') {
    return ks_error("ks_eval_read: read name (2nd arg) cannot be NULL or leading space");
  }

  if (read->rbw <= 0) {
    return ks_error("ks_eval_read: field 'rbw' (1st arg) is not set");
  }
  if (read->duration <= 2) {
    return ks_error("ks_eval_read: field 'duration' (1st arg) must be a positive number in [us]");
  }

  noutputs = CEIL_DIV(read->duration, tsp);
  read->duration = noutputs * tsp;

  /* calculate read->filter (FILTER_INFO) */
  if (ks_calc_filter(&read->filt, tsp, read->duration) == FAILURE)
    return FAILURE;

  return SUCCESS;
}

ks_eval_trap_constrained()

STATUS ks_eval_trap_constrained	(	KS_TRAP *	trap,
		const char *const	desc,
		float	ampmax,
		float	slewrate,
		int	minduration
	)

Sets up a trapezoid using a KS_TRAP sequence object with gradient constraints specified as input arguments

Before calling this function, the following field in the KS_TRAP object must be set:

• .area: Desired gradient area in units of [(G/cm) * us]

ks_eval_trap_constrained() will make a trapezoid pulse with the desired area, constrained by the specified maximum gradient amplitude, slewrate, and minimum plateau time (args 3-5).

If ks_eval_trap_constrained() returns FAILURE, one must also make sure cveval() returns FAILURE, otherwise an error message created in ks_eval_trap_constrained() will not be seen in the UI.

There are three wrapper functions to this function (ks_eval_trap(), ks_eval_trap1(), ks_eval_trap2()) that have reduced number of input arguments, and calls ks_eval_trap_constrained() with different preset gradient constraints. ks_eval_trap() makes fewest assumptions, making it the most general choice.

Parameters

[in,out]	trap	Pointer to the KS_TRAP object to be set up
[in]	desc	A description (text string) of the KS_TRAP object. This description is used for pulse sequence generation (seen in the file generated by TimeHist in MGD Sim/WTools)
[in]	ampmax	The maximum allowed gradient amplitude ([G/cm])
[in]	slewrate	The maximum allowed slewrate ([(G/cm) / us]). Value of 0.01 corresponds to 100 mT/m/s
[in]	minduration	Optional minimum duration ([us]). A zero value is used to disregard this constraint

Return values

STATUS

SUCCESS or FAILURE

                                                                                                                       {
  double triangletrapezoid_area;
  double maxramp_area;
  double requested_area;
  int maxramp_duration;
  int sign_reqarea;
  int minplateautime = KS_MINPLATEAUTIME;
  char tmpdesc[KS_DESCRIPTION_LENGTH];

  /* store desired inputs before resetting the trap object */
  requested_area = (double) trap->area;
  strcpy(tmpdesc, desc); /* copy in case the trap->description has been passed in before ks_init_trap wipes it */

  /* Reset all fields and waveforms (after saving the desired area) */
  ks_init_trap(trap);

  /* put back the input fields */
  trap->area = requested_area;

  strncpy(trap->description, tmpdesc, KS_DESCRIPTION_LENGTH - 1);
  trap->description[KS_DESCRIPTION_LENGTH - 1] = 0;

  /* don't allow empty description or a description with leading space */
  if (trap->description == NULL || trap->description[0] == ' ') {
    return ks_error("ks_eval_trap: trap name (2nd arg) cannot be NULL or leading space");
  }

  if (areSame(requested_area, 0)) {
    return SUCCESS;
  }

  /* sign control: Store the sign of the requested area. Ignore all other signs */
  sign_reqarea = (requested_area < 0) ? -1 : 1;
  requested_area = fabs(requested_area);
  slewrate = fabs(slewrate);
  ampmax = fabs(ampmax);

  /* make sure the minimum duration is divisible by 8us */
  minduration = RUP_FACTOR(minduration, 2 * GRAD_UPDATE_TIME);


  /* area for one ramp from zero to max amplitude ('ampmax') */
  maxramp_duration = RUP_GRD(ceil((double) ampmax / (double) slewrate)); /* [usec] */
  maxramp_area = (double) ampmax * ((double) maxramp_duration) / 2.0; /* [G/cm * usec] */

  /* area for a trapezoid with a plateau time of 'minplateautime' and maximum amplitude ('ampmax') */
  triangletrapezoid_area = ((double) minplateautime * (double) ampmax) + (2.0 * maxramp_area);

  if (requested_area > triangletrapezoid_area) {
    /*      ________......ampmax
           /        \
          /          \
         /            \
      __/              \__

      We need max target amplitude and use a plateau time > minplateautime to reach required area. [amp = ampmax] */

    trap->ramptime = maxramp_duration;
    trap->plateautime = (int) ceil((requested_area - 2.0 * maxramp_area) / (double) ampmax);

    /* Round *up* to nearest 8us to make the plateau contain an even # of points (which is always nice) */
    trap->plateautime = RUP_FACTOR(trap->plateautime, 2 * GRAD_UPDATE_TIME);


  } else {
    /*
      ......... ampmax

          _ amp
         / \
        /   \
     __/     \__

      We don't need max amplitude and will use a minimum plateau time of minplateautime
      [amp = ramptime * slewrate] */

    trap->plateautime = minplateautime; /* Our minimum plateau time */

    /* Quadratic solution in 'ramptime':
       slewrate*(ramptime)^2 + slewrate*minplateautime*(ramptime) - requested_area = 0
       ...where: ramptime = unknownamp / slewrate <=> unknownamp = ramptime * slewrate   */
    trap->ramptime = ((int) ceil(pow(requested_area / (double) slewrate + ((double) minplateautime * (double) minplateautime) / 4.0, 0.5))) - minplateautime / 2;

    /* Round *up* to nearest GRAD_UPDATE_TIME (unit: usec) */
    trap->ramptime = RUP_GRD(trap->ramptime);
  }


  /* amp (G/cm). Make the sign of the amp equal to that of the requested_area */
  trap->amp = (float) (sign_reqarea * requested_area / ((double) (trap->ramptime + trap->plateautime)));

  /* amp watchdog */
  if (fabs(trap->amp) > ampmax)
    return ks_error("ks_eval_trap: amp (%.3f) of trap '%s' exceeds ampmax (%.3f)", trap->amp, trap->description, ampmax);

  /* store the duration */
  trap->duration = trap->ramptime * 2 + trap->plateautime;

  /* if the duration is smaller than the minimum duration, increase the ramp times and reduce the gradient amp accordingly */
  if (trap->duration < minduration) {
    trap->ramptime += (minduration - trap->duration)/2;
    trap->duration = trap->ramptime * 2 + trap->plateautime;
    trap->amp = (float) (sign_reqarea * requested_area / ((double) (trap->ramptime + trap->plateautime)));
  }


  return SUCCESS;

}

ks_eval_trap()

STATUS ks_eval_trap	(	KS_TRAP *	trap,
		const char *const	desc
	)

Sets up a trapezoid using a KS_TRAP sequence object with preset gradient constraints

Before calling this function, the following field in the KS_TRAP object must be set:

• .area: Desired gradient area in units of [(G/cm) * us]

This is a wrapper function to ks_eval_trap_constrained() with gradient constraints set to allow this KS_TRAP to be simultaneously played on XGRAD, YGRAD, ZGRAD for any slice angulation.

Parameters

[in,out]	trap	Pointer to the KS_TRAP object to be set up
[in]	desc	A description (text string) of the KS_TRAP object. This description is used for pulse sequence generation (seen in the file generated by TimeHist in MGD Sim/WTools)

Return values

STATUS

SUCCESS or FAILURE

                                                            {

  return ks_eval_trap_constrained(trap, desc, ks_syslimits_ampmax(loggrd), ks_syslimits_slewrate(loggrd), 0);

}

ks_eval_trap2()

STATUS ks_eval_trap2	(	KS_TRAP *	trap,
		const char *const	desc
	)

Sets up a trapezoid using a KS_TRAP sequence object with preset gradient constraints

Before calling this function, the following field in the KS_TRAP object must be set:

• .area: Desired gradient area in units of [(G/cm) * us]

This is a wrapper function to ks_eval_trap_constrained() with gradient constraints set to allow this KS_TRAP to be simultaneously played on up to two (2) logical gradients for any slice angulation.

Parameters

[in,out]	trap	Pointer to the KS_TRAP object to be set up
[in]	desc	A description (text string) of the KS_TRAP object. This description is used for pulse sequence generation (seen in the file generated by TimeHist in MGD Sim/WTools)

Return values

STATUS

SUCCESS or FAILURE

                                                             {

  return ks_eval_trap_constrained(trap, desc, ks_syslimits_ampmax2(loggrd), ks_syslimits_slewrate2(loggrd), 0);

}

ks_eval_trap1()

STATUS ks_eval_trap1	(	KS_TRAP *	trap,
		const char *const	desc
	)

Sets up a trapezoid using a KS_TRAP sequence object with preset gradient constraints

Before calling this function, the following field in the KS_TRAP object must be set:

• .area: Desired gradient area in units of [(G/cm) * us]

This is a wrapper function to ks_eval_trap_constrained() with gradient constraints set to allow this KS_TRAP to only be played out on one (1) logical gradient at a time. No gradient may be active on another board while this trapezoid is played out.

Parameters

[in,out]	trap	Pointer to the KS_TRAP object to be set up
[in]	desc	A description (text string) of the KS_TRAP object. This description is used for pulse sequence generation (seen in the file generated by TimeHist in MGD Sim/WTools)

Return values

STATUS

SUCCESS or FAILURE

                                                             {

  return ks_eval_trap_constrained(trap, desc, ks_syslimits_ampmax1(loggrd), ks_syslimits_slewrate1(loggrd), 0);

}

ks_eval_trap_constrained_time_maxarea()

STATUS ks_eval_trap_constrained_time_maxarea	(	KS_TRAP *	trap,
		const char *const	desc,
		float	ampmax,
		float	slewrate,
		float	maxarea,
		int	derate_slewrate
	)

                                                                                                                                                       {
  int requested_time;
  int maxramp_duration;
  char tmpdesc[KS_DESCRIPTION_LENGTH];
  int sign = (maxarea < 0) ? -1 : 1;
  strcpy(tmpdesc, desc); /* copy in case the trap->description has been passed in before ks_init_trap wipes it */

  /* make sure the minimum duration is divisible by 8us */
  requested_time = RDN_FACTOR(trap->duration, 2 * GRAD_UPDATE_TIME);
  /* Reset all fields and waveforms (after saving the desired area) */
  ks_init_trap(trap);
  strncpy(trap->description, tmpdesc, KS_DESCRIPTION_LENGTH - 1);
  trap->description[KS_DESCRIPTION_LENGTH - 1] = 0;

  /* don't allow empty description or a description with leading space */
  if (trap->description == NULL || trap->description[0] == ' ') {
    return ks_error("%s: trap name (2nd arg) cannot be NULL or leading space", __FUNCTION__);
  }
  if (requested_time <= 0) {
    return SUCCESS;
  }

  slewrate = fabs(slewrate); /* [(G/cm) / us] */
  ampmax = fabs(ampmax); /* [G/cm] */
  maxramp_duration = RUP_GRD(ceil((double) ampmax / (double) slewrate)); /* [usec] */
  if ((2*maxramp_duration + KS_MINPLATEAUTIME) > requested_time) {
    /* Not enough time to make it to the plateau */
    trap->plateautime = KS_MINPLATEAUTIME;
    trap->ramptime = (requested_time - KS_MINPLATEAUTIME) / 2;
    trap->amp = slewrate * trap->ramptime;
  } else {
    /* Enough time to reach plateau */
    trap->amp = ampmax;
    trap->ramptime = maxramp_duration;
    trap->plateautime = (requested_time - 2 * trap->ramptime);
  }

  trap->area = (trap->plateautime + trap->ramptime) * trap->amp * sign;
  if (fabs(trap->area) > fabs(maxarea)) {
    if (derate_slewrate == 1) {
      trap->amp = maxarea / (trap->plateautime + trap->ramptime);
    } else {
      trap->ramptime = RUP_GRD( (int) ((requested_time - sqrtf(requested_time*requested_time - 4*maxarea/slewrate)) / 2.0));
      trap->amp = trap->ramptime * slewrate;
      trap->plateautime = (requested_time - 2 * trap->ramptime);
    }
    /* Adjust the amplitude to never go above maxarea */
    trap->amp *= fabs(maxarea / ((trap->plateautime + trap->ramptime) * trap->amp));
    trap->area = (trap->plateautime + trap->ramptime) * trap->amp * sign;
  }

  trap->duration = trap->ramptime * 2 + trap->plateautime;
  if (trap->duration != requested_time) {
    ks_error("%s: Duration mismatch. this should not happen", __FUNCTION__);
  }
  return SUCCESS;
}

ks_eval_set_asym_padding()

STATUS ks_eval_set_asym_padding	(	KS_READTRAP *	readtrap,
		float	wanted_paddingarea_pre,
		float	wanted_paddingarea_post
	)

ks_eval_trap1p()

STATUS ks_eval_trap1p	(	KS_TRAP *	trap,
		const char *const	desc
	)

Sets up a trapezoid using a KS_TRAP sequence object with physical gradient constraints (invariant to slice angulation)

Before calling this function, the following field in the KS_TRAP object must be set:

• .area: Desired gradient area in units of [(G/cm) * us]

This is a wrapper function to ks_eval_trap_constrained() with physical gradient constraints set to allow this KS_TRAP to only be played out on one (1) logical gradient at a time. No gradient may be active on another board while this trapezoid is played out.

Parameters

[in,out]	trap	Pointer to the KS_TRAP object to be set up
[in]	desc	A description (text string) of the KS_TRAP object. This description is used for pulse sequence generation (seen in the file generated by TimeHist in MGD Sim/WTools)

Return values

STATUS

SUCCESS or FAILURE

                                                              {

  return ks_eval_trap_constrained(trap, desc, ks_syslimits_ampmax1p(loggrd), ks_syslimits_slewrate1p(loggrd), 0);

}

ks_eval_readtrap_constrained()

STATUS ks_eval_readtrap_constrained	(	KS_READTRAP *	readtrap,
		const char *const	desc,
		float	ampmax,
		float	slewrate
	)

Sets up an acquisition window with a trapezoid, subject to gradient constraints specified as input arguments

Before calling this function, the following fields in the KS_READTRAP object must be set:

1. .fov: Desired image Field-of-View (FOV) in [mm] along the sequence board one intends to place the KS_READTRAP on (typically XGRAD)
2. .res: Number of pixels within the FOV
3. .acq.rbw: Receiver bandwidth (rBW) in [kHz/FOV]. Maximum is 250
4. .rampsampling: If non-zero, data acquisition will be performed on the ramps of the trapezoid as well. This reduces the readout time, especially for high rBWs.
5. .acqdelay: Needs to be set only if .rampsampling = 1. The .acqdelay (in [us]) will dictate the time from the start of the ramp-up until data acquisition will begin
6. .nover: Number of 'overscans'. If 0, a full echo will be generated (filling k-space). If > 0, fractional echo (i.e. shorter TE) will be set up with .nover number of extra sample points beyond .res/2. The total number of samples will be .res/2 + .nover. Values of .nover between 1 and about 16 should be avoided since half Fourier reconstruction methods will likely have difficulties.

If the KS_READTRAP object is initialized with KS_INIT_READTRAP, the fields .nover, .rampsampling and .acqdelay will all be zero (steps 4-6 can be skipped)

Based on the information in the KS_READTRAP object, ks_eval_readtrap_constrained() will set up its .grad trapezoid (KS_TRAP) and its acquisition window .acq (KS_READ), constrained by the specified maximum gradient amplitude, slewrate, and minimum plateau time (args 3-5).

If .rampsampling = 1, ks_eval_readtrap_constrained() will also copy the shape of .grad to .omega (also a KS_TRAP). This is needed for FOV-offsets in the readout direction when data acquisition is done on both the ramps and on the plateau, and ks_pg_readtrap() and ks_scan_offsetfov() will handle the .omega KS_TRAP so that the intended FOV shift in [mm] will be performed.

ks_eval_readtrap_constrained() will also fill in the convenience fields .area2center and .time2center properly. .area2center is useful to use as .area for a read dephaser, and .time2center makes sequence timing calculations easier. Both fields take partial/full Fourier (.nover) into account.

If ks_eval_readtrap_constrained() returns FAILURE, one must also make sure cveval() returns FAILURE, otherwise an error message created in ks_eval_readtrap_constrained() will not be seen in the UI.

There are three wrapper functions to this function (ks_eval_readtrap(), ks_eval_readtrap1(), ks_eval_readtrap2()) that have reduced number of input arguments, and calls ks_eval_readtrap_constrained() with different preset gradient constraints. ks_eval_readtrap() makes fewest assumptions, making it the most general choice.

Parameters

[in,out]	readtrap	Pointer to the KS_READTRAP object to be set up
[in]	desc	A description (text string) of the KS_READTRAP object. This description is used for pulse sequence generation (seen in the file generated by TimeHist in MGD Sim/WTools)
[in]	ampmax	The maximum allowed gradient amplitude ([G/cm])
[in]	slewrate	The maximum allowed slewrate ([(G/cm) / us]). Value of 0.01 corresponds to 100 mT/m/s

Return values

STATUS

SUCCESS or FAILURE

                                                                                                                  {
  float minfov;
  int tsp = 0;
  float readpixelarea;
  int nreadpixels;
  float nonacq_readarea;
  float ampmax_kspace_speedlimit;

  /* This function is for setting up readout trapezoid with fixed amplitude based on FOV and rBW */

  if (desc == NULL || desc[0] == ' ') {
    return ks_error("ks_eval_readtrap: desc (2nd arg) cannot be NULL");
  }
  if (areSame(readtrap->acq.rbw, 0) || isNotSet(readtrap->acq.rbw)) {
    return ks_error("ks_eval_readtrap: field 'acq.rbw' (1st arg) is not set");
  }

  /* reset KS_TRAP's */
  ks_init_trap(&readtrap->grad);
  ks_init_trap(&readtrap->omega);


  /* round rBW to nearest valid value */
  readtrap->acq.rbw = ks_calc_nearestbw(readtrap->acq.rbw);
  tsp = ks_calc_bw2tsp(readtrap->acq.rbw); /* us per sample point */

  minfov = ks_calc_minfov(ampmax, tsp);

  /* Programmer's error */
  if (readtrap->res % 2 || readtrap->res <= 0 || readtrap->res > 2048) {
    return ks_error("ks_eval_readtrap(%s): field 'res' must be even and in the range 2-2048", desc);
  }
  if (readtrap->fov < 10 || readtrap->fov > 600) {
    return ks_error("ks_eval_readtrap(%s): field 'fov' must be in the range 10-600 mm", desc);
  }
  if (abs(readtrap->nover) > readtrap->res / 2) {
    return ks_error("ks_eval_readtrap(%s): field 'nover' may not exceed res/2", desc);
  }
  if (readtrap->acq.rbw > 250) {
    return ks_error("ks_eval_readtrap(%s): rBW cannot exceed +/- 250 kHz/FOV", desc);
  }
  /* Operator's error */
  if (readtrap->fov < minfov && readtrap->rampsampling == 0) {
    return ks_error("%s: Please increase the FOV to %.1f [cm] or decrease the rBW", desc, minfov / 10.0);
  }

  if (abs(readtrap->nover)) {
    nreadpixels = readtrap->res / 2 + abs(readtrap->nover);
  } else {
    nreadpixels = readtrap->res;
  }
  if (nreadpixels % 2) {
    return ks_error("ks_eval_readtrap(%s): number of sampling points must be even (%d)", desc, nreadpixels);
  }


  if (readtrap->rampsampling == 1) { /* rampsampling */

    /* Gradient area necessary to move one pixel in k-space in the read direction */
    readpixelarea = ks_calc_fov2gradareapixel(readtrap->fov); /* [(G/cm)*usec] */

    /* Speed limit the readout (i.e. put a cap on the readout amplitude) based on the FOV and the chosen rBW */
    ampmax_kspace_speedlimit = FMin(2, readpixelarea / tsp, ampmax);

    /* delay of ACQ start relative to the beginning of the attack ramp.
       For rampsampled cases, this value should be at least one dwell time (tsp) */
    if (readtrap->acqdelay < 2 * tsp) {
      readtrap->acqdelay = 2 * tsp;
    }

    readtrap->acqdelay = RUP_FACTOR(readtrap->acqdelay, 2);

    /* gradient area before and after the acq window */
    nonacq_readarea = slewrate /* [G/cm/usec] */ * (readtrap->acqdelay) * (readtrap->acqdelay) /* [usec^2] */; /* from both sides of the readout */

    /* required gradient area: gradient area needed during the acq window + nonacq_readarea */
    readtrap->grad.area = (readpixelarea * nreadpixels) + nonacq_readarea;

    if (ks_eval_trap_constrained(&readtrap->grad, desc, ampmax_kspace_speedlimit, slewrate, 0) == FAILURE)
      return FAILURE;


    if (readtrap->grad.ramptime > readtrap->acqdelay) {
      /* rampsampling attempt ok, continue calculating area2center and time2center */

      if (readtrap->nover > 0) { /* partial Fourier on the first part of the readout */
        readtrap->area2center = readpixelarea * readtrap->nover + nonacq_readarea / 2;
      } else { /* Full Fourier, or partial Fourier on the last part of the readout */
        readtrap->area2center = readpixelarea * readtrap->res / 2 + nonacq_readarea / 2;
      }

      /* area = (s*t^2)/2 [G/cm/usec] * [usec^2] */
      if (readtrap->area2center < slewrate * (readtrap->grad.ramptime * readtrap->grad.ramptime / 2.0)) {
        /* k-space center is on the attack ramp */
        readtrap->time2center = (int) sqrt(readtrap->area2center * 2.0 / slewrate);
      } else {
        float arealeftonplateau = readtrap->area2center - (readtrap->grad.ramptime * readtrap->grad.amp / 2.0);
        readtrap->time2center = (int) readtrap->grad.ramptime + (arealeftonplateau / readtrap->grad.amp); /* whole ramp + some plateau time */
      }

      /* round up the readout window time to the nearest multiple of '2*tsp' to always make filt.outputs even */
      readtrap->acq.duration = RUP_FACTOR(readtrap->grad.duration - readtrap->acqdelay * 2, (int) (2 * tsp));

      /* update 'acqdelay' due to this potential roundoff */
      readtrap->acqdelay = (readtrap->grad.duration - readtrap->acq.duration) / 2;

    } else {

      readtrap->rampsampling = 0; /* let's skip ramp sampling then (and be caught by the next non-rampsampled case) */

    }

  } /* rampsampling */




  if (readtrap->rampsampling == 0) { /* No rampsampling */

    if (desc[0] == ' ') {
      ks_init_trap(&readtrap->grad);
      return ks_error("ks_eval_readtrap: desc (2nd arg) cannot begin with a space");
    } else {
      strncpy(readtrap->grad.description, desc, KS_DESCRIPTION_LENGTH - 1);
      readtrap->grad.description[KS_DESCRIPTION_LENGTH - 1] = 0;
    }

    /* Error if requested constraints cannot be fullfilled */
    if (readtrap->fov < minfov) {
      return ks_error("%s: %s - Please increase the FOV to %.1f [cm] or decrease the rBW", __FUNCTION__, desc, minfov / 10.0);
    }

    readtrap->grad.amp = ((float) (1.0 / (GAM * tsp * 1e-6) * (10.0 / readtrap->fov))); /* [G/cm] */
    readtrap->grad.ramptime = RUP_GRD(readtrap->grad.amp / slewrate); /* [usec] */
    readtrap->acq.duration = RUP_GRD(nreadpixels * tsp);

    /* adjust plateau time to account for padding */
    const float ramparea = readtrap->grad.ramptime * readtrap->grad.amp / 2.0;
    const int extradelay = RUP_GRD(FMax(2, readtrap->paddingarea - ramparea, 0.0) / readtrap->grad.amp);
    readtrap->grad.plateautime = readtrap->acq.duration + 2*extradelay; /* [usec] */ /* Nkx * dwell time */

    readtrap->grad.duration = readtrap->grad.plateautime + readtrap->grad.ramptime * 2; /* [usec] */
    readtrap->grad.area = (readtrap->grad.plateautime + readtrap->grad.ramptime) * readtrap->grad.amp; /* rounding effects */

    /* ACQ starts after the attack ramp */
    readtrap->acqdelay = readtrap->grad.ramptime + extradelay;

    const int pixelstocenter = readtrap->nover > 0 ?
      readtrap->nover : /* partial Fourier on the first part of the readout */
      readtrap->res/2;  /* Full Fourier, or partial Fourier on the last part of the readout */

    readtrap->area2center = (readtrap->grad.ramptime/2 + tsp * pixelstocenter + extradelay)  * readtrap->grad.amp;
    readtrap->time2center = readtrap->grad.ramptime + tsp * pixelstocenter + extradelay;

  } /* no rampsampling */




  /* round up to nearest multiple of GRAD_UPDATE_TIME (4us) */
  readtrap->time2center = RUP_GRD(readtrap->time2center);


  /* setup acq window */
  /* readtrap->acq.rbw is set > 0 by the calling function */
  KS_DESCRIPTION read_description;
  sprintf(read_description, "%s.echo", readtrap->grad.description);
  if (ks_eval_read(&readtrap->acq, read_description) == FAILURE) {
    return FAILURE;
  }

  /* for rampsampling, create an omega waveform (for FOV shifts in the freq (read) direction for rampsampling) */
  if (readtrap->rampsampling) {
    readtrap->omega = readtrap->grad; /* copy the shape of the readout */
    readtrap->omega.amp = 1.0; /* just unity value for conformance. It does not matter during scanning, since ks_scan_omegatrap_hz() ignores this value */
    readtrap->omega.area = 0.0; /* Omega area has no meaning */
    sprintf(readtrap->omega.description, "%s.omega", readtrap->grad.description);
  } else {
    readtrap->omega.duration = 0;
  }


  return SUCCESS;
}

ks_eval_readtrap()

STATUS ks_eval_readtrap	(	KS_READTRAP *	readtrap,
		const char *const	desc
	)

Sets up an acquisition window with a trapezoid with preset gradient constraints

This is a wrapper function to ks_eval_readtrap_constrained() with gradient constraints set to allow this KS_READTRAP to simultaneously be played on XGRAD, YGRAD, ZGRAD for any slice angulation. This is the generic and safest configuration, but for readouts with small FOV and high rBW, the gradient limits may be reached, especially for double oblique slices. See ks_eval_readtrap_constrained() for details on fields that need to be set before calling this function.

Parameters

[in,out]	readtrap	Pointer to the KS_READTRAP object to be set up
[in]	desc	A description (text string) of the KS_READTRAP object. This description is used for pulse sequence generation (seen in the file generated by TimeHist in MGD Sim/WTools)

Return values

STATUS

SUCCESS or FAILURE

                                                                        {

  return ks_eval_readtrap_constrained(readtrap, desc,
                                      ks_syslimits_ampmax(loggrd), ks_syslimits_slewrate(loggrd));

}

ks_eval_readtrap2()

STATUS ks_eval_readtrap2	(	KS_READTRAP *	readtrap,
		const char *const	desc
	)

Sets up an acquisition window with a trapezoid with preset gradient constraints

This is a wrapper function to ks_eval_readtrap_constrained() with gradient constraints set to allow this KS_TRAP to simultaneously be played on up to two (2) logical gradients for any slice angulation. For double oblique slice angulations, this function will allow for smaller FOVs and higher rBWs than ks_eval_readtrap().

See ks_eval_readtrap_constrained() for details on fields that need to be set before calling this function.

Parameters

[in,out]	readtrap	Pointer to the KS_READTRAP object to be set up
[in]	desc	A description (text string) of the KS_READTRAP object. This description is used for pulse sequence generation (seen in the file generated by TimeHist in MGD Sim/WTools)

Return values

STATUS

SUCCESS or FAILURE

                                                                         {

  return ks_eval_readtrap_constrained(readtrap, desc,
                                      ks_syslimits_ampmax2(loggrd), ks_syslimits_slewrate2(loggrd));

}

ks_eval_readtrap1()

STATUS ks_eval_readtrap1	(	KS_READTRAP *	readtrap,
		const char *const	desc
	)

Sets up an acquisition window with a trapezoid with preset gradient constraints

This is a wrapper function to ks_eval_readtrap_constrained() with gradient constraints set to allow this KS_TRAP to only be played out on one (1) logical gradient at a time. No gradient may be active on another board while this trapezoid is played out. For double oblique slice angulations, this function will allow for smaller FOVs and higher rBWs than ks_eval_readtrap() and ks_eval_readtrap2(). See ks_eval_readtrap_constrained() for details on fields that need to be set before calling this function.

Parameters

[in,out]	readtrap	Pointer to the KS_READTRAP object to be set up
[in]	desc	A description (text string) of the KS_READTRAP object. This description is used for pulse sequence generation (seen in the file generated by TimeHist in MGD Sim/WTools)

Return values

STATUS

SUCCESS or FAILURE

                                                                         {

  return ks_eval_readtrap_constrained(readtrap, desc,
                                      ks_syslimits_ampmax1(loggrd), ks_syslimits_slewrate1(loggrd));

}

ks_eval_readtrap_constrained_sample_duration()

STATUS ks_eval_readtrap_constrained_sample_duration	(	KS_READTRAP *	readtrap,
		const char *const	desc,
		const float	ampmax,
		const float	slewrate,
		const int	t_A,
		const int	sample_duration,
		const float	area_post,
		const float	area_total
	)

ks_eval_dixon_wang()

STATUS ks_eval_dixon_wang	(	struct _dixon_dualreadtrap_s *	dual_read,
		const char *const	desc,
		const float	PF,
		float	M
	)

ks_eval_dixon_dualreadtrap()

STATUS ks_eval_dixon_dualreadtrap	(	struct _dixon_dualreadtrap_s *	dual_read,
		const char *const	desc,
		int	flip
	)

ks_verify_dualreadtrap_setup()

STATUS ks_verify_dualreadtrap_setup

(

struct _dixon_dualreadtrap_s *

dual_read

)

ks_eval_dixon_dualreadtrap_slim()

STATUS ks_eval_dixon_dualreadtrap_slim	(	struct _dixon_dualreadtrap_s *	dual_read,
		const char *const	desc,
		int	flip
	)

ks_eval_dixon_asymtriangle_padded()

STATUS ks_eval_dixon_asymtriangle_padded	(	struct _dixon_asymreadwave_s *	asym_readwave,
		const char *const	desc,
		const int	tas,
		const int	time2center,
		const float	area_pre,
		const float	area_acq,
		const float	fov,
		const int	duration
	)

ks_eval_dixon_asymspline_padded()

STATUS ks_eval_dixon_asymspline_padded	(	struct _dixon_asymreadwave_s *	asym_readwave,
		const char *const	desc,
		const int	tas,
		const int	time2center,
		const int	tae,
		const float	Apre,
		const float	Aacq,
		const float	Apost,
		const float	fov,
		const int	duration
	)

ks_eval_dixon_asymspline()

STATUS ks_eval_dixon_asymspline	(	struct _dixon_asymreadwave_s *	asym_readwave,
		const char *const	desc,
		const int	time2center,
		const float	area,
		const float	fov,
		const int	duration,
		const float	paddingarea
	)

ks_eval_dixon_asymtriangle()

STATUS ks_eval_dixon_asymtriangle	(	struct _dixon_asymreadwave_s *	asym_readwave,
		const char *const	desc,
		const int	ttc,
		const float	area,
		const float	fov,
		const int	duration,
		const float	paddingarea
	)

ks_eval_readtrap1p()

STATUS ks_eval_readtrap1p	(	KS_READTRAP *	readtrap,
		const char *const	desc
	)

Sets up an acquisition window with a trapezoid with physical gradient constraints (invariant to slice angulation)

This is a wrapper function to ks_eval_readtrap_constrained() with physical gradient constraints

Parameters

[in,out]	readtrap	Pointer to the KS_READTRAP object to be set up
[in]	desc	A description (text string) of the KS_READTRAP object. This description is used for pulse sequence generation (seen in the file generated by TimeHist in MGD Sim/WTools)

Return values

STATUS

SUCCESS or FAILURE

ks_eval_kynover_fromnex()

int ks_eval_kynover_fromnex	(	int	yres,
		float	nex,
		int	minkynover
	)

                                                                 {
  int kynover;
  
  if (nex < 1) {
    kynover = yres * (nex - 0.5);
    kynover = ((kynover + 1) / 2) * 2; /* round to nearest even number */
    if (kynover < minkynover) {
      kynover = minkynover; /* protect against too few overscans */
    }
    kynover = IMin(2, kynover, yres / 2);
  } else {
    kynover = 0;
  }

  return kynover;

}

ks_eval_phaseviewtable()

void ks_eval_phaseviewtable

(

KS_PHASER *

phaser

)

Sets up which lines to acquire for a KS_PHASER object

This function sets the following fields in a KS_PHASER object

1. .numlinestoacq: Number of phase encoding lines to acquire
2. .linetoacq[]: Array, where the first .numlinestoacq elements denotes which lines to acquire with indices corresponding to a fully sampled k-space. The top-most line has index 0 and the bottom-most line has index (.res-1).

These two fields are set based on .res, .nover, .nacslines, and .R in the KS_PHASER object. If .nover < 0, partial Fourier will be set up, but with flipped k-space coverage

Parameters

[in,out]

phaser

Pointer to the KS_PHASER object to be set up

Returns

void

                                               {
  int i, index, firstline, lastline, halfacslines;
  short viewonflag[KS_MAX_PHASEDYN];

  /* reset arrays */
  for (i = 0; i < KS_MAX_PHASEDYN; i++) {
    phaser->linetoacq[i] = 0;
    viewonflag[i] = 0;
  }

  if (phaser->nover == 0) {
    firstline = 0;
    lastline = phaser->res - 1;
  } else if (phaser->nover > 0) { /* fractional ky upper half */
    firstline = 0;
    lastline = phaser->res / 2 + phaser->nover - 1;
  } else {
    firstline = phaser->res / 2 + phaser->nover; /* NOTE: phase->nover here negative ! */
    lastline = phaser->res - 1;
  }

  if ((lastline - firstline + 1) % 2) {
    /* /vobs/vre/recon/rcapps/rc_filter.cpp requires that rhdayres is odd (according to ARC.e) */
    ks_error("%s: #k-space lines *spanned* must be even",__FUNCTION__);
  }

  int acscenter = (phaser->res / 2) + phaser->acsshift;

  /* lower half of k-space: mark the lines to acquire with '1' */
  halfacslines = phaser->nacslines / 2;
  for (i = acscenter; i <= lastline; i++) {
    if (((i + 1) % phaser->R) == 1 || phaser->R == 1) {
      viewonflag[i] = 1;
    } else if (halfacslines > 0) {
      viewonflag[i] = 1;
      halfacslines--;
    }
  }

  /* upper half of k-space: mark the lines to acquire with '1' */
  halfacslines = phaser->nacslines - (phaser->nacslines / 2) + halfacslines;
  for (i = acscenter - 1; i >= 0; i--) {
    if (((i + 1) % phaser->R) == 1 || phaser->R == 1) {
      viewonflag[i] = 1;
    } else if (halfacslines > 0) {
      viewonflag[i] = 1;
      halfacslines--;
    }
  }

  /* sweep kspace linearly and save the line numbers to acquire.
     firstline/lastline handles full/partial Fourier */
  index = 0;
  for (i = firstline; i <= lastline; i++) {
    if (viewonflag[i]) {
      phaser->linetoacq[index++] = i;
    }
  }
  phaser->numlinestoacq = index;

}

ks_eval_phaser_adjustres()

STATUS ks_eval_phaser_adjustres	(	KS_PHASER *	phaser,
		const char *const	desc
	)

Adjusts the phase encoding resolution to the nearest valid value

Phase resolution must be divisible by .R and be even, and there are additional requirements for partial ky Fourier scans. Moreover, for parallel imaging using ASSET, only the acquired lines are stored in the data (compressed BAM), resulting in an R times lower value for rhnframes.

Here are the rules:

• Resolution (and overscan) choice must guarantee that (rhhnover + rhnframes) is an even number
• Full Fourier, ASSET:
  • rhnframes = res / R
  • rhhnover = 0
  • => res / R must be even
• Partial Fourier:
  • rhnframes = (res / 2) / R
  • rhhnover = overscans/R
  • => res / (2 * R) and (res / (2 * R) + overscans) must be even
    
    • overscans/R and (res/2)/R must be integers
    • => res must be divisible by (4 * R)
    • => overscans must be divisible by (2 * R)

Parameters

[in,out]	phaser	Pointer to KS_PHASER
[in]	desc	A description (text string) of the KS_PHASER object, only used for error msg

Return values

STATUS

SUCCESS or FAILURE

                                                                            {

  int kspacelines_noacc;

  if (phaser->nover == 0)
    kspacelines_noacc = phaser->res;
  else
    kspacelines_noacc = phaser->res / 2 + abs(phaser->nover);

  if (kspacelines_noacc < phaser->R) {
    /* Number of k-space lines less than R */
    return ks_error("%s(%s): R cannot exceed %d", __FUNCTION__, desc, kspacelines_noacc);
  } else if (kspacelines_noacc == phaser->R) {
  /* Number of k-space lines equal to R. Used for EPI when R is used as shots to produce ETL = 1.
    Just make sure that res is even */
    if (phaser->res % 2) {
      return ks_error("%s(%s): res must be even", __FUNCTION__, desc);
    } else {
      return SUCCESS;
    }
  }

  if (phaser->nover != 0) {
    /* partial Fourier */
    const int sign_nover = (phaser->nover >= 0) ? 1 : -1;
    phaser->nover = abs(phaser->nover);
    int invalidnover = TRUE;

    /* round res and nover to nearest valid values */
    if (phaser->R % 2) { /* R is odd */
      phaser->res   = RUP_FACTOR(phaser->res   - 2 * phaser->R, 4 * phaser->R);
      phaser->nover = RUP_FACTOR(phaser->nover - phaser->R, 2 * phaser->R) * sign_nover;
      invalidnover = phaser->nover < (2 * phaser->R) || phaser->nover > (phaser->res / 2);
    } else { /* R is even */
      phaser->res   = RUP_FACTOR(phaser->res   - phaser->R, 2 * phaser->R);
      phaser->nover = RUP_FACTOR(phaser->nover - phaser->R/2, phaser->R) * sign_nover;
      invalidnover = phaser->nover < phaser->R || phaser->nover > (phaser->res / 2);
    }

    if (invalidnover) {
      return ks_error("%s(%s): Valid #overscans not found", __FUNCTION__, desc);
    }

  } else {
    /* full Fourier */

    phaser->res = RUP_FACTOR(phaser->res - phaser->R, 2 * phaser->R);

  }

  return SUCCESS;
}

ks_eval_phaser_setaccel()

STATUS ks_eval_phaser_setaccel	(	KS_PHASER *	phaser,
		int	min_acslines,
		float	R
	)

[ks_eval_phaser_setaccel description]

Parameters

[in,out]	phaser	Pointer to KS_PHASER
[in]	min_acslines	Minimum # of ACS lines
[in]	R	(floating point) acceleration (taken e.g. from the UI opaccel_ph_stride)

Return values

STATUS

SUCCESS or FAILURE

                                                                             {

  if (R <= 1.0) {
    phaser->R = 1.0;
    phaser->nacslines = 0;
    return SUCCESS;
  }

  /* Get integer acceleration and store the Rfraction for ARC mode */
  double Rfraction = ceil(R) - R;
  if (Rfraction > 0.9999) { /* handle roundoff issues for e.g. R=2.0000001 */
    Rfraction = 0.0;
  }
  phaser->R = floor(R + Rfraction + 0.5); /* round-up R to nearest integer */

  if (min_acslines == 0) {
    /* ASSET mode */

    /* phaser.nacslines = 0 triggers ASSET scan mode in GEReq_predownload_setrecon_accel() */
    phaser->nacslines = 0;

  } else {
    /* ARC mode */

    double totlines_spanned = (phaser->nover != 0) ? (phaser->res / 2 + abs(phaser->nover)) : phaser->res;
    double acqlines_R       = totlines_spanned / phaser->R;
    double acqlines_floorR  = totlines_spanned / FMax(2, 1.0, floor(R));

    /* adapt #acs lines based on the fraction of the acceleration factor, but never go below min_acslines */
    phaser->nacslines = IMax(2, (int) ((acqlines_floorR - acqlines_R) * Rfraction), min_acslines);

  }

  return SUCCESS;
}

ks_eval_phaser_constrained()

STATUS ks_eval_phaser_constrained	(	KS_PHASER *	phaser,
		const char *const	desc,
		float	ampmax,
		float	slewrate,
		int	minplateautime
	)

Sets up a trapezoid for phase encoding, subject to gradient constraints specified as input arguments

Before calling this function, the following fields in KS_PHASER must be set up:

1. .fov: The desired image Field-of-View (FOV) in [mm] along the sequence board one intends to place the KS_PHASER on (typically YGRAD, for 3D also ZGRAD)
2. .res: The number of pixels within the FOV
3. .nover: Number of 'overscans'. If 0, a full-Fourier k-space will be set up. If > 0, partial Fourier will be set up (shorter scan time) where .nover number of extra k-space lines beyond .res/2. If < 0, partial Fourier will be set up, but with flipped k-space coverage. The total number of samples will be .res/2 + abs(.nover). Absolute values of .nover between 1 and about 16 should be avoided since half Fourier reconstruction methods will likely have difficulties
4. .R: The parallel imaging acceleration factor
5. .nacslines: If .R > 1, the value of .nacslines is the number of calibration lines around k-space center for parallel imaging calibration
6. .areaoffset: It is possible to embed a static gradient area in the phase encoding functionality of KS_PHASER. This is useful for 3D imaging, where the area needed for the rephaser for the slice select gradient can be put into .areaoffset. This makes the KS_PHASER to act as both slice rephaser and slice phase encoding gradient, which can shorten TE

If the KS_PHASER object is initialized with KS_INIT_PHASER, .nover, .nacslines and .areaoffset will be zero, and .R will be 1 (steps 3-6 can be skipped)

Based on the information in the KS_PHASER object, ks_eval_phaser_constrained() will set up the .grad trapezoid (KS_TRAP). By internally calling ks_eval_phaseviewtable(), .numlinestoacq, and the array .linetoacq[] are also set up. The field .numlinestoacq is an integer corresponding to the actual number of lines to acquire, and also the number of elements to read in .linetoacq[], containing the complete list of phase encoding lines to acquire (honoring partial Fourier, parallel imaging acceleration and ACS lines)

If ks_eval_phaser_constrained() returns FAILURE, one must also make sure cveval() returns FAILURE, otherwise an error message created in ks_eval_phaser_constrained() will not be seen in the UI

There are three wrapper functions to this function (ks_eval_phaser(), ks_eval_phaser1(), ks_eval_phaser2()) that have reduced number of input arguments, and calls ks_eval_phaser_constrained() with different preset gradient constraints. ks_eval_phaser() makes fewest assumptions, making it the most general choice

Parameters

[in,out]	phaser	Pointer to the KS_PHASER object to be set up
[in]	desc	A description (text string) of the KS_PHASER object. This description is used for pulse sequence generation (seen in the file generated by TimeHist in MGD Sim/WTools)
[in]	ampmax	The maximum allowed gradient amplitude ([G/cm])
[in]	slewrate	The maximum allowed slewrate ([(G/cm) / us]). Value of 0.01 corresponds to 100 mT/m/s
[in]	minplateautime	The minimum plateau time of the trapezoid ([us])

Return values

STATUS

SUCCESS or FAILURE

                                                                                 {
  float phasepixelarea;

  ks_init_trap(&phaser->grad);

  if (phaser->fov < 5 || phaser->fov > 600) {
    return ks_error("%s(%s): field 'fov' must be in the range 5-600 mm", __FUNCTION__, phasername);
  }

  /* adjust res and possibly nover to allow both ARC and ASSET scans with full and partial ky Fourier */
  if (ks_eval_phaser_adjustres(phaser, phasername) == FAILURE) {
    return FAILURE;
  }

  phasepixelarea = ks_calc_fov2gradareapixel(phaser->fov); /* [(G/cm)*usec] */

  /* area required to reach the outermost phase encoding step (incl. areaoffset)
  N.B.: The *sign* of the area is controlled in scan using ks_scan_phaser_toline(), hence on HOST all phase encoding gradient will be positive, unlike TGT */
  phaser->grad.area = ((phaser->res - 1.0) / 2.0) * phasepixelarea + fabs(phaser->areaoffset); /* .areaoffset is used in 3D imaging to embed e.g. a slice sel. rephaser in the phase encoding gradient */

  /* setup phaser trap */
  if (!areSame(phaser->grad.area, 0.0)) {
    if (ks_eval_trap_constrained(&phaser->grad, phasername, ampmax, slewrate, minduration) == FAILURE)
      return FAILURE;
  }

  /* setup phaser->linetoacq[] */
  ks_eval_phaseviewtable(phaser);


  return SUCCESS;

}

ks_eval_phaser()

STATUS ks_eval_phaser	(	KS_PHASER *	phaser,
		const char *const	desc
	)

Sets up an acquisition window with a trapezoid with preset gradient constraints

This is a wrapper function to ks_eval_phaser_constrained() with gradient constraints set to allow this KS_PHASER to simultaneously be played on XGRAD, YGRAD, ZGRAD for any slice angulation. This is the generic and safest configuration, but the duration of the KS_PHASER object may increase for double oblique slices

See ks_eval_phaser_constrained() for details on fields that need to be set before calling this function

Parameters

[in,out]	phaser	Pointer to the KS_PHASER object to be set up
[in]	desc	A description (text string) of the KS_PHASER object. This description is used for pulse sequence generation (seen in the file generated by TimeHist in MGD Sim/WTools)

Return values

STATUS

SUCCESS or FAILURE

                                                                        {

  return ks_eval_phaser_constrained(phaser, phasername, ks_syslimits_ampmax(loggrd), ks_syslimits_slewrate(loggrd), 0);

}

ks_eval_phaser2()

STATUS ks_eval_phaser2	(	KS_PHASER *	phaser,
		const char *const	desc
	)

Sets up an acquisition window with a trapezoid with preset gradient constraints

This is a wrapper function to ks_eval_phaser_constrained() with gradient constraints set to allow this KS_PHASER to simultaneously be played on up to two (2) logical gradients for any slice angulation. For double oblique slice angulations, this function may allow for shorter duration than ks_eval_phaser()

See ks_eval_phaser_constrained() for details on fields that need to be set before calling this function

Parameters

[in,out]	phaser	Pointer to the KS_PHASER object to be set up
[in]	desc	A description (text string) of the KS_PHASER object. This description is used for pulse sequence generation (seen in the file generated by TimeHist in MGD Sim/WTools)

Return values

STATUS

SUCCESS or FAILURE

                                                                         {

  return ks_eval_phaser_constrained(phaser, phasername, ks_syslimits_ampmax2(loggrd), ks_syslimits_slewrate2(loggrd), 0);

}

ks_eval_phaser1()

STATUS ks_eval_phaser1	(	KS_PHASER *	phaser,
		const char *const	desc
	)

Sets up an acquisition window with a trapezoid with preset gradient constraints

This is a wrapper function to ks_eval_phaser_constrained() with gradient constraints set to allow this KS_PHASER to only be played out on one (1) logical gradient at a time. No gradient may be active on another board while this trapezoid is played out. For double oblique slice angulations, this function may allow for shorter duration than ks_eval_phaser() and ks_eval_phaser2()

See ks_eval_phaser_constrained() for details on fields that need to be set before calling this function

Parameters

[in,out]	phaser	Pointer to the KS_PHASER object to be set up
[in]	desc	A description (text string) of the KS_PHASER object. This description is used for pulse sequence generation (seen in the file generated by TimeHist in MGD Sim/WTools)

Return values

STATUS

SUCCESS or FAILURE

                                                                         {

  return ks_eval_phaser_constrained(phaser, phasername, ks_syslimits_ampmax1(loggrd), ks_syslimits_slewrate1(loggrd), 0);

}

ks_eval_phaser1p()

STATUS ks_eval_phaser1p	(	KS_PHASER *	phaser,
		const char *const	desc
	)

Sets up an acquisition window with a trapezoid with physical gradient constraints (invariant to slice angulation)

This is a wrapper function to ks_eval_phaser_constrained() with physical gradient constraints

Parameters

[in,out]	phaser	Pointer to the KS_PHASER object to be set up
[in]	desc	A description (text string) of the KS_PHASER object. This description is used for pulse sequence generation (seen in the file generated by TimeHist in MGD Sim/WTools)

Return values

STATUS

SUCCESS or FAILURE

                                                                          {

  return ks_eval_phaser_constrained(phaser, phasername, ks_syslimits_ampmax1p(loggrd), ks_syslimits_slewrate1p(loggrd), 0);

}

ks_eval_wave()

STATUS ks_eval_wave	(	KS_WAVE *	wave,
		const char *const	desc,
		int	res,
		int	duration,
		KS_WAVEFORM	waveform
	)

Sets up a KS_WAVE object based on a waveform (KS_WAVEFORM) in memory

ks_eval_wave() copies the content of a KS_WAVEFORM into a KS_WAVE sequence object. KS_WAVEFORM (5th arg) is a typedef for a float array with a fixed length of KS_MAXWAVELEN elements. Hence, a KS_WAVEFORM, or float array, must first be created and filled with some wave contents before calling this function. res elements are copied from the input KS_WAVEFORM to the field .waveform in the KS_WAVE object (1st arg). duration (4th arg) must be divisible by res (3rd arg) and at least 2x res.

When using (i.e. calling ks_pg_wave()) the waveform for:

1. RF or OMEGA, nothing needs to be done in terms of amplitude scaling. For RF, amplitude scaling is handled via the KS_RF object, and for OMEGA the number of [Hz] are set directly in run-time (scan())
2. THETA, the waveform needs to be scaled to units of [degrees]
3. XGRAD, YGRAD, or ZGRAD, the waveform needs to be scaled to units of [G/cm]

Parameters

[out]	wave	KS_WAVE object to be created
[in]	desc	A description (text string) of the KS_WAVE object. This description is used for pulse sequence generation (seen in the file generated by TimeHist in MGD Sim/WTools)
[in]	res	Resolution of the waveform, i.e. number of elements from KS_WAVEFORM (5th arg) to read
[in]	duration	Desired duration in [us] of the waveform (must be divisible with res)
[in]	waveform	KS_WAVEFORM (float array of max length KS_MAXWAVELEN) with existing waveform content

Return values

STATUS

SUCCESS or FAILURE

                                                                                                        {
  KS_DESCRIPTION tmpdesc;

  strncpy(tmpdesc, desc, KS_DESCRIPTION_LENGTH / 2);
  /* don't allow NULL or a description with leading space */
  if (desc == NULL || desc[0] == ' ') {
    return ks_error("ks_eval_wave: wave name (2nd arg) cannot be NULL or leading space");
  }

  if (duration < 0 || res < 0) {
    return ks_error("ks_eval_wave(%s): 'res' and 'duration' must be positive", desc);
  }
  if (res > KS_MAXWAVELEN) {
    return ks_error("ks_eval_wave(%s): 'res' cannot exceed %d", wave->description, KS_MAXWAVELEN);
  }
  if (res % 2) {
    return ks_error("ks_eval_wave(%s): 'res' must be even", wave->description);
  }
  if (duration > 0 && (duration % res)) {
    return ks_error("ks_eval_wave(%s): 'duration' (%d) [us] must be divisible by 'res' (%d)", desc, duration, res);
  }
  if (duration > 0 && (duration / res) < 2) {
    return ks_error("ks_eval_wave(%s): 'duration' (%d) [us] must be at least 2x 'res' (%d)", desc, duration, res);
  }

  /* reset wave object */
  ks_init_wave(wave);

  /* fill in wave object */
  strcpy(wave->description, tmpdesc);
  wave->res = res;
  wave->duration = duration;

  /* copy the waveform */
  memcpy(wave->waveform, newwave, sizeof(float) * wave->res);



  return SUCCESS;

}

ks_eval_mirrorwave()

STATUS ks_eval_mirrorwave

(

KS_WAVE *

wave

)

Flips the contents of the KS_WAVEFORM in a KS_WAVE object

ks_eval_mirrorwave() replaces the KS_WAVEFORM with its (temporally) mirrored version. This can be used to e.g. mirror a minimum phase excitation pulse for fast recovery and T1-optimization in FSE sequences (ksfse.e).#pragma endregion See also ks_eval_stretch_rf().

Parameters

[in,out]

wave

KS_WAVE object, whose KS_WAVEFORM to be mirrored

Return values

STATUS

SUCCESS or FAILURE

                                         {
  KS_WAVEFORM tmpwave;
  int i;

  memcpy(tmpwave, wave->waveform, sizeof(float) * wave->res);

  for (i = 0; i < wave->res; i++) {
    wave->waveform[i] = tmpwave[wave->res-1 - i];
  }
  return SUCCESS;
}

ks_eval_wave_file()

STATUS ks_eval_wave_file	(	KS_WAVE *	wave,
		const char *const	desc,
		int	res,
		int	duration,
		const char *const	filename,
		const char *const	format
	)

Sets up a KS_WAVE object based on a waveform that resides on disk

ks_eval_wave_file() reads waveforms on disk into a KS_WAVE. The data format (arg 6) may currently be one of:

1. "GE": GE's file format for external pulses (.rho, .gz, etc.). The data will be divided by a factor of MAX_PG_WAMP (32766) before copied to KS_WAVE
2. "short": Plain short integer format. The data will be divided by a factor of MAX_PG_WAMP (32766) before copied to KS_WAVE
3. "float": Plain float format. Data will be read in as is and copied to KS_WAVE

When the first two formats are used the field .waveform in KS_WAVE will contain data in the range [-1.0,1.0]. res elements are read from disk in the specified format into the field .waveform in the KS_WAVE object (1st arg). duration (4th arg) must be divisible by res (3rd arg) and at least 2x res.

When using (i.e. calling ks_pg_wave()) the waveform for:

1. RF or OMEGA, nothing needs to be done in terms of amplitude scaling. For RF, amplitude scaling is handled via the KS_RF object, and for OMEGA the number of [Hz] are set directly in run-time (scan())
2. THETA, the waveform needs to be scaled to units of [degrees]
3. XGRAD, YGRAD, or ZGRAD, the waveform needs to be scaled to units of [G/cm]

Parameters

[out]	wave	KS_WAVE object to be created
[in]	desc	A description (text string) of the KS_WAVE object. This description is used for pulse sequence generation (seen in the file generated by TimeHist in MGD Sim/WTools)
[in]	res	KS_WAVE object to be created
[in]	duration	KS_WAVE object to be created
[in]	filename	Filename on disk
[in]	format	String denoting the data format on disk. Valid values are: "ge" (reads GE's *.rho files with 32byte header), "short", and "float", the latter two being header-less

Return values

STATUS

SUCCESS or FAILURE

                                                                                                                                               {
  KS_DESCRIPTION tmpdesc;
  int i;

  strncpy(tmpdesc, desc, KS_DESCRIPTION_LENGTH / 2);
  /* don't allow empty description or a description with leading space */
  if (desc == NULL || desc[0] == ' ') {
    return ks_error("ks_eval_wave_file: wave name (2nd arg) cannot be NULL or leading space");
  }
  if (res % 2) {
    return ks_error("ks_eval_wave_file(%s): 'res' must be even", wave->description);
  }
  if (duration > 0 && (duration % res)) {
    return ks_error("ks_eval_wave_file(%s): 'duration' (%d) [us] must be divisible by 'res' (%d)", desc, duration, res);
  }
  if (duration > 0 && (duration / res) < 2) {
    return ks_error("ks_eval_wave_file(%s): 'duration' (%d) [us] must be at least 2x 'res' (%d)", desc, duration, res);
  }
  if (duration < 0 || duration > 4 * KS_MAXWAVELEN) {
    return ks_error("ks_eval_wave_file(%s): 'duration' [us] must be in the range [0, %d]", desc, 4 * KS_MAXWAVELEN);
  }

  /* reset wave object */
  ks_init_wave(wave);

  /* fill in wave object */
  strcpy(wave->description, tmpdesc);
  wave->res = res;
  wave->duration = duration;

  /* read from file */
  if (!strncasecmp(format, "ge", 2)) { /* short format with 32-byte header and big-endian short int */
    KS_IWAVE iwave;
    uextwave(iwave, res, (char *) filename);
    for (i = 0; i < res; i++)
      wave->waveform[i] = (float) iwave[i] / (float) MAX_PG_WAMP;
  } else if (!strncasecmp(format, "short", 5)) {
    KS_IWAVE iwave;
    FILE *fp;
    int n;
    if ((fp = fopen(filename, "r")) == NULL)
      return ks_error("ks_eval_wave_file (%s): Error opening file '%s'", wave->description, filename);
    if ((n = fread(iwave, sizeof(short), res, fp)) < res)
      return ks_error("ks_eval_wave_file (%s): Only %d out of %d elements read from file '%s'", wave->description, n, res, filename);
    fclose(fp);
    for (i = 0; i < res; i++)
      wave->waveform[i] = (float) iwave[i] / (float) MAX_PG_WAMP;
  } else if (!strncasecmp(format, "float", 5)) {
    FILE *fp;
    int n;
    if ((fp = fopen(filename, "r")) == NULL)
      return ks_error("ks_eval_wave_file (%s): Error opening file '%s'", wave->description, filename);
    if ((n = fread(wave->waveform, sizeof(float), res, fp)) < res)
      return ks_error("ks_eval_wave_file (%s): Only %d out of %d elements read from file '%s'", wave->description, n, res, filename);
    fclose(fp);
  } else {
    return ks_error("ks_eval_wave_file (%s): 'format' (5th arg) must be 'ge','short' or 'float'", wave->description);
  }


  return SUCCESS;

} /* ks_eval_wave_file */

ks_eval_rf_sinc()

STATUS ks_eval_rf_sinc	(	KS_RF *	rf,
		const char *const	desc,
		double	bw,
		double	tbw,
		float	flip,
		int	wintype
	)

Sets up a KS_RF object with a Sinc pulse shape

For small flip angles, the Fourier transform of the RF envelope is a good approximation of the final slice profile and SLR designed pulses may not be necessary. For these cases, this function can be used to create a Sinc RF pulse (as a KS_RF object) with a desired bandwidth (BW), time-bandwidth-product (TBW) and window function (e.g. KS_RF_SINCWIN_HAMMING, see ks_enum_sincwin). An increased TBW results in more Sinc lobes and sharper slice profiles, and the minimum value is 2. The duration of the RF pulse (.rfwave.duration) increases when BW decreases or TBW increases

Parameters

[out]	rf	KS_RF object to be created
[in]	desc	A description (text string) of the KS_RF object. This description is used for pulse sequence generation (seen in the file generated by TimeHist in MGD Sim/WTools)
[in]	bw	Bandwidth of the RF pulse [Hz]
[in]	tbw	Time-bandwidth-product of the RF pulse. Higher value gives sharper slice profiles but increases the duration
[in]	flip	Nominal flip angle of the RF pulse
[in]	wintype	Window function over the Sinc. See ks_enum_sincwin for enums names that steer the window choice

Return values

STATUS

SUCCESS or FAILURE

                                                                                                           {
  KS_DESCRIPTION tmpdesc;
  int i;
  double x, window, rfenvelope;
  int duration = RUP_GRD(tbw / bw * 1e6); /* [us]. We round up to nearest multiple of 4 (GRAD_UPDATE_TIME) to better align to gradients */
  int res = duration / RF_UPDATE_TIME; /* # sample points. RF_UPDATE_TIME = 2 => res always even */

  /* don't allow empty description or a description with leading space */
  if (desc == NULL || desc[0] == ' ') {
    return ks_error("ks_eval_rf_sinc: RF name (2nd arg) cannot be NULL or leading space");
  }
  strncpy(tmpdesc, desc, KS_DESCRIPTION_LENGTH/2);
  tmpdesc[KS_DESCRIPTION_LENGTH/2] = 0;

  /* reset RF object */
  ks_init_rf(rf);

  /* fill in wave object */
  sprintf(rf->rfwave.description, "%s.wave", tmpdesc);

  if (bw < 2 || bw > 100000) {
    return ks_error("ks_eval_rf_sinc(%s): 'bw' (%g, 3rd arg) must be in range [2,100000] Hz", rf->rfwave.description, bw);
  }
  if (tbw < 2 || tbw > 100) {
    return ks_error("ks_eval_rf_sinc(%s): 'tbw' (%g, 4th arg) must be in range [2,100]", rf->rfwave.description, tbw);
  }
  if (res > KS_MAXWAVELEN || res < 4) {
    return ks_error("ks_eval_rf_sinc(%s): combination of 'bw' and 'tbw' resulted in a resolution outside the valid range [4, %d]", rf->rfwave.description, KS_MAXWAVELEN);
  }
  if (flip <= 0 || flip > 10000.0) {
    return ks_error("ks_eval_rf_sinc(%s): 'flip' must be in range (0, 10000]", rf->rfwave.description);
  }

  rf->rfwave.res = res;
  rf->rfwave.duration = duration;
  rf->iso2end = duration / 2;
  rf->start2iso = duration / 2;
  rf->bw = bw;
  rf->flip = flip;

  /* generate waveform with max 1.0 */
  for (i = 0 ; i < (res - 1) ; i++) {
    x = 2.0 * i / (res - 1) - 1.0;

    if (fabs(2.0 * PI * (tbw / 4.0)*x) > 1e-6) {
      rfenvelope = sin(2.0 * PI * (tbw / 4.0) * x) / (2.0 * PI * (tbw / 4.0) * x);
    } else {
      rfenvelope = 1.0;
    }

    window = 1.0; /* init to no filter */

    if (wintype == KS_RF_SINCWIN_HAMMING) {
      window = 0.54 + 0.46 * cos(PI * x);
    } else if (wintype == KS_RF_SINCWIN_HANNING) {
      window = (1.0 + cos(PI * x)) * 0.5;
    } else if (wintype == KS_RF_SINCWIN_BLACKMAN) {
      window = 0.42 + 0.5 * cos(PI * x) + 0.08 * cos(2 * PI * x);
    } else if (wintype == KS_RF_SINCWIN_BARTLETT) {
      if (x < 0.0)
        window = x + 1.0;
      else
        window = 1.0 - x;
    }

    rf->rfwave.waveform[i] = rfenvelope * window;

  } /* for */

  /* initialize amplitude to 1 */
  rf->amp = 1;

  /* set the usage of the RF PULSE to off until .base.ninst > 0 (see ks_pg_rf() on HOST) */
  rf->rfpulse.activity = PSD_PULSE_OFF;

  /* initialize number of occurrences of RF pulse to zero */
  rf->rfpulse.num = 0;

  /* setup rfpulse structure */
  return ks_eval_rfstat(rf);
}

ks_eval_rf_secant()

STATUS ks_eval_rf_secant	(	KS_RF *	rf,
		const char *const	desc,
		float	A0,
		float	tbw,
		float	bw
	)

Sets up a KS_RF object with a Hyperbolic Secant shape

                                                                                            {
  STATUS status;
  int debug = 1;

  /* reset RF object */
  ks_init_rf(rf);

  KS_DESCRIPTION tmpdesc;
  int i;

  /* don't allow empty description or a description with leading space */
  if (desc == NULL || desc[0] == ' ') {
    return ks_error("ks_eval_rf_secant: 'RF name' (2nd arg) cannot be NULL or leading space");
  }
  strncpy(tmpdesc, desc, KS_DESCRIPTION_LENGTH/2);
  tmpdesc[KS_DESCRIPTION_LENGTH/2] = 0;

  /* fill in wave object */
  sprintf(rf->rfwave.description, "%s.wave", tmpdesc);

  if (A0 < 0 || 0.25 < A0) {
    return ks_error("ks_eval_rf_secant(%s): 'A0' (%g, 3rd arg) must be in range [0,0.25] Gauss", rf->rfwave.description, A0);
  }
  if (tbw < 2 || 20 < tbw) {
    return ks_error("ks_eval_rf_secant(%s): 'tbw' (%g, 4th arg) must be in range [2,20]", rf->rfwave.description, tbw);
  }
  if (bw < 100 || 10000 < bw) {
    return ks_error("ks_eval_rf_secant(%s): 'bw' (%g, 5th arg) must be in range [0,10000] Hz", rf->rfwave.description, bw);
  }

  int duration = RUP_GRD((int)(1000000.0 * tbw / bw));
  int res = duration / GRAD_UPDATE_TIME; /* # sample points. RF_UPDATE_TIME = 2 => res always even */

  if (res < 4 || KS_MAXWAVELEN < res) {
    return ks_error("ks_eval_rf_secant(%s): tbw / bw resulted in a resolution(%d)/duration(%d) outside the valid range [4, %d]", rf->rfwave.description, res, duration, KS_MAXWAVELEN);
  }

  rf->rfwave.res = res;
  rf->rfwave.duration = duration;
  rf->iso2end = duration / 2;
  rf->start2iso = duration / 2;

  /* calculate pulse properties */
  float y = 5; /* 5 is a standard value from literature */
  float B = (bw * PI) / y;
  float Acheck = (PI * bw) / (2.0 * PI * 4258 * sqrt(y)); /* Gauss */

  if (Acheck > A0 * 0.5) {
    return ks_error("ks_eval_rf_secant(%s): The adiabatic condition might not be met since %g !>> %g (needs to be at least half)", rf->rfwave.description, A0, Acheck);
  }

  rf->bw = bw;
  rf->flip = 180.0;

  double rfenvelope, phaseenvelope, tau, sech;
  for (i = 0 ; i < res; i++) {

    /* range from -2pi to 2pi */
    tau = ((i / (((float)res - 1.0) * 0.5)) - 1.0) * 2.0 * PI;

    sech = 1.0 / cosh(tau * B * 0.001);
    rfenvelope = A0 * sech;
    phaseenvelope = y * log(sech) + y * log(A0);

    rf->rfwave.waveform[i] = rfenvelope;
    rf->thetawave.waveform[i] = phaseenvelope * (180.0/PI);

  }

  if (debug == 1) {
    ks_print_waveform(rf->rfwave.waveform, "secant_a.txt", rf->rfwave.res);
    ks_print_waveform(rf->thetawave.waveform, "secant_p.txt", rf->rfwave.res);
    ks_error("HS: A0=%f >> Ac=%f, bw=%f, tbw=%f", A0, Acheck, bw, tbw);
    ks_error("HS: y=%f, B=%f", y, B);
  }

  /* Normalize waveform to one & initialize amplitude to 1 */
  ks_wave_multiplyval(&rf->rfwave, 1.0 / ks_wave_absmax(&rf->rfwave));
  rf->amp = 1;

  /* set the usage of the RF PULSE to off until .base.ninst > 0 (see ks_pg_rf() on HOST) */
  rf->rfpulse.activity = PSD_PULSE_OFF;

  /* initialize number of occurrences of RF pulse to zero */
  rf->rfpulse.num = 0;

  /* setup rfpulse structure */
  status = ks_eval_rfstat(rf);
  if (status != SUCCESS) return status;

  rf->rfpulse.max_b1 = A0;
  rf->thetawave.res = res;
  rf->thetawave.duration = duration;
  rf->role = KS_RF_ROLE_INV;
  return status;
}

ks_eval_rf_hard()

STATUS ks_eval_rf_hard	(	KS_RF *	rf,
		const char *const	desc,
		int	duration,
		float	flip
	)

Sets up a KS_RF object with a rectangular (hard) pulse of a given duration.

This function creates a hard RF pulse of the desired duration. Hard pulses are typically used as non-slice selective RF pulses, as their slice profile would be very poor (Sinc-like). The resolution of the RF pulse created is equal to the duration/2

Parameters

[out]	rf	KS_RF object to be created
[in]	desc	A description (text string) of the KS_RF object. This description is used for pulse sequence generation (seen in the file generated by TimeHist in MGD Sim/WTools)
[in]	duration	Desired duration in [us] of the waveform (must be even)
[in]	flip	Nominal flip angle of the RF pulse

Return values

STATUS

SUCCESS or FAILURE

                                                                                     {
  KS_DESCRIPTION tmpdesc;
  int i;

  /* don't allow empty description or a description with leading space */
  if (desc == NULL || desc[0] == ' ') {
    return ks_error("ks_eval_rf_hard: RF name (2nd arg) cannot be NULL or leading space");
  }
  strncpy(tmpdesc, desc, KS_DESCRIPTION_LENGTH/2);
  tmpdesc[KS_DESCRIPTION_LENGTH/2] = 0;

  /* reset RF object */
  ks_init_rf(rf);

  /* fill in wave object */
  sprintf(rf->rfwave.description, "%s.wave", tmpdesc);

  if (duration > KS_MAXWAVELEN * RF_UPDATE_TIME || duration < 4) {
    return ks_error("ks_eval_rf_hard(%s): 'duration' (3rd arg) must be in range [4, %d]", rf->rfwave.description, KS_MAXWAVELEN * RF_UPDATE_TIME);
  }
  if (duration % 2) {
    return ks_error("ks_eval_rf_hard(%s): 'duration' (3rd arg) must be divisible by 2", rf->rfwave.description);
  }

  rf->rfwave.res = duration / RF_UPDATE_TIME;
  rf->rfwave.duration = duration;
  rf->iso2end = duration / 2;
  rf->start2iso = duration / 2;
  rf->bw = 0;
  rf->flip = flip;

  /* generate waveform with max 1.0 */
  for (i = 0 ; i < rf->rfwave.res ; i++) {
    rf->rfwave.waveform[i] = 1.0;
  }

  /* initialize amplitude to 1 */
  rf->amp = 1;

  /* set the usage of the RF PULSE to off until .base.ninst > 0 (see ks_pg_rf() on HOST) */
  rf->rfpulse.activity = PSD_PULSE_OFF;

  /* initialize number of occurrences of RF pulse to zero */
  rf->rfpulse.num = 0;

  /* setup rfpulse structure */
  STATUS status = ks_eval_rfstat(rf);
  if (status != SUCCESS) return status;

  return SUCCESS;
}

ks_eval_rf_hard_optimal_duration()

STATUS ks_eval_rf_hard_optimal_duration	(	KS_RF *	rf,
		const char *const	desc,
		int	order,
		float	flip,
		float	offsetFreq
	)

Sets up a KS_RF object with a rectangular (hard) pulse with optimal duration for fat selection/saturation

This function creates a hard RF pulse with optimal duration for fat selection/saturation. Hard pulses are typically used as non-slice selective RF pulses. Their slice profile is sinc-like and with this function you can create a hard pulse with a sinc-minima at the center of the spectral fat-peak. You can select wich minima using the input 'order'. A higher order generates a longer pulse duration with a more narrow frequency response. If the pulse is tuned to the fat peak, using input 'offsetFreq', the minimia will instead end up at the water-peak. The resolution of the RF pulse created is equal to the duration/2

Parameters

[out]	rf	KS_RF object to be created
[in]	desc	A description (text string) of the KS_RF object. This description is used for pulse sequence generation (seen in the file generated by TimeHist in MGD Sim/WTools)
[in]	order	Select wich minima to use
[in]	flip	Nominal flip angle of the RF pulse
[in]	offsetFreq	choose center frequency offset

Return values

STATUS

SUCCESS or FAILURE

                                                                                                                     {

  if (order < 1) {
    return ks_error("ks_eval_rf_hard(%s): 'order' (%d, 3rd arg) must be positive", desc, order);
  }

  int duration = RUP_FACTOR((int)(1000000.0 * sqrt(pow(2.0 * PI * (float)order, 2) - pow((float)flip * (PI / 180.0), 2)) / fabs(2.0 * PI * offsetFreq)), GRAD_UPDATE_TIME);

  return ks_eval_rf_hard(rf, desc, duration, flip);

}

ks_eval_rf_binomial()

STATUS ks_eval_rf_binomial	(	KS_RF *	rf,
		const char *const	desc,
		int	offResExc,
		int	nPulses,
		float	flip,
		float	offsetFreq
	)

Sets up a KS_RF object as a Binomial RF pulse

This function creates a binomial RF pulse, which consists of a series of hard pulses. Binomial pulses are used for spectral selection. They utilize the difference in resonance frequency of different tissue types, such as water and fat. Increasing the number of sub-pulses will improve the spectral selectivity but also increse the pulse duration.

Parameters

[out]	rf	KS_RF object to be created
[in]	desc	A description (text string) of the KS_RF object. This description is used for pulse sequence generation (seen in the file generated by TimeHist in MGD Sim/WTools)
[in]	offResExc	If 0 the pulse will excite the spinns at the center frequency, If 1 the pulse will excite the spinns at the offset frequency (given by input: offsetFreq)
[in]	nPulses	Number of sub-pulses
[in]	flip	Nominal flip angle of the RF pulse
[in]	offsetFreq	choose center frequency offset in Hz

Return values

STATUS

SUCCESS or FAILURE

                                                                                                                         {
  KS_DESCRIPTION tmpdesc;
  int i, j;

  /* Don't allow empty description or a description with leading space */
  if (desc == NULL || desc[0] == ' ') {
    return ks_error("ks_eval_rf_binomial: RF name (2nd arg) cannot be NULL or leading space");
  }
  strncpy(tmpdesc, desc, KS_DESCRIPTION_LENGTH/2);
  tmpdesc[KS_DESCRIPTION_LENGTH/2] = 0;

  /* Reset RF object */
  ks_init_rf(rf);

  /* Fill in wave object */
  sprintf(rf->rfwave.description, "%s.wave", tmpdesc);

  if (offResExc < 0 || offResExc > 1) {
    return ks_error("ks_eval_rf_hard(%s): 'offResExc' (3rd arg) must be either 0 or 1", rf->rfwave.description);
  }
  if (nPulses < 2 || nPulses > 10) {
    return ks_error("ks_eval_rf_hard(%s): 'nPulses' (4th arg) must be in range [2, 10]", rf->rfwave.description);
  }

  int pascalstriangle[9][10] = { {1,1},
                                {1,2,1},
                               {1,3,3,1},
                              {1,4,6,4,1},
                            {1,5,10,10,5,1},
                           {1,6,15,20,15,6,1},
                          {1,7,21,35,35,21,7,1},
                         {1,8,28,56,70,56,28,8,1},
                       {1,9,36,84,126,126,84,36,9,1} };

  int P[10];
  int pulseSum = 0;
  for (i = 0; i < nPulses; i++) {
    P[i] = pascalstriangle[nPulses - 2][i];
    pulseSum += P[i];
  }

  /* Calculate subpulse separation */
  float tau = fabs(1.0 / (2.0 * offsetFreq)); /* sec */

  /* Calculate number of samples so that each subpulse is as close as possible to maxB1, without exceeding it */
  float maxB1 = 0.20; /* Gauss */
  float pulseArea = (float) flip * (PI / 180.0); /* radians or Hz (depending on how you look at it) */
  float dt = RF_UPDATE_TIME / 1000000.0; /* sec */
  float subArea[10];
  int ntp[10];
  for (i = 0; i < nPulses; i++) {
    subArea[i] = (P[i] * pulseArea) / (pulseSum * 2.0 * PI * GAM); /* Gauss * sec */
    ntp[i] = ceil(subArea[i] / (maxB1 * dt)); /* number of time points in sub pulse */
    if (ntp[i] < 4 ) {
      ntp[i] = 4;
    }
  }

  int idx = 0;
  for (i = 0; i < nPulses; i++) {

    /* Calculate how much we have to attenuate this pulse
       to account for the fact that with this dwell time
       we couldn't hit the target flip exactly */
    float currentSubArea = ntp[i] * dt * maxB1; /* Gauss * sec */
    float amp = maxB1 * (subArea[i] / currentSubArea); /* Gauss */

    /* Flip every other sub pulse for off resonace excitaion */
    if (offResExc) {
      /* make sure the second center sub-pulse flips in the right direction */
      amp *= pow(-1.0, (float)(i + nPulses/2 % 2));
    }

    /* Stitch on the sub pulse */
    for (j = 0; j < ntp[i]; j++) {
      rf->rfwave.waveform[idx] = amp;
      idx++;
    }

    /* Stitch on the gap, skip for last sub pulse */
    if (i < nPulses - 1) {
      int ntp_gap = ceil(tau / dt - (float)ntp[i] / 2.0 - (float)ntp[i + 1] / 2.0);
      for (j = 0; j < ntp_gap; j++) {
        rf->rfwave.waveform[idx] = 0.0;
        idx++;
      }
    }
  }

  /* Make sure the resolution is divisible by 2 and the duration divisible by 4 */
  rf->rfwave.res = RUP_FACTOR(idx, 4);
  rf->rfwave.duration = rf->rfwave.res * RF_UPDATE_TIME;
  rf->iso2end = rf->rfwave.duration / 2;
  rf->start2iso = rf->rfwave.duration / 2;
  rf->bw = 0; /* ? */
  rf->flip = flip;

  /* If the resolution has been rounded up, place zeros at the end */
  for (j = idx; j < rf->rfwave.res; j++) {
    rf->rfwave.waveform[j] = 0.0;
  }

  /* Normalize waveform to one */
  ks_wave_multiplyval(&rf->rfwave, 1.0 / ks_wave_absmax(&rf->rfwave));

  /* Initialize amplitude to one */
  rf->amp = 1;

  /* Set the usage of the RF PULSE to off until .base.ninst > 0 (see ks_pg_rf() on HOST) */
  rf->rfpulse.activity = PSD_PULSE_OFF;

  /* Never allow binomial RF pulses to be stretched. We can avoid this by always setting extgradfile = 1 (even if this is not the case) */
  rf->rfpulse.extgradfile = 1;

  /* Initialize number of occurrences of RF pulse to zero */
  rf->rfpulse.num = 0;

  /* Save original waveform to fool rfstat, with abs(waveform) */
  float *saveWave = (float*)alloca(rf->rfwave.res * sizeof(float));
  if (offResExc) {
    memcpy(saveWave, rf->rfwave.waveform, rf->rfwave.res * sizeof(float));
    for (j = 0; j < rf->rfwave.res; j++) {
      rf->rfwave.waveform[j] = fabs(rf->rfwave.waveform[j]);
    }
  }

  /* Setup rfpulse structure */
  STATUS status = ks_eval_rfstat(rf);
  if (status != SUCCESS) return status;

  /* Put back the correct waveform */
  if (offResExc) {
    memcpy(rf->rfwave.waveform, saveWave, rf->rfwave.res * sizeof(float));
  }

  return SUCCESS;

}

ks_eval_rfstat()

STATUS ks_eval_rfstat

(

KS_RF *

rf

)

Sets up the RF_PULSE structure of a KS_RF object

For RF scaling, SAR calculation, and RF heating calculations, GE uses a global array of RF_PULSE structs, where each RF pulse is associated with one RF_PULSE struct each. This struct array contains RF pulses from Prescan as well as the pulse sequence itself, and is normally declared in a grad_rf_<psd>.h file.

Here, each KS_RF object has its own RF_PULSE struct (the field .rfpulse), which this function sets up. The following fields in the KS_RF object must be set before calling this ks_eval_rfstat()

1. .rfwave: Must contain the RF pulse waveform. An error is return if either .thetawave or .omegawave are non-empty (complex RF pulses not allowed)
2. .bw: The bandwidth of the RF pulse [Hz]
3. .iso2end: Time from the magnetic center of the RF pulse to the end, in [us]
4. .flip: The flip angle of the RF pulse [degrees]. In this function, .flip will set .rfpulse.nom_fa and make sure .rfpulse.act_fa points to .flip

The RF waveform will be amplitude scaled so that its maximum absolute amplitude is 1.0 before making the calculations. Also the proper links between fields int the .rfpulse (RF_PULSE) struct and the parent fields in KS_RF are set up by calling ks_eval_rf_relink()

Credits: This function has been made largely after the code by Atsushi Takahashi, GE Healthcare.

Parameters

[in,out]

rf

KS_RF object to calculate the RF_PULSE parameters for (in field .rfpulse)

Return values

STATUS

SUCCESS or FAILURE

                                 {
  double standard_pw = 1e-3;

  double nRFenvelope;
  int indx;

  double area          = 0.0;
  double abswidth      = 0.0;
  double effwidth      = 0.0;
  double dtycyc        = 0.0;
  double max_pw        = 0.0;
  double max_b1        = 0.0;
  double max_int_b1_sq = 0.0;
  double max_rms_b1    = 0.0;


  if (rf->thetawave.res > 0 || rf->omegawave.res > 0) {
    return ks_error("ks_eval_rfstat(%s): function is not validated for phase/frequency modulated RF-pulses", rf->rfwave.description);
  }
  /* require fields 'duration', 'isodelay' and 'bw' to be set to realistic values */
  if (rf->rfwave.duration < 4 || rf->rfwave.duration > KS_MAXWAVELEN * RF_UPDATE_TIME || rf->rfwave.duration % 2) {
    return ks_error("ks_eval_rfstat: 'rf.rfwave.duration' (%d) must be an even number in the range [4,%d] us", rf->rfwave.duration, KS_MAXWAVELEN * RF_UPDATE_TIME);
  }
  if (rf->bw < 0 || rf->bw > 100000) {
    return ks_error("ks_eval_rfstat: 'rf.bw' (%f) must be in the range [0,100000] Hz", rf->bw);
  }
  if (rf->iso2end < 0 || rf->iso2end > KS_MAXWAVELEN * RF_UPDATE_TIME) {
    return ks_error("ks_eval_rfstat: 'rf.iso2end' (%d) must be in the range [0,%d] us", rf->iso2end, KS_MAXWAVELEN * RF_UPDATE_TIME);
  }
  if (rf->flip < 0.0 || rf->flip > 10000.0) {
    return ks_error("ks_eval_rfstat: 'rf.flip' (%.2f) must be in the range [0,3000] deg", rf->flip);
  }
  /* for reference, see: /ESE_xxxxx/psd/include/private/sar_pm.h  */

  /* normalize RF just in case */
  ks_wave_multiplyval(&rf->rfwave, 1.0 / ks_wave_absmax(&rf->rfwave));


  for (indx = 0; indx < rf->rfwave.res; indx++) {
    nRFenvelope = rf->rfwave.waveform[indx];
    area += nRFenvelope;
    abswidth += fabs(nRFenvelope);
    effwidth += (nRFenvelope * nRFenvelope);

    /* dtycyc: % of Pulse Widths above 5% power */
    if (fabs(nRFenvelope) > 0.05)
      dtycyc++;
  }

  area     /= rf->rfwave.res;
  abswidth /= rf->rfwave.res;
  effwidth /= rf->rfwave.res;
  dtycyc   /= rf->rfwave.res;

  /* max_pw: % of the pulse width whose widest lobe is above 5% power
     GE uses max_pw = dtycyc for most pulses (sar_pm.h)
     Neither max_pw nor dtycyc seem to match well with the values used in GEs product sequences unlike
     the other fields, which seems to agree within a few percent */
  max_pw = dtycyc;

  max_b1 = rf->flip / 360.0 / (area * (rf->rfwave.duration) * 1e-6) / GAM;
  max_int_b1_sq = max_b1 * max_b1 * effwidth * (rf->rfwave.duration) * 1e-6 / standard_pw;
  max_rms_b1 = sqrt(max_int_b1_sq / ((rf->rfwave.duration) * 1e-6) * standard_pw);


  ks_eval_rf_relink(rf);

  rf->rfpulse.abswidth       =  abswidth;
  rf->rfpulse.effwidth       =  effwidth;
  rf->rfpulse.area           =  area;
  rf->rfpulse.dtycyc         =  dtycyc;
  rf->rfpulse.maxpw          =  max_pw;
  rf->rfpulse.num            =  0;
  rf->rfpulse.max_b1         =  max_b1;
  rf->rfpulse.max_int_b1_sq  =  max_int_b1_sq;
  rf->rfpulse.max_rms_b1     =  max_rms_b1;
  rf->rfpulse.nom_fa         =  rf->flip;   /* nom_fa and act_fa are equal */
  rf->rfpulse.nom_pw         =  rf->rfwave.duration;
  rf->rfpulse.nom_bw         =  rf->bw;
  rf->rfpulse.activity       =  PSD_PULSE_OFF; /* is set to PSD_SCAN_ON by ks_pg_rf() */
  rf->rfpulse.reference      =  0;
  rf->rfpulse.isodelay       =  rf->iso2end;
  rf->rfpulse.scale          =  1.0;
  if (rf->rfpulse.extgradfile != 1) {
    rf->rfpulse.extgradfile =  0; /* Only allow 0 or 1. Disallows RF pulse stretching if 1 */
  }

  return SUCCESS;
}

ks_eval_rf()

STATUS ks_eval_rf	(	KS_RF *	rf,
		const char *const	desc
	)

Sets up a KS_RF object

See documentation for the KS_RF object for details on how to prepare the KS_RF object before calling ks_eval_rf()

This function does not set up a KS_RF object by itself, merely it peforms final validation, naming, makes sure fields and links in KS_RF are properly set up. ks_eval_rf() should be called for non-slice selective RF pulses. For slice-selective RF pulses, use KS_SELRF and call ks_eval_selrf() instead

Parameters

[in,out]	rf	Pointer to the KS_RF object to be set up
[in]	desc	A description (text string) of the KS_RF object. This description is used for pulse sequence generation (seen in the file generated by TimeHist in MGD Sim/WTools)

Return values

STATUS

SUCCESS or FAILURE

                                                      {

  if (desc == NULL || desc[0] == ' ') {
    return ks_error("ks_eval_rf: description (2nd arg) cannot be NULL or begin with a space");
  } else {
    strncpy(rf->rfwave.description, desc, KS_DESCRIPTION_LENGTH / 2); /* truncate after half max # chars to allow for suffixes */
  }

  ks_eval_rf_relink(rf);

  if (rf->role <= KS_RF_ROLE_NOTSET || rf->role > KS_RF_ROLE_INV) {
    return ks_error("ks_eval_rf(%s): 'rf.role' is not set or is invalid", desc);
  }
  if (rf->flip <= 0.0 || rf->flip > 10000.0) {
    return ks_error("ks_eval_rf(%s): 'rf.flip' (%.2f) must be in the range (0,3000] deg", desc, rf->flip);
  }
  if (rf->bw < 0 || rf->bw > 100000) {
    return ks_error("ks_eval_rf(%s): 'rf.bw' (%.2f)  must be in the range [0,100000]", desc, rf->bw);
  }
  /* check that RF duration is even */
  if (rf->rfwave.duration % 2)
    return ks_error("ks_eval_rf (%s): RF duration (%d) [us] must be even", rf->rfwave.description, rf->rfwave.duration);

  /* check that RF duration and optional THETA / OMEGA waveforms have same duration */
  if (rf->omegawave.res) {
    sprintf(rf->omegawave.description, "%s", rf->rfwave.description); /* suffix '.x' is added automatically in ks_pg_wave(), where 'x' is the 1st letter of the board */
    if (rf->rfwave.duration != rf->omegawave.duration)
      return ks_error("ks_eval_rf (%s): OMEGA duration (%d) [us] must equal RF duration (%d) [us]", rf->rfwave.description, rf->omegawave.duration, rf->rfwave.duration);
  }
  if (rf->thetawave.res) {
    sprintf(rf->thetawave.description, "%s", rf->rfwave.description);
    if (rf->rfwave.duration != rf->thetawave.duration)
      return ks_error("ks_eval_rf (%s): THETA duration (%d) [us] must equal RF duration (%d) [us]", rf->rfwave.description, rf->thetawave.duration, rf->rfwave.duration);
  }

  if (rf->iso2end < 0 || rf->iso2end > rf->rfwave.duration) {
    return ks_error("ks_eval_rf (%s): 'rf.iso2end (%d) must in range [0,%d] [us]", rf->rfwave.description, rf->iso2end, rf->rfwave.duration);
  }

  /* check that .iso2end is equal to .rfpulse.isodelay */
  if (rf->rfpulse.isodelay != rf->iso2end) {
    return ks_error("ks_eval_rf (%s): 'rf.rfpulse.isodelay (%d) must be equal to 'rf.iso2end' (%d) [us]", rf->rfwave.description, rf->rfpulse.isodelay, rf->iso2end);
  }

  rf->rfpulse.isodelay = RUP_GRD(rf->rfpulse.isodelay); /* Round up using RUP_GRD() to fall on gradient raster (GRAD_UPDATE_TIME = 4us) */
  rf->iso2end = rf->rfpulse.isodelay;
  rf->start2iso = rf->rfwave.duration - rf->iso2end; /* time from start of RF pulse to its magnetic center */

  /* initialize amplitude to 1 */
  rf->amp = 1;

  /* set the usage of the RF PULSE to off until .base.ninst > 0 (see ks_pg_rf() on HOST) */
  rf->rfpulse.activity = PSD_PULSE_OFF;

  /* initialize number of occurrences of RF pulse to zero */
  rf->rfpulse.num = 0;


  return SUCCESS;

} /* ks_eval_rf */

ks_eval_rf_relink()

void ks_eval_rf_relink

(

KS_RF *

rf

)

(Internal use) Relinks pointers between fields in a KS_RF object

This function is used by other RF functions to make sure that the links from pointers in .rfpulse are relinked to other fields inside the KS_RF object. This function does not need to be called manually as long as either ks_eval_rf(), ks_eval_selrf() are called.

If a KS_RF object is copied to another KS_RF object by simple assignment ('=' sign), then these pointers must be updated before the assigned KS_RF object can be used. Best practice is to call ks_eval_rf() or ks_eval_selrf() instead of this function, as more validation is performed and because description of the new KS_RF is also updated

Parameters

[in,out]

rf

Pointer to the KS_RF object to be set up

                                  {

  /* link as required by RF_PULSE */
  rf->rfpulse.pw = &(rf->rfwave.duration);
  rf->rfpulse.amp = &(rf->amp);
  rf->rfpulse.act_fa = &(rf->flip);
  rf->rfpulse.res = &(rf->rfwave.res);
  rf->rfpulse.exciter = &ks_rhoboard;
}

ks_eval_stretch_rf()

STATUS ks_eval_stretch_rf	(	KS_RF *	rf,
		float	stretch_factor
	)

In-place stretching of a KS_RF object

This function takes a KS_RF object already set up, having some resolution (rfwave.res), bandwidth (.bw), duration (rfwave.duration) and waveform (.rfwave.waveform) and performs a linear interpolation of the waveform contained in .rfwave.waveform so its new duration becomes

newDuration = oldDuration * stretch_factor

• Note that regardless of the input resolution of the waveform, the output resolution will always be newDuration/2.
• The description of the stretched KS_RF object (.rfwave.description) is updated with a suffix stretched
• The fields .start2iso, .iso2end and .bw are automatically updated to reflect the new duration

Parameters

[in,out]	rf	Pointer to the KS_RF object to be stretched
[in]	stretch_factor	Stretch factor (float) that widens/shortens the RF pulse if larger/smaller than 1.0. If negative, the RF waveform will be mirrored (in time)

Return values

STATUS

SUCCESS or FAILURE

                                                           {

  STATUS status;
  int idx;
  int debug = 0;
  int mirror_rfpulse = 0;

  if (areSame(stretch_factor, 1.0)) {
    return SUCCESS;
  }

  mirror_rfpulse = (stretch_factor < 0); /* we are going to mirror the RF pulse after stretching */
  stretch_factor = fabsf(stretch_factor);

  if (stretch_factor < FLT_EPSILON) {
    return ks_error("%s(%s): can not stretch by %f", __FUNCTION__, rf->rfwave.description, stretch_factor);
  }

  /* get original duration/resolution and calculate new duration/resolution */
  int orgDur = rf->rfwave.duration;
  int newDur = RUP_GRD((int)(orgDur * stretch_factor));
  int orgRes = rf->rfwave.res;
  int newRes = newDur/RF_UPDATE_TIME;

  if (newRes > KS_MAXWAVELEN) {
    return ks_error("%s(%s): stretch => too high res (%d)", __FUNCTION__, rf->rfwave.description, newRes);
  }

  /* create index for interpolation */
  float *orgGrid = (float*)alloca(orgRes * sizeof(float));
  float *newGrid = (float*)alloca(newRes * sizeof(float));
  for (idx = 0; idx < orgRes; idx++) {
    orgGrid[idx] = (float) idx / (orgRes-1);
  }
  for (idx = 0; idx < newRes; idx++) {
    newGrid[idx] = (float) idx / (newRes-1);
  }

  if (debug == 1) {ks_print_waveform(rf->rfwave.waveform, "stretch_orgrf.txt", orgRes); }

  /* perform linear interpolation */
  ks_eval_linear_interp1(orgGrid, orgRes, rf->rfwave.waveform, newGrid, newRes, rf->rfwave.waveform);

  if (debug == 1) {ks_print_waveform(rf->rfwave.waveform, "stretch_newrf.txt", newRes); }

  /* set new duration, resolution and bandwidth */
  rf->rfwave.duration = newDur;
  rf->rfwave.res = newRes;
  rf->bw *= ((float)orgDur/newDur);
  rf->rfpulse.isodelay = RUP_FACTOR((int)(rf->rfpulse.isodelay * stretch_factor),RF_UPDATE_TIME);
  rf->iso2end = rf->rfpulse.isodelay;
  rf->start2iso = rf->rfwave.duration - rf->iso2end;

  if (mirror_rfpulse) {
    rf->iso2end = rf->start2iso; /* N.B.: start2iso will be updated again in ks_eval_rf() */
    rf->rfpulse.isodelay = rf->start2iso;
    ks_eval_mirrorwave(&rf->rfwave);
    ks_eval_mirrorwave(&rf->thetawave);
    ks_eval_mirrorwave(&rf->omegawave);
  }

  char description[KS_DESCRIPTION_LENGTH];
  sprintf(description, "%s_stretched", rf->rfwave.description);
  status = ks_eval_rf(rf, description);
  if (status != SUCCESS) return status;

  status = ks_eval_rfstat(rf);
  if (status != SUCCESS) return status;

  return SUCCESS;
}

ks_eval_seltrap()

STATUS ks_eval_seltrap	(	KS_TRAP *	trap,
		const char *const	desc,
		float	slewrate,
		float	slthick,
		float	bw,
		int	rfduration
	)

(Internal use) Sets up a trapezoid for RF slice selection

This function is used by ks_eval_selrf_constrained() (and its wrapper functions, e.g. ks_eval_selrf()), and there is no need to use this function directly.

Based on the RF bandwidth and duration, this function will create a trapezoid gradient that with this type of RF pulse creates a slice with the desired thickness, by in turn calling ks_calc_selgradamp().

Parameters

[out]	trap	Pointer to the KS_TRAP object to be set up
[in]	desc	A description (text string) of the KS_PHASER object. This description is used for pulse sequence generation (seen in the file generated by TimeHist in MGD Sim/WTools)
[in]	slewrate	The maximum allowed slewrate ([(G/cm) / us]). Value of 0.01 corresponds to 100 mT/m/s
[in]	slthick	The desired slice thickness in [mm]. If = 0, the slice selection gradient will have zero amplitude (hard pulses)
[in]	bw	The bandwidth of the RF pulse to use with the gradient. If = 0, the slice selection gradient will have zero amplitude (hard pulses)
[in]	rfduration	The duration of the RF pulse to use with the gradient

Return values

STATUS

SUCCESS or FAILURE

                                                                                                                        {

  /* Reset all fields and waveforms */
  ks_init_trap(trap);

  if ((rfduration < GRAD_UPDATE_TIME) || (rfduration % GRAD_UPDATE_TIME)) {
    return ks_error("%s: RF duration must be positive and divisible by 4", __FUNCTION__);
  }

  if (slthick < 0 || bw < 0) {
    /* N.B.: slthick may be exactly 0, in which case a zero amp gradient is created */
    return ks_error("%s: slice thickness & bandwidth cannot be negative", __FUNCTION__);
  }

  if (desc == NULL || desc[0] == ' ') {
    return ks_error("ks_eval_seltrap: trap name (2nd arg) cannot be NULL or begin with a space");
  }

  strncpy(trap->description, desc, KS_DESCRIPTION_LENGTH - 1);

  trap->amp = ks_calc_selgradamp(bw, slthick); /* amp [G/cm] */

  trap->ramptime = RUP_GRD((int) (trap->amp / slewrate)); /* ramp time [us] */

  if (trap->ramptime <= 0) {
    trap->ramptime = 4;
  }

  trap->plateautime = rfduration; /* plateau time [us] */
  trap->duration = trap->plateautime + 2 * trap->ramptime; /* total duration [us] */
  trap->area = (trap->plateautime + trap->ramptime) * trap->amp;


 return SUCCESS;

}

ks_eval_selrf_constrained()

STATUS ks_eval_selrf_constrained	(	KS_SELRF *	selrf,
		const char *const	desc,
		float	ampmax,
		float	slewrate
	)

Sets up a KS_SELRF object for RF slice selection, subject to gradients constraints specified as input arguments

This function does not set up the KS_RF field in KS_SELRF itself, see KS_RF and ks_eval_rf() for more details on how to prepare the .rf field in KS_SELRF before calling ks_eval_selrf_constrained()

The following fields in the KS_SELRF object must be set up before calling this function:

1. A ready KS_RF object, with a proper .rf.role (see below for details)
2. .slthick: Slice thickness in [mm]. Note that the slice thickness often needs to be made larger to compensate from slice narrowing due to multiple RF pulses. GE uses usually gscale_rfX CVs with values often between 0.8-0.9. Dividing with this number gives a thicker slice in the calculations. NOTE: .slthick = 0 is accepted and results in zero gradient amplitude with minimal 4us ramps and a plateautime = .rf.rfwave.duration (cf. ks_eval_seltrap()->ks_calc_selgradamp())

ks_eval_selrf_constrained() checks .rf.role to decide on how to set up its gradient objects. The following values of .rf.role are allowed:

• KS_RF_ROLE_EXC, indicating an RF excitation role. ks_eval_selrf_constrained() will in this case:
  • disable .pregrad
  • make .grad.plateautime equal to the RF duration (.rf.rfwave.duration) and the gradient amplitude (.grad.amp [G/cm]) will be set to the proper value depending on the BW (.rf.bw) and slice thickness (.slthick). The field .grad.description will have a ".trap" suffix added to it
  • make .postgrad to have a gradient area that rephases the slice. This is dependent on the isodelay of the RF pulse (.rf.iso2end) and the slice select gradient amplitude (.grad.amp). The field .postgrad.description will have a ".reph" suffix added to it
• KS_RF_ROLE_REF, indicating an RF refocusing role. ks_eval_selrf_constrained() will in this case:
  • use .pregrad to make the left crusher (never bridged with slice selection). The size of the crusher can be controlled by .crusherscale. The field .pregrad.description will have a ".LC" suffix added to it
  • do the same with .grad as done for KS_RF_ROLE_EXC
  • use .postgrad to make the right crusher (never bridged with slice selection). The size of the crusher can be controlled by .crusherscale. The field .postgrad.description will have a ".RC" suffix added to it
• KS_RF_ROLE_INV, indicating an RF inversion role. ks_eval_selrf_constrained() will in this case:
  • disable .pregrad
  • do the same with .grad as done for KS_RF_ROLE_EXC
  • disable .postgrad
• KS_RF_ROLE_SPSAT, indicating a spatial RF saturation. ks_eval_selrf_constrained() will in this case:
  • disable .pregrad
  • do the same with .grad as done for KS_RF_ROLE_EXC
  • use .postgrad to make a gradient spoiler (never bridged with slice selection). The size of the spoiler can be controlled by .crusherscale. The field .postgrad.description will have a ".spoiler" suffix added to it

The role KS_RF_ROLE_CHEMSAT, indicates a non-slice selective, chemically selective, RF (usually fat-sat). ks_eval_selrf_constrained() will in this case throw an error since no gradients should be used

There are three wrapper functions to this function (ks_eval_selrf(), ks_eval_selrf1(), ks_eval_selrf2()) that have reduced number of input arguments, and calls ks_eval_selrf_constrained() with different preset gradient constraints. ks_eval_selrf() makes fewest assumptions, making it the most general choice.

Using a custom gradient wave for slice selection (.gradwave)

To support e.g. VERSEd RF excitations, a custom gradient wave can be used. If .gradwave.res > 0, ks_eval_selrf_constrained() will disable .grad and use .gradwave instead. When .rf.role = KS_RF_ROLE_EXC, the rephasing gradient area (in .postgrad) will be calculated by integrating the gradient waveform from the RF isocenter to the end. .gradwave must be created before calling ks_eval_selrf_constrained() using either ks_eval_wave() or ks_eval_wave_file(), and the units must be in [G/cm]. To further scale the amplitude of .gradwave before calling ks_eval_selrf_constrained(), consider e.g. ks_wave_multiplyval(), ks_wave_absmax(), and possibly ks_wave_addval()

Parameters

[in,out]	selrf	Pointer to the KS_SELRF object to be set up
[in]	desc	A description (text string) of the KS_SELRF object. This description is used for pulse sequence generation (seen in the file generated by TimeHist in MGD Sim/WTools)
[in]	ampmax	The maximum allowed gradient amplitude ([G/cm])
[in]	slewrate	The maximum allowed slewrate ([(G/cm) / us]). Value of 0.01 corresponds to 100 mT/m/s

Return values

STATUS

SUCCESS or FAILURE

                                                                                                         {
  char selname[KS_DESCRIPTION_LENGTH], preselname[KS_DESCRIPTION_LENGTH], postselname[KS_DESCRIPTION_LENGTH];
  float minthick;
  STATUS status;

  if (desc == NULL || desc[0] == ' ') {
    return ks_error("%s: description (2nd arg) cannot be NULL or begin with a space", __FUNCTION__);
  }

  /* setup the RF pulse */
  status = ks_eval_rf(&selrf->rf, desc);
  if (status != SUCCESS) return status;

  /* with slice selection (trap or gradwave), the RF duration must be divisible by GRAD_UPDATE_TIME (4) [us] */
  if ((selrf->rf.rfwave.duration < 4) || (selrf->rf.rfwave.duration % 4)) {
    return ks_error("%s (%s): RF duration (%d) must be divisible by GRAD_UPDATE_TIME (4)", __FUNCTION__, desc, selrf->rf.rfwave.duration);
  }

  /* init members of selrf to their default state */
  ks_init_trap(&selrf->pregrad);
  ks_init_trap(&selrf->grad);
  ks_init_trap(&selrf->postgrad);
  ks_init_sms_info(&selrf->sms_info);

  /* Slice thickness */
  /* protect against e.g. +/-Inf thicknesses. Note that we do *NOT* complain about slthick = 0. This is OK and means zero amp dummy gradient */
  if (selrf->slthick < 0 || selrf->slthick > 600) {
    return ks_error("%s (%s): Thickness not in range [0,600] mm", __FUNCTION__, desc);
  }

  minthick = selrf->rf.bw  / (ampmax * (0.1) * GAM);
  if (selrf->slthick > 0 && selrf->slthick < minthick) {
    /* N.B.: checking for slthick > 0 above, allows slthick = 0 without leaading to this error (meaning no slice sel amp) */
    return ks_error("%s (%s): Minimum thickness (%.1f [mm]) violated", __FUNCTION__, desc, minthick);
  }

  /* if we have a gradwave generated, check that it has the same duration as the rfpulse */
  if (selrf->gradwave.res) {
    if (selrf->gradwave.duration != selrf->rf.rfwave.duration) {
      return ks_error("%s (%s): Custom gradient wave duration (%d) must equal the RF duration (%d)", __FUNCTION__, desc, selrf->gradwave.duration, selrf->rf.rfwave.duration);
    }
    if (selrf->gradwave.duration % selrf->gradwave.res) {
      return ks_error("%s (%s): Custom gradient wave duration (%d) must be divisible by res (%d)", __FUNCTION__, desc, selrf->gradwave.duration, selrf->gradwave.res);
    }
    sprintf(selrf->gradwave.description, "%s.gradwave", selrf->rf.rfwave.description); /* suffix '.x' is added automatically in ks_pg_wave(), where 'x' is the 1st letter of the board */
  }

  /* Setup the gradients (trapezoid case) */
  sprintf(selname, "%s.trap", selrf->rf.rfwave.description); /* suffix '.x' is added automatically in ks_pg_wave(), where 'x' is the 1st letter of the board */

  /* slice select */
  if (selrf->gradwave.res == 0) {
    /* slice select using trapezoid (.grad). If selrf->slthick = 0 or selrf->rf.bw = 0, a zero amp gradient will be created to make consistent KS_SELRF
       This is facilitated by ks_eval_seltrap()->ks_calc_selgradamp() */
    status = ks_eval_seltrap(&selrf->grad, selname, slewrate, selrf->slthick, selrf->rf.bw, selrf->rf.rfwave.duration);
    if (status != SUCCESS) return status;
  } else {
    if (selrf->gradwave.gradwave_units == KS_GRADWAVE_RELATIVE) {
      /* slice select using existing custom waveform (.gradwave) - scaling gradwave amplitude correctly regardless of current amplitude
       assumes that the maximum absolute value in gradwave.waveform corresponds to the gradient amplitude intended for the current rf BW and slthick */
      float maxval = ks_wave_max(&selrf->gradwave); /* not absmax, but max, to allow for larger negative lobes for e.g. flyback SPSP */
      if (maxval <= 0) {
        /* a gradwave that is strictly below zero, normalize instead by absmax */
        maxval = fabs(ks_wave_min(&selrf->gradwave));
      }
      ks_wave_multiplyval(&selrf->gradwave, ks_calc_selgradamp(selrf->rf.bw, selrf->slthick) / maxval);

    } else if (selrf->gradwave.gradwave_units == KS_NOTSET) {
      return ks_error("%s (%s): Custom gradient wave scaling policy not set", __FUNCTION__, desc);
    }
  }
  

  switch (selrf->rf.role) {

  /********************************************************************************/
  /*********************** RF SEL EXCITATION **************************************/
  /********************************************************************************/
  case KS_RF_ROLE_EXC:

    sprintf(postselname, "%s.reph", selrf->rf.rfwave.description);

    if (selrf->gradwave.res == 0) { /* Slice selection using .grad (KS_TRAP) */

      /* area needed for rephaser */
      selrf->postgrad.area = -(selrf->rf.rfpulse.isodelay + selrf->grad.ramptime / 2) * selrf->grad.amp;

    } else { /* Slice selection using .gradwave (KS_WAVE) */

      int i, isostart;
      int grad_dwell = selrf->gradwave.duration / selrf->gradwave.res;

      /* rephaser area needed for gradient wave */
      selrf->postgrad.area = 0;
      if (selrf->rf.iso2end_subpulse != KS_NOTSET) {
        /* SPSP's subpulses may be linear, min or max phase pulses, not neccesarily
           centered on the plateau of each lobe. For these pulses, the iso2end_subpulse field
           is not KS_NOTSET (-1). One can also have self-rephased gradwaves, not needing
           a .postgrad. In this case rf.iso2end_subpulse = 0 would disable this, while keeping
           rf.iso2end for TE calculations */
        isostart = (selrf->gradwave.duration - selrf->rf.iso2end_subpulse) / grad_dwell;
      } else {
        isostart = (selrf->gradwave.duration - selrf->rf.iso2end) / grad_dwell;
      }
      for (i = isostart; i < selrf->gradwave.res; i++) {
        selrf->postgrad.area -= selrf->gradwave.waveform[i] * grad_dwell;
      }

    }

    /* setup rephaser trapezoid */
    status = ks_eval_trap_constrained(&selrf->postgrad, postselname, ampmax, slewrate, 0);
    if (status != SUCCESS) return status;

    break;
  /********************************************************************************/
  /*********************** RF SEL REFOCUSING **************************************/
  /********************************************************************************/
  case KS_RF_ROLE_REF:

    selrf->pregrad.area = KS_RF_STANDARD_CRUSHERAREA * selrf->crusherscale;
    selrf->postgrad.area = KS_RF_STANDARD_CRUSHERAREA * selrf->crusherscale;

    sprintf(preselname,  "%s.LC", selrf->rf.rfwave.description);
    sprintf(postselname, "%s.RC", selrf->rf.rfwave.description);

    status = ks_eval_trap_constrained(&selrf->pregrad,  preselname, ampmax, slewrate, 0);
    if (status != SUCCESS) return status;
    status = ks_eval_trap_constrained(&selrf->postgrad, postselname, ampmax, slewrate, 0);
    if (status != SUCCESS) return status;

    break;
  /********************************************************************************/
  /*********************** RF SEL INVERSION ***************************************/
  /********************************************************************************/
  case KS_RF_ROLE_INV:

    /* nothing to do for pregrad or postgrad */

    break;
  /********************************************************************************/
  /*********************** RF SPATIAL SATURATION **********************************/
  /********************************************************************************/
  case KS_RF_ROLE_SPSAT:

    selrf->postgrad.area = KS_RF_STANDARD_CRUSHERAREA * selrf->crusherscale;

    sprintf(postselname, "%s.spoiler", selrf->rf.rfwave.description);

    status = ks_eval_trap_constrained(&selrf->postgrad, postselname, ampmax, slewrate, 0);
    if (status != SUCCESS) return status;

    break;
  /********************************************************************************/
  /********************************************************************************/
  /********************************************************************************/
  default:
    return ks_error("ks_eval_selrf(%s): RF role must be one of: KS_RF_ROLE_EXC, KS_RF_ROLE_REF, KS_RF_ROLE_INV, KS_RF_ROLE_SPSAT", desc);
    break;

  } /* role */



  /********************************************************************************/
  /*********************** Validation *********************************************/
  /********************************************************************************/

  if (selrf->gradwave.res) { /* custom gradient wave */
    float mostfavorable_gradmax = FMax(3, loggrd.tx, loggrd.ty, loggrd.tz);
    


    if (ks_wave_absmax(&selrf->gradwave) > mostfavorable_gradmax) {
      return ks_error("ks_eval_selrf(%s): too large gradient amplitude for 'gradwave'", desc);
    }

    /* we explicitly check for the hardware limits since loggrd is typically lower because obloptimze_epi 
    (which allows access to the full slewrate limits) was not called for the rf pulse  */
    float max_sys_slewrate = phygrd.zfs/phygrd.zrt;
    float max_gradwave_slewrate = ks_wave_maxslew(&selrf->gradwave);
    if (max_gradwave_slewrate > max_sys_slewrate) {
      return ks_error("ks_eval_selrf(%s): slewrate of gradwave (%.1f T/m/s) exceeds limits (%.1f T/m/s)", desc, max_gradwave_slewrate*1e4, max_sys_slewrate*1e4);
    }

  } else { /* standard trapezoid */

    /* timing check: grad vs. RF */
    if (selrf->grad.duration && selrf->grad.plateautime != selrf->rf.rfwave.duration) {
      return ks_error("ks_eval_selrf(%s): grad.plateautime (%d) != rf.rfwave.duration (%d)", desc, selrf->grad.plateautime, selrf->rf.rfwave.duration);
    }

    /* gradient duration divisibility check */
    if (selrf->grad.duration % GRAD_UPDATE_TIME) {
      return ks_error("ks_eval_selrf(%s): grad.duration (%d) must be divisible by 4 [us]", desc, selrf->grad.duration);
    }

  }

  return SUCCESS;

} /* ks_eval_selrf_constrained */

ks_eval_selrf()

STATUS ks_eval_selrf	(	KS_SELRF *	selrf,
		const char *const	desc
	)

Sets up a KS_SELRF object for RF slice selection with preset gradient constraints

This is a wrapper function to ks_eval_selrf_constrained() with gradient constraints set to allow this KS_SELRF to be played on any axis while other gradients (set up with the same constraints) can be played out on the other two gradient boards, for any slice angulation. This is the generic and safest configuration, but for thin slices and high RF BWs, the gradient limits may be reached, especially for double oblique slices

See ks_eval_selrf_constrained() for details on fields that need to be set before calling this function

Parameters

[in,out]	selrf	Pointer to the KS_SELRF object to be set up
[in]	desc	A description (text string) of the KS_SELRF object. This description is used for pulse sequence generation (seen in the file generated by TimeHist in MGD Sim/WTools)

Return values

STATUS

SUCCESS or FAILURE

                                                               {

  return ks_eval_selrf_constrained(selrf, desc, ks_syslimits_ampmax(loggrd), ks_syslimits_slewrate(loggrd));

}

ks_eval_selrf2()

STATUS ks_eval_selrf2	(	KS_SELRF *	selrf,
		const char *const	desc
	)

Sets up a KS_SELRF object for RF slice selection with preset gradient constraints

This is a wrapper function to ks_eval_selrf_constrained() with gradient constraints set to allow this KS_SELRF to be played on any axis while one more gradient (set up with the same constraints) can be played out on another gradient board, for any slice angulation. For double oblique slice angulations, this function will allow for thinner slices and higher RF BWs than ks_eval_selrf()

See ks_eval_selrf_constrained() for details on fields that need to be set before calling this function

Parameters

[in,out]	selrf	Pointer to the KS_SELRF object to be set up
[in]	desc	A description (text string) of the KS_SELRF object. This description is used for pulse sequence generation (seen in the file generated by TimeHist in MGD Sim/WTools)

Return values

STATUS

SUCCESS or FAILURE

                                                                {

  return ks_eval_selrf_constrained(selrf, desc, ks_syslimits_ampmax2(loggrd), ks_syslimits_slewrate2(loggrd));

}

ks_eval_selrf1()

STATUS ks_eval_selrf1	(	KS_SELRF *	selrf,
		const char *const	desc
	)

Sets up a KS_SELRF object for RF slice selection with preset gradient constraints

This is a wrapper function to ks_eval_selrf_constrained() with gradient constraints set to allow this KS_SELRF to be played on any axis, as long as no other gradients are be played out simultaneously. For double oblique slice angulations, this function will allow for thinner slices and higher RF BWs than ks_eval_selrf() and ks_eval_selrf2()

See ks_eval_selrf_constrained() for details on fields that need to be set before calling this function

Parameters

[in,out]	selrf	Pointer to the KS_SELRF object to be set up
[in]	desc	A description (text string) of the KS_SELRF object. This description is used for pulse sequence generation (seen in the file generated by TimeHist in MGD Sim/WTools)

Return values

STATUS

SUCCESS or FAILURE

                                                                {

  return ks_eval_selrf_constrained(selrf, desc, ks_syslimits_ampmax1(loggrd), ks_syslimits_slewrate1(loggrd));

}

ks_eval_selrf1p()

STATUS ks_eval_selrf1p	(	KS_SELRF *	selrf,
		const char *const	desc
	)

Sets up a KS_SELRF object for RF slice selection with physical gradient constraints (invariant to slice angulation)

Parameters

[in,out]	selrf	Pointer to the KS_SELRF object to be set up
[in]	desc	A description (text string) of the KS_SELRF object. This description is used for pulse sequence generation (seen in the file generated by TimeHist in MGD Sim/WTools)

Return values

STATUS

SUCCESS or FAILURE

                                                                 {

  return ks_eval_selrf_constrained(selrf, desc, ks_syslimits_ampmax1p(loggrd), ks_syslimits_slewrate1p(loggrd));

}

ks_eval_sms_get_phase_modulation()

STATUS ks_eval_sms_get_phase_modulation	(	float *	sms_phase_modulation,
		const int	sms_multiband_factor,
		const int	sms_phase_modulation_mode
	)

Sets up an array with values for phase modulation between slices in a multi-band (MB) RF

Parameters

[out]	sms_phase_modulation	Array with phase modulation between slices in a MB RF
[in]	sms_multiband_factor	The multi-band acceleration factor
[in]	sms_phase_modulation_mode	See ks_enum_smstype for options

Return values

STATUS

SUCCESS or FAILURE

                                                                                                                                          {
  /*
  %   Return optimal phases for phase-modulated or amplitude-modulated low-peak power multiband pulses.
  %
  %   sms_phase_modulation: Optimal phases
  %   sms_multiband_factor: Number of bands
  %   sms_phase_modulation_mode: phasmod, amplmod, or quadmod
  %
  %   Adopted for EPIC from Will Grissom's (Vanderbilt University, 2015) MATLAB code by Ola Norbeck (Karolinska Unviversity Hospital, 2015).
  */

  int jdx;

  if (sms_phase_modulation_mode == KS_SELRF_SMS_PHAS_MOD_PHAS) {

    /* Wong's sms_phase_modulation: From E C Wong, ISMRM 2012, p. 2209 */

    if ((sms_multiband_factor < 2) || (sms_multiband_factor > 16)) {
      return ks_error("ks_eval_sms_get_phase_modulation: multiband factor (%d, 2nd arg) must be in range [2,16] for Wong's sms_phase_modulation", sms_multiband_factor);
    }

    float P[15][16] = {
      /* mbf = 2  */  {0.0, 0.0}, /* alt.{0.0, 3.142} */
      /* mbf = 3  */  {0.0, 0.730, 4.602},
      /* mbf = 4  */  {0.0, 3.875, 5.940, 6.197},
      /* mbf = 5  */  {0.0, 3.778, 5.335, 0.872, 0.471},
      /* mbf = 6  */  {0.0, 2.005, 1.674, 5.012, 5.736, 4.123},
      /* mbf = 7  */  {0.0, 3.002, 5.998, 5.909, 2.624, 2.528, 2.440},
      /* mbf = 8  */  {0.0, 1.036, 3.414, 3.778, 3.215, 1.756, 4.555, 2.467},
      /* mbf = 9  */  {0.0, 1.250, 1.783, 3.558, 0.739, 3.319, 1.296, 0.521, 5.332},
      /* mbf = 10 */  {0.0, 4.418, 2.360, 0.677, 2.253, 3.472, 3.040, 3.974, 1.192, 2.510},
      /* mbf = 11 */  {0.0, 5.041, 4.285, 3.001, 5.765, 4.295, 0.056, 4.213, 6.040, 1.078, 2.759},
      /* mbf = 12 */  {0.0, 2.755, 5.491, 4.447, 0.231, 2.499, 3.539, 2.931, 2.759, 5.376, 4.554, 3.479},
      /* mbf = 13 */  {0.0, 0.603, 0.009, 4.179, 4.361, 4.837, 0.816, 5.995, 4.150, 0.417, 1.520, 4.517, 1.729},
      /* mbf = 14 */  {0.0, 3.997, 0.830, 5.712, 3.838, 0.084, 1.685, 5.328, 0.237, 0.506, 1.356, 4.025, 4.483, 4.084},
      /* mbf = 15 */  {0.0, 4.126, 2.266, 0.957, 4.603, 0.815, 3.475, 0.977, 1.449, 1.192, 0.148, 0.939, 2.531, 3.612, 4.801},
      /* mbf = 16 */  {0.0, 4.359, 3.510, 4.410, 1.750, 3.357, 2.061, 5.948, 3.000, 2.822, 0.627, 2.768, 3.875, 4.173, 4.224, 5.941}
    };

    for (jdx = 0; jdx < sms_multiband_factor; jdx++ ) {
      sms_phase_modulation[jdx] = P[sms_multiband_factor - 2][jdx];
    }

  } else if (sms_phase_modulation_mode == KS_SELRF_SMS_PHAS_MOD_AMPL) {

    /*  Seada's Hermitian sms_phase_modulation: From Seada et. al. Optimized Amplitude Modulated Multiband RF Pulse Design. MRM 2017 */

    if ((sms_multiband_factor < 3) || (sms_multiband_factor > 12)) {
      return ks_error("ks_eval_sms_get_phase_modulation: multiband factor (%d, 2nd arg) must be in range [3,12] for Seada's Hermitian sms_phase_modulation", sms_multiband_factor);
    }

    float P[10][12] = {
      /* mbf = 3  */  {1.2846,  0.0000, -1.2846},
      /* mbf = 4  */  {0.9739,  1.3718, -1.3718, -0.9739},
      /* mbf = 5  */  {1.1572, -0.9931,  0.0000,  0.9931, -1.1572},
      /* mbf = 6  */  {1.6912,  2.8117,  1.1572, -1.1572, -2.8117, -1.6912},
      /* mbf = 7  */  {2.5813, -0.5620,  0.1030,  0.0000, -0.1030,  0.5620, -2.5813},
      /* mbf = 8  */  {2.1118,  0.2199,  1.4643,  1.9914, -1.9914, -1.4643, -0.2199, -2.1118},
      /* mbf = 9  */  {0.4800, -2.6669, -0.6458, -0.4189,  0.0000,  0.4189,  0.6458,  2.6669, -0.4800},
      /* mbf = 10 */  {1.6825, -2.3946,  2.9130,  0.3037,  0.7365, -0.7365, -0.3037, -2.9130,  2.3946, -1.6825},
      /* mbf = 11 */  {1.4050,  0.8866, -1.8535,  0.0698, -1.4940,  0.0000,  1.4940, -0.0698,  1.8535, -0.8866, -1.4050},
      /* mbf = 12 */  {1.7296,  0.4433,  0.7208,  2.1904, -2.1956,  0.9844, -0.9844,  2.1956, -2.1904, -0.7208, -0.4433, -1.7296}
    };

    for (jdx = 0; jdx < sms_multiband_factor; jdx++ ) {
      sms_phase_modulation[jdx] = P[sms_multiband_factor - 3][jdx];
    }


  } else if (sms_phase_modulation_mode == KS_SELRF_SMS_PHAS_MOD_QUAD) {

    /* Grissom's quadratic sms_phase_modulation (unpublished) */

    for (jdx = 0; jdx < sms_multiband_factor; jdx++) {
      sms_phase_modulation[jdx] = pow( (3.4 / sms_multiband_factor) * (float)(1.0 + (float)jdx - ((float)sms_multiband_factor / 2.0) - 0.5), 2.0); /* sms_phase_modulation for each band */
    }

  } else {

    return ks_error("ks_eval_sms_get_phase_modulation: sms_phase_modulation_mode (%d, 3rd arg) is of unrecognized type. Choose phasmod = 1, amplmod = 2, or quadmod = 3", sms_phase_modulation_mode);

  }; /* end of if  */

  return SUCCESS;

} /* EOF */

ks_eval_findb1()

float ks_eval_findb1	(	KS_SELRF *	selrf,
		float	max_b1,
		double	scaleFactor,
		int	sms_multiband_factor,
		int	sms_phase_modulation_mode,
		float	sms_slice_gap
	)

Finds a stretch factor leading to the specified peak B1

Parameters

[in]	selrf	rf object KS_SELRF
[in]	max_b1	peak B1
[in]	scaleFactor	initial stretch factor
[in]	sms_multiband_factor	SMS factor
[in]	sms_phase_modulation_mode	SMS phase modulation mode
[in]	sms_slice_gap	SMS slice gap

Returns

float stretch factor

                                                                                                                                                      {

  STATUS status;
  float curr_b1 = 0.0;
  int debug = 0;
  double stepDown = 1.01;
  double stepUp = 1.05;

  /* Init tmp rf object */
  KS_SELRF selrftmp;
  ks_init_selrf(&selrftmp);

  /* Make the RF-pulse longer until its B1 peak is under its target */
  do {
    selrftmp = *selrf;
    ks_eval_stretch_rf(&selrftmp.rf, scaleFactor);
    status = ks_eval_selrf(&selrftmp, "tmp+");
    if (status == FAILURE) {continue;}
    if (sms_multiband_factor > 1) {
      status = ks_eval_sms_make_multiband(&selrftmp, &selrftmp, sms_multiband_factor, sms_phase_modulation_mode, sms_slice_gap, 0);
    } else {
      status = ks_eval_rfstat(&selrftmp.rf);
    }
    if (status == FAILURE) {continue;}
    curr_b1 = selrftmp.rf.rfpulse.max_b1;
    scaleFactor *= stepUp;
    if (debug) {ks_dbg("+ scaleFactor=%f, currB1=%f, maxB1=%f", scaleFactor, curr_b1, max_b1);}
  }
  while (fabs(curr_b1) > max_b1);
  scaleFactor /= stepUp;

  /* Make the RF-pulse shorter until its B1 peak hits its target */
  while ((fabs(curr_b1) < max_b1) && (scaleFactor > 0)) {
    selrftmp = *selrf;
    ks_eval_stretch_rf(&selrftmp.rf, scaleFactor);
    status = ks_eval_selrf(&selrftmp, "tmp-");
    if (status == FAILURE) {break;}
    if (sms_multiband_factor > 1) {
      status = ks_eval_sms_make_multiband(&selrftmp, &selrftmp, sms_multiband_factor, sms_phase_modulation_mode, sms_slice_gap, 0);
    } else {
      status = ks_eval_rfstat(&selrftmp.rf);
    }
    if (status == FAILURE) {break;}
    curr_b1 = selrftmp.rf.rfpulse.max_b1;
    scaleFactor /= stepDown;
    if (debug) {ks_dbg("- scaleFactor=%f, currB1=%f, maxB1=%f", scaleFactor, curr_b1, max_b1);}
  }
  scaleFactor *= stepDown;

  return scaleFactor;
}

ks_eval_transient_SPGR_FA_train_recursive()

void ks_eval_transient_SPGR_FA_train_recursive	(	float *	FA_train,
		float *	MZ_train,
		int	N,
		float	E1,
		float	target_MT,
		int	n
	)

                                                                                                                          {
  float MT;
  n = (n < 0) ? (N-1) : n;
  if (n == 0) {
    MZ_train[n] = 1.0;
    FA_train[n] = asin(target_MT);
  } else {
    ks_eval_transient_SPGR_FA_train_recursive(FA_train, MZ_train, N, E1, target_MT, n-1);
    MT = MZ_train[n-1] * sin(FA_train[n-1]);
    MZ_train[n] = MZ_train[n-1] * cos(FA_train[n-1]) * E1 + 1.0 - E1;
    FA_train[n] = asin( MT / MZ_train[n] );
  }
}

ks_eval_transient_SPGR_FA_train_binary_search()

void ks_eval_transient_SPGR_FA_train_binary_search	(	float *	FA_train,
		float *	MZ_train,
		int	N,
		float	E1,
		float	MTlo,
		float	MThi,
		float	total_FA
	)

                                                                                                                                              {
  float thresh = 1e-7;
  if ((MThi-MTlo) < thresh) {
    return ks_eval_transient_SPGR_FA_train_recursive(FA_train, MZ_train, N, E1, MTlo, -1);
  }
  float MT = (MTlo + MThi)/2.0;
  ks_eval_transient_SPGR_FA_train_recursive(FA_train, MZ_train, N, E1, MT, -1);
  if (ks_eval_check_FA_train(N, FA_train, MZ_train, total_FA) == FAILURE) {
    return ks_eval_transient_SPGR_FA_train_binary_search(FA_train, MZ_train, N, E1, MTlo, MT, total_FA); /* Less greed */
  } else {
    return ks_eval_transient_SPGR_FA_train_binary_search(FA_train, MZ_train, N, E1, MT, MThi, total_FA); /* More greed */
  }
}

ks_eval_check_FA_train()

STATUS ks_eval_check_FA_train	(	int	N,
		float *	FA_train,
		float *	MZ_train,
		float	total_FA
	)

                                                                                       {
  if (isnan(FA_train[N-1])) {return FAILURE;} /* infeasible solution */
  if (acos(MZ_train[N-1] * cos(FA_train[N-1])) > total_FA * PI/180.0) {return FAILURE;} /* total FA exceeded */
  int n;
  for (n=0; n<N; n++) {
    if ((n > 0) && (FA_train[n] < FA_train[n-1])) {return FAILURE;} /* decreasing FA */
    if ((n < N-1) && (FA_train[n] > 89.0 * PI/180.0)) {return FAILURE;} /* only last FA may be 90 degrees */
  }
  return SUCCESS;
}

ks_eval_transient_SPGR_FA_train()

STATUS ks_eval_transient_SPGR_FA_train	(	float *	FA_train,
		int	N,
		float	TR,
		float	T1,
		float	total_FA
	)

                                                                                                   {
  if (N <= 0) {return ks_error("%s: N must be >0, but is %d", __FUNCTION__, N);}
  float E1 = exp(-TR/T1);
  float MTlo = 0.0;
  float MThi = 1.0;
  float MZ_train[N];
  ks_eval_transient_SPGR_FA_train_binary_search(FA_train, MZ_train, N, E1, MTlo, MThi, total_FA);
  if (ks_eval_check_FA_train(N, FA_train, MZ_train, total_FA) == FAILURE) {
    return FAILURE;
  } else {
    int n;
    for (n=0; n<N; n++) {FA_train[n]*=180.0/PI;} /* radians->degrees */
    return SUCCESS;
  }
}

ks_eval_sms_make_multiband()

STATUS ks_eval_sms_make_multiband	(	KS_SELRF *	selrfMB,
		const KS_SELRF *	selrf,
		const int	sms_multiband_factor,
		const int	sms_phase_modulation_mode,
		const float	sms_slice_gap,
		int	debug
	)

Creates a SMS (simultaneous-multi-slice) version of a KS_SELRF object

Parameters

[out]	selrfMB	Pointer to multiband (SMS) KS_SELRF object
[in]	selrf	The original (single-band) KS_SELRF object (set up using ks_eval_selrf())
[in]	sms_multiband_factor	The multi-band acceleration factor
[in]	sms_phase_modulation_mode	See ks_enum_smstype for options
[in]	sms_slice_gap	Slice gap in [mm] for the selrfMB pulse
[in]	debug	Debug flag for writing out text files (SIM: in current dir HW:/usr/g/mrraw/kstmp)

Return values

STATUS

SUCCESS or FAILURE

                                                                                                             {
/*
%
*/
  int jdx, idx, kdx;
  float sms_phase_modulation[16] = KS_INITZEROS(16);
  STATUS status;

  /* Debug stuff */
  int single_band_mode = -1;
  char fname[KS_DESCRIPTION_LENGTH + 14];
  char outputdir_uid[250];
  FILE *asciiWaveReal;
  FILE *asciiWaveImag;
  FILE *asciiWaveRealMB;
  FILE *asciiWaveImagMB;
  FILE *asciiWaveRealMod;
  FILE *asciiWaveImagMod;
  FILE *asciiWaveParams;

  if (debug) {

#ifdef SIM
    sprintf(outputdir_uid, "./");
#else
    char cmd[250];
    sprintf(outputdir_uid, "/usr/g/mrraw/kstmp/%010d/", rhkacq_uid);
    sprintf(cmd, "mkdir -p %s > /dev/null", outputdir_uid);
    system(cmd);
#endif

    sprintf(fname, "%s%s_mb_rf_Real.txt", outputdir_uid, selrfMB->rf.rfwave.description);
    asciiWaveReal = fopen(fname,"w");
    sprintf(fname, "%s%s_mb_rf_Imag.txt", outputdir_uid, selrfMB->rf.rfwave.description);
    asciiWaveImag = fopen(fname,"w");
    sprintf(fname, "%s%s_mb_rfMB_Real.txt", outputdir_uid, selrfMB->rf.rfwave.description);
    asciiWaveRealMB = fopen(fname,"w");
    sprintf(fname, "%s%s_mb_rfMB_Imag.txt", outputdir_uid, selrfMB->rf.rfwave.description);
    asciiWaveImagMB = fopen(fname,"w");
    sprintf(fname, "%s%s_mod_rfMB_Real.txt", outputdir_uid, selrfMB->rf.rfwave.description);
    asciiWaveRealMod = fopen(fname,"w");
    sprintf(fname, "%s%s_mod_rfMB_Imag.txt", outputdir_uid, selrfMB->rf.rfwave.description);
    asciiWaveImagMod = fopen(fname,"w");
  }

  /* Check if gradient is present */
  if (areSame(selrf->grad.amp, 0)){
    return ks_error("ks_eval_sms_make_multiband: Need a pre calculated gradient amp (2nd arg. selrf->grad.amp = %g)", selrf->grad.amp);
  }

  /* Duplicate the selRF structure  */
  if (selrfMB != selrf ) {
    *selrfMB = *selrf;
  }

  /* Set info struct */
  selrfMB->sms_info.mb_factor = sms_multiband_factor;
  selrfMB->sms_info.slice_gap = sms_slice_gap;
  selrfMB->sms_info.pulse_type = KS_SELRF_SMS_MB;

  /* Save max b1 to make sure it does not get overwritten */
  double base_rf_max_amp = ks_waveform_absmax(selrf->rf.rfwave.waveform, ks_wave_res(&selrf->rf.rfwave));

  /* Get phase modulation to lower peak B1 */
  if (sms_phase_modulation_mode != KS_SELRF_SMS_PHAS_MOD_OFF) {
    status = ks_eval_sms_get_phase_modulation(sms_phase_modulation, sms_multiband_factor, sms_phase_modulation_mode);
    if (status != SUCCESS) return status;
  }

  /* initialize thetawave */
  if (selrfMB->rf.thetawave.res == 0) {
    ks_init_wave(&selrfMB->rf.thetawave);
    strncpy(selrfMB->rf.thetawave.description, selrfMB->rf.rfwave.description, KS_DESCRIPTION_LENGTH);
    selrfMB->rf.thetawave.res = selrfMB->rf.rfwave.res;
    selrfMB->rf.thetawave.duration = selrfMB->rf.rfwave.duration;
  }

  if (debug) {sprintf(fname, "%s%s_mb_rf_base.txt", outputdir_uid, selrfMB->rf.rfwave.description); ks_print_waveform(selrf->rf.rfwave.waveform, fname, selrf->rf.rfwave.res); }

  /* Figure out a new resolution, since many pulses are of low resolution */
  int newRes = selrf->rf.rfwave.duration/RF_UPDATE_TIME;
  int nPoints = newRes/selrf->rf.rfwave.res;

  /* Calc and apply sms modulation to base pulse */
  float *sms_wave_real = (float*)alloca(newRes*sizeof(float));
  float *sms_wave_imag = (float*)alloca(newRes*sizeof(float));

  kdx = 0;
  for (idx=0; idx < newRes; idx++) {

    double wave_real, wave_imag, sms_modulation_real = 0, sms_modulation_imag = 0, p, slice_offset;

    /* Convert base pulse from polar to cartesian */
    wave_real = selrf->rf.rfwave.waveform[kdx] * cos(selrf->rf.thetawave.waveform[kdx]*(PI/180.0));
    wave_imag = selrf->rf.rfwave.waveform[kdx] * sin(selrf->rf.thetawave.waveform[kdx]*(PI/180.0));
    if (debug) {
      fprintf(asciiWaveReal, "%d %f\n", idx, wave_real); fflush(asciiWaveReal);
      fprintf(asciiWaveImag, "%d %f\n", idx, wave_imag); fflush(asciiWaveImag);
    }

    if (idx % nPoints == 0 && idx > 0) {
      kdx++;
    }

    /* Calc sms modulation */
    double centeredIndex = idx - (newRes-1) * 0.5;
    for (jdx = 0; jdx < sms_multiband_factor; jdx++) {

      slice_offset = (sms_slice_gap / 10) * (1.0 + jdx - (sms_multiband_factor / 2.0) - 0.5);
      p = 2.0 * PI * GAM * slice_offset * selrf->grad.amp * centeredIndex * RF_UPDATE_TIME * 1e-6 + sms_phase_modulation[jdx];

      if (single_band_mode >= 0) {
        if (jdx == single_band_mode) {
          sms_modulation_real += cos(p);
          sms_modulation_imag += sin(p);
        }
      } else {
        sms_modulation_real += cos(p);
        sms_modulation_imag += sin(p);
      }
    }

    /* Apply sms modulation via complex multiplication */
    sms_wave_real[idx] = wave_real * sms_modulation_real - wave_imag * sms_modulation_imag;
    sms_wave_imag[idx] = wave_real * sms_modulation_imag + wave_imag * sms_modulation_real;

    if (debug) {
      fprintf(asciiWaveRealMB, "%d %f\n", idx, sms_wave_real[idx]); fflush(asciiWaveRealMB);
      fprintf(asciiWaveImagMB, "%d %f\n", idx, sms_wave_imag[idx]); fflush(asciiWaveImagMB);
      fprintf(asciiWaveRealMod, "%d %f\n", idx, sms_modulation_real); fflush(asciiWaveRealMod);
      fprintf(asciiWaveImagMod, "%d %f\n", idx, sms_modulation_imag); fflush(asciiWaveImagMod);
    }

  }

  if (debug) {
    fclose(asciiWaveReal);
    fclose(asciiWaveImag);
    fclose(asciiWaveRealMB);
    fclose(asciiWaveImagMB);
    /*ks_error("GAM=%g, PI=%g, grad.amp=%g, slice_gap=%g, dt=%d", GAM, PI, selrf->grad.amp, sms_slice_gap, RF_UPDATE_TIME);*/
  }

  kdx = 0;
  for (idx=0; idx < newRes; idx++) {

    if (sms_phase_modulation_mode == KS_SELRF_SMS_PHAS_MOD_OFF || sms_phase_modulation_mode == KS_SELRF_SMS_PHAS_MOD_AMPL) {

      /* Use real part and place waves in selrfMB */
      selrfMB->rf.rfwave.waveform[idx] = sms_wave_real[idx];

    } else {

      /* Convert from polar to cartesian and place waves in selrfMB */
      selrfMB->rf.rfwave.waveform[idx]    = sqrt(pow(sms_wave_real[idx], 2.0) + pow(sms_wave_imag[idx], 2.0));
      selrfMB->rf.thetawave.waveform[idx] = atan2(sms_wave_imag[idx], sms_wave_real[idx]) * (180.0/PI);

    }

    if (idx % nPoints == 0 && idx > 0) {
      kdx++;
    }
  }

  /* Update resolution fields */
  selrfMB->rf.rfwave.res = newRes;
  if (sms_phase_modulation_mode == KS_SELRF_SMS_PHAS_MOD_OFF || sms_phase_modulation_mode == KS_SELRF_SMS_PHAS_MOD_AMPL) {
    selrfMB->rf.thetawave.res = 0;
    selrfMB->rf.thetawave.duration = 0;
  } else {
    selrfMB->rf.thetawave.res = newRes;
  }

  if (debug) {sprintf(fname, "%s%s_mb_rf.txt", outputdir_uid, selrfMB->rf.rfwave.description); ks_print_waveform(selrfMB->rf.rfwave.waveform, fname, selrfMB->rf.rfwave.res); }
  if (debug) {sprintf(fname, "%s%s_mb_theta.txt", outputdir_uid, selrfMB->rf.rfwave.description); ks_print_waveform(selrfMB->rf.thetawave.waveform, fname, selrfMB->rf.thetawave.res); }

  /* Modify rfpulse structure */
  double standard_pw = 1e-3;
  double b1_scale_factor = ks_waveform_absmax(selrfMB->rf.rfwave.waveform, newRes) / base_rf_max_amp;
  selrfMB->rf.rfpulse.max_b1 *= b1_scale_factor;
  selrfMB->rf.rfpulse.area /= b1_scale_factor;
  selrfMB->rf.rfpulse.effwidth /= b1_scale_factor;
  selrfMB->rf.rfpulse.max_int_b1_sq = selrfMB->rf.rfpulse.max_b1 * selrfMB->rf.rfpulse.max_b1 * selrfMB->rf.rfpulse.effwidth * (selrfMB->rf.rfwave.duration) * 1e-6 / standard_pw;
  selrfMB->rf.rfpulse.max_rms_b1 = sqrt(selrfMB->rf.rfpulse.max_int_b1_sq / ((selrfMB->rf.rfwave.duration) * 1e-6) * standard_pw);


  /* Normalize to 1 */
  ks_wave_multiplyval(&selrfMB->rf.rfwave, 1.0 / ks_wave_absmax(&selrfMB->rf.rfwave));

  /* register the RF for later heat calcs and RF scaling */
  char description[KS_DESCRIPTION_LENGTH + 4];
  sprintf(description, "%s_sms", selrfMB->rf.rfwave.description);
  status = ks_eval_rf(&selrfMB->rf, description);
  if (status != SUCCESS) return status;

  if (debug) {
    sprintf(fname, "%s%s_mb_params.txt", outputdir_uid, selrfMB->rf.rfwave.description);
    asciiWaveParams = fopen(fname,"w");
    fprintf(asciiWaveParams, "%f\n", (float)selrfMB->rf.flip);
    fprintf(asciiWaveParams, "%f\n", (float)selrfMB->grad.amp);
    fprintf(asciiWaveParams, "%f\n", (float)selrfMB->rf.rfpulse.max_b1);
    fprintf(asciiWaveParams, "%f\n", (float)selrfMB->slthick);
    fprintf(asciiWaveParams, "%f\n", (float)sms_slice_gap);
    fprintf(asciiWaveParams, "%f\n", (float)sms_multiband_factor);
    fprintf(asciiWaveParams, "%f\n", (float)b1_scale_factor);
    fflush(asciiWaveParams); fclose(asciiWaveParams);
  }

  return SUCCESS;

} /* EOF */

ks_eval_sms_calc_slice_gap()

float ks_eval_sms_calc_slice_gap	(	int	sms_multiband_factor,
		const SCAN_INFO *	org_slice_positions,
		int	nslices,
		float	slthick,
		float	slspace
	)

Calculates the resulting slice gap in [mm] for SMS RF

Parameters

[in]	sms_multiband_factor	The multi-band acceleration factor
[in]	org_slice_positions	SCAN_INFO struct holding the original slice information
[in]	nslices	Prescribed number of slices
[in]	slthick	Prescribed slice thickness
[in]	slspace	Prescribed slice spacing

Return values

slicegap

SMS slice gap in [mm]

                                                                                                                                            {

  float gap;

  if (nslices % sms_multiband_factor) {
    ks_error("ks_eval_sms_calc_slice_gap: Number of slices (%d, 3rd arg) must be divisible with the MB factor (%d, 1st arg)", nslices, sms_multiband_factor);
  }

  /* gap between MB slices mm */
  /*gap = org_slice_positions[nslices/sms_multiband_factor].optloc - org_slice_positions[0].optloc;*/
  gap = (float)((nslices + sms_multiband_factor - 1) / sms_multiband_factor) * (float)(slthick + slspace);

  return gap;

} /* EOF */

ks_eval_sms_calc_caipi_area()

float ks_eval_sms_calc_caipi_area	(	int	caipi_fov_shift,
		float	sms_slice_gap
	)

Calculates the CAIPI blip area

Parameters

[in]	caipi_fov_shift	The FOV shift in units of faction of FOV (e.g. 2 means shift of FOV/2)
[in]	sms_slice_gap	Slice gap in [mm] for the selrfMB pulse

Return values

caipi_blip_area

The area of the CAIPIRINHA blip in [(G/cm) * us]

                                                                            {

  if (sms_slice_gap <= 0) {
    return 0.0;
  }

  /* Calculate CAIPI-blip area in us*G/cm */
  return ((caipi_fov_shift-1)*(float)PI/(float)caipi_fov_shift) / (2.0*PI*GAM*1e-6 * (sms_slice_gap/10.0));

} /* EOF */

ks_eval_sms_make_pins()

STATUS ks_eval_sms_make_pins	(	KS_SELRF *	selrfPINS,
		const KS_SELRF *	selrf,
		float	sms_slice_gap
	)

Creates a PINS RF pulse (KS_SELRF) based on a KS_SELRF object

Parameters

[out]	selrfPINS	PINS RF pulse (KS_SELRF object)
[in]	selrf	The original (single-band) KS_SELRF object (set up using ks_eval_selrf())
[in]	sms_slice_gap	Slice gap in [mm] for the selrfMB pulse

Return values

STATUS

SUCCESS or FAILURE

                                                  {

  STATUS status;
  int jdx, idx, kdx = 0, gdx = 0, debug = 0;
  int orgDur = selrfPINS->rf.rfwave.duration;
  KS_TRAP gzblip = KS_INIT_TRAP;

  /* Duplicate the selRF structure  */
  if (selrfPINS != selrf ) {
    *selrfPINS = *selrf;
  }

  /* Set info struct */
  selrfPINS->sms_info.slice_gap = sms_slice_gap;
  selrfPINS->sms_info.pulse_type = KS_SELRF_SMS_PINS;

  ks_init_trap(&selrfPINS->grad);

  if (debug == 1) {ks_print_waveform(selrf->rf.rfwave.waveform, "pins_rfMB_base.txt", selrf->rf.rfwave.res); }

  double kzw = (selrf->rf.bw * selrf->rf.rfwave.duration * 1e-6) / (selrf->slthick / 10); /* 1/cm, width in kz-space we must go */
  int NPulses = (floor(ceil(kzw / (1 / (sms_slice_gap / 10))) / 2) * 2) + 1; /* number of subpulses (odd) */

  /* Init waves */
  KS_WAVEFORM rfLowRes = KS_INIT_WAVEFORM;
  KS_WAVE gzBlipWave = KS_INIT_WAVE;
  float *lowResGrid = (float*)alloca(NPulses * sizeof(float));
  float *baseGrid = (float*)alloca(selrf->rf.rfwave.res * sizeof(float));

  /* create index for interpolation */
  for (idx = 0; idx < selrf->rf.rfwave.res; idx++) {
    baseGrid[idx] = (float) idx / (selrf->rf.rfwave.res - 1);
  }
  for (idx = 0; idx < NPulses; idx++) {
    lowResGrid[idx] = (float) idx / (NPulses - 1);
  }

  /* Interpolate the base rf to get PINS sub pulse amplitudes and high res for MB pulse */
  ks_eval_linear_interp1(baseGrid, selrf->rf.rfwave.res, selrf->rf.rfwave.waveform, lowResGrid, NPulses, rfLowRes);

  if (debug == 1) {ks_print_waveform(rfLowRes, "pins_rfLowRes.txt", NPulses); }

  /* Create blip */
  double gArea = 1 / (sms_slice_gap / 10) / (GAM); /* (g sec)/cm, k-area of each blip */
  gzblip.area = gArea * 1e6; /* (G/cm)*us */
  status = ks_eval_trap1(&gzblip, "PINSblip"); if (status != SUCCESS) return status;
  status = ks_eval_trap2wave(&gzBlipWave, &gzblip); if (status != SUCCESS) return status;
  ks_init_trap(&gzblip);

  /* Matched-duration RF subpulses */
  float maxB1 = 0.24; /* temp. */
  float dt = GRAD_UPDATE_TIME / 1000000.0; /* sec */
  float pulseArea = (float) selrf->rf.flip * (PI / 180.0); /* radians or Hz (depending on how you look at it) */
  float subArea = (ks_waveform_absmax(rfLowRes, NPulses) * pulseArea) / (ks_waveform_sum(rfLowRes, NPulses) * 2.0 * PI * GAM); /* Gauss * sec */
  int hpw = ceil(subArea / (maxB1 * dt)); /* number of time points in sub pulse */
  float scaleFactor = 1.0;

  /* kludge :( */
  for (idx = 0; idx < NPulses; idx++) {
    if (areSame(rfLowRes[idx], 0)) {
      rfLowRes[idx] = rfLowRes[idx] + 0.01;
    }
  }

  /* Loop to concatenate the sub pulses and gradient blips */
  for (idx = 0; idx < NPulses; idx++) {
    for (jdx = 0; jdx < hpw; jdx++) {
      selrfPINS->rf.rfwave.waveform[kdx] = rfLowRes[idx] / scaleFactor;
      selrfPINS->gradwave.waveform[kdx] = 0.0;
      kdx++;
    }
    if (idx != NPulses - 1) {
      for (jdx = 0; jdx < gzBlipWave.res; jdx++) {
        selrfPINS->rf.rfwave.waveform[kdx] = 0.0;
        selrfPINS->gradwave.waveform[kdx] = gzBlipWave.waveform[jdx];
        kdx++; gdx++;
      }
    }
  }

  /* Set duration and resolution */
  selrfPINS->gradwave.gradwave_units = KS_GRADWAVE_ABSOLUTE;
  selrfPINS->gradwave.res = RUP_FACTOR(kdx, GRAD_UPDATE_TIME);
  selrfPINS->gradwave.duration = selrfPINS->gradwave.res * GRAD_UPDATE_TIME;
  selrfPINS->rf.rfwave.res = selrfPINS->gradwave.res;
  selrfPINS->rf.rfwave.duration = selrfPINS->gradwave.duration;
  selrfPINS->rf.rfpulse.isodelay = RUP_FACTOR(ceil((float)selrfPINS->rf.rfpulse.isodelay * ((float)selrfPINS->rf.rfwave.duration/(float)orgDur)), GRAD_UPDATE_TIME);
  selrfPINS->rf.iso2end = selrfPINS->rf.rfpulse.isodelay;
  selrfPINS->rf.bw = 1e3 * (NPulses+1) * selrf->slthick / sms_slice_gap;

  /* If the resolution has been rounded up, place zeros at the end */
  for (idx = kdx; idx < selrfPINS->rf.rfwave.res; idx++) {
    selrfPINS->rf.rfwave.waveform[idx] = 0.0;
    selrfPINS->gradwave.waveform[idx] = 0.0;
  }

  if (debug == 1) {ks_print_waveform(selrfPINS->rf.rfwave.waveform, "pins_RF.txt", selrfPINS->rf.rfwave.res); }
  if (debug == 1) {ks_print_waveform(selrfPINS->gradwave.waveform, "pins_GRAD.txt", selrfPINS->gradwave.res); }

  /* Normalize to 1 */
  ks_waveform_multiplyval(selrfPINS->rf.rfwave.waveform, 1.0 / ks_waveform_absmax(selrfPINS->rf.rfwave.waveform, selrfPINS->rf.rfwave.res), selrfPINS->rf.rfwave.res);

  /* rfStat */
  status = ks_eval_rfstat(&selrfPINS->rf); if (status != SUCCESS) return status;

  /* init theta wave */
  ks_init_wave(&selrfPINS->rf.thetawave);
  selrfPINS->rf.thetawave.duration = selrfPINS->gradwave.duration;
  selrfPINS->rf.thetawave.res = selrfPINS->gradwave.res;
  if (debug == 1) {ks_print_waveform(selrfPINS->rf.thetawave.waveform, "pins_TH.txt", selrfPINS->rf.thetawave.res); }

  /* Register the RF */
  char description[KS_DESCRIPTION_LENGTH + 4];
  sprintf(description, "%s_PINS", selrfPINS->rf.rfwave.description);
  sprintf(selrfPINS->gradwave.description, "%s_PINS", selrfPINS->rf.rfwave.description);
  if (debug == 1) {fprintf(stderr, "---------- PINS %s rfstat ---------\n", selrfPINS->rf.rfwave.description);}
  if (debug == 1) {ks_print_rfpulse(selrfPINS->rf.rfpulse, stderr);}
  return ks_eval_rf(&selrfPINS->rf, description);

}

ks_eval_sms_make_pins_dante()

STATUS ks_eval_sms_make_pins_dante	(	KS_SELRF *	selrfPINS,
		const KS_SELRF *	selrf,
		float	sms_slice_gap
	)

                                                                                                    {
  STATUS status;
  int jdx, idx, kdx = 0, gdx = 0, debug = 1;
  int orgDur = selrfPINS->rf.rfwave.duration;
  KS_TRAP gzblip = KS_INIT_TRAP;

  /* Duplicate the selRF structure  */
  if (selrfPINS != selrf ) {
    *selrfPINS = *selrf;
  }

  /* Set info struct */
  selrfPINS->sms_info.slice_gap = sms_slice_gap;
  selrfPINS->sms_info.pulse_type = KS_SELRF_SMS_PINS_DANTE;

  if (debug == 1) {ks_print_waveform(selrf->rf.rfwave.waveform, "dpins_rfMB_base.txt", selrf->rf.rfwave.res); }
  if (debug == 1) {ks_print_waveform(selrf->rf.thetawave.waveform, "dpins_phMB_base.txt", selrf->rf.thetawave.res); }

  /* Create blip */
  KS_WAVE gzBlipWave = KS_INIT_WAVE;
  double gArea = 1 / (sms_slice_gap / 10) / (GAM); /* (g sec)/cm, k-area of each blip */
  gzblip.area = gArea * 1e6; /* (G/cm)*us */
  status = ks_eval_trap1(&gzblip, "PINSblip"); if (status != SUCCESS) return status;
  status = ks_eval_trap2wave(&gzBlipWave, &gzblip); if (status != SUCCESS) return status;
  ks_init_trap(&gzblip);

  /* Calcualte PINS parameters */
  double kzw = (selrf->rf.bw * selrf->rf.rfwave.duration * 1e-6) / (selrf->slthick / 10); /* 1/cm, width in kz-space we must go */
  int NPulses = (floor(ceil(kzw / (1 / (sms_slice_gap / 10))) / 2) * 2) + 1; /* number of subpulses (odd) */
  int hpw = ceil((float)selrf->rf.rfwave.res / (float)NPulses); /* number of time points in sub pulse */
  int interpolRes = hpw * NPulses;

  /* Create index for interpolation */
  float *newGrid = (float*)alloca(interpolRes * sizeof(float));
  float *baseGrid = (float*)alloca(selrf->rf.rfwave.res * sizeof(float));
  for (idx = 0; idx < selrf->rf.rfwave.res; idx++) {
    baseGrid[idx] = (float) idx / (selrf->rf.rfwave.res - 1);
  }
  for (idx = 0; idx < interpolRes; idx++) {
    newGrid[idx] = (float) idx / (interpolRes - 1);
  }

  /* Interpolate the base rf & phase to make their resolution divideble by NPulses */
  KS_WAVEFORM rfNewRes = KS_INIT_WAVEFORM;
  KS_WAVEFORM phNewRes = KS_INIT_WAVEFORM;
  ks_eval_linear_interp1(baseGrid, selrf->rf.rfwave.res, selrf->rf.rfwave.waveform, newGrid, interpolRes, rfNewRes);
  ks_eval_linear_interp1(baseGrid, selrf->rf.thetawave.res, selrf->rf.thetawave.waveform, newGrid, interpolRes, phNewRes);

  if (debug == 1) {ks_print_waveform(rfNewRes, "rfNewRes.txt", interpolRes); }
  if (debug == 1) {ks_print_waveform(phNewRes, "phNewRes.txt", interpolRes); }

  /* Loop to concatenate the sub pulses and gradient blips */
  for (idx = 0; idx < NPulses; idx++) {
    for (jdx = 0; jdx < hpw; jdx++) {
      selrfPINS->rf.rfwave.waveform[kdx] = rfNewRes[(idx * hpw) + jdx];
      selrfPINS->rf.thetawave.waveform[kdx] = phNewRes[(idx * hpw) + jdx];
      selrfPINS->gradwave.waveform[kdx] = 0.0;
      kdx++;
    }
    if (idx != NPulses - 1) {
      for (jdx = 0; jdx < gzBlipWave.res; jdx++) {
        selrfPINS->rf.rfwave.waveform[kdx] = 0.0;
        selrfPINS->rf.thetawave.waveform[kdx] = 0.0;
        selrfPINS->gradwave.waveform[kdx] = gzBlipWave.waveform[jdx];
        kdx++; gdx++;
      }
    }
  }

  /* Set duration and resolution */
  selrfPINS->grad.duration = 0;
  selrfPINS->gradwave.gradwave_units = KS_GRADWAVE_ABSOLUTE;
  selrfPINS->gradwave.res = RUP_FACTOR(kdx, GRAD_UPDATE_TIME);
  selrfPINS->gradwave.duration = selrfPINS->gradwave.res * GRAD_UPDATE_TIME;
  selrfPINS->rf.rfwave.res = selrfPINS->gradwave.res;
  selrfPINS->rf.rfwave.duration = selrfPINS->gradwave.duration;
  selrfPINS->rf.rfpulse.isodelay = RUP_FACTOR((int)(selrfPINS->rf.rfpulse.isodelay * ((float)selrfPINS->rf.rfwave.duration/(float)orgDur)),RF_UPDATE_TIME);
  selrfPINS->rf.iso2end = selrfPINS->rf.rfpulse.isodelay;
  selrfPINS->rf.bw = 1e3 * (NPulses+1) * selrf->slthick / sms_slice_gap;

  /* If the resolution has been rounded up, place zeros at the end */
  for (idx = kdx; idx < selrfPINS->rf.rfwave.res; idx++) {
    selrfPINS->rf.rfwave.waveform[idx] = 0.0;
    selrfPINS->rf.thetawave.waveform[idx] = selrfPINS->rf.thetawave.waveform[kdx];
    selrfPINS->gradwave.waveform[idx] = 0.0;
  }

  if (debug == 1) {ks_print_waveform(selrfPINS->rf.rfwave.waveform, "dpins_RF.txt", selrfPINS->rf.rfwave.res); }
  if (debug == 1) {ks_print_waveform(selrfPINS->gradwave.waveform, "dpins_GRAD.txt", selrfPINS->gradwave.res); }

  /* Normalize to 1 */
  ks_waveform_multiplyval(selrfPINS->rf.rfwave.waveform, 1.0 / ks_waveform_absmax(selrfPINS->rf.rfwave.waveform, selrfPINS->rf.rfwave.res), selrfPINS->rf.rfwave.res);

  /* rfStat */
  float orgMaxB1 = selrfPINS->rf.rfpulse.max_b1;
  selrfPINS->rf.thetawave.res = 0;
  status = ks_eval_rfstat(&selrfPINS->rf); if (status != SUCCESS) return status;
  selrfPINS->rf.rfpulse.max_b1 = orgMaxB1;

  /* Theta wave */
  selrfPINS->rf.thetawave.duration = selrfPINS->gradwave.duration;
  selrfPINS->rf.thetawave.res = selrfPINS->gradwave.res;

  for (idx = 0; idx < selrfPINS->rf.thetawave.res; idx++) {
    if (fabs(selrfPINS->rf.thetawave.waveform[idx]) > 180.0) {
      double angle = selrfPINS->rf.thetawave.waveform[idx];
      double revolutions = floor((angle + 180.0) / 360.0);
      selrfPINS->rf.thetawave.waveform[idx] = (float) (angle - revolutions * 360.0);
    }
  }

  if (debug == 1) {ks_print_waveform(selrfPINS->rf.thetawave.waveform, "dpins_TH.txt", selrfPINS->rf.thetawave.res); }

  /* Register the RF */
  char description[KS_DESCRIPTION_LENGTH + 4];
  sprintf(description, "%s_PINSDANTE", selrfPINS->rf.rfwave.description);
  sprintf(selrfPINS->gradwave.description, "%s_PINSDANTE", selrfPINS->rf.rfwave.description);
  if (debug == 1) {fprintf(stderr, "---------- PINS DANTE %s rfstat ---------\n", selrfPINS->rf.rfwave.description);}
  if (debug == 1) {ks_print_rfpulse(selrfPINS->rf.rfpulse, stderr);}
  return ks_eval_rf(&selrfPINS->rf, description);

}

ks_eval_findNearestNeighbourIndex()

int ks_eval_findNearestNeighbourIndex	(	float	value,
		const float *	x,
		int	length
	)

Find nearest neighbor index (NEEDS BETTER DOCUMENTATION)

Parameters

[in]	value
[in]	x	Input array
[in]	length	Length of array

Return values

index

Index into array

                                                                               {

  float dist = fabs(value - x[0]);
  float newDist;
  int idx = 0, i;

  for (i = 1; i < length; i++) {

    newDist = value - x[i];

    if (0 < newDist && newDist < dist) {

      dist = newDist;
      idx = i;
    }
  }

  return idx;
}

ks_eval_linear_interp1()

void ks_eval_linear_interp1	(	const float *	x,
		int	x_length,
		const float *	y,
		const float *	xx,
		int	xx_length,
		float *	yy
	)

Linear interpolation

Parameters

[in]	x	Input array of x coordinates for data (y)
[in]	x_length	Length of array
[in]	y	Input array of data (same length as x)
[in]	xx	Array of new sample points of the data in y
[in]	xx_length	Length of array with new sample points
[out]	yy	Output array with interpolated data

Return values

STATUS

SUCCESS or FAILURE

                                                                                                                     {

  int i, index;
  float dx, dy;
  float *slope = (float*)alloca(x_length * sizeof(float));
  float *intercept = (float*)alloca(x_length * sizeof(float));
  float *Y = (float*)alloca(x_length * sizeof(float));
  memcpy(Y, y, x_length * sizeof(float));

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

    if (i < x_length - 1) {

      dx = x[i + 1] - x[i];
      dy = Y[i + 1] - Y[i];
      slope[i] = dy / dx;
      intercept[i] = Y[i] - x[i] * slope[i];

    } else {

      slope[i] = slope[i - 1];
      intercept[i] = intercept[i - 1];

    }
  }

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

    index = ks_eval_findNearestNeighbourIndex(xx[i], x, x_length);
    yy[i] = slope[index] * xx[i] + intercept[index];
  }
} /* EOF */

ks_eval_trap2wave()

STATUS ks_eval_trap2wave	(	KS_WAVE *	wave,
		const KS_TRAP *	trap
	)

Converts a trapezoid object (KS_TRAP) to a wave object (KS_WAVE)

The input KS_TRAP object will be converted to a KS_WAVE object, which will have its .waveform (float array) field filled with the shape of the trapezoid with the maintained GRAD_UPDATE_TIME (4 [us]) sample duration. The .waveform amplitude on the plateau will be .amp [G/cm].

Parameters

[out]	wave	Pointer to a KS_WAVE object to be set up with same shape as the trapezoid (KS_TRAP) in arg 2
[in]	trap	The trapezoid to convert into a waveform

Return values

STATUS

SUCCESS or FAILURE

                                                             {

  int i;
  int idx = 0;

  ks_init_wave(wave);

  int pointsInRamp = (trap->ramptime / GRAD_UPDATE_TIME) + 1;
  int pointsInPlateau = (trap->plateautime / GRAD_UPDATE_TIME) - 2;
  int pointsInWave = 2 * pointsInRamp + pointsInPlateau;
  double slope = trap->amp / pointsInRamp;

  if (trap->duration != (pointsInWave * GRAD_UPDATE_TIME)) {
    return ks_error("ks_eval_trap2wave(%s): field .ramptime or .plateautime not divisible by GRAD_UPDATE_TIME (4)", trap->description);
  }

  /* ramp up */
  for (i = 1; i <= pointsInRamp; i++) {
    wave->waveform[idx++] = (float)(i * slope);
  }

  /* plateau */
  for (i = 0; i < pointsInPlateau; i++) {
    wave->waveform[idx++] = trap->amp;
  }

  /* ramp down */
  for (i = pointsInRamp; i > 0; i--) {
    wave->waveform[idx++] = (float)(i * slope);
  }

  /* set fields */
  wave->res = idx;
  if (pointsInWave != wave->res) {
    return ks_error("ks_eval_trap2wave(%s): Implementation error - The resulting KS_WAVE has wrong res [%d!=%d]", trap->description, pointsInWave, wave->res);
  }

  wave->duration = idx * GRAD_UPDATE_TIME;
  if (trap->duration != wave->duration) {
    return ks_error("ks_eval_trap2wave(%s): Implementation error - The resulting KS_WAVE has wrong duration [%d!=%d]", trap->description,trap->duration,wave->duration);
  }

  sprintf(wave->description, "%s_wave", trap->description);

  return SUCCESS;

} /* EOF */

ks_eval_append_two_waves()

STATUS ks_eval_append_two_waves	(	KS_WAVE *	first_wave,
		KS_WAVE *	second_wave
	)

                                                                           {
  memcpy( &(first_wave->waveform[first_wave->res]), second_wave->waveform, sizeof(float) *second_wave->res);
  first_wave->res += second_wave->res;
  first_wave->duration += second_wave->duration;
  if (first_wave->res % 2) {
    first_wave->waveform[++first_wave->res] = 0.0f;
    first_wave->duration += GRAD_UPDATE_TIME;
  }
  return SUCCESS;
}

ks_eval_concatenate_waves()

STATUS ks_eval_concatenate_waves	(	int	num_waves,
		KS_WAVE *	target_wave,
		KS_WAVE **	waves_to_append
	)

                                                                                                 {
  int idx;
  for(idx = 0; idx < num_waves; idx++) {
    if (ks_eval_append_two_waves(target_wave, waves_to_append[idx]) != SUCCESS) {
      ks_error("%s failed", __FUNCTION__);
      return FAILURE;
    };
  }

  return SUCCESS;
}

ks_eval_epi_constrained()

STATUS ks_eval_epi_constrained	(	KS_EPI *	epi,
		const char *const	desc,
		float	ampmax,
		float	slewrate
	)

Sets up a KS_EPI composite sequence object, subject to gradients constraints specified as input arguments

The KS_EPI composite sequence object controls an entire EPI train (including de/rephasers on freq & phase axes). Four fields in KS_EPI are other sequence objects:

• KS_READTRAP .read: The EPI readout lobes including data acquisition
• KS_TRAP .readphaser: The dephaser & rephaser gradients before & after the train of readout lobes, on the same board as .read
• KS_TRAP .blip: The blip gradients in the phase encoding direction between the readout lobes
• KS_PHASER .blipphaser: The dephaser & rephaser gradients on the same board as the .blip gradients. For multi-shot EPI these gradients will change in scan() when calling ks_scan_epi_shotcontrol()

Before calling this function, portions of the .read field (KS_READTRAP) and .blipphaser field (KS_PHASER) must be set up. Here follows a list of fields that must be set:

1. .read.fov: The Field-of-View (FOV) in the frequency encoding (readout) direction
2. .read.res: The number of pixels within the FOV along the frequency encoding direction
3. .blipphaser.fov: The Field-of-View (FOV) in the phase encoding direction
4. .blipphaser.res: The number of pixels within the FOV along the phase encoding direction
5. .blipphaser.R: Either the number of EPI shots or the parallel imaging factor
6. .read.rampsampling: Whether rampsampling should be used (see KS_READTRAP). Value of 1 is recommended for EPI
7. .read.acq.rbw: The receiver bandwidth in [kHz/FOV]. Maximum: 250 (recommended)

If the KS_EPI object is initialized with KS_INIT_EPI on declaration, .read.rampsampling will already be set to 1 and .read.acq.rbw will be set to 250.0 (hence steps 6-7 can be skipped).

Single-shot EPI acquisitions are geometrically distorted to some degree depending on chosen .read.res and .blipphaser.fov. To reduce the EPI distortions, either multi-shot EPI or parallel imaging acceleration can be used. For both alternatives, every Rth phase ecoding lines are acquired in k-space as the EPI train is played out. R corresponds to the number of shots (opnshots menu in the UI) or the parallel imaging factor. Therefore, e.g. a 4-shot EPI readout is identical to an R = 4 accelerated EPI readout with the same FOV and resolution, why one same field .R may be used to control the EPI train setup, be it multi-shot or parallel imaging acceleration (but not both at the same time). What differs between multi-shot and parallel imaging acceleration in the acquisition is only whether the .blipphaser should change from TR to TR. Hence, to set up a KS_EPI object, use the field .R for both multi-shot EPI and parallel imaging scenarios.

The remaining fields of interest in the KS_EPI sequence objects are:

• .etl: This is the echo-train-length (ETL) of the EPI readout train, set by ks_eval_epi() based on .blipphaser.res and .blipphaser.R
• .read_spacing: Additional spacing in [us] between readout lobes. Default value is zero, but can be set > 0 if additional gradients is to be inserted between the readout lobes. One scenario is adding CAIPIRINHA blips on ZGRAD during the time where the EPI readout is played out in the pulse sequence
• .duration: Convenience information for timing calculations, set by ks_eval_epi(). This is the total time in [us] for the EPI train, including the de/rephasers on the frequency/phase axes. Note that there are also .duration fields for each of the four KS_*** sequence objects in KS_EPI, stating the duration of each of these components.
• .time2center: Convenience information for timing calculations, set by ks_eval_epi(). The time in [us] from the start of the first dephaser until the center of k-space is reached. This deviates from <epi>.duration/2 for partial Fourier EPI trains where .blipphaser.nover > 0 (a.k.a. fractional NEX, but typically shown as MiniumTE in the UI for EPI)

If peripheral nerve stimulation would be observed, consider calling ks_eval_epi_constrained() with reduced slewrate. This will however increase the geometric distortions in the images

Parameters

[in,out]	epi	Pointer to the KS_EPI object to be set up
[in]	desc	A description (text string) of the KS_SELRF object. This description is used for pulse sequence generation (seen in the file generated by TimeHist in MGD Sim/WTools)
[in]	ampmax	The maximum allowed gradient amplitude ([G/cm])
[in]	slewrate	The maximum allowed slewrate ([(G/cm) / us]). Value of 0.01 corresponds to 100 mT/m/s

Return values

STATUS

SUCCESS or FAILURE

                                                                                                   {  
  char tmpstr[1000];
  int kspacelines_noacc;
  /* same code as ks_eval_dixon_dualreadtrap  */
  const float ampmax_phys = FMin(3, phygrd.xfs,    phygrd.yfs,    phygrd.zfs);
  const int ramptimemax_phys = IMax(3, phygrd.xrt, phygrd.yrt, phygrd.zrt);
  const float slewrate_phys = ampmax_phys / ramptimemax_phys;
  float slewrate_phasers; /* lower slew rate for phasers before/after the train */
  float ampmax_phasers; /* lower ampmax for phasers before/after the train */

  /* for now spherical model such that out of spec slewrate or amplitude cannot happen (for the phasers), even with prospective moco */
  if (epi->zphaser.res > 1) {
    slewrate_phasers = FMin(2, slewrate, slewrate_phys / sqrt(3));
    ampmax_phasers = FMin(2, ampmax, ampmax_phys / sqrt(3));
  } else {
    slewrate_phasers = FMin(2, slewrate, slewrate_phys / sqrt(2));
    ampmax_phasers = FMin(2, ampmax, ampmax_phys / sqrt(2));
  }

  if (desc == NULL || desc[0] == ' ') {
    return ks_error("%s: description (2nd arg) cannot be NULL or begin with a space", __FUNCTION__);
  }

  /************************** Step 1: resolution checking ************************/

  /* For EPI, we don't allow negative 'nover'. For lower k-space pFourier control, we use ks_phaseencoding_generate_epi() */
  if (epi->blipphaser.nover < 0) {
    return ks_error("%s(%s): negative 'blipphaser.nover' not allowed for EPI. See ks_phaseencoding_generate_epi()", __FUNCTION__, desc);
  }
  if (abs(epi->read.nover) > 0) {
    return ks_error("%s(%s): partial Fourier in read is not supported", __FUNCTION__, desc);
  }
  if (epi->minbliparea < 0 || epi->minbliparea > 1000) {
    return ks_error("%s(%s): field 'minbliparea' must be in range [0,1000]", __FUNCTION__, desc);
  }
  if (epi->read.res % 2) {
    return ks_error("%s(%s): Read res must be even", __FUNCTION__, desc);
  }

  /************************** Step 2: blip phaser (DE/REphasers)  ***************************/
  epi->blipphaser.nacslines = 0; /* ACS lines are forbidden for EPI */

  /* blip DE/REphaser (KS_PHASER). Here the '.res' and '.nover' fields may be rounded due to '.R'
     as ks_eval_phaser_constrained() is also calling ks_eval_phaser_adjustres() */
  sprintf(tmpstr, "%s.blipphaser", desc);
  if (ks_eval_phaser_constrained(&epi->blipphaser, tmpstr, ampmax_phasers, slewrate_phasers, 0) == FAILURE)
    return FAILURE;

  /************************** Step 3: z phaser ***************************/

  /* blip DE/REphaser (KS_PHASER). Here the '.res' and '.nover' fields may be rounded due to '.R'
     as ks_eval_phaser_constrained() is also calling ks_eval_phaser_adjustres() */
  sprintf(tmpstr, "%s.zphaser", desc);
  if ((epi->blipphaser.nover > 0) && (epi->zphaser.nover > 0)) {
    return ks_error("%s: Cannot have partial Fourier in both ky (nover=%d) and kz (nover=%d)", __FUNCTION__, epi->blipphaser.nover, epi->zphaser.nover);
  }
  if (epi->zphaser.res > 1) {
    if (ks_eval_phaser_constrained(&epi->zphaser, tmpstr, ampmax_phasers, slewrate_phasers, 0) == FAILURE)
      return FAILURE;
  } else {
    ks_init_phaser(&epi->zphaser);
  }

  /************************** Step 4: ETL ***************************/

  if (epi->blipphaser.nover > 0) {
    kspacelines_noacc = epi->blipphaser.res / 2 + epi->blipphaser.nover;
  } else {
    kspacelines_noacc = epi->blipphaser.res;
  }

  epi->etl = kspacelines_noacc / epi->blipphaser.R;

  if (epi->etl < 1) {
    return ks_error("%s(%s): R (or shots) must be in range [1,%d]", __FUNCTION__, desc, kspacelines_noacc);
  }

  /********************* Step 5: EPI blips ********************/

  /* blip area [(G/cm)*usec] */
  if (epi->etl > 1) {

    epi->blip.area = epi->blipphaser.R * ks_calc_fov2gradareapixel(epi->blipphaser.fov);

    /* The blip area should not be too small to reduce discretization errors. This is based on observations doing moment calcs in WTools.  */
    if (epi->blip.area < epi->minbliparea)
      epi->blipoversize = (epi->minbliparea / epi->blip.area); /* design a bigger blip, and use .blipoversize in ks_scan_epi_shotcontrol() to reduce the amp correspondingly */
    else
      epi->blipoversize = 1.0;

    epi->blip.area = epi->blipphaser.R * ks_calc_fov2gradareapixel(epi->blipphaser.fov) * epi->blipoversize;
  } else {
    epi->blip.area = 0.0;
  }
  /* Get ramp & plateau time as well as amplitude of the blip */
  sprintf(tmpstr, "%s.blip", desc);

  if (ks_eval_trap_constrained(&epi->blip, tmpstr, ampmax, slewrate, 0) == FAILURE)
    return FAILURE;


  /************************** Step 6: Read width and amp **************************/

  /* rampsampling (normal case): We don't want to acquire data during half the blip duration (straddling two readouts) */
  if (epi->read.rampsampling)
    epi->read.acqdelay = epi->blip.duration / 2;

  sprintf(tmpstr, "%s.read", desc);
  if (ks_eval_readtrap_constrained(&epi->read, tmpstr, ampmax, slewrate) == FAILURE)
    return FAILURE;

  if (!epi->read.rampsampling) {
    /* non-rampsampling (unusual case) */
    if (epi->read.grad.ramptime < (epi->blip.duration / 2)) {
      /* blip-duration limited: Prolong the read gradient ramps to fit the blip, reduce PNS and acoustic noise */
      epi->read.grad.ramptime = epi->blip.duration / 2;
      epi->read.acqdelay = epi->read.grad.ramptime;
      epi->read.grad.duration = epi->read.grad.plateautime + 2 * epi->read.grad.ramptime;
      epi->read.grad.area = (epi->read.grad.plateautime + epi->read.grad.ramptime) * epi->read.grad.amp;
      epi->read.area2center = epi->read.grad.area / 2;
    }
  }


  /************************** Step 7: read phaser (DE/REphasers) **************************/

  /* readphaser (KS_TRAP) */
  epi->readphaser.area = -epi->read.area2center;

  if (!areSame(epi->readphaser.area, 0.0)) {
    sprintf(tmpstr, "%s.readphaser", desc);
    if (ks_eval_trap_constrained(&epi->readphaser, tmpstr, ampmax_phasers, slewrate_phasers, 0) == FAILURE)
      return FAILURE;
  }


  /**************************** Step 8: Convenience info ****************************/

  ks_eval_epi_setinfo(epi);


  return SUCCESS;

} /* ks_eval_epi_constrained */

ks_eval_epi_setinfo()

STATUS ks_eval_epi_setinfo

(

KS_EPI *

epi

)

Set convenience info for KS_EPI based on objects' timing in KS_EPI

                                        {

    epi->duration = epi->etl * epi->read.grad.duration + \
                    (epi->etl - 1) * epi->read_spacing + \
                    IMax(3, epi->readphaser.duration, epi->blipphaser.grad.duration, epi->zphaser.grad.duration) + \
                    IMax(3, epi->readphaser.duration, epi->blipphaser.grad.duration, epi->zphaser.grad.duration);

    if (abs(epi->blipphaser.nover)) {
      /* partial Fourier */
      epi->time2center = ((epi->read.grad.duration + epi->read_spacing) * (epi->blipphaser.nover / epi->blipphaser.R)) - epi->read_spacing / 2;
    } else {
      epi->time2center = ((epi->read.grad.duration + epi->read_spacing) * epi->etl / 2) - epi->read_spacing / 2;
    }
    epi->time2center += IMax(3, epi->readphaser.duration, epi->blipphaser.grad.duration, epi->zphaser.grad.duration);

  return SUCCESS;  
}

ks_eval_epi_maxamp_slewrate()

STATUS ks_eval_epi_maxamp_slewrate	(	float *	ampmax,
		float *	slewrate,
		int	xres,
		float	quietnessfactor
	)

Get maximum amplitude and slewrate for the EPI readout constrained by hardware and PNS

Get a reasonably optimized max gradient amplitude and slewrate for the EPI train. This function results in similar values as GE's epigradopts(), where gradient system limits and peripheral-nerve-stimulation (PNS) are not to be exceeded. ks_eval_epi_maxamp_slewrate() has no dB/dt model, but is dependent on xres (assuming fixed FOV, rampsampling and maxmimum rBW). This has also been tested for axial and oblique scans on volunteers at Karolinska without PNS experience using FOV = 24 cm on both DV750 and DV750w with rampsampling and rBW = 250. If PNS should still occur, the slewrate value passed to ks_eval_epi_constrained() should be decreased. The units of the slewrate is [(G / cm) / us], i.e. gradient amp in G / cm divided by the ramptime in us. This value times 1e4 gives slewrate in SI units: T / m / s (up to e.g. 200).

Parameters

[out]	ampmax	The maximum allowed gradient amplitude ([G/cm])
[out]	slewrate	The maximum allowed slewrate ([(G/cm) / us]). Value of 0.01 corresponds to 100 mT/m/s
[in]	xres	The frequency encoding resolution
[in]	quietnessfactor	Value >= 1 used for optional gradient derating

Return values

STATUS

SUCCESS or FAILURE

                                                                                                    {
  PHYS_GRAD epiphygrd = { 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0 };
  LOG_GRAD  epiloggrd = {0, 0, 0, 0, 0, 0, {0, 0, 0, 0, 0, 0}, {0, 0, 0, 0}, {0, 0, 0, 0}, {0, 0, 0, 0}, {0, 0, 0, 0}, {0, 0, 0, 0}, {0, 0, 0, 0}, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0 };
  int epi_initnewgeo = 1;
  extern SCAN_INFO scan_info[SLTAB_MAX];
  extern int opcoax;
  extern int opplane;
  extern int opslquant;
  extern int obl_debug;
  int stronggradient_flag = 0;
  int premiersystem_flag = 0;
  const float premierslewrate_max = 0.0150; /* 0.0150 (G/cm)/us = SR150 (T/m)/s */
  const float stronggradient_ampmax = 3.5; /* 35 mT/m. Maximum gradient amplitude to avoid too high rBW at k-space center */

  /* relationships below have been tested in the range [16,256] */
  if (xres < 16)
    xres = 16;
  if (xres > 256)
    xres = 256;


  if (quietnessfactor < 1.0) {
    return ks_error("%s: The quietness factor must be >= 1.0", __FUNCTION__);
  }


  inittargets(&epiloggrd, &epiphygrd);

  /* we need to know the system limits, but we don't want to be dependent on GERequired:GEReq_init_gradspecs() and ks_srfact
     for the EPI readout. I.e. ks_srfact (GERequired.e) can be used to set a proper slewrate tweak factor for all gradients except for
     the EPI readout (and EPI blips), while the ampmax and slewrate for the EPI train is controlled only by this function */
  if (obloptimize_epi(&epiloggrd, &epiphygrd, scan_info, (opslquant),
                      (opplane), (opcoax), PSD_OBL_OPTIMAL, (obl_debug), &epi_initnewgeo, cfsrmode) == FAILURE) {
    return ks_error("%s: obloptimize_epi() failed", __FUNCTION__);
  }

  /* ampmax */
#if EPIC_RELEASE >= 27
  stronggradient_flag = (cfgcoiltype == PSD_XRMB_COIL || cfgcoiltype == PSD_HRMW_COIL); /* 750 or Premier. 50+ mT/m */
  premiersystem_flag = (cfgcoiltype == PSD_HRMW_COIL);
#else
  stronggradient_flag = cfgcoiltype == PSD_XRMB_COIL; /* 750 */
#endif

  if (stronggradient_flag) {
   *ampmax = FMin(2, stronggradient_ampmax, 0.01 * xres + 2); /* very unscientific linear relationship, but GE's EPI gradients increase semi-linearly with xres (they use epigradopt.c) */
  } else {
    /* 750w and others */
    if (xres > 128)
      *ampmax = 0.005 * xres + 1.36; /* allow the amp to increase slowly for higher res than 128 */
    else
      *ampmax = 2.0;
  }
  *ampmax = FMin(2, *ampmax, epiphygrd.xfs);


  /* slewrate */
  if (stronggradient_flag) {
    //* 750 or Premier. 50+ mT/m */
    if (xres <= 48){
      *slewrate = 250e-4; /* SR250 */
    } else {
      *slewrate = 1.0e-4 / (2.4e-5 * xres + 0.003); /* SR250 (xres 48) -> SR110 (xres 256). 1/x function */
    }
    if (premiersystem_flag && *slewrate > premierslewrate_max) {
      *slewrate = premierslewrate_max;
    }
  } else {
    /* 750w. 33 mT/m, SR120 (and all others) */
    if (xres <= 48)
      *slewrate = 170e-4; /* SR170 */
    else
      *slewrate = 120e-4; /* SR120 */

    /* use the relative ampmax reduction dependent on slice angulation to instead reduce the slewrate on 750w.
       ks_syslimits_ampmax2(&epiloggrd) returns 1.0 for axial scans,
       but for oblique scans the value is reduced. Although this should cap the amplitude, we use
       is here to instead reduce the slewrate, since we need some way to make the slewrate lower for (double)
       oblique scans, or maybe when the XGRAD is not parallel to the physical X-axis (R/L) */

    *slewrate *= epiloggrd.tx_xy / epiloggrd.xfs;
  }

  /* but if user wants a quieter scan, reduce the slewate */
  *slewrate /= quietnessfactor;


  return SUCCESS;

} /* ks_eval_epi_maxamp_slewrate() */

ks_eval_epi()

STATUS ks_eval_epi	(	KS_EPI *	epi,
		const char *const	desc,
		float	quietnessfactor
	)

Sets up a KS_EPI composite sequence object with preset gradient constraints

This is a wrapper function to ks_eval_epi_constrained() with a reduced set of input arguments using preset gradient constraints. These constraints should allow for EPI readouts for double oblique slice angulations, but the values for ampmax or slewrate may not be optimal. If peripheral nerve stimulation (PNS) would be observed, consider calling ks_eval_epi_constrained() directly with reduced slewrate. This will however increase the geometric distortions in the images

See ks_eval_epi_constrained() for more details on fields in KS_EPI that must be set before calling this function

Parameters

[in,out]	epi	Pointer to the KS_EPI object to be set up
[in]	desc	A description (text string) of the KS_SELRF object. This description is used for pulse sequence generation (seen in the file generated by TimeHist in MGD Sim/WTools)
[in]	quietnessfactor	Value >= 1 used for optional gradient derating

Return values

STATUS

SUCCESS or FAILURE

                                                                                {
  float ampmax, slewrate;

  if (ks_eval_epi_maxamp_slewrate(&ampmax, &slewrate, epi->read.res, quietnessfactor) == FAILURE)
    return FAILURE;

  return ks_eval_epi_constrained(epi, desc, ampmax, slewrate);

} /* ks_eval_epi */

ks_eval_gradrflimits()

int ks_eval_gradrflimits	(	KS_SAR *	sar,
		KS_SEQ_COLLECTION *	seqcollection,
		float	gheatfact
	)

Returns the time required to play out a certain number of sequence modules over some interval, honoring SAR, RF power and gradient heating constraints

This function uses one KS_SEQ_COLLECTION struct holding the RF and gradient information for the entire psd (involving one or more sequence modules) to check if an interval can be played out as is or if the overall duration needs to be increased to honor SAR and hardware limits. The interval of measurement is given by the function pointer passed to ks_eval_mintr(), which typically is a sliceloop function playing out the slices for one TR (using one or more sequence modules).

The net time for this period is given by the sum of instances and durations of the sequence modules involved. This information is taken from ks_eval_seqcollection_gettotalduration(), which sums the product of the duration of each sequence module by the number of instances of each sequence module.

ks_eval_gradrflimits() will call GE's regular SAR, RF power and gradient heating functions after creating temporary RF_PULSE and GRAD_PULSE structs using the sequence objects (RF and gradients) in the sequence modules.

The gradient information for all sequence modules is accessed via seqcollection->seqctrlptr[i].gradrf.trapptr[...], while the RF information for all sequence modules is accessed via seqcollection->seqctrlptr[i].gradrf.rfptr[...], with i being the internal sequence module index.

GE's hardware and SAR check functions will return new minimum durations, which may be equal or larger than the net time, depending on the hardware and safety limits. The largest new minimum duration is the return value for this function. Also, if the 1st argument (KS_SAR *) is not pointing to NULL, the SAR information will be stored in this struct, so it can be used by the calling function.

Currently, KSFoundation does not use GE's new gradheat method where cornerpoints of the sequence waveforms are used for the gradient heating calculations. When using the old method, the minseq() function will likely be too conservative and may add unnecessary time penalty. The level of exaggeration is not clear, why there is a temporary solution with a 'gheatfact' as an input argument, where it is up to the EPIC programmer to decide on this. This variable should be 1.0 to fully obey the old gradient heating calculations (understanding the minimum TR can bump up significantly). To fully ignore gradient heating calculations a value of 0.0 is used. The proper value of this variable, that would correspond to the actual hardware gradient limits, is not known at the moment, but a value closer to 0.0 than 1.0 better matches the new gradient heating model used by GE's product psds. Having said that, absolutely no guarantees are given in terms of gradient damage or similar.

See also: ks_eval_mintr(), ks_eval_maxslicespertr(), ks_eval_seqcollection_gettotalduration()

Parameters

[out]	sar	Pointer to KS_SAR struct with SAR parameters. If NULL, no attempt to store SAR parameters will be done. If not null, KS_SAR will be set up. In addition, the description of GE's CV 'optr' will be changed so that one can see the limit factor and how much time that had to be added to be within specs. This information can be viewed on the MR system while scanning by DisplayCV and type in 'optr'.
[in]	seqcollection	A KS_SEQ_COLLECTION struct, which have undergone a reset of seqctlptr[].nseqinstances followed by a single run of the sequence's slice loop or equivalent period
[in]	gheatfact	Experimental fudge factor in range [0.0, 1.0] to control how much to obey the gradient heating calculations using the old gradient heating model. It is up to the EPIC programmer to set this to a proper value for now. This input argument can hopefully be removed in the future

Return values

int	Minimum time in [us] that is needed to safetly play out the .nseqinstances sequence modules over the intended interval (usually one TR for 2D sequences)

                                                                                         {
  int i, j;
  int rfindx = 0;
  int numuniquetrap = 0;
  int numxtrap = 0;
  int numytrap = 0;
  int numztrap = 0;
  int numuniquerf = 0;
  int nettime = 0;
  int newtime_gradheat = 0;
  int newtime_rfamp = 0;
  int newtime_sar = 0;
  int newtime_allconstraints = 0;
  int dummy;
  double ave_sar = 0;
  double peak_sar = 0;
  double cave_sar = 0; /* Coil SAR */
  double b1rms = 0;
  GRAD_PULSE tempgrad;

  STATUS status;
  if (seqcollection == NULL) {
    ks_error("%s: 2nd arg is NULL (KS_SEQ_COLLECTION)", __FUNCTION__);
    return KS_NOTSET;
  } else if (seqcollection->numseq < 1) {
    ks_error("%s: No sequence modules in 2nd arg (KS_SEQ_COLLECTION)", __FUNCTION__);
    return KS_NOTSET;
  }

  /********** copy to common struct arrays for grad and RF from the sequence collection **********/
  for (i = 0; i < seqcollection->numseq; i++) {
    numuniquetrap += seqcollection->seqctrlptr[i]->gradrf.numtrap;
    numuniquerf   += seqcollection->seqctrlptr[i]->gradrf.numrf;
  }

  nettime = ks_eval_seqcollection_gettotalduration(seqcollection);
  if (nettime <= 0) {
    return nettime;
  }

  GRAD_PULSE *mygradx = (GRAD_PULSE*)alloca(numuniquetrap * sizeof(GRAD_PULSE));
  GRAD_PULSE *mygrady = (GRAD_PULSE*)alloca(numuniquetrap * sizeof(GRAD_PULSE));
  GRAD_PULSE *mygradz = (GRAD_PULSE*)alloca(numuniquetrap * sizeof(GRAD_PULSE));
  RF_PULSE *myrfpulse = (RF_PULSE*)alloca(numuniquerf * sizeof(RF_PULSE));


  for (i = 0; i < seqcollection->numseq; i++) {

    for (j = 0; j < seqcollection->seqctrlptr[i]->gradrf.numtrap; j++) {

      tempgrad = ks_eval_makegradpulse(seqcollection->seqctrlptr[i]->gradrf.trapptr[j], XGRAD);
      if (tempgrad.num > 0) {
        /* change from "number of instances per sequence module" to "number of instances per TR"
         by multiplying by the number of times this sequence module is played out each TR */
        tempgrad.num *= seqcollection->seqctrlptr[i]->nseqinstances;
        mygradx[numxtrap++] = tempgrad;
      }

      tempgrad = ks_eval_makegradpulse(seqcollection->seqctrlptr[i]->gradrf.trapptr[j], YGRAD);
      if (tempgrad.num > 0) {
        tempgrad.num *= seqcollection->seqctrlptr[i]->nseqinstances;
        mygrady[numytrap++] = tempgrad;
      }

      tempgrad = ks_eval_makegradpulse(seqcollection->seqctrlptr[i]->gradrf.trapptr[j], ZGRAD);
      if (tempgrad.num > 0) {
        tempgrad.num *= seqcollection->seqctrlptr[i]->nseqinstances;
        mygradz[numztrap++] = tempgrad;
      }

    }

    for (j = 0; j < seqcollection->seqctrlptr[i]->gradrf.numrf; j++) {
      ks_eval_rf_relink(seqcollection->seqctrlptr[i]->gradrf.rfptr[j]);
      myrfpulse[rfindx] = seqcollection->seqctrlptr[i]->gradrf.rfptr[j]->rfpulse;
      /* change from "number of instances per sequence module" to "number of instances per TR"
      by multiplying by the number of times this sequence module is played out each TR */
      myrfpulse[rfindx].num *= seqcollection->seqctrlptr[i]->nseqinstances;
      rfindx++;
    }

  }

  /********** Gradient heating ***********/

  /* turn gradHeatMethod off until we understand how/if getCornerPoints() work (PGenOnHost()) in minseq.c */
  const int saveGradHeatMethod = gradHeatMethod;

  /* gradHeatMethod:
     - Off: old traditional gradient heating calcs where minseq() is calling minseqgrad() and minseqcoil()
            Warning: minseqcoil() is also calling Safe_DC_Model() if the CV gradDCsafeMethod is 1, which will cause problems for
            non-product PSDs. This because of the call to Safe_DC_Model()->predict_gcontirms_fse(), which contains hardcoded indices to gradient
            entries for product FSE. To avoid this, we now force gradDCsafeMethod = 0 until KSFoundation PSDs are using PGenOnHost for
            gradient heating calcs (gradHeatMethod = 1).
     - On: New gradient heating calcs where minseq() is calling minseqseg(). This is not supported yet in KSFoundation, but is indeed the preferred
           choice.
  */
  gradHeatMethod = PSD_OFF;
  gradDCsafeMethod = PSD_OFF; /* must be off until PGenOnHost is used (gradHeatMethod = 1) */

  status = minseq(&newtime_gradheat,
                         mygradx, numxtrap, mygrady, numytrap, mygradz, numztrap,
                         &loggrd, seqcollection->seqctrlptr[0]->handle.index /* assume 0 is main seq */, /*tsamp*/ GRAD_UPDATE_TIME, nettime,
                         /*use_ermes*/0, /*debug*/0);

  if (status != SUCCESS) {
    ks_error("%s: minseq() failed (gradient heating)", __FUNCTION__);
    return KS_NOTSET;
  }
  gradHeatMethod = saveGradHeatMethod;

  /* Protection against not understood values of minseqcable_t or minseqbusbar_t
     which can be -2147483648 (neg INT max). This is nonsense and out of valid CV range (by 1 value)
     and leads to download failure. Need to find where minseqcable_t and minseqbusbar_t are set.
   */
  if (minseqcable_t < 0 || minseqcable_t > 100 * nettime) {
    minseqcable_t = 0;
  }
  if (minseqbusbar_t < 0 || minseqbusbar_t > 100 * nettime) {
    minseqbusbar_t = 0;
  }



  /********** RF amplifier **********/
  status = minseqrfamp(&newtime_rfamp, numuniquerf, myrfpulse, L_SCAN);

  if (status != SUCCESS) {
    ks_error("%s: minseqrfamp() failed - Please reduce FA", __FUNCTION__);
    return KS_NOTSET;
  }

  /********** RF SAR **********/
#if EPIC_RELEASE >= 24
  status = maxsar(&newtime_sar,
                  &dummy, &ave_sar, &cave_sar, &peak_sar, &b1rms,
                  numuniquerf, myrfpulse, L_SCAN, nettime);
#else
  status = maxsar(&newtime_sar,
                  &dummy, &ave_sar, &cave_sar, &peak_sar,
                  numuniquerf, myrfpulse, L_SCAN, nettime);
#endif

  if (status != SUCCESS) {
    ks_error("%s: maxsar() failed", __FUNCTION__);
    return KS_NOTSET;
  }

  if (sar != NULL) {
    sar->average = ave_sar;
    sar->coil = cave_sar;
    sar->peak = peak_sar;
    sar->b1rms = b1rms;
  }

  newtime_allconstraints = IMax(4, nettime, (int) (newtime_gradheat * gheatfact), newtime_rfamp, newtime_sar);

  if (sar == NULL) {
  /* Change description of optr only if `sar` (1st arg) == NULL (c.f. GEReq_eval_TR()->ks_eval_mintr() )
     This is because when we use ks_eval_mintr() we have .duration = .min_duration and hence nettime is equal
     to the bare sum of sequence module durations */
    char tmpstr[100];

    if (newtime_allconstraints == nettime) {
      sprintf(tmpstr, "TR [Not SAR/heat limited (%d)]", nettime);
    } else if (newtime_allconstraints == newtime_gradheat) {
      sprintf(tmpstr, "TR [Grad. heat limited (%d/%d)]", nettime, newtime_allconstraints);
    } else if (newtime_allconstraints == newtime_rfamp) {
      sprintf(tmpstr, "TR [RF amp limited (%d/%d)]", nettime, newtime_allconstraints);
    } else if (newtime_allconstraints == newtime_sar) {
      sprintf(tmpstr, "TR [SAR limited (%d/%d)]", nettime, newtime_allconstraints);
    }
    cvdesc(optr, tmpstr);  /* optr declared as extern int in epic.ext.h included by KSFoundation_private.h */
  }

  /* return the maximum value (rounded up to nearest divisible by 8) */
  return RUP_GRD(newtime_allconstraints);

} /* ks_eval_gradrflimits */

ks_eval_mintr()

int ks_eval_mintr	(	int	nslices,
		KS_SEQ_COLLECTION *	seqcollection,
		float	gheatfact,
		int(*)(int, int, void **)	play_loop,
		int	nargs,
		void **	args
	)

Returns the minimum TR based on the content of a slice loop, adding additional time due to SAR and hardware constraints if necessary

This function relies on the existence of a slice loop (wrapper) function that can be run on both HOST and TGT. In addition, it needs a KS_SEQ_COLLECTION struct containing references to the sequence modules (KS_SEQ_CONTROL) used in the slice loop. ks_eval_mintr() will call the slice loop, passed in as a function pointer, with nslices as the first argument.

Different psds have different arguments to their slice loop function depending on what is needed to know for the particular sequence, but a standardized argument list of the sliceloop function is required to allow it to be passed in to ks_eval_mintr(). Therefore, a small wrapper function is likely needed for the psd's sliceloop. Moreover, the sliceloop function must return the time in [us] (int) corresponding to the duration to play out the slice loop for nslices number of slices. E.g. if there is a psd specific function

int mysliceloop(int nslices, int ky, int exc, float somecustominfo) {
   int time = 0;

   for (i = 0; i < nslices; i++) {
      time += ks_scan_playsequence(&fatsatseqctrl); // play the fatsat sequence module, and count up fatsatseqctrl.nseqinstances by 1
      time += ks_scan_playsequence(&mymainseqctrl); // play the main sequence, and count up mymainseqctrl.nseqinstances by 1
   }

  return time; // return the duration of the sliceloop given 'nslices' slices.
               // This time is used to set the scan clock, while the .nseqinstances and .duration fields of each seqctrl struct
               // is used by ks_eval_gradrflimits() and ks_eval_mintr() to determine the total duration. .nseqinstances must be
               // known to calculate SAR in order to get the correct number of RF pulses for the slice loop via seqctrl.gradrf.rfptr[]
}

there should be a wrapper function with the following fixed input args:

1. nslices
2. nargs (number of extra arguments)
3. args (pointer to array of (void *) for the nargs extra arguments)

The most important argument is nslices, which must be passed to mysliceloop() so that different times are returned for different nslices. Hence, mysliceloop() must also have nslices as an input argument.

Scenario 1:

If the remaining arguments to mysliceloop() (like ky, exc, somecustominfo) do not affect the sequence timing, the sliceloop wrapper function can be written as (using mysliceloop() above):

 int mysliceloop_nargs(int nslices, int nargs, void **args) {

    mysliceloop(nslices, 0, 0, 0.0); // args 2-4 are set to 0 since ky, exc, or somecustominfo do not change the sliceloop timing and we will
                                     // only evaluate this on HOST where we are dry-running the sliceloop for timing reasons

}

Scenario 2:

If some of the remaining arguments to mysliceloop() (like ky, exc, somecustominfo) affect the sequence timing, the sliceloop wrapper function can be written as (using mysliceloop() above):

int mysliceloop_nargs(int nslices, int nargs, void **args) {
  int ky = 0;
  int exc = 0;
  float somecustominfo = 0;

  if (nargs >= 1 && args[0] != NULL) {
    ky = *((int *) args[0]); // cast from (void *) to (int *) and dereference
  }
  if (nargs >= 2 && args[1] != NULL) {
    exc = *((int *) args[1]); // cast from (void *) to (int *) and dereference
  }
  if (nargs >= 3 && args[2] != NULL) {
    somecustominfo = *((float *) args[2]); // cast from (void *) to (float *) and dereference
  }

  return mysliceloop(nslices, ky, exc, somecustominfo);
}

For scenario #2, nargs and args must be set up before calling ks_eval_mintr(), e.g. like:

void *args[] = {(void *) &ky,
                (void *) &exc,
                (void *) &somecustominfo}; // pass on the args to mysliceloop() via mysliceloop_nargs()
int nargs = sizeof(args) / sizeof(void *);

ks_eval_mintr(nslices, &seqcollection, mysliceloop_nargs, nargs, args);

Calculation of the minimum TR in three steps using ks_eval_mintr():

1. Set the .nseqinstances field to 0 for all KS_SEQ_CONTROL structs being a part of the KS_SEQ_COLLECTION using ks_eval_seqcollection_resetninst()
2. Run the slice loop (wrapper) function for the psd (see above) passed in as a function pointer. This will set the .nseqinstances field for each sequence module equal to the number of playouts of that sequence module in the slice loop
3. Call ks_eval_gradrflimits(), which will
   • use the .nseqinstances and .duration fields of each sequence module to determine the total net duration for the given number of slices
   • add potential extra time to keep us within SAR and hardware limits

The return value of ks_eval_gradrflimits() is also the return value of ks_eval_mintr()

Parameters

[in]	nslices	Number of slices to play out in the slice loop
[in]	seqcollection	A KS_SEQ_COLLECTION struct, which have undergone a reset of seqctlptr[].nseqinstances followed by a single run of the sequence's slice loop or equivalent period
[in]	gheatfact	Experimental fudge factor in range [0.0, 1.0] to control how much to obey the gradient heating calculations using the old gradient heating model. It is up to the EPIC programmer to set this to a proper value for now. This input argument can hopefully be removed in the future
[in]	play_loop	Function pointer to the sliceloop (wrapper) function of the sequence. This function should perform all time consuming tasks for one TR. It is a requirement that this function has three input arguments: int nslices, int nargs, void **args
[in]	nargs	Number of extra arguments to the slice loop wrapper function. This can be 0 if the slice loop is only temporally dependent on nslices
[in]	args	void * pointer array to extra arguments. This can be NULL if the slice loop is temporally dependent only on nslices

Return values

int	Minimum time in [us] that is needed to safetly play out the .nseqinstances sequence modules over the intended interval (usually one TR for 2D sequences)

                                                                                                                                                     {

  /* must be run before each call to function pointer `play_loop()` to set all `seqctrl.nseqinstances` to 0 */
  ks_eval_seqcollection_resetninst(seqcollection);

  play_loop(nslices, nargs, args); /* => seqctrl.nseqinstances = # times each seq. module has been played out */

  return ks_eval_gradrflimits(NULL, seqcollection, gheatfact);

} /* ks_eval_mintr() */

ks_eval_maxslicespertr()

int ks_eval_maxslicespertr	(	int	TR,
		KS_SEQ_COLLECTION *	seqcollection,
		float	gheatfact,
		int(*)(int, int, void **)	play_loop,
		int	nargs,
		void **	args
	)

Returns the maximum number of slices that can be played out in one TR, honoring SAR and hardware constraints

The maximum numbers of slices per TR is determined by calling ks_eval_mintr() with an increasing number of slices until the input TR value is reached

Parameters

[in]	TR	Repetition time in [us]
[in]	seqcollection	A KS_SEQ_COLLECTION struct, which have undergone a reset of seqctlptr[].nseqinstances followed by a single run of the sequence's slice loop or equivalent period
[in]	gheatfact	Experimental fudge factor in range [0.0, 1.0] to control how much to obey the gradient heating calculations using the old gradient heating model. It is up to the EPIC programmer to set this to a proper value for now. This input argument can hopefully be removed in the future
[in]	play_loop	Function pointer to the sliceloop (wrapper) function of the sequence. This function should perform all time consuming tasks for one TR. It is a requirement that this function has three input arguments: int nslices, int nargs, void **args
[in]	nargs	Number of extra arguments to the slice loop wrapper function. This can be 0 if the slice loop is only temporally dependent on nslices
[in]	args	void * pointer array to extra arguments. This can be NULL if the slice loop is temporally dependent only on nslices

Return values

int	Maximum number of slices that can fit in one TR

                                                                                                    {
  int max_slquant1 = 0;
  int i, acqtime;
  for (i = 1; i < 1024; i++) {

    acqtime = ks_eval_mintr(i, seqcollection, gheatfact, play_loop, nargs, args);

    if (acqtime == KS_NOTSET) {
      return KS_NOTSET;
    }
    if (acqtime > TR) {
      return max_slquant1;
    }
    max_slquant1 = i;
  }

  return max_slquant1;
}

ks_eval_seqctrl_setminduration()

STATUS ks_eval_seqctrl_setminduration	(	KS_SEQ_CONTROL *	seqctrl,
		int	mindur
	)

Sets the minimum duration and duration fields of a KS_SEQ_CONTROL struct based on some minimum time (arg 2)

It is recommended that this function is put at the end of the sequence generating function for the current sequence module (c.f. KS_SEQ_CONTROL), e.g. mypsd_pg(), which is a point where one knows how long the pulse sequence is, as the last gradient or RF waveform has been placed out. After passing the known minimum allowed sequence module duration as arg2 to ks_eval_seqctrl_setminduration(), both seqctrl.duration and `seqctrl.min_duration are set to this minimum value + the SSI time for the sequence module (which must be > 0 before calling this function).

This function is only available on HOST for the reason that the .duration field should not be reset to the minimum duration on TGT. The recommended order of events is the following:

1. In cveval() on HOST: Call mypsd_pg(). Having the ks_eval_seqctrl_setminduration() call at the end of mypsd_pg(), with the second argument (minimum duration) set to the absolute time corresponding to the last waveform, it is assured that both seqctrl.duration (which can grow bigger later) and seqctrl.min_duration (which should not be modified later) is equal to the same minimum possible value at this point.

   #ifndef IPG // make it explicit that this function is to be called only on HOST (not IPG)
    // ...end of mypsd_pg()...
    // N.B.: .seqctrl.ssi_time must be > 0 before calling ks_eval_seqctrl_setminduration()
    ks_eval_seqctrl_setminduration(&ksfse.seqctrl, tmploc.pos); // tmploc.pos now corresponds to the end of last gradient in the sequence
   #endif

2. In cveval() on HOST, after the mypsd_pg() call: Do some TR timing calculations and increase the seqctrl.duration field(s) for one or more sequence modules to fill up to the intended TR. The reasons for why seqctrl.duration needs to be larger than seqctrl.min_duration could be either that the TR is larger than the minimum possible by the waveforms, and/or that SAR or hardware constraints (reported back by ks_eval_mintr()) mandates that additional time must be added to the sequence to honor these limits.
3. In pulsegen() on TGT (IPG): The mypsd_pg() function is called to place out the actual hardware waveforms, followed by the "sequence ending here"-call to KS_SEQLENGTH(), which is using seqctrl.duration to determine the length of the sequence module. As efforts have been made on HOST to set seqctrl.duration, we cannot have ks_eval_seqctrl_setminduration() to reset it again on TGT when mypsd_pg() is called. Hence this is why ks_eval_seqctrl_setminduration() is only accessible on HOST

Parameters

[in,out]	seqctrl	Pointer to KS_SEQ_CONTROL struct for the current sequence module
[in]	mindur	mindur + .ssi_time => .min_duration = .duration @retval STATUSSUCCESSorFAILURE`

                                                                           {
#ifndef IPG
  /* only do this on HOST */

  if (seqctrl == NULL) {
    return ks_error("%s: arg 1 is NULL", __FUNCTION__);
  } else if (mindur > 0 && seqctrl->ssi_time <= 0) {
    return ks_error("%s: %s - seqctrl.ssi_time must be > 0 before setting minimum duration", __FUNCTION__, seqctrl->description);
  } else if (mindur > 0 && seqctrl->ssi_time % 4) {
    return ks_error("%s: %s - seqctrl.ssi_time must be divisible by GRAD_UPDATE_TIME", __FUNCTION__, seqctrl->description);
  } else if (mindur < 0) {
    return ks_error("%s: %s - min duration (arg 2) must be >= 0", __FUNCTION__, seqctrl->description);
  } else if (mindur % 4) {
    return ks_error("%s: %s - min duration (arg 2) must be divisible by GRAD_UPDATE_TIME", __FUNCTION__, seqctrl->description);
  } else {
    if (mindur == 0) {
      seqctrl->min_duration = 0;
    } else {
      /* we add 4us (GRAD_UPDATE_TIME) to avoid waveform-after-seqcore errors */
      seqctrl->min_duration = RUP_GRD(mindur + seqctrl->ssi_time + GRAD_UPDATE_TIME);
    }
    seqctrl->duration = seqctrl->min_duration;
  }
#endif

 return SUCCESS;
}

ks_eval_seqctrl_setduration()

STATUS ks_eval_seqctrl_setduration	(	KS_SEQ_CONTROL *	seqctrl,
		int	dur
	)

Sets the .duration field of the sequence module (KS_SEQ_CONTROL), while checking that the input value is not less than .min_duration

Parameters

[in,out]	seqctrl	Pointer to KS_SEQ_CONTROL struct for the current sequence module
[in]	dur	Desired duration of the current sequence module (including its SSI time, .ssi_time)

Return values

STATUS

SUCCESS or FAILURE

                                                                     {
#ifndef IPG
  /* only do this on HOST */

  if (seqctrl == NULL) {
    return ks_error("%s: arg 1 is NULL", __FUNCTION__);
  } else if (dur < seqctrl->min_duration) {
    return ks_error("%s: duration (arg 2) must be >= min duration (%d", __FUNCTION__, seqctrl->min_duration);
  } else {
    seqctrl->duration = RUP_GRD(dur);
  }
#endif

 return SUCCESS;
}

ks_eval_seqcollection_durations_setminimum()

STATUS ks_eval_seqcollection_durations_setminimum

(

KS_SEQ_COLLECTION *

seqcollection

)

Sets the .duration fields of all sequence modules being part of the sequence collection (KS_SEQ_COLLECTION) to their .min_duration value

Parameters

[in,out]

seqcollection

Pointer to KS_SEQ_COLLECTION struct holding pointers to all sequence modules

Return values

STATUS

SUCCESS or FAILURE

                                                                                    {
#ifndef IPG
  /* only do this on HOST */

 int i;
  if (seqcollection != NULL) {
    for (i = 0; i < seqcollection->numseq; i++) {
      if (seqcollection->seqctrlptr[i]->min_duration % 4) {
        return ks_error("%s: Field min_duration for sequence module #%d is not divisible by GRAD_UPDATE_TIME", __FUNCTION__, i);
      }
      seqcollection->seqctrlptr[i]->duration = seqcollection->seqctrlptr[i]->min_duration;
    }
  }
#endif

  return SUCCESS;
}

ks_eval_seqcollection_durations_atleastminimum()

STATUS ks_eval_seqcollection_durations_atleastminimum

(

KS_SEQ_COLLECTION *

seqcollection

)

Assures the .duration fields of all sequence modules being part of the sequence collection (KS_SEQ_COLLECTION) are at least their .min_duration value

Parameters

[in,out]

seqcollection

Pointer to KS_SEQ_COLLECTION struct holding pointers to all sequence modules

Return values

STATUS

SUCCESS or FAILURE

                                                                                        {
#ifndef IPG
  /* only do this on HOST */

 int i;
  if (seqcollection != NULL) {
    for (i = 0; i < seqcollection->numseq; i++) {
      if (seqcollection->seqctrlptr[i]->min_duration % 4) {
        return ks_error("%s: Field min_duration for sequence module #%d is not divisible by GRAD_UPDATE_TIME", __FUNCTION__, i);
      }
      if (seqcollection->seqctrlptr[i]->duration < seqcollection->seqctrlptr[i]->min_duration) {
        seqcollection->seqctrlptr[i]->duration = seqcollection->seqctrlptr[i]->min_duration;
      }
    }
  }
#endif

  return SUCCESS;
}

ks_eval_seqcollection_resetninst()

void ks_eval_seqcollection_resetninst

(

KS_SEQ_COLLECTION *

seqcollection

)

Set the .nseqinstances field of each sequence module (KS_SEQ_CONTROL) equal to 0

This function is called in ks_eval_mintr() and GEReq_eval_TR() to reset the sequence module counters before calling the psd's scanloop function, where the ks_scan_playsequence() functions internally increment .nseqinstances by one every time they are called

Parameters

[in,out]

seqcollection

Collection of all sequence modules (KS_SEQ_COLLECTION). C.f. ks_eval_addtoseqcollection()

Returns

void

                                                                        {
  int i;
  if (seqcollection != NULL) {
    for (i = 0; i < seqcollection->numseq; i++) {
#ifndef IPG
      seqcollection->seqctrlptr[i]->nseqinstances = 0;
#endif
    }
  }

}

ks_print_seqcollection()

void ks_print_seqcollection	(	KS_SEQ_COLLECTION *	seqcollection,
		FILE *	fp
	)

Print out the duration of each sequence module in the sequence collection to a file pointer

Besides printing out the duration of each sequence module, it will also show the number of occurences of each sequence module each TR. However, for this to be correct ks_eval_seqcollection_resetninst() should first be called followed by one call to the sequence's sliceloop function to increment each .seqctrl.nseqinstances field. See e.g. GEReq_eval_checkTR_SAR().

Parameters

[in]	seqcollection	Collection of all sequence modules (KS_SEQ_COLLECTION). C.f. ks_eval_addtoseqcollection()
[in]	fp	File pointer to file to write to

Returns

void

                                                                        {
  int i;

  /* duration based on the sequence collection struct */
  fprintf(fp, "\n----------------------------------------------\n");
  fprintf(fp, "Sequence modules in the sequence collection:\n");
  for (i = 0; i < seqcollection->numseq; i++) {
    fprintf(fp, "%s: %dx %d us = %d\n", seqcollection->seqctrlptr[i]->description, seqcollection->seqctrlptr[i]->nseqinstances, seqcollection->seqctrlptr[i]->duration,
      seqcollection->seqctrlptr[i]->nseqinstances * seqcollection->seqctrlptr[i]->duration);
  }
  fprintf(fp, "Sum of durations: %d us\n", ks_eval_seqcollection_gettotalduration(seqcollection));
  fprintf(fp, "----------------------------------------------\n\n");
  fflush(fp);

  return;
} /* ks_print_seqcollection() */

ks_print_scaninfo()

void ks_print_scaninfo	(	const SCAN_INFO *	scan_info,
		int	nslices,
		const char *	desc,
		FILE *	fp
	)

Print out the slice location info [mm]

Parameters

[in]	scan_info	File pointer to SCAN_INFO
[in]	nslices	Number of slices prescribed
[in]	desc	Description of the slice info (or NULL)
[in]	fp	File pointer to file to write to

Returns

void

                                                                                            {
  int i;

  fprintf(fp, "=============================================\n\n");

  if (desc != NULL) {
    fprintf(fp, "\nScan info %s (%d slices):\n", desc, nslices);
  } else {
    fprintf(fp, "\nScan info (%d slices):\n", nslices);
  }
  fprintf(fp, "---------------------------------------------\n");
  for (i = 0; i < nslices; i++) {
    fprintf(fp, "%.3f   \t%.3f   \t%.3f\n", scan_info[i].oprloc, scan_info[i].opphasoff, scan_info[i].optloc);
  }
  fprintf(fp, "=============================================\n\n");

}

ks_eval_seqcollection_gettotalduration()

int ks_eval_seqcollection_gettotalduration

(

KS_SEQ_COLLECTION *

seqcollection

)

Returns the total duration of the sequence collection

Based on the seqctrl.ninstances and seqctrl.duration fields for each KS_SEQ_CONTROL (sequence module) that have been added to the sequence collection struct (KS_SEQ_COLLECTION), this function returns the total duration of the sequence collection. No time is added to comply with SAR or hardware limits, hence this time may not be possible to use in practice. See ks_eval_mintr(), GEReq_eval_TR(), and ks_eval_gradrflimits() for more details.

Parameters

[in]

seqcollection

Collection of all sequence modules (KS_SEQ_COLLECTION). C.f. ks_eval_addtoseqcollection()

Return values

int	Time in [us]

                                                                             {
 int i;
 int nettime = 0;

  /* duration based on the sequence collection struct */
  for (i = 0; i < seqcollection->numseq; i++) {
    /*
    if (seqcollection->seqctrlptr[i]->duration > 0 && seqcollection->seqctrlptr[i]->nseqinstances == 0) {
      ks_error("%s: Sequence module #%d was not played out in sliceloop using ks_scan_playsequence()", __FUNCTION__, i);
      return KS_NOTSET;
    }
    */
    nettime += seqcollection->seqctrlptr[i]->duration * seqcollection->seqctrlptr[i]->nseqinstances;
  }

  if (nettime == 0) {
    ks_error("%s: Sum of durations of sequence modules used is 0", __FUNCTION__);
  }

  return nettime;
} /* ks_eval_seqcollection_gettotalduration() */

ks_eval_seqcollection_gettotalminduration()

int ks_eval_seqcollection_gettotalminduration

(

KS_SEQ_COLLECTION *

seqcollection

)

Returns the total duration of the sequence collection

Based on the seqctrl.ninstances and seqctrl.min_duration fields for each KS_SEQ_CONTROL (sequence module) that have been added to the sequence collection struct (KS_SEQ_COLLECTION), this function returns the total minimum duration possible of the sequence collection, i.e. the time needed to play out the sequence waveforms without any deadtime. See ks_eval_mintr(), GEReq_eval_TR(), and ks_eval_gradrflimits() for more details

Parameters

[in]

seqcollection

Collection of all sequence modules (KS_SEQ_COLLECTION). C.f. ks_eval_addtoseqcollection()

Return values

int	Time in [us]

                                                                                {
 int i;
 int nettime = 0;

  /* duration based on the sequence collection struct */
  for (i = 0; i < seqcollection->numseq; i++) {
    /*
    if (seqcollection->seqctrlptr[i]->min_duration > 0 && seqcollection->seqctrlptr[i]->nseqinstances == 0) {
      ks_error("%s: Sequence module #%d was not played out in sliceloop using ks_scan_playsequence()", __FUNCTION__, i);
      return KS_NOTSET;
    }
    */
    nettime += seqcollection->seqctrlptr[i]->min_duration * seqcollection->seqctrlptr[i]->nseqinstances;
  }

  if (nettime == 0) {
    ks_error("%s: Sum of min_durations of sequence modules used is 0", __FUNCTION__);
  }

  return nettime;
} /* ks_eval_seqcollection_gettotalminduration() */

ks_eval_seqcollection2rfpulse()

STATUS ks_eval_seqcollection2rfpulse	(	RF_PULSE *	rfpulse,
		KS_SEQ_COLLECTION *	seqcollection
	)

(Internal use) Sets up GE's rfpulse[] array from the contents of a KS_SEQ_COLLECTION struct

To use GE's maxsar() and maxseqrfamp() functions in ks_eval_gradrflimits() there needs to be an rfpulse[] array containing info about the RF pulses. This info is for standard EPIC psds stored on disk in a file grad_rf_<psdname>.h. KSFoundation EPIC psds with one or more sequence modules (KS_SEQ_CONTROL) have all RF information stored in seqcollection->seqctrlptr[i].gradrf.rfptr[]. This function takes all RF information from all sequence modules in the sequence collection and puts in the proper format in rfpulse[]. Then rfpulse[] can be passed on to maxsar() and maxseqrfamp() (see ks_eval_gradrflimits())

Parameters

[out]	rfpulse	Pointer to rfpulse[] array
[in]	seqcollection	Pointer to the sequence collection struct for the sequence

Return values

STATUS

SUCCESS or FAILURE

                                                                                          {
  int i, j, k;

  /* clear the activity bits for all (KS_MAXUNIQUE_RF) available RF pulse slots */
  for (i = 0; i < KS_MAXUNIQUE_RF; i++) {
    rfpulse[i].activity = 0;
  }

  i = 0;
  for (k = 0; k < seqcollection->numseq; k++) {

    for (j = 0; j < seqcollection->seqctrlptr[k]->gradrf.numrf; j++) {

      if (i >= KS_MAXUNIQUE_RF) {
        return ks_error("%s: too many RF pulses, recompilation is needed with an increased KS_MAXUNIQUE_RF",
                        __FUNCTION__);
      }

      ks_eval_rf_relink(seqcollection->seqctrlptr[k]->gradrf.rfptr[j]);
      rfpulse[i++] = seqcollection->seqctrlptr[k]->gradrf.rfptr[j]->rfpulse;
    }
  }

  return SUCCESS;

} /* ks_eval_seqcollection2rfpulse */

ks_eval_makegradpulse()

GRAD_PULSE ks_eval_makegradpulse	(	KS_TRAP *	trp,
		int	gradchoice
	)

(Internal use) Creates a GRAD_PULSE struct from a KS_TRAP object

To use GE's minseq() function that determines gradient heating limits from the gradient usage, a GRAD_PULSE array needs to be generated for each gradient axis. This info is for standard EPIC psds stored on disk in a file grad_rf_<psdname>.h. KSFoundation EPIC psds with one or more sequence modules (KS_SEQ_CONTROL) being part of a KS_SEQ_COLLECTION struct, have all gradient trapezoid (KS_TRAP) information stored in seqcollection->seqctrlptr[i].gradrf.trapptr[]. Hence, from the seqcollection struct it is possible to reach all KS_TRAP for all sequence modules (see ks_eval_gradrflimits()), which one by one can be converted to GRAD_PULSE structs using this function.

Parameters

[in]	trp	Pointer to a KS_TRAP object
[in]	gradchoice	XGRAD, YGRAD, or ZGRAD, specifying which gradient this is used on

Return values

GRAD_PULSE

A gradient pulse structure in GE's standard form

                                                               {
  GRAD_PULSE g;

  /* we have to compute it here because g.amp is a pointer */
  trp->heat_scaled_amp[gradchoice] = trp->amp*trp->heat_scaling_factor[gradchoice];


  g.ptype = G_TRAP;
  g.attack = &trp->ramptime;
  g.decay = &trp->ramptime;
  g.pw = &trp->plateautime;
  g.amps = NULL;
  g.amp = &trp->heat_scaled_amp[gradchoice];
  g.ampd = NULL;
  g.ampe = NULL;
  g.gradfile = NULL;
  g.num = trp->gradnum[gradchoice];
  g.scale = 1.0; /* scale. < 1 for phase enc. */
  g.time = NULL;
  g.tdelta = 0; /* Time delta in microseconds in between multiple occurances of the pulse */
  g.powscale = 1.0; /* might want to do loggrd.xfs/loggrd.tx_xyz instead? */

  /* the following are set by minseq***() later */
  g.power = 0.0;
  g.powpos = 0.0;
  g.powneg = 0.0;
  g.powabs = 0.0;
  g.amptran = 0.0;
  g.pwm = 1;
  g.bridge = 0;
  g.intabspwmcurr = 0;

  return g;
}

ks_read_header_pool()

void ks_read_header_pool	(	int *	exam_number,
		int *	series_number,
		int *	run_number
	)

ks_calc_nextpow2()

unsigned int ks_calc_nextpow2

(

unsigned int

x

)

Gives the next higher 2^N for a given number

Parameters

[in]

x

Integer (usually related to resolution)

Return values

nextpow2

Unsigned integer with a value equal to the nearest larger power-of-2

                                              {
  n--;
  n |= n >> 1;
  n |= n >> 2;
  n |= n >> 4;
  n |= n >> 8;
  n |= n >> 16;
  n++;
  return n;
}

ks_calc_roundupms()

int ks_calc_roundupms

(

int

time

)

Rounds up a value in [us] to nearest whole [ms]

Parameters

[in]

time

Time in [us]

Return values

newtime

Time in [us], rounded up to next whole [ms] unless already rounded

                               {
  return (((val + 999) / 1000) * 1000);
}

ks_calc_filter()

STATUS ks_calc_filter	(	FILTER_INFO *	echo_filter,
		int	tsp,
		int	duration
	)

Sets up GE's FILTER_INFO struct based on dwell (sample point) time and duration of an acquisition window

This function is used internally by ks_eval_read() as a part of the setup of a KS_READ sequence object, which contains the .filt (FILTER_INFO) field that is used with the corresponding acquisition window in the field .echo of the KS_READ object

ks_calc_filter() will set the field .filt.slot to KS_NOTSET (= -1). A final (global) hardware slot number is set when either setfilter() or GEReq_predownload_setfilter() is called in predownload(). With the assigned slot number, ks_pg_read() in pulsegen() will connect this filter to the acquisition window by internally calling setrfltrs()

Steps for a main sequence written entirely using KSFoundation

• GE's function initfilter() is called in the Requiredcvinit section of GERequired.e. Make sure this section is @inline'd in cvinit() in the main sequence
• In predownload(): GEReq_predownload_setfilter() should be called instead of setfilter(), after @inlining the RequiredpredownloadBegin section of GERequired.e. Pass the .filt field set up by this function to GEReq_predownload_setfilter()

Parameters

[out]	echo_filter	FILTER_INFO struct needed for data acquisition
[in]	tsp	Duration in [us] for each data sample (dwell time) in the acquisition window. Minimum: 2 [us]
[in]	duration	Duration in [us] of the entire data acquisition window

Return values

STATUS

SUCCESS or FAILURE

                                                                   {

  echortf->decimation = tsp / 2;
  echortf->bw = 1.0e3 / (tsp * 2.0);
  echortf->tsp = tsp; /* dwell time [us] */
  echortf->tdaq = duration;
  echortf->outputs = duration / echortf->tsp;
  echortf->fslot = KS_NOTSET; /* set this to an unusable value so we are forced to call setfilter() or GEReq_predownload_setfilter() */
  echortf->prefills = 0;
  echortf->taps = -1;

  if ((floor(echortf->tsp) < echortf->tsp) || (duration % (int) echortf->tsp)) {
    return ks_error("ks_calc_filter: tsp must be an integer number and 2nd arg (duration) must be even (divisible by 'tsp'), in units of us");
  }
  if (echortf->outputs % 2) {
    return ks_error("ks_calc_filter: the number of sample outputs must be even");
  }
  return SUCCESS;
}

ks_calc_bw2tsp()

int ks_calc_bw2tsp

(

float

bw

)

Convert receiver bandwidth to dwell time

Parameters

[in]

bw

+/- bandwidth per FOV in [kHz]. Maximum: 250

Return values

tsp	Duration in [us] for each data sample (dwell time) in the acquisition window

                             {
  int tsp;
  int sysmintsp = 2;

  tsp = ((int) floor((float) HALF_KHZ_USEC / bw / (float) sysmintsp + 0.5)) * sysmintsp;

  if (tsp < sysmintsp)
    tsp = sysmintsp;

  return tsp;
}

ks_calc_tsp2bw()

float ks_calc_tsp2bw

(

int

tsp

)

Convert dwell time to receiver bandwidth

Parameters

[in]

tsp

Duration in [us] for each data sample in the acquisition window. Minimum: 2 [us]

Return values

bw	+/- bandwidth per FOV in [kHz]

                              {

  return ( (float) HALF_KHZ_USEC / (float) tsp );

}

ks_calc_trap_time2area()

int ks_calc_trap_time2area	(	KS_TRAP *	trap,
		float	area
	)

Calculates the time from start of gradient until area is reached

Parameters

[in]	trap	KS_TRAP* Trapezoid gradient
[in]	area	Area to reach

Return values

time

in [us]

                                                      {
  float ramp_area = trap->amp * trap->ramptime / 2.0;
  float plateau_area = trap->amp * trap->plateautime;
  float slewrate = trap->amp / trap->ramptime;
  int time2area;
  if (area < ramp_area) {
    /* Target area reached on ramp */
    time2area = (int) sqrtf(area * 2.0 / slewrate);
  } else if (area < (ramp_area + plateau_area)) {
    /* Target area reached on plateau*/
    float area_remaining = area - ramp_area;
    time2area = trap->ramptime + (area_remaining / trap->amp);
  } else {
    /* Target area reached on ramp down */
    float area_remaining = area - ramp_area - plateau_area;
    time2area = (trap->amp - sqrtf(trap->amp*trap->amp  - 2*area_remaining*slewrate) ) / slewrate;
  }
  return time2area;
}

ks_calc_nearestbw()

float ks_calc_nearestbw

(

float

bw

)

Round receiver bandwidth to nearest valid value

As the dwell time is an integer and the reciprocal of receiver bandwidth, only certain values of receiver bandwidth are possible. This functions rounds a desired receiver bandwidth to the nearest valid value

Parameters

[in]

bw

+/- bandwidth per FOV in [kHz]. Maximum: 250

Return values

bw	Rounded +/- bandwidth per FOV in [kHz]

                                  {
  int tsp;
  if (bw > 0) {
    tsp = (int) ks_calc_bw2tsp(bw); /* convert rBW to dwell time [us] */
    return (ks_calc_tsp2bw(tsp)); /* round rBW to exacly match the dwell time */
  } else {
    return bw;
  }
}

ks_calc_lower_rbw()

float ks_calc_lower_rbw

(

float

rbw

)

                                   {
  if (isNotSet(rbw)) {
    return rbw;
  }
  int tsp = ks_calc_bw2tsp(rbw);
  return ks_calc_nearestbw(500.0f / (tsp + 2));
}

ks_calc_higher_rbw()

float ks_calc_higher_rbw

(

float

rbw

)

                                    {
  int tsp = ks_calc_bw2tsp(rbw);
  if (tsp == 2 || isNotSet(rbw)) {
    return rbw;
  } else {
    return ks_calc_nearestbw(500.0f / (tsp - 2));
  }
}

ks_calc_max_rbw()

float ks_calc_max_rbw	(	float	ampmax,
		float	fov
	)

Find the maximum reciever bandwidth based on a max gradient amplitude and FOV

Calculates maximum receiver bandwidth

As the dwell time is an integer and the reciprocal of receiver bandwidth, only certain values of receiver bandwidth are possible. This functions rounds a desired receiver bandwidth to the nearest valid value

Parameters

[in]	ampmax	Max gradient amplitude allowed
[in]	fov	FOV in the readout direction [mm]

Return values

bw	Rounded +/- bandwidth per FOV in [kHz]

Given a maximum allowed gradient amplitude in [G/cm] and a readout FOV in [mm], the largest rBW time (i.e. smallest dwell time) in [us] is calculated.

Parameters

[in]	ampmax	The maximum allowed gradient amplitude ([G/cm])
[in]	fov	FOV in the readout direction

Return values

rbw	Receiver bandwidth in kHz.

                                               {
  float max_rbw = -1.0f;
  int dwelltime;
  for (dwelltime = 2; max_rbw < 0.0; dwelltime += 2) {
    float required_amp = 1.0/(GAM * fov * 0.1 * dwelltime * 0.000001);
    if (required_amp <= ampmax) {
      max_rbw = 500.0f / ((float) dwelltime);
    }
  }
  return max_rbw;
}

ks_calc_minfov()

float ks_calc_minfov	(	float	ampmax,
		int	tsp
	)

Calculates the minimum readout FOV

Given a maximum allowed gradient amplitude in [G/cm] and a dwell time in [us] (see ks_calc_bw2tsp()), the minimum possible readout FOV in [mm] is calculated. This function is called internally by ks_eval_readtrap_constrained() when rampsampling is not used (.rampsampling = 0)

Parameters

[in]	ampmax	The maximum allowed gradient amplitude ([G/cm])
[in]	tsp	Duration in [us] for each data sample in the acquisition window. Minimum: 2 [us]

Return values

minFOV

Minimum FOV in the readout direction

                                            {
  float minfov;

  minfov = ((float) (2 * (1.0e3 / (tsp * 2.0)) * 1000 / GAM) * (10.0 / ampmax));

  return minfov;
}

ks_calc_minslthick()

float ks_calc_minslthick

(

float

bw

)

Calculates the minimum slice thickness [mm]

Given an RF bandwidth in [kHz], this function returns the minimum slice thickness possible given the gradient max amplitude.

Parameters

[in]

bw

RF bandwidth in [kHz]

Return values

minSliceThickness

Minimum slice thickness in [mm]

                                   {
  return (bw  / (ks_syslimits_ampmax(loggrd) * (0.1) * GAM));
}

ks_calc_mintsp()

int ks_calc_mintsp	(	float	ampmax,
		float	fov
	)

Calculates the minimum dwell time

Given a maximum allowed gradient amplitude in [G/cm] and a readout FOV in [mm], the smallest dwell time (i.e. largest rBW) in [us] is calculated.

Parameters

[in]	ampmax	The maximum allowed gradient amplitude ([G/cm])
[in]	fov	FOV in the readout direction

Return values

tsp	Duration in [us] for each data sample in the acquisition window

                                            {
  int mintsp;
  int sysmintsp = 2;

  mintsp = (int) ceil(1.0e3 / (fov / ((float) (2 * 1000 / GAM) * (10.0 / ampmax)) * 2.0));

  if (mintsp < sysmintsp)
    mintsp = mintsp;

  return mintsp;
}

ks_calc_fov2gradareapixel()

float ks_calc_fov2gradareapixel

(

float

fov

)

Calculates the gradient area needed to move one pixel in k-space

Given a readout FOV in [mm], the gradient area needed to move one pixel in a fully sampled k-space is calculated

Parameters

[in]

fov

FOV in the readout direction

Return values

area	Gradient area in [(G/cm) * us]

                                             {
  if (fov > 0) {
    /* G/cm * us. Area needed to move one pixel in k-space corresponding to the input FOV */
    return (1.0e6 / (fov / 10.0 * GAM));
  } else {
    return (0.0);
  }
}

ks_calc_dixon_times_within_one_period()

int ks_calc_dixon_times_within_one_period	(	float	t1,
		float	t2,
		float	B0
	)

                                                                        {
  float frequency = 42.5759*B0*3.4;
  float periods = fabs(t1 - t2) * frequency;
  if (periods > 1.0) {
    return FAILURE;
  } else {
    return SUCCESS;
  }
}

ks_calc_dixon_fat_nsa_2p()

float ks_calc_dixon_fat_nsa_2p	(	float	t1,
		float	t2,
		float	B0,
		float	F
	)

                                                                     {
  return ks_calc_dixon_water_nsa_2p(t1, t2, B0, 1-F);
}

ks_calc_dixon_water_nsa_2p()

float ks_calc_dixon_water_nsa_2p	(	float	t1,
		float	t2,
		float	B0,
		float	W
	)

                                                                       {
  float F = 1 - W;
  float omega = 2*PI*42.5759*B0*3.4;
  float c1 = cos(omega * t1);
  float c2 = cos(omega * t2);
  float scale = pow((c1 - c2) * (pow(F,2)  - pow(W,2)),2); /* No time difference as it will cancel */
  float Mw = pow(W,4) * pow(c1,2) +
             pow(W,4) * pow(c2,2) +
             pow(F*W*c1,2)  + 
             pow(F*W*c2,2)  + 
             2 * pow(F,4)   + 
             2 * pow(F*W,2) +
             2 * c1 * (F*pow(W,3) + 2*W*pow(F,3)) +
             2 * c2 * (F*pow(W,3) + 2*W*pow(F,3)) +
             2 * c1 * c2 * (4*pow(F*W,2) + F*pow(W,3)*(c1 + c2));
  return (scale/Mw);
}

ks_calc_dixon_cond_2p()

double ks_calc_dixon_cond_2p	(	double	t1,
		double	t2,
		double	B0
	)

                                                              {
  double pha1 = 2*PI*42.5759*t1*B0*(1.3-4.7);
  double pha2 = 2*PI*42.5759*t2*B0*(1.3-4.7);
  double pha_diff = pha2 - pha1;
  double real_phasor = cos(pha_diff);
  double lambda1 = 2.0 + .5*sqrt(16 - 4*(2 - 2*real_phasor));
  double lambda2 = 2.0 - .5*sqrt(16 - 4*(2 - 2*real_phasor));
  double cond = lambda1 / (lambda2 + .00000001);
  return cond;
}

ks_calc_dixon_mean_nsa_2p_ss()

float ks_calc_dixon_mean_nsa_2p_ss	(	float	t1,
		float	t2,
		float	B0
	)

                                                                 {
    const double omega = 2*PI*42.5759*B0*3.4; /* 3.4 ppm */
    const double c1 = cos(omega * t1);
    const double c2 = cos(omega * t2);
    return pow(c1 - c2, 2) * (c1*c1 + c2*c2 + 2) / (4 * (c1*c1 + c2*c2));
}

ks_calc_dixon_mean_nsa_2p_ss_weighted()

float ks_calc_dixon_mean_nsa_2p_ss_weighted	(	float	t1,
		float	t2,
		float	B0,
		float	w1,
		float	w2
	)

                                                                                              {
    /* Normalize scales s.t. w1+w2 = 1 */
    const float n = w1 + w2;
    w1 = w1 / n;
    w2 = w2 / n;
    
    const float omega = 2*PI*42.5759*B0*3.4; /* 3.4 ppm */
    const float c1 = cos(omega * t1);
    const float c2 = cos(omega * t2);
    /* Return scaled to [0,1] */
    return (w1 * w2 * pow(c1 - c2, 2) * (w1*c1*c1 + w2*c2*c2 + w1 + w2) / (2 * (w1 + w2) * (w1*c1*c1 + w2*c2*c2)) );
}

ks_phaseencoding_init_tgt()

void ks_phaseencoding_init_tgt

(

KS_PHASEENCODING_PLAN *

phaseenc_plan_ptr

)

Internal use for correct migration of KS_PHASEENCODING_PLAN from HOST to TGT (IPG)

Parameters

[in]

phaseenc_plan_ptr

Pointer to KS_PHASEENCODING_PLAN

Returns

void

                                                                         {
#ifdef IPG
  if (phaseenc_plan_ptr->is_cleared_on_tgt == FALSE) {
    phaseenc_plan_ptr->entries = NULL; /* clear memory pointer from HOST (which is garbage to the TGT) */
    phaseenc_plan_ptr->phaser = NULL; /* clear memory pointer from HOST (which is garbage to the TGT) */
    phaseenc_plan_ptr->zphaser = NULL; /* clear memory pointer from HOST (which is garbage to the TGT) */
    phaseenc_plan_ptr->is_cleared_on_tgt = TRUE;
  }
#else
  (void) (phaseenc_plan_ptr);
#endif
}

ks_phaseencoding_get()

KS_PHASEENCODING_COORD ks_phaseencoding_get	(	const KS_PHASEENCODING_PLAN *	phaseenc_plan_ptr,
		int	echo,
		int	shot
	)

Get [ky,kz] coordinate from KS_PHASEENCODING_PLAN for given echo and shot

If the .ky and .kz values returned by this function is = KS_NOTSET (-1), it indicates that this echo/shot combination should have zero phase encoding and should be ignored. For 2D, .kz will always be KS_NOTSET

Parameters

[in]	phaseenc_plan_ptr	Pointer to KS_PHASEENCODING_PLAN
[in]	echo	Echo index in the sequence ETL in range [0,ETL-1]
[in]	shot	Shot index (i.e. how many times the sequence is played out per slice). For 3D, this is the combined number of shots over ky and kz

Return values

<tt>KS_PHASEENCODING_COORD</tt>

                                                                                                                {
#ifdef IPG
  int oktoset = ((phaseenc_plan_ptr != NULL) && phaseenc_plan_ptr->etl != KS_NOTSET) && (phaseenc_plan_ptr->is_cleared_on_tgt);
#else
  int oktoset = (phaseenc_plan_ptr != NULL) && phaseenc_plan_ptr->etl != KS_NOTSET;
#endif

  if (!oktoset || !(phaseenc_plan_ptr->entries) ||
      shot < 0 || shot >= phaseenc_plan_ptr->num_shots ||
      echo < 0 || echo >= phaseenc_plan_ptr->etl) {

    KS_PHASEENCODING_COORD fake_coords = KS_INIT_PHASEENCODING_COORD;
    return fake_coords;
  }

  return phaseenc_plan_ptr->entries[echo + phaseenc_plan_ptr->etl * shot];
}

ks_phaseencoding_set()

void ks_phaseencoding_set	(	KS_PHASEENCODING_PLAN *	phaseenc_plan_ptr,
		int	echo,
		int	shot,
		int	ky,
		int	kz
	)

Set [ky,kz] coordinate from KS_PHASEENCODING_PLAN for given echo and shot

If the .ky and .kz values passed to this function is = KS_NOTSET (-1), it indicates that this echo/shot combination should have zero phase encoding and should be ignored. However, ignored echo/shot combinations are not necessary since the etl*num_shots entries in .entries of KS_PHASEENCODING_PLAN are always initialized to KS_NOTSET by ks_phaseencoding_resize(). Hence, it is only necessary to explicitly set the echo/shot combination for ky/kz coordinates being acquired.

For 2D, kz (5th arg) should always be KS_NOTSET.

Parameters

[in]	phaseenc_plan_ptr	Pointer to KS_PHASEENCODING_PLAN
[in]	echo	Echo index in the sequence ETL in range [0,ETL-1]
[in]	shot	Shot index (in range [0,how many times the sequence is played out per slice - 1]). For 3D, this is the combined number of shots over ky and kz
[in]	ky	K-space coordinate along the first (only for 2D) phase encoding direction (integer) in range [0, phaser.numlinestoacq-1]
[in]	kz	K-space coordinate along the second (use KS_NOTSET for 2D) phase encoding direction (integer) in range [0, zphaser.numlinestoacq-1]

Returns

void

                                                                                                        {
#ifdef IPG
  int oktoset = (phaseenc_plan_ptr->etl != KS_NOTSET) && (phaseenc_plan_ptr->is_cleared_on_tgt);
#else
  int oktoset = phaseenc_plan_ptr->etl != KS_NOTSET;
#endif

  if (!oktoset || !phaseenc_plan_ptr || !(phaseenc_plan_ptr->entries) ||
      shot < 0 || shot >= phaseenc_plan_ptr->num_shots ||
      echo < 0 || echo >= phaseenc_plan_ptr->etl) {

    return;
  }

  ky = (ky < 0) ? KS_NOTSET : ky; /* KS_NOTSET = shut off phase encoding */
  kz = (kz < 0) ? KS_NOTSET : kz;

  phaseenc_plan_ptr->entries[echo + phaseenc_plan_ptr->etl * shot].ky = ky;
  phaseenc_plan_ptr->entries[echo + phaseenc_plan_ptr->etl * shot].kz = kz;

}

ks_phaseencoding_print()

void ks_phaseencoding_print

(

const KS_PHASEENCODING_PLAN *

phaseenc_plan_ptr

)

Print out KS_PHASEENCODING_PLAN to a text file

In SIM (WTools), a file ks_phaseencodingtable.txt will be generated in the current directory On HW (MR scanner), the same file will be located in /usr/g/mrraw

Parameters

[in]

phaseenc_plan_ptr

Pointer to KS_PHASEENCODING_PLAN

Returns

void

                                                                            {
  KS_PHASEENCODING_COORD coord = KS_INIT_PHASEENCODING_COORD;
  int shot, echo;
#ifdef PSD_HW
  FILE *fp = fopen("/usr/g/mrraw/ks_phaseencodingtable.txt", "w");
#else
  FILE *fp = fopen("./ks_phaseencodingtable.txt", "w");
#endif

  if (phaseenc_plan_ptr->etl == KS_NOTSET) {
    return; /* we haven't set it up yet */
  }

  fprintf(fp, "numshots (vertical): %d, etl (horizontal): %d\n\n", phaseenc_plan_ptr->num_shots, phaseenc_plan_ptr->etl);

  for (shot = 0; shot < phaseenc_plan_ptr->num_shots; shot++) {
    for (echo = 0; echo < phaseenc_plan_ptr->etl; echo++) {
        coord = ks_phaseencoding_get(phaseenc_plan_ptr, echo, shot);
        if (coord.ky != KS_NOTSET) {
          fprintf(fp, "[%03d", coord.ky);
        } else {
          fprintf(fp, "[***");
        }
        if (coord.kz != KS_NOTSET) {
          fprintf(fp, ",%03d] ", coord.kz);
        } else {
          fprintf(fp, ",***] ");
        }
      }
    fprintf(fp,"\n");
  }

  fclose(fp);

}

ks_phaseencoding_resize()

STATUS ks_phaseencoding_resize	(	KS_PHASEENCODING_PLAN *	phaseenc_plan_ptr,
		int	etl,
		int	num_shots
	)

Reallocate memory for KS_PHASEENCODING_PLAN entries

For every (and custom) ks_phaseencoding_generate_** functions, this function must be called before ks_phaseencoding_set() so that there is memory allocataed for the array of KS_PHASEENCODING_COORD

Parameters

[in]	phaseenc_plan_ptr	Pointer to KS_PHASEENCODING_PLAN
[in]	etl	The number of acquisition window in the pulse sequence, or echo train length (ETL)
[in]	num_shots	Number of shots (i.e. how many times the sequence is played out per slice). For 3D, shot is over both ky and kz

Returns

void

                                                                                                 {
  void *ptr = NULL;
  int i;

  ks_phaseencoding_init_tgt(phaseenc_plan_ptr);

  ptr = realloc(phaseenc_plan_ptr->entries, etl * num_shots * sizeof(KS_PHASEENCODING_COORD));
  if (!ptr) {
    return ks_error("%s: failed reallocation", __FUNCTION__);
  }

  phaseenc_plan_ptr->etl = etl;
  phaseenc_plan_ptr->num_shots = num_shots;
  phaseenc_plan_ptr->entries = (KS_PHASEENCODING_COORD *) ptr;

  for (i = 0; i < etl * num_shots; i++) {
    phaseenc_plan_ptr->entries[i].ky = KS_NOTSET;
    phaseenc_plan_ptr->entries[i].kz = KS_NOTSET;
  }

  return SUCCESS;
}

ks_phaseencoding_generate_simple()

STATUS ks_phaseencoding_generate_simple	(	KS_PHASEENCODING_PLAN *	phaseenc_plan_ptr,
		const char *const	desc,
		KS_PHASER *	phaser,
		KS_PHASER *	zphaser
	)

Generation of a KS_PHASEENCODING_PLAN for any sequence having only one echo (or same phasenc step for all echoes)

For sequences having only one echo (ETL=1) or having more echoes but where all echoes have the same ky/kz coordinate, there is no special logic necessary regarding which order to traverse the ky-kz plane over shots.

Parallel imaging in ky (and kz for 3D), with acs lines, is set up as usual using ks_eval_phaser() first before calling this function. For 2D, the phase encoding object (KS_PHASER) is then passed in as the 2nd arg to this function, with the 3rd arg being NULL. For 3D, both KS_PHASERs are passed in as 2nd and 3rd args, each with their own acceleration and resolution. For both 2D and 3D, the KS_PHASEENCODING_PLAN will be set up based on the KS_PHASER(s), but for 2D all entries.kz in the KS_PHASEENCODING_PLAN will be KS_NOTSET (-1)

Parameters

[out]	phaseenc_plan_ptr	Pointer to KS_PHASEENCODING_PLAN
[in]	desc	A description (text string) of the KS_PHASEENCODING_PLAN object. This description is used in the psd plot.
[in]	phaser	Pointer to the KS_PHASER object for the first (3D) / only (2D) phase encoding direction
[in]	zphaser	Pointer to the KS_PHASER object for the second phase encoding direction (NULL for 2D)

Returns

void

                                                                                                                                                  {
  int etl = 1;
  int num_shots;
  int shot, ky, kz;
  STATUS status;

  strncpy(phaseenc_plan_ptr->description, desc, KS_DESCRIPTION_LENGTH - 1);
  phaseenc_plan_ptr->description[KS_DESCRIPTION_LENGTH - 1] = 0;

  /* don't allow empty description or a description with leading space */
  if (phaseenc_plan_ptr->description == NULL || phaseenc_plan_ptr->description[0] == ' ') {
    return ks_error("%s: description of phase encoding plan (2nd arg) cannot be NULL or leading space", __FUNCTION__);
  }

  num_shots = (zphaser != NULL) ? (phaser->numlinestoacq * zphaser->numlinestoacq) : phaser->numlinestoacq;

  status = ks_phaseencoding_resize(phaseenc_plan_ptr, etl, num_shots);
  if (status != SUCCESS) return status;

  shot = 0;
  if (zphaser != NULL) { /* 3D */
    for (kz = 0; kz < zphaser->numlinestoacq; kz++) {
      for (ky = 0; ky < phaser->numlinestoacq; ky++) {
        ks_phaseencoding_set(phaseenc_plan_ptr, 0, shot++, phaser->linetoacq[ky], zphaser->linetoacq[kz]);
      }
    }
    phaseenc_plan_ptr->zphaser = zphaser;
  } else { /* 2D */
    for (ky = 0; ky < phaser->numlinestoacq; ky++) {
      ks_phaseencoding_set(phaseenc_plan_ptr, 0, shot++, phaser->linetoacq[ky], KS_NOTSET);
    }
    phaseenc_plan_ptr->zphaser = NULL;
  }

  phaseenc_plan_ptr->phaser = phaser;

  return SUCCESS;
}

ks_phaseencoding_generate_simple_ellipse()

STATUS ks_phaseencoding_generate_simple_ellipse	(	KS_PHASEENCODING_PLAN *	phaseenc_plan_ptr,
		const char *const	desc,
		KS_PHASER *	phaser,
		KS_PHASER *	zphaser
	)

Generation of a KS_PHASEENCODING_PLAN for any sequence having only one echo (or same phasenc step for all echoes) - ellipse version

For sequences having only one echo (ETL=1) or having more echoes but where all echoes have the same ky/kz coordinate, there is no special logic necessary regarding which order to traverse the ky-kz plane over shots.

Parallel imaging in ky (and kz for 3D), with acs lines, is set up as usual using ks_eval_phaser() first before calling this function. For 2D, the phase encoding object (KS_PHASER) is then passed in as the 2nd arg to this function, with the 3rd arg being NULL. For 3D, both KS_PHASERs are passed in as 2nd and 3rd args, each with their own acceleration and resolution. For both 2D and 3D, the KS_PHASEENCODING_PLAN will be set up based on the KS_PHASER(s), but for 2D all entries.kz in the KS_PHASEENCODING_PLAN will be KS_NOTSET (-1). This function will create an elliptical k-space in ky/kz. For rectangular k-space, use ks_phaseencoding_generate_simple.

Parameters

[out]	phaseenc_plan_ptr	Pointer to KS_PHASEENCODING_PLAN
[in]	desc	A description (text string) of the KS_PHASEENCODING_PLAN object. This description is used in the psd plot.
[in]	phaser	Pointer to the KS_PHASER object for the first (3D) / only (2D) phase encoding direction
[in]	zphaser	Pointer to the KS_PHASER object for the second phase encoding direction (NULL for 2D)

Returns

void

                                                                                                                                                          {
  int etl = 1;
  int ky, kz, i;
  float radius_ky, radius_kz, center_ky, center_kz;
  float x1, x2;
  STATUS status;
  int inellipse; /* Number of ky,kz points in the ellipse */

  strncpy(phaseenc_plan_ptr->description, desc, KS_DESCRIPTION_LENGTH - 1);
  phaseenc_plan_ptr->description[KS_DESCRIPTION_LENGTH - 1] = 0;

  /* don't allow empty description or a description with leading space */
  if (phaseenc_plan_ptr->description == NULL || phaseenc_plan_ptr->description[0] == ' ') {
    return ks_error("%s: description of phase encoding plan (2nd arg) cannot be NULL or leading space", __FUNCTION__);
  }

  if (zphaser == NULL) { /* We can't do ellipse k-space coverage (ky,kz) in 2D */
    return ks_phaseencoding_generate_simple(phaseenc_plan_ptr, desc, phaser, NULL);
  }


  phaseenc_plan_ptr->phaser = phaser;
  radius_ky = phaser->res/2.0;
  center_ky = phaser->res/2.0 - 0.5;

  phaseenc_plan_ptr->zphaser = zphaser;
  radius_kz = zphaser->res/2.0;
  center_kz = zphaser->res/2.0 - 0.5;

  for (i = 0; i < 2; i++) { /* i = 0: check how many. i = 1: set up coords */

    if (i == 1) {
      status = ks_phaseencoding_resize(phaseenc_plan_ptr, etl, inellipse);
      if (status != SUCCESS) return status;
    }
    inellipse = 0;

    for (kz = 0; kz < zphaser->numlinestoacq; kz++) {
      for (ky = 0; ky < phaser->numlinestoacq; ky++) {
          x1 = (phaser->linetoacq[ky]  - center_ky) / (float) radius_ky;
          x2 = (zphaser->linetoacq[kz] - center_kz) / (float) radius_kz;
          if ((x1 * x1 + x2 * x2) <= 1.0) {
            if (i == 1) {
              ks_phaseencoding_set(phaseenc_plan_ptr, 0, inellipse, phaser->linetoacq[ky], zphaser->linetoacq[kz]);
            }
            inellipse++;
          }
      } /* ky */
    } /* kz */

  } /* i */

  return SUCCESS;
}

ks_fse_calcecho()

STATUS ks_fse_calcecho	(	double *	bestecho,
		double *	optecho,
		int *	nacqlines_to_kspacecenter,
		KS_PHASER *	pe,
		ks_enum_pf_earlylate_te	pf_direction,
		int	TE,
		int	etl,
		int	esp
	)

Calculates the ETL index corresponding the desired TE given a KS_PHASER object and echo spacing

Given the KS_PHASER object used in the FSE train (containing res and partial ky Fourier info), the desired effective echo time (TE [us]), the echo train length (etl) and the echo spacing between consecutive echoes (esp [us]), this function calculates two echo indices:

• bestecho: is the 0-based index corresponding to the echo in the FSE train that should be placed in the center of k-space, i.e. the echo that most closely matches the desired TE. If bestecho is an integer value (although it is in double format), the data acquired for this echo should straddle the k-space center. bestecho can also be an interger + 0.5, indicating that there are two echo indices that should be placed around the k-space center. For example, floor(bestecho) corresponds to the echo index that should be placed just below the k-space center and ceil(bestecho) corresponds to the echo index that should be placed just above the k-space center. I.e. when bestecho = *.5, no single echo index will straddle the k-space center, and the k-space line located at ky position +0.5 will come from data acquired from echo #[floor(bestecho)] and ky position -0.5 correspondingly from echo #[ceil(bestecho)].
• optecho: is the 0-based index corresponding to an ideal TE choice that would allow the data from the echoes in the FSE train to be placed out linearly each time. Doing so will reduce ghosting and T2 blurring. Hence, optecho ignores the input TE value here, but the calling function can use this information to determine k-space acquisition order, but also to suggest a TE (optecho * esp) that would result in optimal image quality for the chosen ETL.

Parameters

[out]	bestecho	Pointer to the echo number in the train that should be placed at the center of k-space given the current ETL and ESP
[out]	optecho	Pointer to the optimal echo number in the train that would allow k-space to be sampled linearly (to reduce T2-blurring and ghosting)
[out]	nacqlines_to_kspacecenter	Pointer to a an integer with the number of k-space lines until center
[in]	pe	Pointer to a KS_PHASER
[in]	pf_direction	Should be either KS_PF_EARLY_TE or KS_PF_LATE_TE (applies to partial Fourier in ky to set if k-space center should be acquired early or late in the EPI train. Has no effect for full ky Fourier)
[in]	TE	(Echo Time in [us])
[in]	etl	(EchoTrain Length)
[in]	esp	(Echo Spacing in [us])

Return values

STATUS

SUCCESS or FAILURE

                                                                                                                                                                             {
  int numshots, i;
  int nacqlines_fullside, nacqlines_pfside;
  double numshots_double;

  if (etl < 1) {
    return ks_error("%s: ETL (arg 5) must be at least 1", __FUNCTION__);
  }
  if (pe->numlinestoacq < 1) {
    return ks_error("%s: field '.numlinestoacq' in 3rd arg must be at least 1", __FUNCTION__);
  }
  if (etl > pe->numlinestoacq) {
    return ks_error("%s: ETL (arg 5) cannot exceed number of lines to acquire", __FUNCTION__);
  }
  if (esp <= 0) {
    return ks_error("%s: ESP (arg 6) must be larger than 1", __FUNCTION__);
  }
  if (pe->nover < 0) {
    return ks_error("%s: Only top half of k-space supported for pFourier", __FUNCTION__);
  }

  /* Number of shots */
  numshots = CEIL_DIV(pe->numlinestoacq, etl);
  numshots_double = (double) pe->numlinestoacq / (double) etl;

  /* index 'i' will stop incrementing as we pass the center of k-space (i=0 is top row of k-space). 
     Note that 'i' will be much less that res/2 (after break) even for full Fourier when
     we have R > 1 and acslines */
  for (i = 0; i < pe->numlinestoacq - 1; i++) {
    if (((pe->res - 1) / 2.0 - pe->linetoacq[i]) < 0)
      break;
  }
  
  nacqlines_fullside = i;
  nacqlines_pfside = pe->numlinestoacq - i; /* which is equal or almost equal to nacqlines_fullside for full Fourier */

  if (pf_direction == KS_PF_EARLY_TE) {
    *nacqlines_to_kspacecenter = nacqlines_pfside;
  } else {
    *nacqlines_to_kspacecenter = nacqlines_fullside;
  }


  if (etl % 2) {
    /* etl is odd. The optimal echo will straddle around the center of k-space */

    if (optecho != NULL)
      *optecho = ceil((((double) *nacqlines_to_kspacecenter + numshots_double / 2.0) / numshots_double) - 1e-5); /* integer value since ETL is odd */

    if (bestecho != NULL) {
      *bestecho = floor((double) TE / (double) esp + 0.5); /* integer */
      if (*bestecho < 1)
        *bestecho = 1;
      if (*bestecho > etl)
        *bestecho = etl;
    }

  } else {
    /* etl is even. The optimal two echoes will be placed above and below k-space center, respectively */

    if (optecho != NULL)
      *optecho = ceil((double) *nacqlines_to_kspacecenter / numshots_double) + 0.5; /* half-integer value since ETL is even */

    if (bestecho != NULL) {
      if (etl == 2) {
        /* special case for ETL = 2 */
        if (TE < 1.25 * esp)
          *bestecho = 1; /* 1st echo straddling around k-space center */
        else if (TE < 1.75 * esp)
          *bestecho = 1.5; /* 1st/end echo below/above k-space center */
        else
          *bestecho = 2; /* 2nd echo straddling around k-space center */
      } else {
        *bestecho = floor((double) TE / (double) esp) + 0.5; /* half-integer */
        if (*bestecho <= 1.5)
          *bestecho = 1; /* minTE, back to integer 'bestecho' for center-out encoding */
        if (*bestecho >= (etl - 0.5))
          *bestecho = etl; /* max TE, back to integer 'bestecho' for out-center encoding */
      }
    }

  }

  if (optecho != NULL) {
    /* Partial Fourier MinTE case, regardless if ETL is even or odd */
    if ((pe->nover > 0) && (*nacqlines_to_kspacecenter <= numshots / 2))
      *optecho = 1;

    /* Partial Fourier MaxTE case, regardless if ETL is even or odd */
    if ((pe->nover < 0) && (*nacqlines_to_kspacecenter >= (pe->linetoacq[i] - numshots / 2)))
      *optecho = etl;
  }

  return SUCCESS;

} /* ks_fse_calcecho() */

ks_phaseencoding_generate_2Dfse()

STATUS ks_phaseencoding_generate_2Dfse	(	KS_PHASEENCODING_PLAN *	phaseenc_plan_ptr,
		const char *const	desc,
		KS_PHASER *	phaser,
		KS_PHASER *	zphaser,
		ks_enum_pf_earlylate_te	pf_direction,
		int	TE,
		int	etl,
		int	esp
	)

2DFSE: Makes a KS_PHASEENCODING_PLAN depending on etl, desired TE, and echo spacing (esp)

This function is only executed on TGT and will return early when called on HOST.

The phase encoding sorting is depending on many factors. First, the desired TE will dictate which one (or two) of the echoes in the FSE train (of length etl) that should be placed in the center. This is determined based on the properties of the KS_PHASER object (phase encoding gradients in the FSE train), TE and esp by calling ksfse_calc_echo().

Second, the sorting of the echoes will first of all depend on whether bestecho is equal to optecho. If it is, then the etl echoes can be placed out linearly in k-space (from the bottom->top of k-space, or vice versa). This will produce the best image quality with minimal T2-blurring and FSE ghosting.

As partial ky Fourier is allowed, this function first checks on which side (top or bottom half) of k-space that has more room for the echo indices that are either before or after the bestecho index corresponding to the desired TE. The goal with this is to try to sweep k-space as linearly as possible in as much of the center portion of k-space as possible when bestecho != optecho.

When bestecho != optecho, there will be data from either the first or last echo indices that won't fit in k-space if placed next to a neighboring index. If this data would be placed on the other size of k-space (that still needs lines to be filled in), where e.g. echo index #0 would be placed next to echo index #(etl-1), strong ghosting will occur due to the much strong signal from echo #0 compared to #(etl-1). With an echo train length of etl, k-space is filled in numshots = ceil(numlinestoacq / etl. Using half of the numshots lines for each echo index a linear sweep of the center half of k-space can is layed out. To avoid FSE ghosting, the numshots/2 remaining lines for each early or late echo index are placed such as neighboring ky lines will never have a change in echo index by more than one. For example if etl = 8, esp = 10 ms and TE = 25, then bestecho = 1.5 and optecho = 4.5. We avoid to sort the echoes in the following k-space order for ghosting reasons: 7-6-0-1*2-3-4-5 (* = k-space center) since there will be a strong discontinuity between 6 and 0. Instead we use groups of numshots/2 per echo index (and get two groups per echo index in k-space): 5-4-3-2-1-0-0-1*2-3-4-5-6-7-6-5

Parameters

[out]	phaseenc_plan_ptr	Pointer to KS_PHASEENCODING_PLAN
[in]	desc	A description (text string) of the KS_PHASEENCODING_PLAN object. This description is used in the psd plot.
[in]	phaser	Pointer to a KS_PHASER
[in]	zphaser	Pointer to a KS_PHASER (3D) or NULL (2D)
[in]	pf_direction	Should be either KS_PF_EARLY_TE or KS_PF_LATE_TE (applies to partial Fourier in ky to set if k-space center should be acquired early or late in the EPI train. Has no effect for full ky Fourier)
[in]	TE	(Echo Time in [us])
[in]	etl	(EchoTrain Length)
[in]	esp	(Echo Spacing in [us])

Return values

STATUS

SUCCESS or FAILURE

Grouping shots for each of the ETL echoes in k-space: We don't place all shots for each echo together in k-space since we need to make a z-shaped pattern to avoid ghosting. Instead we let half of the shots be one group (of size 'cgroupsize') that we place in the central ~50% of k-space, which allows us to get a linear sweep in this central half of k-space using all 'etl' echoes, regardless of the chosen effective TE. The actual center-ness depends on TE, and the remaining of k-space is filled using the echoes belonging to the latter 'numshots-cgroupsize' number of shots. At the edges of k-space, numshots*etl seldom match up to the chosen opyres, but numshots*etl is always >= opyres thanks to the CEIL_DIV at the beginning of this function. The surplus echoes we don't need are numshots*etl - opyres (for full Fourier and no ARC), and as they are already tagged as -1 = KS_NOTSET in the beginning of this function, they will be placed in baseline view (0) in the ksfse_scan_acqloop()

                                                                                                                                                                                                                 {
  int i, j, ky, kz;
  int numshots, numkz;
  double bestecho, optecho;
  int nacqlines_to_kspacecenter;
  int cgroupsize, halfgroupsize;
  int cstart, cshift;
  STATUS status;

  strncpy(phaseenc_plan_ptr->description, desc, KS_DESCRIPTION_LENGTH - 1);
  phaseenc_plan_ptr->description[KS_DESCRIPTION_LENGTH - 1] = 0;

  /* don't allow empty description or a description with leading space */
  if (phaseenc_plan_ptr->description == NULL || phaseenc_plan_ptr->description[0] == ' ') {
    return ks_error("%s: description of phase encoding plan (2nd arg) cannot be NULL or leading space", __FUNCTION__);
  } 

  if (etl < 1) {
    return SUCCESS; /* we haven't set it up yet */
  }
  if (phaser->numlinestoacq < 2) {
    return ks_error("%s: field '.numlinestoacq' in 2nd arg must be at least 2", __FUNCTION__);
  }
  if (etl > phaser->numlinestoacq) {
    return ks_error("%s: ETL cannot exceed number of lines to acquire", __FUNCTION__);
  }
  if (phaser->nover < 0) {
    return ks_error("%s: Only top half of k-space supported for pFourier", __FUNCTION__);
  }

  phaseenc_plan_ptr->phaser = phaser;
  phaseenc_plan_ptr->zphaser = zphaser;

  /* Number of shots (2D) */
  numshots = CEIL_DIV(phaser->numlinestoacq, etl);

  /* Number of kz */
  numkz = (zphaser != NULL) ? zphaser->numlinestoacq : 1;

  /* allocate KS_PHASEENCODING_PLAN table (all entries will be initialized to KS_NOTSET) */
  status = ks_phaseencoding_resize(phaseenc_plan_ptr, etl, numshots * numkz);
  if (status != SUCCESS) return status;


  for (kz = 0; kz < numkz; kz++) {

    if (etl == 1) {

      /* Special case for ETL = 1. Just acquire the data in order */
      for (ky = 0; ky < phaser->numlinestoacq; ky++) {
        ks_phaseencoding_set(phaseenc_plan_ptr,
                             0, ky + kz * phaser->numlinestoacq,
                             phaser->linetoacq[ky], (zphaser != NULL) ? zphaser->linetoacq[kz] : KS_NOTSET);
      }

    } else {

      /* ETL > 1 (this is a long else-statement) */

      /* get the best echo number for the given TE/ETL/ESP, and also the optimal echo number that would allow for a linear k-space sweep */
      status = ks_fse_calcecho(&bestecho, &optecho, &nacqlines_to_kspacecenter, phaser, pf_direction, TE, etl, esp);
      if (status != SUCCESS) return status;


      if (areSame(bestecho, optecho)) {
        /* we can place the echoes linearly in k-space in groups of 'numshots' per echo given the current combination of TE, ETL and ESP */
        cgroupsize = numshots;
        halfgroupsize = (int) floor((float) phaser->numlinestoacq / (etl * 2.0) + 0.5);
      } else {
        cgroupsize = (int) ceil((float) phaser->numlinestoacq / (etl * 2.0)); /* ~numshots/2 lines per etl in the central 50% of k-space */
        halfgroupsize = (int) floor((float) phaser->numlinestoacq / (etl * 4.0) + 0.5);
      }

      /* if bestecho == optecho: Place out all echoes
         if bestecho != optecho: Place out the center half of lines */
      if (areSame(bestecho,1)) /* minTE */
        cshift = cgroupsize;
      else if (areSame(bestecho, etl)) /* maxTE */
        cshift = 0;
      else
        cshift = halfgroupsize; /* non-extreme TE */
      cstart = (int)((nacqlines_to_kspacecenter + cshift) - cgroupsize * bestecho);
      if (pf_direction == KS_PF_EARLY_TE)
        cstart = (phaser->numlinestoacq - 1) - cstart;
      ky = cstart;
      for (i = 0; i < etl; i++) {
        for (j = 0; j < cgroupsize; j++) {
          if (ky >= 0 && ky < phaser->numlinestoacq) {
            ks_phaseencoding_set(phaseenc_plan_ptr, i, j + kz * numshots, phaser->linetoacq[ky], (zphaser != NULL) ? zphaser->linetoacq[kz] : KS_NOTSET);
          }
          if (pf_direction == KS_PF_EARLY_TE)
            ky--;
          else
            ky++;
        }
      }

      if (!areSame(bestecho, optecho)) {
        /* remaining 'numshots-cgroupsize' number of shots for late echoes */
        i = etl - 1;
        while (i >= 0) {
          for (j = cgroupsize; j < numshots; j++) {
            if (ky >= 0 && ky < phaser->numlinestoacq) {
              ks_phaseencoding_set(phaseenc_plan_ptr, i, j + kz * numshots, phaser->linetoacq[ky], (zphaser != NULL) ? zphaser->linetoacq[kz] : KS_NOTSET);
            }
            if (pf_direction == KS_PF_EARLY_TE)
              ky--;
            else
              ky++;
          } /* for j */
          i--;
        }

        /* remaining 'numshots-cgroupsize' number of shots for early echoes */
        if (pf_direction == KS_PF_EARLY_TE)
          ky = cstart + 1;
        else
          ky = cstart - 1;
        i = 0;
        while (i < etl) {
          for (j = cgroupsize; j < numshots; j++) {
            if (ky >= 0 && ky < phaser->numlinestoacq) {
              ks_phaseencoding_set(phaseenc_plan_ptr, i, j + kz * numshots, phaser->linetoacq[ky], (zphaser != NULL) ? zphaser->linetoacq[kz] : KS_NOTSET);
            }
            if (pf_direction == KS_PF_EARLY_TE)
              ky++;
            else
              ky--;
          } /* for j */
          i++;
        }
      } /* bestecho != optecho */

    } /* etl > 1 */

  } /* numkz */


  return SUCCESS;


} /* ks_phaseencoding_generate_2Dfse() */

ks_phaseencoding_generate_epi()

STATUS ks_phaseencoding_generate_epi	(	KS_PHASEENCODING_PLAN *	phaseenc_plan_ptr,
		const char *const	desc,
		const KS_EPI *	epitrain,
		const ks_enum_epiblipsign	blipsign,
		const ks_enum_pf_earlylate_te	pf_direction,
		const int	numileavestoacq,
		ks_enum_sweep_order	sweep_order,
		int	numsegments,
		const int	caipi_delta
	)

EPI: Makes a KS_PHASEENCODING_PLAN suitable for 2D or 3D epi

The etl is the number of readouts in the EPI train, derived from the phaser. The number of ky shots is also given by the phaser, while the number of kz shots is given by zphaser. Any partial fourier is handled by the phasers, and acceleration and acs lines in the z direction is handled by zphaser. For 3D EPI, the number of shots in the phase encoding plan will be the product of the number of shots in the ky direction and the number of kz lines to acquire.

Each shot will be played out in a single kz plane. The shot order will be linear in ky and kz. The ky shots will be in the inner loop, unless kzshotsfirst is TRUE.

Parameters

[out]	phaseenc_plan_ptr	Pointer to the phase encoding plan
[in]	desc	A description (text string) of the KS_PHASEENCODING_PLAN object. This description is used in the psd plot.
[in]	epitrain	Pointer to a KS_EPI
[in]	blipsign	Should be either KS_EPI_POSBLIPS or KS_EPI_NEGBLIPS. Determines distortion direction.
[in]	pf_direction	Should be either KS_PF_EARLY_TE or KS_PF_LATE_TE (applies to partial Fourier in ky to set if k-space center should be acquired early or late in the EPI train. Has no effect for full ky Fourier)
[in]	numileavestoacq	Number of ky interleaves to play. Must be within 1-numInterleaves and an integer factor of numInterleaves. Set =1 for single-shot EPI. Set to phaser.R for full multi-shot EPI.
[in]	sweep_order	Sweep order for shots as defined in KSFoundation.h (ks_enum_sweep_order). Has no effect on distortions.
[in]	numsegments	Number of kz encodes to play
[in]	caipi_delta	Use CAIPIRINHA sampling pattern (affects 3D epi only)

Return values

STATUS

SUCCESS or FAILURE

                                                                                                                                                                                                                                                                                                                      {

  int numileaves = epitrain->blipphaser.R;

  if (epitrain->blipphaser.numlinestoacq < 2 && (numileaves != epitrain->blipphaser.res)) {
    return ks_error("%s: field '.numlinestoacq' of epitrain->blipphaser must be at least 2, not %d", __FUNCTION__, epitrain->blipphaser.numlinestoacq);
  }

  strncpy(phaseenc_plan_ptr->description, desc, KS_DESCRIPTION_LENGTH - 1);
  phaseenc_plan_ptr->description[KS_DESCRIPTION_LENGTH - 1] = 0;

  /* don't allow empty description or a description with leading space */
  if (phaseenc_plan_ptr->description == NULL || phaseenc_plan_ptr->description[0] == ' ') {
    return ks_error("%s: description of phase encoding plan (2nd arg) cannot be NULL or leading space", __FUNCTION__);
  }

  int readout, shot, interleaf, kyview, kzview, kzind;
  int etl, numfullsegments, numshotsforsegment, totalnumshots, i;
  int shift;
  STATUS status;

  /* Number of shots (2D) */
  if (numileavestoacq < 1 || numileavestoacq > numileaves || (numileaves % numileavestoacq != 0)) {
    return ks_error("%s: numileavestoacq (=%d) must be in range 1-blipphaser.R and an integer factor of blipphaser.R (=%d)", __FUNCTION__, numileavestoacq, numileaves);
  }

  /* Number of segments (3D) */
  if (epitrain->zphaser.res != KS_NOTSET && (numsegments < 1 || numsegments > epitrain->zphaser.numlinestoacq)) {
    return ks_error("%s: numsegments (=%d) must be in range 1-zphaser.numlinestoacq (=%d)", __FUNCTION__, numsegments, epitrain->zphaser.numlinestoacq);
  }

  /* Number of readouts per EPI train (etl) */
  etl = epitrain->blipphaser.numlinestoacq;

  /* Check number of kz segments and how many should be fully sampled (controlled by zphaser.nacslines) */
  if (epitrain->zphaser.res == KS_NOTSET) { /* 2D epi */
    numsegments = 1;
    numfullsegments = (numileavestoacq == numileaves);
  } else { /* 3D epi */
    if (epitrain->zphaser.R == 1) {
      numfullsegments = epitrain->zphaser.nacslines; /* special interpretation for zR=1 */
    } else { /* zR > 1 */
      if (epitrain->zphaser.nacslines > 0) {
        numfullsegments = 1; /* initialize */
        for (kzind = 1; kzind < numsegments; kzind++) {
          if (abs(epitrain->zphaser.linetoacq[kzind]-epitrain->zphaser.linetoacq[kzind-1])==1) {
            numfullsegments++;
          }
        }
      } else { /* no kz "acs lines" */
        numfullsegments = 0;
      }
    }
  }

  /* allocate KS_PHASEENCODING_PLAN table (all entries will be initialized to KS_NOTSET) */
  totalnumshots = numfullsegments * numileaves + (numsegments-numfullsegments) * numileavestoacq;
  status = ks_phaseencoding_resize(phaseenc_plan_ptr, etl, totalnumshots);

  phaseenc_plan_ptr->phaser = &epitrain->blipphaser;
  phaseenc_plan_ptr->zphaser = &epitrain->zphaser;

  if (status != SUCCESS) return status;

  shot = 0; /* initialize */
  int ileaves[numileaves]; /* interleaf indices */

  for (kzind = 0; kzind < numsegments; kzind++) {
    kzview = (epitrain->zphaser.numlinestoacq > 0) ? epitrain->zphaser.linetoacq[kzind] : KS_NOTSET;
    
    if (kzview != KS_NOTSET && abs(kzview*2 - (epitrain->zphaser.res-1)) <= numfullsegments) {
      numshotsforsegment = numileaves;
    } else {
      numshotsforsegment = numileavestoacq;
    }
    
    if (sweep_order == KS_SWEEP_ORDER_TOP_DOWN) {
      for (i = 0; i < numshotsforsegment; i++) {
        ileaves[i] = i;
      }
    } else if (sweep_order == KS_SWEEP_ORDER_BOTTOM_UP) {
      for (i = 0; i < numshotsforsegment; i++) {
        ileaves[numshotsforsegment - i - 1] = i;
      }
    } else if (sweep_order == KS_SWEEP_ORDER_OUTSIDE_IN) {
      for (i = 0; i < numshotsforsegment; i++) {
        ileaves[i] = (i % 2) ? numshotsforsegment - 1 - i/2 : i/2;
      }
    } else if (sweep_order == KS_SWEEP_ORDER_CENTER_OUT) {
      for (i = 0; i < numshotsforsegment; i++) {
        ileaves[numshotsforsegment - i - 1] = (i % 2) ? numshotsforsegment - 1 - i/2 : i/2;
      }
    }
    for (i = 0; i < numshotsforsegment; i++) {
      interleaf = ileaves[i];
      for (readout = 0; readout < etl; readout++) {
        shift = interleaf * (numileaves / numshotsforsegment); /* interleaf shift */
        shift = (shift + (kzview/epitrain->zphaser.R) * caipi_delta) % numileaves; /* CAIPIRINHA shift */
        if ((epitrain->blipphaser.nover != 0) && (((pf_direction == KS_PF_LATE_TE) && (blipsign == KS_EPI_POSBLIPS)) || ((pf_direction == KS_PF_EARLY_TE) && (blipsign == KS_EPI_NEGBLIPS))) ) {
          /* shift kspace area to lower half */
          shift += epitrain->blipphaser.res - (epitrain->blipphaser.res/2 + epitrain->blipphaser.nover);
        }
        if (blipsign == KS_EPI_NEGBLIPS) {
          kyview = epitrain->blipphaser.linetoacq[readout] + shift; /* admittedly, .linetoacq[] has lost its role a bit for EPI with all shifting we do */
        } else if (blipsign == KS_EPI_POSBLIPS) {
          kyview = epitrain->blipphaser.linetoacq[(etl - 1) - readout] + shift; /* admittedly, .linetoacq[] has lost its role a bit for EPI with all shifting we do */
        } else if (blipsign == KS_EPI_NOBLIPS) {
          kyview = KS_NOTSET;
          kzview = KS_NOTSET;
        } else {
          return ks_error("%s: blipsign must be KS_EPI_POSBLIPS or KS_EPI_NEGBLIPS, not %d", __FUNCTION__, blipsign);
        }
        ks_phaseencoding_set(phaseenc_plan_ptr, readout, shot, kyview, kzview);
      } /* readout */
      shot++;
    } /* interleaf */
  } /* kzind */

  return SUCCESS;

} /* ks_phaseencoding_generate_epi() */

ks_phaseencoding_generate_allepiplans()

STATUS ks_phaseencoding_generate_allepiplans	(	KS_PHASEENCODING_ALLEPIPLANS	phaseenc_plans,
		const char *const	desc,
		const KS_EPI *	epitrain,
		const int	caipi_delta
	)

EPI: Makes all 8 KS_PHASEENCODING_PLANs possible for 2D or 3D epi

Parameters

[out]	phaseenc_plans	Pointer to the phase encoding plan array (KS_PHASEENCODING_ALLEPIPLANS containing KS_EPI_PEPLAN_NUMPLANS elements)
[in]	desc	A description (text string) of the KS_PHASEENCODING_PLAN object. This description is used in the psd plot.
[in]	epitrain	Pointer to a KS_EPI
[in]	caipi_delta	Use CAIPIRINHA sampling pattern (affects 3D epi only)

Return values

STATUS

SUCCESS or FAILURE

                                                                                                                                                                  {
  ks_enum_epiblipsign kspace_direction;
  ks_enum_pf_earlylate_te pf_direction;
  int numileavestoacq, p;
  KS_DESCRIPTION tmpdesc;
  STATUS status;
  int is3Dscan = epitrain->zphaser.res > 1;
  int numileaves = epitrain->blipphaser.R;

  for (p = 0; p < KS_EPI_PEPLAN_NUMPLANS; p++) {

    switch (p) {
    case KS_EPI_PEPLAN_EARLYTE_BOTTOMUP_MULTISHOT:
      pf_direction = KS_PF_EARLY_TE;
      kspace_direction = KS_EPI_POSBLIPS;
      numileavestoacq = (is3Dscan) ? (numileaves / epitrain->R_3d) : numileaves;
      sprintf(tmpdesc, "%s:mShot/EarlyTE/blip+", desc);
      break;
    case KS_EPI_PEPLAN_EARLYTE_BOTTOMUP_UNDERSAMPLED:
      pf_direction = KS_PF_EARLY_TE;
      kspace_direction = KS_EPI_POSBLIPS;
      numileavestoacq = 1;
      sprintf(tmpdesc, "%s:Undersampled/EarlyTE/blip+", desc);
      break;
    case KS_EPI_PEPLAN_EARLYTE_TOPDOWN_MULTISHOT:
      pf_direction = KS_PF_EARLY_TE;
      kspace_direction = KS_EPI_NEGBLIPS;
      numileavestoacq = (is3Dscan) ? (numileaves / epitrain->R_3d) : numileaves;
      sprintf(tmpdesc, "%s:mShot/EarlyTE/blip-", desc);
      break;
    case KS_EPI_PEPLAN_EARLYTE_TOPDOWN_UNDERSAMPLED:
      pf_direction = KS_PF_EARLY_TE;
      kspace_direction = KS_EPI_NEGBLIPS;
      numileavestoacq = 1;
      sprintf(tmpdesc, "%s:Undersampled/EarlyTE/blip-", desc);
      break;
    case KS_EPI_PEPLAN_LATETE_BOTTOMUP_MULTISHOT:
      pf_direction = KS_PF_LATE_TE;
      kspace_direction = KS_EPI_POSBLIPS;
      numileavestoacq = (is3Dscan) ? (numileaves / epitrain->R_3d) : numileaves;
      sprintf(tmpdesc, "%s:mShot/LateTE/blip+", desc);
      break;
    case KS_EPI_PEPLAN_LATETE_BOTTOMUP_UNDERSAMPLED:
      pf_direction = KS_PF_LATE_TE;
      kspace_direction = KS_EPI_POSBLIPS;
      numileavestoacq = 1;
      sprintf(tmpdesc, "%s:Undersampled/LateTE/blip+", desc);
      break;
    case KS_EPI_PEPLAN_LATETE_TOPDOWN_MULTISHOT:
      pf_direction = KS_PF_LATE_TE;
      kspace_direction = KS_EPI_NEGBLIPS;
      numileavestoacq = (is3Dscan) ? (numileaves / epitrain->R_3d) : numileaves;
      sprintf(tmpdesc, "%s:mShot/LateTE/blip-", desc);
      break;
    case KS_EPI_PEPLAN_LATETE_TOPDOWN_UNDERSAMPLED:
      pf_direction = KS_PF_LATE_TE;
      kspace_direction = KS_EPI_NEGBLIPS;
      numileavestoacq = 1;
      sprintf(tmpdesc, "%s:Undersampled/LateTE/blip-", desc);
      break;   
    default:
      return ks_error("%s:Error, we should not have arrived here", __FUNCTION__);
      break;
    }

    status = ks_phaseencoding_generate_epi(&phaseenc_plans[p], tmpdesc,
                                    epitrain, 
                                    kspace_direction, 
                                    pf_direction,
                                    numileavestoacq,
                                    KS_SWEEP_ORDER_TOP_DOWN,
                                    epitrain->zphaser.numlinestoacq, 
                                    caipi_delta);
    if (status != SUCCESS) return status;

  }

  return SUCCESS;

} /* ks_phaseencoding_generate_allepiplans() */

ks_phaseencoding_allepiplans_setechoes()

STATUS ks_phaseencoding_allepiplans_setechoes	(	KS_PHASEENCODING_PLAN_16PTRS	peplan_echoes,
		KS_PHASEENCODING_ALLEPIPLANS	allepiplans,
		int	nechoes,
		int	multishot_flag,
		int	min1stTE,
		int	mirrorTE,
		ks_enum_epiblipsign	blipsign
	)

EPI: Makes a pointer to an entry in KS_PHASEENCODING_ALLEPIPLANS for each echo and store it in an array for scan loop usage

Parameters

[out]	peplan_echoes	Pointers to the phase encoding plan array to use for each EPI train in the sequence (max 16 EPI trains per sequence playout)
[in]	allepiplans	All possible EPI plans for current EPI train (with given read.res and blipphaser.res/.nover)
[in]	nechoes	Number of EPI train (echoes) in sequence (max 16)
[in]	multishot_flag	Multishot EPI or underampled EPI (both controlled by epitrain.blipphaser.R)
[in]	min1stTE	For partial ky Fourier (.blipphaser.nover > 0), should 1st EPI train pass k-space center early or late. Has no effect for full ky Fourier
[in]	mirrorTE	Should lateTE/earlyTE alternate between EPI trains (as when an RF refocusing pulse is placed in-between trains)
[in]	blipsign	Positive (KS_EPI_POSBLIPS) or negative (KS_EPI_NEGBLIPS) to control k-space direction and hence the geometric distortion direction

Return values

STATUS

SUCCESS or FAILURE

                                                                                                                                                                                                                               {
/*
  Assumes KSFoundation.h has the ks_enum_epiplans enum in the following ORDER:
  KS_EPI_PEPLAN_EARLYTE_BOTTOMUP_UNDERSAMPLED, // 0
  KS_EPI_PEPLAN_EARLYTE_BOTTOMUP_MULTISHOT, // 1
  KS_EPI_PEPLAN_EARLYTE_TOPDOWN_UNDERSAMPLED, // 2
  KS_EPI_PEPLAN_EARLYTE_TOPDOWN_MULTISHOT, // 3
  KS_EPI_PEPLAN_LATETE_BOTTOMUP_UNDERSAMPLED, // 4
  KS_EPI_PEPLAN_LATETE_BOTTOMUP_MULTISHOT, // 5
  KS_EPI_PEPLAN_LATETE_TOPDOWN_UNDERSAMPLED, // 6
  KS_EPI_PEPLAN_LATETE_TOPDOWN_MULTISHOT, // 7
  KS_EPI_PEPLAN_NUMPLANS // 8
*/

  int echo, whichplan;

  if (peplan_echoes == NULL) {
    return ks_error("%s: arg 1 (output) is NULL", __FUNCTION__);
  }
  if (allepiplans == NULL) {
    return ks_error("%s: arg 2 (input) is NULL", __FUNCTION__);
  }
  if (nechoes < 1 || nechoes > 16) {
    return ks_error("%s: nechoes (%d, arg 3) must be in range [1,16]", __FUNCTION__, nechoes);
  }
  if ( !(multishot_flag == 0 || multishot_flag == 1) ) {
    return ks_error("%s: multishot_flag (%d, arg 4) must be 0 or 1", __FUNCTION__, multishot_flag);
  }
  if ( !(min1stTE == 0 || min1stTE == 1) ) {
    return ks_error("%s: min1stTE (%d, arg 5) must be 0 or 1", __FUNCTION__, min1stTE);
  }
  if ( !(mirrorTE == 0 || mirrorTE == 1) ) {
    return ks_error("%s: mirrorTE (%d, arg 6) must be 0 or 1", __FUNCTION__, mirrorTE);
  }
  if ( !(blipsign == KS_EPI_POSBLIPS || blipsign == KS_EPI_NEGBLIPS || blipsign == KS_EPI_NOBLIPS) ) {
    return ks_error("%s: blipsign (%d, arg 7) must be -1, 0 or 1", __FUNCTION__, blipsign);
  }

  for (echo = 0; echo < 16; echo++) {
    peplan_echoes[echo] = NULL; /* reset all pointers in case #EPI trains has been reduced */
  }

  for (echo = 0; echo < nechoes; echo ++) {
    if (mirrorTE) { /* with 'mirrorTE', lateTE and earlyTE are alternating across echoes */
      whichplan = (min1stTE) ? ((echo % 2) * 4) : (((echo % 2) == 0) * 4); /* 0 or 4 */
    } else {
      whichplan = (min1stTE) ? 0 : 4;
    }
    whichplan += (blipsign == KS_EPI_NEGBLIPS) ? 2 : 0;
    whichplan += multishot_flag > 0;

    peplan_echoes[echo] = &allepiplans[whichplan];
  }

  return SUCCESS;

} /* ks_phaseencoding_allepiplans_setechoes() */

ks_calc_sliceplan()

STATUS ks_calc_sliceplan	(	KS_SLICE_PLAN *	slice_plan,
		int	nslices,
		int	slperpass
	)

Calculates the data acquisition order for a standard interleaved 2D scans using one or more passes

This function calls ks_calc_slice_acquisition_order_interleaved() with the last argument being 2, indicating an interleave factor of 2. This will make odd slices in each pass to be acquired first, followed by the even slices.

Parameters

[out]	slice_plan	The slice plan (KS_SLICE_PLAN) set up earlier using ks_calc_sliceplan() or similar
[in]	nslices	Total number of slices (usually opslquant)
[in]	slperpass	Number of slices per pass (i.e. per TR)

Return values

STATUS

SUCCESS or FAILURE

                                                                                {

  return ks_calc_sliceplan_interleaved(slice_plan, nslices, slperpass, 2);

}

ks_calc_sliceplan_interleaved()

STATUS ks_calc_sliceplan_interleaved	(	KS_SLICE_PLAN *	slice_plan,
		int	nslices,
		int	slperpass,
		int	inpass_interleaves
	)

Calculates the data acquisition order for custom interleaved 2D scans using one or more passes

The last argument to this function indicates the interleave factor of slices within each pass. If this value is

• 1: The slices will be acquired in spatial order (within each pass)
• 2: The odd slices will be acquired first, followed by the even slices in each pass (standard practice)
• 3: etc.

Parameters

[out]	slice_plan	Pointer to the slice plan (KS_SLICE_PLAN) set up earlier using ks_calc_sliceplan() or similar
[in]	nslices	Total number of slices (usually opslquant)
[in]	slperpass	Number of slices per pass (i.e. per TR)
[in]	inpass_interleaves	Interleave factor of slices in a pass

Return values

STATUS

SUCCESS or FAILURE

                                                                                                              {

  if (!slice_plan) {
    return ks_error("%s: invalid input, slice_plan is NULL", __FUNCTION__);
  }

  if (nslices <= 0 || slperpass <= 0 || ninterleaves <= 0) {
   return ks_error("%s: invalid input (nslices: %d, slperpass: %d, ninterleaves: %d)",
             __FUNCTION__, nslices, slperpass, ninterleaves);
  }

  slice_plan->nslices = nslices;
  slice_plan->npasses = CEIL_DIV(nslices, slperpass);
  slice_plan->nslices_per_pass = CEIL_DIV(nslices, slice_plan->npasses);

  int nslicesthispass[slice_plan->npasses];
  int sllocthispass[slice_plan->npasses][slperpass];
  int i, p, s, k, t, interleaf;
  /*
  - slice_plan->npasses: a.k.a. number of acquisitions (standard GE CV is: `acqs`)
  - slperpass: maximum number of slices in a pass (some passes may have fewer slices)
  - nslicesthispass[slice_plan->npasses]: Array where each element indicates how many slices to acquired in this pass
  - sllocthispass[slice_plan->npasses][slperpass]: Spatial location index into the prescribed slice stack, i.e. all slices
    for current pass and pass_sliceindx (spatially sorted)
  */

  if (slice_plan->npasses == slice_plan->nslices) {
    /* Sequential scanning, opirmode = 1 (i.e. fill k-space fully for each slice, then change slice). We don't want
       to acquire them sequentially in space though to avoid cross talk. Therefore, interleaves are made over the slice stack. */
    
    p = 0;
    for (interleaf = 0; interleaf < ninterleaves; interleaf++) {
      /* interleaf: slice interleaves over stack (typically odd/even) */
      for (i = 0; i < CEIL_DIV(slice_plan->nslices, ninterleaves); i++) {
        k = interleaf + i * ninterleaves;
        slice_plan->acq_order[p].slloc  = k; /* Spatial location index into the prescribed slice stack */
        slice_plan->acq_order[p].slpass = p; /* pass index */
        slice_plan->acq_order[p].sltime = 0; /* time index in current pass = 0 */
        p++;
      }
    }

  } else {
    /* Standard, interleaved scanning, opirmode = 0. Interleaves are made within passes. */

    for (p = 0; p < slice_plan->npasses; p++) {
      nslicesthispass[p] = 0;
      for (s = 0; s < slperpass; s++) {
        sllocthispass[p][s] = -1;
        if (s * slice_plan->npasses + p < nslices) {
          nslicesthispass[p]++;
          sllocthispass[p][s] = p + (s * slice_plan->npasses);
        }
      }
    }
  
    for (p = 0; p < slice_plan->npasses; p++) {
      t = 0; /* linearly increasing time index in current pass */
      for (interleaf = 0; interleaf < ninterleaves; interleaf++) {
        /* interleaf: slice interleaves *within* each pass (typically odd/even) */
        for (i = 0; i < CEIL_DIV(nslicesthispass[p], ninterleaves); i++) {
          k = interleaf + i * ninterleaves; /* pass_sliceindx */
          if (k < nslicesthispass[p]) {
            slice_plan->acq_order[sllocthispass[p][k]].slloc  = sllocthispass[p][k]; /* Spatial location index into the prescribed slice stack */
            slice_plan->acq_order[sllocthispass[p][k]].slpass = p; /* pass index */
            slice_plan->acq_order[sllocthispass[p][k]].sltime = t++; /* time index in current pass. 0->nslicesthispass[p] */
          }
        }
      }
    }

  } /* sequential scanning or not */


  return SUCCESS;
}

ks_calc_sliceplan_sms()

STATUS ks_calc_sliceplan_sms	(	KS_SLICE_PLAN *	slice_plan,
		int	nslices,
		int	slperpass,
		int	multiband_factor
	)

Calculates the data acquisition order for simulaneous-multi-slice (SMS)2D scans

Parameters

[out]	slice_plan	The slice plan (KS_SLICE_PLAN) set up earlier using ks_calc_sliceplan() or similar
[in]	nslices	Total number of slices (usually opslquant)
[in]	slperpass	Number of slices per pass (i.e. per TR)
[in]	multiband_factor	Number of SMS slices

Return values

STATUS

SUCCESS or FAILURE

                                                                                                          {
  int slices_per_stack, passes_per_stack;
  int i;
  STATUS status;

  /* sanitize the input */
  multiband_factor = multiband_factor < 1 ? 1 : multiband_factor;
  nslices = nslices < 0 ? 1 : nslices;
  slperpass = slperpass < 0 ? 1 : slperpass;

  if (slperpass > nslices)
    slperpass = nslices;

  /* no SMS?, fall back to standard slice plan */
  if (multiband_factor == 1) {
    status = ks_calc_sliceplan(slice_plan, nslices, slperpass);
    return status;
  }

  /* a 'stack' is a group of slices out of the prescribed slices (opslquant), where the #slices in the stack is equal to
     opslquant / multiband_factor. The stack does only cover 1/multiband_factor of the entire slice FOV (i.e. not interleaved).
     The exact number of slices in each stack is ceil(opslquant/multiband_factor), which may often lead to that more slices than
     prescribed need to be acquired for divisibility */
  slices_per_stack = CEIL_DIV(nslices, multiband_factor);

  /* number of passes per TR for one slice stack */
  passes_per_stack = CEIL_DIV(slices_per_stack, slperpass);

  if (passes_per_stack == 1) {
    /* we can fit all slices in the stack in 1 pass (acquisition), i.e. one TR. Do SMS-specific slice interleaving */
    ks_calc_slice_acquisition_order_smssingleacq(slice_plan->acq_order, slices_per_stack);
  } else {
    /* need 2+ acqs to acquire the 'slices_per_stack' slices. Do standard slice interleaving */
    ks_calc_sliceplan(slice_plan, slices_per_stack, slperpass);
  }

  /* copy to stacks 2->multiband_factor */
  slice_plan->nslices = slices_per_stack * multiband_factor;
  slice_plan->npasses = passes_per_stack * multiband_factor;

  for (i = slices_per_stack; i < slice_plan->nslices; i++) {
    int slice_in_stack = i % slices_per_stack;
    int stack = i / slices_per_stack;
    slice_plan->acq_order[i].slloc  = i;
    slice_plan->acq_order[i].slpass = slice_plan->acq_order[slice_in_stack].slpass + stack * passes_per_stack;
    slice_plan->acq_order[i].sltime = slice_plan->acq_order[slice_in_stack].sltime;
  }

  return SUCCESS;
}

ks_calc_slice_acquisition_order_smssingleacq()

int ks_calc_slice_acquisition_order_smssingleacq	(	DATA_ACQ_ORDER *	dacq,
		int	nslices
	)

Calculates the data acquisition order for single acquisition SMS

Parameters

[out]	dacq	Data acquisition order array (local)
[in]	nslices	Total number of slices prescribed

Return values

int	Resulting number of passes (or acqs) (in this case 1)

                                                                                    {

  return nslices % 2 ?
    ks_calc_slice_acquisition_order_smssingleacq_impl(dacq, nslices, 2) :
    ks_calc_slice_acquisition_order_smssingleacq_impl(dacq, nslices, 3);
}

ks_calc_sms_min_gap()

int ks_calc_sms_min_gap	(	DATA_ACQ_ORDER *	dacq,
		int	nslices
	)

Calculates the minimum time gap between adjacent slices in a SMS acquisition

Parameters

[out]	dacq	Data acquisition order array (local)
[in]	nslices	Total number of slices prescribed

Return values

int	The minimum time gap between adjacent slices

                                                           {
  int min_gap = nslices;

  int i;
  for (i=1; i<nslices; i++) {
    int gap = abs(dacq[i-1].sltime - dacq[i].sltime);
    if (gap < min_gap) {
      min_gap = gap;
    }
  }

  int last_to_first = nslices - dacq[nslices-1].sltime;
  if (last_to_first < min_gap) {
    min_gap = last_to_first;
  }

  return min_gap;
}

ks_print_sliceplan()

void ks_print_sliceplan	(	const KS_SLICE_PLAN	slice_plan,
		FILE *	fp
	)

Writes a KS_SLICE_PLAN to a file pointer

Parameters

slice_plan	KS_SLICE_PLAN for the sequence
fp	A file pointer (or stderr)

Returns

void

                                                                  {
  int i;

  fprintf(fp, "\nSlice Plan:\n");
  fprintf(fp, "=============================================\n");
  fprintf(fp, "Number of slices: %d\n", slice_plan.nslices);
  fprintf(fp, "Number of passes: %d\n", slice_plan.npasses);
  fprintf(fp, "Slices per pass:  %d\n", slice_plan.nslices_per_pass);
  fprintf(fp, "\nslpass\tsltime\tslloc\n");
  fprintf(fp, "---------------------------------------------\n");
  for (i = 0; i < slice_plan.nslices; i++) { /* i = spatial location */
    fprintf(fp, "%03d   \t%03d   \t%03d\n", slice_plan.acq_order[i].slpass, slice_plan.acq_order[i].sltime, slice_plan.acq_order[i].slloc);
  }
  fprintf(fp, "=============================================\n\n");

}

ks_print_waveform()

void ks_print_waveform	(	const KS_WAVEFORM	waveform,
		const char *	filename,
		int	res
	)

Writes a KS_WAVEFORM to disk with the specified filename

Parameters

[in]	waveform	A KS_WAVEFORM (i.e. float array) to be written
[in]	filename	String with the output file name
[in]	res	Number of elements in the waveform to be written

Returns

void

                                                                                  {

  int i;
  FILE *asciiWaveFile;
  asciiWaveFile = fopen(filename, "w");

  if (asciiWaveFile == NULL) {
    return;
  }

  for (i = 0; i < res; i++) {
    fprintf(asciiWaveFile, "%d %f\n", i, waveform[i]); fflush(asciiWaveFile);
  }

  fclose(asciiWaveFile); /* close ascii file */
}

ks_print_read()

void ks_print_read	(	KS_READ	read,
		FILE *	fp
	)

Writes out the contents of a KS_READ sequence object for debugging

If 2nd argument is stderr or stdout, the printed result will be seen in WTools for simulation. On the MR system, stderr will show up in one of the mgd_term windows. A file pointer (opened with e.g. fp = fopen("/usr/g/mrraw/myname.txt","w")) saves a text file to disk

Parameters

[in]	read	A KS_READ object to be printed
[in]	fp	A file pointer (or stderr)

Returns

void

                                        {
  if (a.description == NULL || a.duration == 0)
    return;
  fprintf(fp, "%s.duration: %d\n", a.description, a.duration);
  fprintf(fp, "%s.rbw: %g\n", a.description, a.rbw);
  fprintf(fp, "%s.filt.decimation: %g\n", a.description, a.filt.decimation);
  fprintf(fp, "%s.filt.tdaq: %d\n", a.description, a.filt.tdaq);
  fprintf(fp, "%s.filt.bw: %g\n", a.description , a.filt.bw);
  fprintf(fp, "%s.filt.tsp: %g\n", a.description, a.filt.tsp);
  fprintf(fp, "%s.filt.outputs: %d\n", a.description, a.filt.outputs);
  fprintf(fp, "%s.filt.prefills: %d\n", a.description, a.filt.prefills);
  fprintf(fp, "%s.filt.taps: %d\n", a.description, a.filt.taps);
  fflush(fp);
}

ks_print_trap()

void ks_print_trap	(	KS_TRAP	trap,
		FILE *	fp
	)

Writes out the contents of a KS_TRAP sequence object for debugging

If 2nd argument is stderr or stdout, the printed result will be seen in WTools for simulation. On the MR system, stderr will show up in one of the mgd_term windows. A file pointer (opened with e.g. fp = fopen("/usr/g/mrraw/myname.txt","w")) saves a text file to disk

Parameters

[in]	trap	A KS_TRAP object to be printed
[in]	fp	A file pointer (or stderr)

Returns

void

                                        {
  if (t.description == NULL || t.duration == 0)
    return;
  fprintf(fp, "%s.amp: %g\n", t.description, t.amp);
  fprintf(fp, "%s.ramptime: %d\n", t.description, t.ramptime);
  fprintf(fp, "%s.plateautime: %d\n", t.description, t.plateautime);
  fprintf(fp, "%s.duration: %d\n", t.description , t.duration);
  fprintf(fp, "%s.area: %g\n", t.description, t.area);
  fflush(fp);
}

ks_print_readtrap()

void ks_print_readtrap	(	KS_READTRAP	readtrap,
		FILE *	fp
	)

Writes out the contents of a KS_READTRAP sequence object for debugging

If 2nd argument is stderr or stdout, the printed result will be seen in WTools for simulation. On the MR system, stderr will show up in one of the mgd_term windows. A file pointer (opened with e.g. fp = fopen("/usr/g/mrraw/myname.txt","w")) saves a text file to disk

Parameters

[in]	readtrap	A KS_READTRAP object to be printed
[in]	fp	A file pointer (or stderr)

Returns

void

                                                {
    if (r.grad.description == NULL || r.grad.duration == 0)
    return;
  fprintf(fp, "\nKS_READTRAP (%s):\n", r.grad.description);
  fprintf(fp, "fov: %g\n", r.fov);
  fprintf(fp, "res: %d\n", r.res);
  fprintf(fp, "rampsampling: %d\n", r.rampsampling);
  fprintf(fp, "nover: %d\n", r.nover);
  fprintf(fp, "acqdelay: %d\n", r.acqdelay);
  fprintf(fp, "area2center: %g\n", r.area2center);
  fprintf(fp, "time2center: %d\n", r.time2center);
  fflush(fp);
  ks_print_read(r.acq, fp);
  ks_print_trap(r.grad, fp);
  if (r.omega.duration > 0) {
    ks_print_trap(r.omega, fp);
  }
}

ks_print_phaser()

void ks_print_phaser	(	KS_PHASER	phaser,
		FILE *	fp
	)

Writes out the contents of a KS_PHASER sequence object for debugging

If 2nd argument is stderr or stdout, the printed result will be seen in WTools for simulation. On the MR system, stderr will show up in one of the mgd_term windows. A file pointer (opened with e.g. fp = fopen("/usr/g/mrraw/myname.txt","w")) saves a text file to disk

Parameters

[in]	phaser	A KS_PHASER object to be printed
[in]	fp	A file pointer (or stderr)

Returns

void

                                            {
  if (p.grad.description == NULL || p.grad.duration == 0)
    return;
  fprintf(fp, "\nKS_PHASER (%s):\n", p.grad.description);
  fprintf(fp, "fov: %g\n", p.fov);
  fprintf(fp, "res: %d\n", p.res);
  fprintf(fp, "nover: %d\n", p.nover);
  fprintf(fp, "R: %d\n", p.R);
  fprintf(fp, "nacslines: %d\n", p.nacslines);
  fprintf(fp, "areaoffset: %g\n", p.areaoffset);
  fprintf(fp, "numlinestoacq: %d\n", p.numlinestoacq);
  fflush(fp);
  ks_print_trap(p.grad, fp);
}

ks_print_epi()

void ks_print_epi	(	KS_EPI	epi,
		FILE *	fp
	)

Writes out the contents of a KS_EPI sequence object for debugging

If 2nd argument is stderr or stdout, the printed result will be seen in WTools for simulation. On the MR system, stderr will show up in one of the mgd_term windows. A file pointer (opened with e.g. fp = fopen("/usr/g/mrraw/myname.txt","w")) saves a text file to disk

Parameters

[in]	epi	A KS_EPI object to be printed
[in]	fp	A file pointer (or stderr)

Returns

void

                                      {
  fprintf(fp, "\nKS_EPI (%s):\n", s.read.grad.description);
  fprintf(fp, "etl: %d\n", s.etl);
  fprintf(fp, "read_spacing: %.2f [ms]\n", s.read_spacing / 1000.0);
  fprintf(fp, "duration: %.2f [ms]\n", s.duration / 1000.0);
  fprintf(fp, "time2center: %.2f [ms]\n", s.time2center / 1000.0);
  ks_print_readtrap(s.read, fp);
  ks_print_trap(s.readphaser, fp);
  ks_print_trap(s.blip, fp);
  ks_print_phaser(s.blipphaser, fp);
} /* ks_print_epi */

ks_print_rf()

void ks_print_rf	(	KS_RF	rf,
		FILE *	fp
	)

Writes out the contents of a KS_RF sequence object for debugging

If 2nd argument is stderr or stdout, the printed result will be seen in WTools for simulation. On the MR system, stderr will show up in one of the mgd_term windows. A file pointer (opened with e.g. fp = fopen("/usr/g/mrraw/myname.txt","w")) saves a text file to disk

Parameters

[in]	rf	A KS_RF object to be printed
[in]	fp	A file pointer (or stderr)

Returns

void

                                    {
  if (r.rfpulse.activity == 0) {
    return;
  }

  fprintf(fp, "\nKS_RF (%s):\n", r.rfwave.description);
  fprintf(fp, "%s\n", r.designinfo);
  switch (r.role) {
  case KS_RF_ROLE_NOTSET: fprintf(fp, "role: KS_RF_ROLE_NOTSET\n"); break;
  case KS_RF_ROLE_EXC: fprintf(fp, "role: KS_RF_ROLE_EXC\n"); break;
  case KS_RF_ROLE_REF: fprintf(fp, "role: KS_RF_ROLE_REF\n"); break;
  case KS_RF_ROLE_CHEMSAT: fprintf(fp, "role: KS_RF_ROLE_CHEMSAT\n"); break;
  case KS_RF_ROLE_SPSAT: fprintf(fp, "role: KS_RF_ROLE_SPSAT\n"); break;
  case KS_RF_ROLE_INV: fprintf(fp, "role: KS_RF_ROLE_INV\n"); break;
  }
  fprintf(fp, "rfwave.res: %d\n", r.rfwave.res);
  fprintf(fp, "rfwave.duration: %d\n", r.rfwave.duration);
  fprintf(fp, "amp: %g\n", r.amp);
  fprintf(fp, "flip: %g\n", r.flip);
  fprintf(fp, "bw: %g\n", r.bw);
  fprintf(fp, "cf_offset: %g\n", r.cf_offset);
  fprintf(fp, "start2iso: %d\n", r.start2iso);
  fprintf(fp, "iso2end: %d\n", r.iso2end);

  ks_print_rfpulse(r.rfpulse, fp);

  if (r.rfwave.res == 0)
    fprintf(fp, "     rfwave: OFF\n");
  else
    fprintf(fp, "     rfwave: Waveform assigned\n");

  if (r.thetawave.res == 0)
    fprintf(fp, "     thetawave: OFF\n");
  else
    fprintf(fp, "     thetawave: Waveform assigned\n");

  fflush(fp);

} /* ks_print_rf */

ks_print_rfpulse()

void ks_print_rfpulse	(	RF_PULSE	rfpulse,
		FILE *	fp
	)

Writes out the contents of an RF_PULSE struct for debugging

If 2nd argument is stderr or stdout, the printed result will be seen in WTools for simulation. On the MR system, stderr will show up in one of the mgd_term windows. A file pointer (opened with e.g. fp = fopen("/usr/g/mrraw/myname.txt","w")) saves a text file to disk

Parameters

[in]	rfpulse	An RF_PULSE struct (<rf>.rfpulse) to be printed
[in]	fp	A file pointer (or stderr)

Returns

void

                                                  {
  fprintf(fp, "     rfpulse.pw: %d\n", *(rfpulse.pw));
  fprintf(fp, "     rfpulse.amp: %g\n", *(rfpulse.amp));
  fprintf(fp, "     rfpulse.abswidth: %g\n", rfpulse.abswidth);
  fprintf(fp, "     rfpulse.effwidth: %g\n", rfpulse.effwidth);
  fprintf(fp, "     rfpulse.area: %g\n", rfpulse.area);
  fprintf(fp, "     rfpulse.dtycyc: %g\n", rfpulse.dtycyc);
  fprintf(fp, "     rfpulse.maxpw: %g\n", rfpulse.maxpw);
  fprintf(fp, "     rfpulse.num: %d\n", (int)rfpulse.num);
  fprintf(fp, "     rfpulse.max_b1: %g\n", rfpulse.max_b1);
  fprintf(fp, "     rfpulse.max_int_b1_sq: %g\n", rfpulse.max_int_b1_sq);
  fprintf(fp, "     rfpulse.max_rms_b1: %g\n", rfpulse.max_rms_b1);
  fprintf(fp, "     rfpulse.nom_fa: %g\n", rfpulse.nom_fa);
  fprintf(fp, "     rfpulse.act_fa: %g\n", *(rfpulse.act_fa));
  fprintf(fp, "     rfpulse.nom_pw: %g\n", rfpulse.nom_pw);
  fprintf(fp, "     rfpulse.nom_bw: %g\n", rfpulse.nom_bw);
  fprintf(fp, "     rfpulse.activity: %d\n", rfpulse.activity);
  fprintf(fp, "     rfpulse.isodelay: %d\n", rfpulse.isodelay);
  fprintf(fp, "     rfpulse.scale: %g\n", rfpulse.scale);
  fprintf(fp, "     rfpulse.res: %d\n", *(rfpulse.res));
  fprintf(fp, "     rfpulse.extgradfile: %d\n", rfpulse.extgradfile);

  fflush(fp);

}

ks_print_selrf()

void ks_print_selrf	(	KS_SELRF	selrf,
		FILE *	fp
	)

Writes out the contents of a KS_SELRF sequence object for debugging

If 2nd argument is stderr or stdout, the printed result will be seen in WTools for simulation. On the MR system, stderr will show up in one of the mgd_term windows. A file pointer (opened with e.g. fp = fopen("/usr/g/mrraw/myname.txt","w")) saves a text file to disk

Parameters

[in]	selrf	A KS_SELRF object to be printed
[in]	fp	A file pointer (or stderr)

Returns

void

                                          {

  if (r.rf.rfpulse.activity == 0 || r.rf.rfwave.description == NULL || r.rf.rfwave.duration == 0) {
    return;
  }

  fprintf(fp, "\nKS_SELRF(%s):\n", r.rf.rfwave.description);

  fprintf(fp, "slthick: %g\n", r.slthick);
  if (r.rf.role == KS_RF_ROLE_REF)
    fprintf(fp, "crusherscale: %g\n", r.crusherscale);

  ks_print_trap(r.pregrad, fp);
  ks_print_trap(r.grad, fp);
  if (r.gradwave.res > 0) {
    fprintf(fp, "     gradwave: Waveform assigned\n");
  }
  ks_print_trap(r.postgrad, fp);
  ks_print_rf(r.rf, fp);

} /* ks_print_selrf */

ks_print_gradrfctrl()

void ks_print_gradrfctrl	(	KS_GRADRFCTRL	gradrfctrl,
		FILE *	fp
	)

Writes out the contents of KS_GRADRFCTRL for debugging

If 2nd argument is stderr or stdout, the printed result will be seen in WTools for simulation. On the MR system, stderr will show up in one of the mgd_term windows. A file pointer (opened with e.g. fp = fopen("/usr/g/mrraw/myname.txt","w")) saves a text file to disk

Parameters

[in]	gradrfctrl	A KS_GRADRFCTRL object to be printed
[in]	fp	A file pointer (or stderr)

Returns

void

                                                             {
  int i;

  for (i = 0; i < gradrfctrl.numrf; i++) {
    fprintf(fp, "RF[%d] '%s': %d times\n", i, gradrfctrl.rfptr[i]->rfwave.description, gradrfctrl.rfptr[i]->rfwave.base.ninst);
  }
  for (i = 0; i < gradrfctrl.numtrap; i++) {
    fprintf(fp, "TRAP[%d] '%s': [%d, %d, %d] times on [X,Y,Z]\n", i, gradrfctrl.trapptr[i]->description, gradrfctrl.trapptr[i]->gradnum[XGRAD], gradrfctrl.trapptr[i]->gradnum[YGRAD], gradrfctrl.trapptr[i]->gradnum[ZGRAD]);
  }
  for (i = 0; i < gradrfctrl.numwave; i++) {
    fprintf(fp, "WAVE[%d] '%s': [%d, %d, %d] times on [X,Y,Z]\n", i, gradrfctrl.waveptr[i]->description, gradrfctrl.waveptr[i]->gradnum[XGRAD], gradrfctrl.waveptr[i]->gradnum[YGRAD], gradrfctrl.waveptr[i]->gradnum[ZGRAD]);
  }

}

ks_error()

STATUS ks_error	(	const char *	format,
			...
	)

Common error message function for HOST and TGT

• On the MR-scanner, this function will append error messages with a timestamp to the file /usr/g/mrraw/ksf_errors.txt in addition to sending an epic_error(), which will show the error at the bottom of the UI
• In simluation, the error message will be seen both in Evaltool and in the main WTools window

Parameters

[in]

format

Standard C printf input arguments

Return values

STATUS

Returns FAILURE

ks_dbg()

STATUS STATUS ks_dbg	(	const char *	format,
			...
	)

Common debug message function for HOST and TGT

• On the MR-scanner, this function will append error messages with a timestamp to the file /usr/g/mrraw/ksf_debug.txt

Parameters

[in]

format

Standard C printf input arguments

Return values

STATUS

Returns SUCCESS

existfile()

STATUS STATUS STATUS existfile

(

const char *

fname

)

                                    {
    FILE *file;
    if ((file = fopen(fname, "r"))) {
        fclose(file);
        return SUCCESS;
    }
    return FAILURE;
}

ks_syslimits_hasICEhardware()

int ks_syslimits_hasICEhardware

(

)

Check for ICE Hardware (e.g. RX27+ on SIGNA Premier)

Return values

int	1: ICE 0: MGD

                                  {
  int isice = FALSE;
#if EPIC_RELEASE >= 27
  isice = cfssctype;
#endif

  return isice;

}

ks_dbg_reset()

void ks_dbg_reset

(

)

Clear debug file content

                    {
  FILE *fp;

/* if on MR scanner (HOST and TGT/IPG, HW=hardware=MRscanner) */
#ifdef PSD_HW
  fp = fopen("/usr/g/mrraw/ks_debug.txt", "w");
#else
  fp = fopen("./ks_debug.txt", "w");
#endif

fclose(fp);

}

ks_syslimits_ampmax()

float ks_syslimits_ampmax

(

LOG_GRAD

loggrd

)

Returns the maximum gradient amplitude that can be used on all gradient boards simultaneously

Since the waveform design (using ks_eval_***() functions) is separated from the placement of waveforms (using ks_pg_***() functions), the maximum gradient limit to use for gradient design must account for the least capable gradient board given the current slice angulation. ks_syslimits_ampmax() assumes that all gradients may be on simultaneously

The return value from this function can be passed in as ampmax to all ks_eval***_constrained() functions

Parameters

[in]

loggrd

GE's LOG_GRAD struct, dependent on the gradient system and current slice angulation

Return values

gradmax

Maximum gradient amplitude ([G/cm]) that can be used on all boards simultaneously

                                           {
  return (FMin(3, loggrd.tx_xyz, loggrd.ty_xyz, loggrd.tz_xyz));
}

ks_syslimits_ampmax2()

float ks_syslimits_ampmax2

(

LOG_GRAD

loggrd

)

Returns the maximum gradient amplitude that can be used on two gradient boards simultaneously

Since the waveform design (using ks_eval_***() functions) is separated from the placement of waveforms (using ks_pg_***() functions), the maximum gradient limit to use for gradient design must account for the least capable gradient board given the current slice angulation. ks_syslimits_ampmax2() assumes that gradients are played out on at most one more board at the same time as the current trapezoid

The return value from this function can be passed in as ampmax to all ks_eval***_constrained() functions

Parameters

[in]

loggrd

GE's LOG_GRAD struct, dependent on the gradient system and current slice angulation

Return values

gradmax

Maximum gradient amplitude ([G/cm]) that can be used on 2 boards simultaneously

                                            {
  return (FMin(6, loggrd.tx_xy, loggrd.tx_xz, loggrd.ty_xy, loggrd.ty_yz, loggrd.tz_xz, loggrd.tz_yz));
}

ks_syslimits_ampmax1()

float ks_syslimits_ampmax1

(

LOG_GRAD

loggrd

)

Returns the maximum gradient amplitude that can be used on one gradient board at a time

Since the waveform design (using ks_eval_***() functions) is separated from the placement of waveforms (using ks_pg_***() functions), the maximum gradient limit to use for gradient design must account for the least capable gradient board given the current slice angulation. ks_syslimits_ampmax1() assumes that no other gradient is played out on another board at the same time as the current trapezoid

The return value from this function can be passed in as ampmax to all ks_eval***_constrained() functions

Parameters

[in]

loggrd

GE's LOG_GRAD struct, dependent on the gradient system and current slice angulation

Return values

gradmax

Maximum gradient amplitude ([G/cm]) that can be used on one board at a time

                                            {
  return (FMin(3, loggrd.tx, loggrd.ty, loggrd.tz));
}

ks_syslimits_ampmax1p()

float ks_syslimits_ampmax1p

(

LOG_GRAD

loggrd

)

Returns the maximum gradient amplitude on the physical gradient axes

Parameters

[in]

loggrd

GE's LOG_GRAD struct, dependent on the gradient system and current slice angulation

Return values

gradmax

Maximum gradient amplitude ([G/cm]) as defined by the physical gradients (lowest of physical X, Y, Z)

                                             {
  return (FMin(3, loggrd.xfs, loggrd.yfs, loggrd.zfs));
}

ks_syslimits_ramptimemax()

int ks_syslimits_ramptimemax

(

LOG_GRAD

loggrd

)

Returns the minimum ramp time to get from zero to full gradient scale

Parameters

[in]

loggrd

GE's LOG_GRAD struct, dependent on the gradient system and current slice angulation

Return values

ramptime

Ramptime in [us] to get from zero to full gradient scale

                                              {
  /* ramptime at full gradient scale */
  return IMax(3, loggrd.xrt, loggrd.yrt, loggrd.zrt);
}

ks_syslimits_slewrate()

float ks_syslimits_slewrate

(

LOG_GRAD

loggrd

)

Returns the maximum slewrate that can be used on all gradient boards simultaneously

The return value from this function is the ratio of ks_syslimits_ampmax() and ks_syslimits_ramptimemax() and can be passed in as slewrate to all ks_eval***_constrained() functions

Parameters

[in]

loggrd

GE's LOG_GRAD struct, dependent on the gradient system and current slice angulation

Return values

slewrate

Maximum slewrate ([(G/cm) / us]) that can be used on all boards simultaneously

                                             {
  return (ks_syslimits_ampmax(loggrd) / ks_syslimits_ramptimemax(loggrd));
}

ks_syslimits_slewrate2()

float ks_syslimits_slewrate2

(

LOG_GRAD

loggrd

)

Returns the maximum slewrate that can be used on two gradient boards simultaneously

The return value from this function is the ratio of ks_syslimits_ampmax2() and ks_syslimits_ramptimemax() and can be passed in as slewrate to all ks_eval***_constrained() functions

Parameters

[in]

loggrd

GE's LOG_GRAD struct, dependent on the gradient system and current slice angulation

Return values

slewrate

Maximum slewrate ([(G/cm) / us]) that can be used on all boards simultaneously

                                              {
  return (ks_syslimits_ampmax2(loggrd) / ks_syslimits_ramptimemax(loggrd));
}

ks_syslimits_slewrate1()

float ks_syslimits_slewrate1

(

LOG_GRAD

loggrd

)

Returns the maximum slewrate that can be used on one gradient board at a time

The return value from this function is the ratio of ks_syslimits_ampmax1() and ks_syslimits_ramptimemax() and can be passed in as slewrate to all ks_eval***_constrained() functions

Parameters

[in]

loggrd

GE's LOG_GRAD struct, dependent on the gradient system and current slice angulation

Return values

slewrate

Maximum slewrate ([(G/cm) / us]) that can be used on one board at at time

                                              {
  return (ks_syslimits_ampmax1(loggrd) / ks_syslimits_ramptimemax(loggrd));
}

ks_syslimits_slewrate1p()

float ks_syslimits_slewrate1p

(

LOG_GRAD

loggrd

)

Returns the maximum gradient amplitude on the physical gradient axes

Parameters

[in]

loggrd

GE's LOG_GRAD struct, dependent on the gradient system and current slice angulation

Return values

gradmax

Maximum slewrate ([(G/cm) / us]) that can be used on one board at at time as defined by the physical gradients (lowest of physical X, Y, Z)

                                               {
  return (ks_syslimits_ampmax1p(loggrd) / ks_syslimits_ramptimemax(loggrd));
}

ks_syslimits_gradtarget()

float ks_syslimits_gradtarget	(	LOG_GRAD	loggrd,
		int	board
	)

Returns the maximum target amplitude for a board (internal use)

For gradient boards, the field .tx, .ty or .tz is returned. For non-gradient boards, 1.0 is returned. This function is used internally by ks_pg_***() functions and there should be no need to call it directly.

Parameters

[in]	loggrd	GE's LOG_GRAD struct, dependent on the gradient system and current slice angulation
[in]	board	The board on which the current trapezoid or waveform is to be played out on

Return values

gradamp

Maximum target amplitude for a board

                                                          {
  switch (board) {
  case XGRAD:
    return loggrd.tx;
  case YGRAD:
    return loggrd.ty;
  case ZGRAD:
    return loggrd.tz;
  default:
    return 1.0;
  }
}

ks_syslimits_ampmax_phys()

float ks_syslimits_ampmax_phys

(

)

Returns the integer phase (not in use)

All phase values in KSFoundation are in [degrees], including flip angles, RF/receive phases and THETA waveforms. This function is therefore currently not used. See instead ks_phase_degrees2hw()

Parameters

[in]

radphase

Phase in radians

Return values

intphase

Integer phase to use on THETA board on hardware

                                 {
  return FMin(3, phygrd.xfs,    phygrd.yfs,    phygrd.zfs);
}

ks_syslimits_ramptimemax_phys()

int ks_syslimits_ramptimemax_phys

(

)

                                    {
  /* ramptime at full gradient scale */
  return IMax(3, phygrd.xrt, phygrd.yrt, phygrd.zrt);
}

ks_syslimits_slewrate_phys()

float ks_syslimits_slewrate_phys

(

)

                                   {
  return ks_syslimits_ampmax_phys()/((float) ks_syslimits_ramptimemax_phys());
}

ks_phase_radians2hw()

short ks_phase_radians2hw

(

float

radphase

)

                                       {
  short iphase;
  UINT uiphase;
  double dphase = (double) phase;
  double twopi = (double) 2.0 * PI;

  /* Resolve angle to lie within range ( -2*pi <= dphase < 2*pi ) */
  dphase = fmod(dphase, twopi);

  /* Find the equivalent positive angle */
  if (dphase < 0.0)
    dphase = twopi + dphase;

  /* Convert the angle to exciter DDS phase representation where only the
     upper 14 bits of 16 are used */
  uiphase = (UINT) (dphase * 16384.0 / twopi + 0.5);
  if (uiphase == 16384)
    uiphase = 0;

  /* left shift the result by 2 bits */
  iphase = (short) (uiphase << 2);

  return iphase;
}

ks_phase_degrees2hw()

short ks_phase_degrees2hw

(

float

degphase

)

Returns the integer phase (internal use)

All phase values in KSFoundation are in [degrees], including flip angles, RF/receive phases and THETA waveforms. This function is used internally by another internal function ks_wave2iwave(), which is in turn called by ks_pg_wave()

Parameters

[in]

degphase

Phase in degrees

Return values

intphase

Integer phase to use on THETA board on hardware

                                       {

  return ks_phase_radians2hw(phase * PI / 180.0);
}

ks_calc_selgradamp()

float ks_calc_selgradamp	(	float	rfbw,
		float	slthick
	)

Returns the gradient amplitude in [G/cm] necessary for slice selection (internal use)

Given an RF bandwidth in [Hz] and a slice thickness in [mm], this function calculates the gradient strength in [G/cm] necessary to produce a slice with the given slice thickness

This function is used by ks_eval_seltrap(), ks_eval_selrf_constrained() and ks_scan_selrf_setfreqphase()

Parameters

[in]	rfbw	The bandwidth of the RF pulse to use with the gradient
[in]	slthick	The desired slice thickness in [mm]

Return values

gradamp

Gradient amplitude to use [G/cm]

                                                    {

  if (slthick > 0 && rfbw > 0)
    return (rfbw / (GAM * slthick / 10.0));
  else
    return 0.0; /* return zero amp if requested slice thickness is <= 0 */
}

ks_wave_res()

int ks_wave_res

(

const KS_WAVE *

wave

)

Returns the number of samples in a KS_WAVE sequence object

Parameters

[in]

wave

KS_WAVE object

Return values

res	Resolution (i.e. number of samples) in the KS_WAVE object

                                     {

  if (wave == NULL) {
    ks_error("ks_wave_res: wave is NULL");
    return KS_NOTSET;
  }
  if (wave->description == NULL || wave->description[0] == ' ') {
    ks_error("ks_wave_res: wave description not initialized or has leading space");
    return KS_NOTSET;
  }
  if (wave->res < 2 || wave->res > KS_MAXWAVELEN) {
    ks_error("ks_wave_res(%s): 'res' (%d) is out of valid range [2, %d]", wave->description, wave->res, KS_MAXWAVELEN);
    return KS_NOTSET;
  }
  if (wave->res % 2) {
    ks_error("ks_wave_res(%s): 'res' (%d) must be even", wave->description, wave->res);
    return KS_NOTSET;
  }

  return wave->res;
}

ks_waveform_max()

float ks_waveform_max	(	const KS_WAVEFORM	waveform,
		int	res
	)

Returns the maximum value in a KS_WAVEFORM

Parameters

[in]	waveform	KS_WAVEFORM (float array)
[in]	res	Resolution (i.e. number of samples) in the KS_WAVEFORM

Return values

maxval

Maximum value

                                                           {
  float maxv = -1.0e38;
  int i;

  if (waveform == NULL) {
    ks_error("ks_waveform_max: wave is NULL");
    return maxv;
  }
  if (res <= 0) {
    return maxv;
  }

  for (i = 0; i < res; i++) {
    if (waveform[i] > maxv)
      maxv = waveform[i];
  }

  return maxv;
}

ks_wave_max()

float ks_wave_max

(

const KS_WAVE *

wave

)

Returns the maximum value in a KS_WAVE sequence object

Parameters

[in]

wave

KS_WAVE object

Return values

maxval

Maximum value

                                       {
  return ks_waveform_max(wave->waveform, wave->res);
}

ks_waveform_min()

float ks_waveform_min	(	const KS_WAVEFORM	waveform,
		int	res
	)

Returns the minimum value in a KS_WAVEFORM

Parameters

[in]	waveform	KS_WAVEFORM (float array)
[in]	res	Resolution (i.e. number of samples) in the KS_WAVEFORM

Return values

minval

Minimum value

                                                           {
  float minv = 1.0e38;
  int i;

  if (waveform == NULL) {
    ks_error("ks_waveform_min: wave is NULL");
    return minv;
  }
  if (res <= 0) {
    return minv;
  }

  for (i = 0; i < res; i++) {
    if (waveform[i] < minv)
      minv = waveform[i];
  }

  return minv;
}

ks_wave_min()

float ks_wave_min

(

const KS_WAVE *

wave

)

Returns the minimum value in a KS_WAVE sequence object

Parameters

[in]

wave

KS_WAVE object

Return values

minval

Minimum value

                                       {
  return ks_waveform_min(wave->waveform, wave->res);
}

ks_waveform_absmax()

float ks_waveform_absmax	(	const KS_WAVEFORM	waveform,
		int	res
	)

Returns the maximum absolute value in a KS_WAVEFORM

Parameters

[in]	waveform	KS_WAVEFORM (float array)
[in]	res	Resolution (i.e. number of samples) in the KS_WAVEFORM

Return values

absmaxval

Maximum absolute value

                                                              {
  float maxv = -1.0e38;
  int i;

  if (waveform == NULL) {
    ks_error("ks_waveform_absmax: wave is NULL");
    return maxv;
  }
  if (res <= 0) {
    return maxv;
  }

  for (i = 0; i < res; i++) {
    if (fabs(waveform[i]) > maxv)
      maxv = fabs(waveform[i]);
  }

  return maxv;
}

ks_waveform_maxslew()

float ks_waveform_maxslew	(	const KS_WAVEFORM	waveform,
		int	res,
		int	duration
	)

Returns the maximum absolute value in a KS_WAVEFORM

Parameters

[in]	waveform	KS_WAVEFORM
[in]	res	Resolution (i.e. number of samples) in the KS_WAVEFORM
[in]	duration	Duration of the waveform in us

Return values

absmaxval

Maximum absolute value

                                                                             {
  float maxslew = -1.0e38;
  int i;

  if (waveform == NULL) {
    ks_error("ks_waveform_absmax: wave is NULL");
    return maxslew;
  }
  if (res <= 0) {
    return maxslew;
  }
  float tmp = 0;
  for (i = 0; i < res-1; i++) {
    tmp = fabs(waveform[i] - waveform[i+1]);
    if (tmp > maxslew)
      maxslew = tmp;
  }
  maxslew = maxslew*res/duration;
  return maxslew;
}

ks_wave_maxslew()

float ks_wave_maxslew

(

const KS_WAVE *

wave

)

Returns the maximum absolute value in a KS_WAVE

Parameters

[in]

wave

KS_WAVE

Return values

absmaxval

Maximum absolute value

                                           {
  return ks_waveform_maxslew(wave->waveform, wave->res, wave->duration);
}

ks_iwave_absmax()

short ks_iwave_absmax	(	const KS_IWAVE	waveform,
		int	res
	)

Returns the max amp of a KS_IWAVE between 0 and res

Parameters

[in]	waveform	KS_WAVE object
[in]	res	Check up to this many samples

Return values

maximum

amplitude of the waveform

                                                        {
  short maxv = 0;
  int i;

  if (waveform == NULL) {
    ks_error("%s: wave is NULL", __FUNCTION__);
    return maxv;
  }
  if (res <= 0) {
    return maxv;
  }

  for (i = 0; i < res; i++) {
    if (abs(waveform[i]) > maxv)
      maxv = abs(waveform[i]);
  }

  return maxv;
}

ks_wave_absmax()

float ks_wave_absmax

(

const KS_WAVE *

wave

)

Returns the maximum absolute value in a KS_WAVE sequence object

Parameters

[in]

wave

KS_WAVE object

Return values

absmaxval

Maximum absolute value

                                          {
  return ks_waveform_absmax(wave->waveform, wave->res);
}

ks_waveform_area()

float ks_waveform_area	(	const KS_WAVEFORM	waveform,
		int	start,
		int	end,
		int	dwelltime
	)

Returns the area of a KS_WAVEFORM over a specified interval given in [us]

Parameters

[in]	waveform	KS_WAVEFORM (float array)
[in]	start	[us] Start position of area calculation in [us] (0 = start of waveform)
[in]	end	[us] End position of area calculation in [us] (res * dwelltime = end of waveform)
[in]	dwelltime	[us] of each waveform point (duration/res)

Return values

area	The area of the KS_WAVEFORM over the specified interval in [(G/cm) * us]

                                                                                            {
  int i;
  double area = 0;
  int start_indx = CEIL_DIV(start, dwelltime);
  int end_indx = end / dwelltime;

  if (waveform == NULL) {
    ks_error("%s: wave is NULL", __FUNCTION__);
  }
  if (start_indx < 0) {
    ks_error("%s: start must be >= 0", __FUNCTION__);
  }
  if (end_indx > KS_MAXWAVELEN) {
    ks_error("%s: end cannot exceed %d", __FUNCTION__, KS_MAXWAVELEN);
  }

  for (i = start_indx; i < end_indx; i++) {
    area += waveform[i] * dwelltime;
  }

  /* add potential partial dwell time due to CEIL_DIV, when start [us] is not divisible by dwelltime */
  if ((start_indx * dwelltime) > start && start_indx > 0) {
    area += waveform[start_indx - 1] * (((double) start_indx * dwelltime) - (double) start);
  }

  /* add potential partial dwell time due to (floor) integer division, when end [us] is not divisible by dwelltime */
  if ((end_indx * dwelltime) < end && (end_indx < (KS_MAXWAVELEN - 1))) {
    area += waveform[end_indx + 1] * ((double) end - ((double) end_indx * dwelltime));
  }

  return ((float) area);
}

ks_wave_area()

float ks_wave_area	(	const KS_WAVE *	wave,
		int	start,
		int	end
	)

Returns the area of a KS_WAVE object over a specified interval given in [us]

Parameters

[in]	wave	KS_WAVE object
[in]	start	[us] Start position of area calculation in [us] (0 = start of waveform)
[in]	end	[us] End position of area calculation in us

Return values

area	The area of the KS_WAVE object over the specified interval in [(G/cm) * us]

                                                                {
  int dwelltime = wave->duration / wave->res;
  return ks_waveform_area(wave->waveform, start, end, dwelltime);
}

ks_waveform_sum()

float ks_waveform_sum	(	const KS_WAVEFORM	waveform,
		int	res
	)

Returns the sum of a KS_WAVEFORM

Parameters

[in]	waveform	KS_WAVEFORM (float array)
[in]	res	Resolution (i.e. number of samples) in the KS_WAVEFORM

Return values

sum	The sum of the KS_WAVEFORM

                                                           {
  int i;
  double sum = 0;

  if (waveform == NULL) {
    ks_error("ks_waveform_sum: wave is NULL");
  }
  if (res <= 0) {
    ks_error("ks_waveform_sum: res must be positive");
  }

  for (i = 0; i < res; i++) {
    sum += waveform[i];
  }

  return (float)sum;
}

ks_wave_sum()

float ks_wave_sum

(

const KS_WAVE *

wave

)

Returns the sum of a KS_WAVE sequence object

Parameters

[in]

wave

KS_WAVE object

Return values

sum	The sum of the KS_WAVEFORM

                                       {
  return ks_waveform_sum(wave->waveform, wave->res);
}

ks_waveform_norm()

float ks_waveform_norm	(	const KS_WAVEFORM	waveform,
		int	res
	)

Returns the 2-norm of a KS_WAVEFORM

Parameters

[in]	waveform	KS_WAVEFORM (float array)
[in]	res	Resolution (i.e. number of samples) in the KS_WAVEFORM

Return values

norm2

The 2-norm of a KS_WAVEFORM

                                                            {
  int i;
  double sum = 0;

  if (waveform == NULL) {
    ks_error("ks_waveform_norm: wave is NULL");
  }
  if (res <= 0) {
    ks_error("ks_waveform_norm: res must be positive");
  }

  for (i = 0; i < res; i++) {
    sum += pow(fabs(waveform[i]), 2.0);
  }

  return (float)sqrt(sum);
}

ks_wave_norm()

float ks_wave_norm

(

const KS_WAVE *

wave

)

Returns the 2-norm of a KS_WAVE

Parameters

[in]

wave

KS_WAVE object

Return values

norm2

The 2-norm of a KS_WAVE

                                        {
  return ks_waveform_norm(wave->waveform, wave->res);
}

ks_waveform_cumsum()

void ks_waveform_cumsum	(	KS_WAVEFORM	cumsumwaveform,
		const KS_WAVEFORM	waveform,
		int	res
	)

Calculates a KS_WAVEFORM with the cumulative sum (i.e. integral) of a KS_WAVEFORM

Parameters

[out]	cumsumwaveform	KS_WAVEFORM (float array)
[in]	waveform	KS_WAVEFORM (float array)
[in]	res	Resolution (i.e. number of samples) in the KS_WAVEFORM

                                                                                         {
  int i, j;

  for (j = 0; j < res; j++) {

    double sum = 0;
    for (i = 0; i < j; i++) {
      sum += waveform[i];
    }

    cumsumwaveform[j] = (float)sum;
  }
}

ks_wave_cumsum()

void ks_wave_cumsum	(	KS_WAVE *	cumsumwave,
		const KS_WAVE *	wave
	)

Calculates a KS_WAVE with the cumulative sum (i.e. integral) of a KS_WAVE

Parameters

[out]	cumsumwave	KS_WAVE object
[in]	wave	KS_WAVE

                                                              {
  int res;
  res = (cumsumwave->res > wave->res) ? wave->res : cumsumwave->res; /* smallest of the two */
  ks_waveform_cumsum(cumsumwave->waveform, wave->waveform, res);
}

ks_waveform_multiply()

void ks_waveform_multiply	(	KS_WAVEFORM	waveform_mod,
		const KS_WAVEFORM	waveform,
		int	res
	)

In-place multiplication of one KS_WAVEFORM with another KS_WAVEFORM

Multiplication of waveform a (arg 1) with waveform b (arg 2) as: a *= b

Parameters

[in,out]	waveform_mod	KS_WAVE object
[in]	waveform	KS_WAVEFORM (float array)
[in]	res	Resolution (i.e. number of samples) in the KS_WAVEFORM

                                                                                         {
  int i;

  for (i = 0; i < res; i++) {
    waveform_mod[i] *= waveform[i];
  }
}

ks_wave_multiply()

void ks_wave_multiply	(	KS_WAVE *	wave_mod,
		const KS_WAVE *	wave
	)

In-place multiplication of one KS_WAVE with another KS_WAVE

Multiplication of waveform a (arg 1) with waveform b (arg 2) as: a *= b

If the duration of the two KS_WAVE objects have different resolution, the shorter KS_WAVE will be multiplied with the first part of the longer KS_WAVE

Parameters

[in,out]	wave_mod	KS_WAVE object
[in]	wave	KS_WAVE object

                                                              {
  int res;
  res = (wave_mod->res > wave->res) ? wave->res : wave_mod->res; /* smallest of the two */
  ks_waveform_multiply(wave_mod->waveform, wave->waveform, res);
}

ks_waveform_add()

void ks_waveform_add	(	KS_WAVEFORM	waveform_mod,
		const KS_WAVEFORM	waveform,
		int	res
	)

In-place addition of one KS_WAVEFORM with another KS_WAVEFORM

Addition of waveform a (arg 1) with waveform b (arg 2) as: a += b

Parameters

[in,out]	waveform_mod	KS_WAVEFORM (float array)
[in]	waveform	KS_WAVEFORM (float array)
[in]	res	Resolution (i.e. number of samples) in the KS_WAVEFORM

                                                                                    {
  int i;

  for (i = 0; i < res; i++) {
    waveform_mod[i] += waveform[i];
  }
}

ks_wave_add()

void ks_wave_add	(	KS_WAVE *	wave_mod,
		const KS_WAVE *	wave
	)

In-place addition of one KS_WAVE with another KS_WAVE

Addition of waveform a (arg 1) with waveform b (arg 2) as: a *= b

If the duration of the two KS_WAVE objects have different resolution, the shorter KS_WAVE will be added to the first part of the longer KS_WAVE

Parameters

[in,out]	wave_mod	KS_WAVE object
[in]	wave	KS_WAVE object

                                                         {
  int res;
  res = (wave_mod->res > wave->res) ? wave->res : wave_mod->res; /* smallest of the two */
  ks_waveform_add(wave_mod->waveform, wave->waveform, res);
}

ks_waveform_multiplyval()

void ks_waveform_multiplyval	(	KS_WAVEFORM	waveform,
		float	val,
		int	res
	)

In-place scalar multiplication of a KS_WAVEFORM

The values in a KS_WAVEFORM are multiplied with a scalar value val

Parameters

[in,out]	waveform	KS_WAVEFORM (float array)
[in]	val	Floating point value to multiply with
[in]	res	Resolution (i.e. number of samples) in the KS_WAVEFORM

                                                                       {
  int i;

  for (i = 0; i < res; i++) {
    waveform[i] *= val;
  }
}

ks_wave_multiplyval()

void ks_wave_multiplyval	(	KS_WAVE *	wave,
		float	val
	)

In-place scalar multiplication of a KS_WAVE

The waveform values in a KS_WAVE sequence object (.waveform[]) are multiplied with a scalar value val

Parameters

[in,out]	wave	KS_WAVE object
[in]	val	Floating point value to multiply with

                                                   {
  ks_waveform_multiplyval(wave->waveform, val, wave->res);
}

ks_waveform_addval()

void ks_waveform_addval	(	KS_WAVEFORM	waveform,
		float	val,
		int	res
	)

In-place scalar addition of a KS_WAVEFORM

The values in a KS_WAVEFORM are added with a scalar value val

Parameters

[in,out]	waveform	KS_WAVEFORM (float array)
[in]	val	Floating point value to add
[in]	res	Resolution (i.e. number of samples) in the KS_WAVEFORM

                                                                  {
  int i;

  for (i = 0; i < res; i++) {
    waveform[i] += val;
  }
}

ks_wave_addval()

void ks_wave_addval	(	KS_WAVE *	wave,
		float	val
	)

In-place scalar addition of a KS_WAVE

The waveform values in a KS_WAVE sequence object (.waveform[]) are added with a scalar value val

Parameters

[in,out]	wave	KS_WAVE object
[in]	val	Floating point value to add

                                              {
  ks_waveform_addval(wave->waveform, val, wave->res);
}

ks_waveform2iwave()

STATUS ks_waveform2iwave	(	KS_IWAVE	iwave,
		const KS_WAVEFORM	waveform,
		int	res,
		int	board
	)

(Internal use) Conversion of a KS_WAVEFORM to a short int array for use on hardware

This function is used internally by ks_pg_wave() and there should be no need to call this function directly.

For all boards except THETA, this function auto-scales the (float) values in KS_WAVEFORM so that the maximum absolute value becomes +/- 32766. The output short int (KS_IWAVE) array is to be copied to hardware. For a KS_WAVEFORM on the THETA board, the necessary phase wraps and scaling to short int format is performed using ks_phase_degrees2hw(). GE's requirement of only having even numbers in the waveform except for a final odd value (end-of-waveform) is also taken care of here

Note that the preservation of the physical units are done in ks_pg_wave() by setting the correct instruction amplitude to multiply this auto-scaled waveform with in the sequence's hardware memory

Parameters

[out]	iwave	KS_IWAVE (short int array)
[in]	waveform	KS_WAVEFORM
[in]	res	Resolution (i.e. number of samples) in the KS_WAVEFORM
[in]	board	One of XGRAD, YGRAD, ZGRAD, RHO, THETA, OMEGA

Return values

STATUS

SUCCESS or FAILURE

                                                                                         {
  int i;

  if (board != THETA) {
    float absmax = ks_waveform_absmax(waveform, res);
    for (i = 0; i < res; i++) {
      iwave[i] = ((short) (max_pg_wamp * waveform[i] / absmax)) & ~WEOS_BIT;
    }
  } else {
    for (i = 0; i < res; i++) {
      iwave[i] = ((short) ks_phase_degrees2hw(waveform[i])) & ~WEOS_BIT;
    }
  }

  /* set end-of-waveform flag */
  iwave[res - 1] |= WEOS_BIT;

  return SUCCESS;

} /* ks_wave2iwave() */

ks_wave2iwave()

STATUS ks_wave2iwave	(	KS_IWAVE	iwave,
		const KS_WAVE *	wave,
		int	board
	)

(Internal use) Conversion of waveform content in a KS_WAVE sequence object to a short int array for use on hardware

This function is used internally by ks_pg_wave() and there should be no need to call this function directly.

For all boards except THETA, this function auto-scales the (float) values in the .waveform[] field so that the maximum absolute value becomes +/- 32766. The output short int (KS_IWAVE) array is to be copied to hardware. For a KS_WAVE on the THETA board, the necessary phase wraps and scaling to short int format is performed using ks_phase_degrees2hw(). GE's requirement of only having even numbers in the waveform except for a final odd value (end-of-waveform) is also taken care of here

Note that the preservation of the physical units are done in ks_pg_wave() by setting the correct instruction amplitude to multiply this auto-scaled waveform with in the sequence's hardware memory

Parameters

[out]	iwave	KS_IWAVE (short int array)
[in]	wave	KS_WAVE
[in]	board	One of XGRAD, YGRAD, ZGRAD, RHO, THETA, OMEGA

Return values

STATUS

SUCCESS or FAILURE

                                                                     {
  return ks_waveform2iwave(iwave, wave->waveform, wave->res, board);
}

ks_pg_echossp()

WF_PULSE* ks_pg_echossp	(	WF_PULSE *	echo,
		const char *	suffix
	)

Returns the pointer to XTR or RBA for an echo WF_PULSE (internal use)

This function is used internally by ks_pg_read() to get pointers to the XTR and RBA SSP packets for an acquisition window

Parameters

[in]	echo	Pointer to an echo (WF_PULSE)
[in]	suffix	String being "xtr", "rba", or empty

Return values

wfptr

Pointer to a WF_PULSE

                                                             {

  if (!strcmp(suffix, "xtr")) {
    return echo->assoc_pulse;
  } else if (!strcmp(suffix, "rba")) {
    return echo->assoc_pulse->assoc_pulse;
  } else {
    return echo;
  }

}

ks_pg_trap()

STATUS ks_pg_trap	(	KS_TRAP *	trap,
		KS_SEQLOC	loc,
		KS_SEQ_CONTROL *	ctrl
	)

Places a KS_TRAP sequence object on a board at some position in the pulse sequence

This function should be called in the @pg section to place out a KS_TRAP sequence object that creates a static trapezoid in the pulse sequence. The same KS_TRAP object can be freely placed on XGRAD, YGRAD and ZGRAD as many times as desired, by only changing the second argument each time (to avoid waveform overlaps). The second argument is a KS_SEQLOC struct with three fields:

• .board: Choose between XGRAD, YGRAD, ZGRAD (or OMEGA)
• .pos: Absolute time in [us] of the start of the attack ramp of the trapezoid
• .ampscale: A factor that must be in range [-1.0,1.0] that is multiplied with .amp to yield a per-instance (i.e. per-placement) amplitude ([G/cm]). The simplest is to use 1.0, which makes the KS_TRAP object to be placed out on the board as initially designed using ks_eval_trap(). For the OMEGA board, this factor must be 1.0.

Regardless of the order placed out in the @pg section, and on which boards (XGRAD, YGRAD, ZGRAD) the KS_TRAP object is placed, the instance number of the KS_TRAP is automatically sorted in time. If two instances of one KS_TRAP occur at the same time (.pos) on different boards, XGRAD comes before YGRAD, which comes before ZGRAD. These abstract, sorted, instance numbers are used by ks_scan_***() functions in scan() to refer to a specific instance of a KS_TRAP object in the sequence

If the .duration field in the KS_TRAP object is 0, ks_pg_trap() will return SUCCESS and quietly ignore placing it out. This is a part of the mechanism that setting the .duration field to 0 in cveval() should eliminate its existance in both timing calulations and in the pulse sequence generation in @pg

When a trapezoid is placed on OMEGA, neither the designed amplitude (the .amp field in KS_TRAP) nor the .ampscale (in KS_SEQLOC) has an effect on the final frequency modulation. Instead the run-time amplitude of a KS_TRAP object on the OMEGA board is controlled in scan() via a function called ks_scan_omegatrap_hz()

GENERAL NOTE: It is a requirement that the function in the @pg section containing all ks_pg_***() calls is also called exactly once in cveval() after the calls to the corresponding ks_eval_***() functions that design the KS_*** sequence objects. Each ks_pg_***() will throw an error if this has not been done.

Parameters

[in,out]	trap	Pointer to a KS_TRAP sequence object
[in]	loc	KS_SEQLOC struct to specify when and where to place the KS_TRAP
[in,out]	ctrl	Pointer to the KS_SEQ_CONTROL struct corresponding to the sequence module for this KS_TRAP

Return values

STATUS

SUCCESS or FAILURE

                                                                      {
  float boardmax;
  char boardc[8] = "xyz---o";

  boardmax = ks_syslimits_gradtarget(loggrd, loc.board); /* returns 1.0 for OMEGA board */

  /* checking for NULL pointers */
  if (trap == NULL) {
    return ks_error("ks_pg_trap: First argument is NULL");
  }
  /* duration of 0 should not throw an error as this is a sign of that it has not been set up
     or has manually been disabled this way */
  if (trap->duration == 0) {
    return SUCCESS;
  }

  if (trap->description == NULL || trap->description[0] == 0 || trap->description[0] == ' ') {
    return ks_error("ks_pg_trap: Invalid description ('%s')", trap->description);
  }

#ifdef IPG
  /* TGT: Don't place anything on hardware if ctrl->duration = 0.
     This is in concert with:
     - not performing createseq() in KS_SEQLENGTH if seqctrl.duration = 0
     - not playing sequence modules in scan() using ks_scan_playsequence() if seqctrl.duration = 0
     */
  if (ctrl->duration == 0) {
    return ks_error("%s(%s): Refusing to place trap since seqctrl.duration = 0 (indicating `%s` not to be played in scan())", __FUNCTION__, trap->description, ctrl->description);
  }
#endif

  /* input validation */
  if ((trap->ramptime % 4) || (trap->plateautime % 4) || (trap->duration % 4)) {
    ks_error("ks_pg_trap(%s): All timing parameters must be divisible by 4", trap->description);
    return FAILURE;
  }

  if ((trap->ramptime < 4) || (trap->plateautime < 4) || (trap->duration < 4)) {
    ks_error("ks_pg_trap(%s): All timing parameters must be at least 4 us", trap->description);
    return FAILURE;
  }

  if (isNaN(loc.ampscale)) {
    return ks_error("ks_pg_trap(%s): loc.ampscale NaN", trap->description);
  }

  if (loc.pos < GRAD_UPDATE_TIME || loc.pos > 4e6) {
    ks_error("ks_pg_trap(%s): Invalid position %d, it must be between 4us and 4s", trap->description, loc.pos);
    return FAILURE;
  }

  if (loc.board == OMEGA && !areSame(loc.ampscale,1.0)) {
    return ks_error("ks_pg_trap(%s): ampscale must be +1.0 for OMEGA", trap->description);
  }

  if (loc.ampscale < -1.0 || loc.ampscale > 1.0) {
    ks_error("ks_pg_trap(%s): Invalid ampscale %g, it must be between -1.0 and 1.0", trap->description, loc.ampscale);
    return FAILURE;
  }

  if (loc.board != XGRAD && loc.board != YGRAD && loc.board != ZGRAD && loc.board != OMEGA) {
    ks_error("ks_pg_trap(%s): Invalid board code %d, it must be %d (XGRAD), %d (YGRAD), %d (ZGRAD) or %d (OMEGA)", trap->description, loc.board, XGRAD, YGRAD, ZGRAD, OMEGA);
    return FAILURE;
  }

  if (fabs(trap->amp * loc.ampscale) > boardmax) {
    ks_error("ks_pg_trap(%s): trapezoid amplitude %g exceeds maximum (%g) for board %c", trap->description, trap->amp * loc.ampscale, boardmax, boardc[loc.board]);
    return FAILURE;
  }

  loc.pos = RUP_GRD(loc.pos);

#ifdef IPG
  {

    int i;

    char tmpstr[KS_DESCRIPTION_LENGTH + 7];
    tmpstr[KS_DESCRIPTION_LENGTH + 7 - 1] = 0;

    if (trap->base.ngenerated >= trap->base.ninst) {
      ks_error("ks_pg_trap @tgt(%s): the number of instances generated on the target exceeds the number of ones generated on the host", trap->description);
      return FAILURE;
    }

    if (!ctrl->gradrf.is_cleared_on_tgt) /* Reset gradrfctrl on tgt to remove dead pointers copied from host. */
    {
      ks_tgt_reset_gradrfctrl(&ctrl->gradrf);
    }

    /* TODO: consider freeing memory if ngenerated is zero -- EA */

    if (trap->wfpulse == NULL) {
      WF_PULSE wfInit = INITPULSE;

      trap->wfpulse = (WF_PULSE **) AllocNode(8 * sizeof(WF_PULSE *)); /* X, Y, Z, (OMEGA = 6). Not applicable to other boards */

      for (i = XGRAD; i <= OMEGA; i++) {

        if (i == XGRAD || i == YGRAD || i == ZGRAD || i == OMEGA) {

          trap->wfpulse[i] = (WF_PULSE *) AllocNode(3 * sizeof(WF_PULSE)); /* attack, plateau, decay */

          /* init pulse structure */
          trap->wfpulse[i][G_ATTACK] = wfInit;
          trap->wfpulse[i][G_PLATEAU] = wfInit;
          trap->wfpulse[i][G_DECAY] = wfInit;

          /* Name for WF_PULSEs */
          sprintf(tmpstr, "%s.%ca", trap->description, boardc[i]); pulsename(&(trap->wfpulse[i][G_ATTACK]), tmpstr);
          sprintf(tmpstr, "%s.%c", trap->description,  boardc[i]); pulsename(&(trap->wfpulse[i][G_PLATEAU]), tmpstr);
          sprintf(tmpstr, "%s.%cd", trap->description, boardc[i]); pulsename(&(trap->wfpulse[i][G_DECAY]), tmpstr);

          createramp(&(trap->wfpulse[i][G_ATTACK]), (WF_PROCESSOR) i, trap->ramptime, 0, max_pg_wamp,
                     maxGradRes * (trap->ramptime / GRAD_UPDATE_TIME), 1.0);
          createconst(&(trap->wfpulse[i][G_PLATEAU]), (WF_PROCESSOR) i, trap->plateautime, max_pg_wamp);
          createramp(&(trap->wfpulse[i][G_DECAY]), (WF_PROCESSOR) i, trap->ramptime, max_pg_wamp, 0,
                     maxGradRes * (trap->ramptime / GRAD_UPDATE_TIME), 1.0);

          linkpulses(3, &(trap->wfpulse[i][G_PLATEAU]), &(trap->wfpulse[i][G_ATTACK]), &(trap->wfpulse[i][G_DECAY]));

        } else {

          trap->wfpulse[i] = NULL;

        }

      } /* per board */

    } /* wfpulse == NULL */


    /* allocate the array of WFINSTANCE's if needed */
    if (!trap->wfi) {
      trap->wfi = (KS_WFINSTANCE *) AllocNode(trap->base.ninst * sizeof(KS_WFINSTANCE));
    }

    /* Set instruction amplitudes at the proper position and board */
    {
      const int corrected_pos = loc.pos + (loc.board == OMEGA)*psd_rf_wait;
      /* creating new instructions */
      createinstr(&(trap->wfpulse[loc.board][G_ATTACK]),
                  corrected_pos,
                  trap->ramptime,
                  (int)(trap->amp * loc.ampscale * MAX_PG_IAMP / boardmax));
      createinstr(&(trap->wfpulse[loc.board][G_PLATEAU]),
                  corrected_pos + trap->ramptime,
                  trap->plateautime,
                  (int)(trap->amp * loc.ampscale * MAX_PG_IAMP / boardmax));
      createinstr(&(trap->wfpulse[loc.board][G_DECAY]),
                  corrected_pos + trap->ramptime + trap->plateautime,
                  trap->ramptime,
                  (int)(trap->amp * loc.ampscale * MAX_PG_IAMP / boardmax));
    }

    /* initializing the corresponding KS_WFINSTANCE */
    trap->wfi[trap->base.ngenerated].boardinstance = trap->wfpulse[loc.board][G_PLATEAU].ninsts - 1; /* zero based */
    trap->wfi[trap->base.ngenerated].wf = &(trap->wfpulse[loc.board][G_PLATEAU]);
    trap->wfi[trap->base.ngenerated].loc = loc;

    trap->base.ngenerated++;

    /* sort after the last instance is generated */
    if (trap->base.ngenerated == trap->base.ninst) {
      ks_sort_wfi_by_timeboard(trap->wfi, trap->base.ninst);
    }
  }
#else /* TGT(IPG) or HOST */
  {
    /* HOST */

    trap->locs[trap->base.ninst] = loc;

    /* update instance counter on host only. This counter is used to allocate the right amount of WFINSTANCEs on IPG */
    trap->base.ninst++;

    /* for trap, we also need to keep track of #instances per X, Y, Z for gradient heating calculations.
       As this needs to be done in HOST before the IPG (target), we can't use the wfi[...].boardinstance or .loc information above for this */
    if (loc.board == XGRAD || loc.board == YGRAD || loc.board == ZGRAD)
      trap->gradnum[loc.board]++;
  }

#endif /* IPG */
    /* register this KS_TRAP for later heating calculations */
    {
      STATUS status = ks_eval_addtraptogradrfctrl(&ctrl->gradrf, trap);
      if (status != SUCCESS) return status;
    }
  return SUCCESS;

} /* ks_pg_trap */

ks_pg_read()

STATUS ks_pg_read	(	KS_READ *	read,
		int	pos,
		KS_SEQ_CONTROL *	ctrl
	)

Places a KS_READ sequence object at some position in the pulse sequence

This function should be called in the @pg section to place out a KS_READ sequence object that creates an acquisition window in the pulse sequence. The same KS_READ object can be freely placed as many times as desired, by only changing the second argument each time (to avoid overlaps). The second argument is an integer with the absolute time in [us] of the start of the acquisition. System gradient delays are accounted for in ks_pg_read() by internally adjusting the position by adding the system variable psd_grd_wait to the position value. This assures the gradients boards and acquisition window are in sync on the MR system.

Regardless of the order the acquisition windows are placed out in the @pg section, the instance number of the KS_READ is automatically sorted in time

If the .duration field in the KS_READ object is 0, ks_pg_read() will return SUCCESS and quietly ignore placing it out. This is a part of the mechanism that setting the .duration field to 0 in cveval() should eliminate its existance in both timing calulations and in the pulse sequence generation in @pg

GENERAL NOTE: It is a requirement that the function in the @pg section containing all ks_pg_***() calls is also called exactly once in cveval() after the calls to the corresponding ks_eval_***() functions that design the KS_*** sequence objects. Each ks_pg_***() will throw an error if this has not been done.

Parameters

[in,out]	read	Pointer to a KS_READ sequence object
[in]	pos	Absolute time in [us] when to start data acquisition
[in,out]	ctrl	Pointer to the KS_SEQ_CONTROL struct corresponding to the sequence module for this KS_READ

Return values

STATUS

SUCCESS or FAILURE

                                                                {
#ifdef IPG
  int acqwin_start;
  int placementindx;
  long dab_pos;
  char tmpstr[KS_DESCRIPTION_LENGTH + 7];
#endif
  STATUS status;

  /* duration of 0 should not throw an error as this is a sign of that it has not been set up or has manually been disabled this way */
  if (read->duration == 0) {
    return SUCCESS;
  }

#ifdef IPG
  {
    tmpstr[KS_DESCRIPTION_LENGTH + 7 - 1] = 0;

    if (read->base.ngenerated >= read->base.ninst) {
      ks_error("ks_pg_read @tgt(%s): the number of instances generated on the target exceeds the number of ones generated on the host", read->description);
      return FAILURE;
    }

    if (!ctrl->gradrf.is_cleared_on_tgt) { /* Reset gradrfctrl on tgt to remove dead pointers copied from host. */
      ks_tgt_reset_gradrfctrl(&ctrl->gradrf);
    }

    if (read->echo == NULL) {
      /* this relies on that we have run the sequence in cveval() (i.e. on host) before to get proper grad.ninst */
      read->echo = (WF_PULSE *) AllocNode(read->base.ninst * sizeof(WF_PULSE));
    }

    placementindx = read->base.ngenerated; /* not sorted in time, but in placement order */

    acqwin_start = pos + psd_grd_wait;

    if (placementindx == 0 || read->filt.tdaq > 200) {
      dab_pos = DEFAULTPOS; /* results in 200 us before RBA (DEFAULTPOS is defined as 0. See: /ESE_.../psd/include/private/pulsegen.h) */
    } else {
      /* For small matrix sizes, the acq window is so short that the DAB packet
         for current lobe may collide with the RBA belonging to the previous lobe.
         We are not allowed to decrease the DAB-RBA distance below 200us. Instead,
         let's put it right after the end of the previous XTR pulse.
         With the default XTR-RBA offset of 143us, and since the RBA-RBA distance
         is equal to read->grad.duration, we will get a DAB-RBA offset of
      acqwin_duration + 143us - 17us (XTR duration)
      */
      dab_pos = pbegallssp(ks_pg_echossp(&read->echo[placementindx - 1], "xtr"), 0) + 32 /* LONG_DAB_length = 31 */;
      if (dab_pos + 200 > acqwin_start)
        dab_pos = DEFAULTPOS; /* fallback to default pos. Perhaps the readouts were not placed out in time order in the PSD ? */
    }

    /* name the ACQ pulse */
    sprintf(tmpstr, "%s%03d", read->description, placementindx); pulsename(&(read->echo[placementindx]), tmpstr);

    if (read->filt.fslot == KS_NOTSET) {
      /* add 'return' before ks_error once we've got an answer from GE regarding acqq and setrfltrs() */
      ks_error("ks_pg_read @tgt(%s): WARNING no filter slot assigned. First run setfilter(&read.filt)", read->description);
    }

    /* place the ACQ pulse */
    acqq_longdab(&(read->echo[placementindx]),
         (long) acqwin_start,
         (long) dab_pos, /* DAB */
         (long) DEFAULTPOS, /* XTR */
         read->filt.fslot /* filter slot */);

    read->base.ngenerated++;

    /* sort after the last instance is generated */
    if (read->base.ngenerated == read->base.ninst) {
      ks_sort_wfp_by_time(read->echo, read->base.ninst);
    }

    /* Associate this echo with a global filter slot number
       This number is generated by the GE function setfilter() in e.g. predownload(), before this function is called.
       For main sequences, there is also the wrapper function GEReq_predownload_setfilter() */
    if (read->filt.fslot >= 0 && read->filt.fslot <= MAX_FILTER_SLOT) {
      setrfltrs((int) read->filt.fslot, &(read->echo[placementindx]));
    }

  }
#else /* IPG */
  {
    read->pos[read->base.ninst] = pos;
    read->base.ninst++; /* update acq counter on host */
  }
#endif /* IPG */

  status = ks_eval_addreadtogradrfctrl(&ctrl->gradrf, read);
  if (status != SUCCESS) return status;
  return SUCCESS;
}

ks_pg_phaser()

STATUS ks_pg_phaser	(	KS_PHASER *	phaser,
		KS_SEQLOC	loc,
		KS_SEQ_CONTROL *	ctrl
	)

Places a KS_PHASER sequence object on a board at some position in the pulse sequence

This function should be called in the @pg section to place out a KS_PHASER sequence object that creates a dynamic trapezoid for phase encoding. For 3D applications, two different KS_PHASER objects should have been designed by calling ks_eval_phaser() on each KS_PHASER as FOV and resolution typically differ for the two phase encoding directions. The same KS_PHASER object can be freely placed on XGRAD, YGRAD and ZGRAD as many times as desired, by only changing the second argument each time (to avoid waveform overlaps). For Cartesian applications, phase encoding gradients such as KS_PHASER are typically placed out on YGRAD (phase encoding axis), for 3D also on ZGRAD. For 3D, the KS_PHASER object may embed a slice rephaser (static trapezoid) by setting .areaoffset to a non-zero value (see ks_eval_phaser()). The second argument is a KS_SEQLOC struct with three fields:

• .board: Choose between XGRAD, YGRAD, ZGRAD
• .pos: Absolute time in [us] of the start of the attack ramp of the phase encoding trapezoid
• .ampscale: For KS_PHASER objects, this must be 1.0. If not, ks_pg_phaser() will throw an error. Amplitude control should solely be done in scan using ks_scan_phaser_toline() and ks_scan_phaser_fromline().

Regardless of the order placed out in the @pg section, and on which boards (XGRAD, YGRAD, ZGRAD) the KS_PHASER object is placed, the instance number of the KS_PHASER is automatically sorted in time. If two instances of one KS_PHASER occur at the same time (.pos) on different boards, XGRAD comes before YGRAD, which comes before ZGRAD. These abstract, sorted, instance numbers are used by ks_scan_***() functions in scan() to refer to a specific instance of a KS_PHASER object in the sequence

If the .duration field in the KS_PHASER object is 0, ks_pg_phaser() will return SUCCESS and quietly ignore placing it out. This is a part of the mechanism that setting the .duration field to 0 in cveval() should eliminate its existance in both timing calulations and in the pulse sequence generation in @pg

GENERAL NOTE: It is a requirement that the function in the @pg section containing all ks_pg_***() calls is also called exactly once in cveval() after the calls to the corresponding ks_eval_***() functions that design the KS_*** sequence objects. Each ks_pg_***() will throw an error if this has not been done.

Parameters

[in,out]	phaser	Pointer to a KS_PHASER sequence object
[in]	loc	KS_SEQLOC struct to specify when and where to place the KS_PHASER
[in,out]	ctrl	Pointer to the KS_SEQ_CONTROL struct corresponding to the sequence module for this KS_PHASER

Return values

STATUS

SUCCESS or FAILURE

                                                                            {


  /* loc.ampscale != 1.0 is not allowed  */
  if (!areSame(loc.ampscale,1.0)) {
    return ks_error("ks_pg_phaser(%s): field 'ampscale' in 2nd arg must be 1.0", phaser->grad.description);
  }

  /* loc.board must be one of XGRAD, YGRAD, ZGRAD  */
  if (loc.board != XGRAD && loc.board != YGRAD && loc.board != ZGRAD) {
    return ks_error("ks_pg_phaser(%s): field 'board' in 2nd arg must be XGRAD, YGRAD, or ZGRAD", phaser->grad.description);
  }

  return ks_pg_trap(&phaser->grad, loc, ctrl);

}

ks_pg_readtrap()

STATUS ks_pg_readtrap	(	KS_READTRAP *	readtrap,
		KS_SEQLOC	loc,
		KS_SEQ_CONTROL *	ctrl
	)

Places a KS_READTRAP sequence object on a board at some position in the pulse sequence

This function should be called in the @pg section to place out a KS_READTRAP sequence object consisting of a trapezoid (KS_TRAP) and an acquisition window (KS_READ). The same KS_READTRAP object can be freely placed on XGRAD, YGRAD and ZGRAD as many times as desired, by only changing the second argument each time (to avoid waveform overlaps). For Cartesian applications, readouts such as KS_READTRAP are typically placed on XGRAD (frequency encoding axis). The second argument is a KS_SEQLOC struct with three fields:

• .board: Choose between XGRAD, YGRAD, ZGRAD
• .pos: Absolute time in [us] of the start of the attack ramp of the readout trapezoid
• .ampscale: For KS_READTRAP objects, this must be either +1.0 or -1.0 so that the FOV is not altered. Negative amplitudes will automatically be taken into account in ks_scan_offsetfov() to create the necessary frequency offset

Regardless of the order placed out in the @pg section, and on which boards (XGRAD, YGRAD, ZGRAD) the KS_READTRAP object is placed, the instance number of the KS_READTRAP is automatically sorted in time. If two instances of one KS_READTRAP occur at the same time (.pos) on different boards, XGRAD comes before YGRAD, which comes before ZGRAD. These abstract, sorted, instance numbers are used by ks_scan_***() functions in scan() to refer to a specific instance of a KS_READTRAP object in the sequence.

If the .duration field in the KS_READTRAP object is 0, ks_pg_readtrap() will return SUCCESS and quietly ignore placing it out. This is a part of the mechanism that setting the .duration field to 0 in cveval() should eliminate its existance in both timing calulations and in the pulse sequence generation in @pg

GENERAL NOTE: It is a requirement that the function in the @pg section containing all ks_pg_***() calls is also called exactly once in cveval() after the calls to the corresponding ks_eval_***() functions that design the KS_*** sequence objects. Each ks_pg_***() will throw an error if this has not been done.

Parameters

[in,out]	readtrap	Pointer to a KS_READTRAP sequence object
[in]	loc	KS_SEQLOC struct to specify when and where to place the KS_READTRAP
[in,out]	ctrl	Pointer to the KS_SEQ_CONTROL struct corresponding to the sequence module for this KS_READTRAP

Return values

STATUS

SUCCESS or FAILURE

                                                                                  {
  KS_SEQLOC omegaloc;

  /* checking for NULL pointers */
  if (readtrap == NULL) {
    return ks_error("%s: First argument is NULL", __FUNCTION__);
  }
  /* duration of 0 should not throw an error as this is a sign of that it has not been set up
     or has manually been disabled this way */
  if (readtrap->grad.duration == 0) {
    return SUCCESS;
  }
  if (readtrap->grad.description == NULL || readtrap->grad.description[0] == 0 || readtrap->grad.description[0] == ' ') {
    return ks_error("%s: Invalid description ('%s')", __FUNCTION__, readtrap->grad.description);
  }

#ifdef IPG
  /* TGT (IPG): Don't place anything on hardware if ctrl->duration = 0.
      This is in concert with:
      - not performing createseq() in KS_SEQLENGTH if seqctrl.duration = 0
     - not playing sequence modules in scan() using ks_scan_playsequence() if seqctrl.duration = 0
     */
  if (ctrl->duration == 0) {
    return ks_error("%s(%s): Refusing to place readtrap since seqctrl.duration = 0 (indicating `%s` not to be played in scan())", __FUNCTION__, readtrap->grad.description, ctrl->description);
  }
#endif

  if (!areSame(loc.ampscale, 1.0) && !areSame(loc.ampscale, -1.0)) {
    ks_error("%s(%s): .ampscale %g must be exactly +1 or -1 for readout gradients", __FUNCTION__, readtrap->grad.description, loc.ampscale);
    return FAILURE;
  }

  /*** acq ***/
  if (ks_pg_read(&readtrap->acq, loc.pos + readtrap->acqdelay, ctrl) == FAILURE)
    return FAILURE;


  /*** trapezoid ***/
  if (ks_pg_trap(&readtrap->grad, loc, ctrl) == FAILURE)
    return FAILURE;

  /* also place the omega wave form for rampsampled cases */
  if (readtrap->omega.duration > 0) {
    /* omega trapezoid matching the readout lobe to allow for FOV offsets in freq dir. with ramp sampling */
    omegaloc.board = OMEGA;
    omegaloc.pos = loc.pos;
    omegaloc.ampscale = 1.0; /* just unity value for conformance. It does not matter during scanning, since ks_scan_omegahz() ignores this value */
    if (ks_pg_trap(&readtrap->omega, omegaloc, ctrl) == FAILURE)
      return FAILURE;
  }


  return SUCCESS;


} /* ks_pg_readtrap */

ks_pg_wave()

STATUS ks_pg_wave	(	KS_WAVE *	wave,
		KS_SEQLOC	loc,
		KS_SEQ_CONTROL *	ctrl
	)

Places a KS_WAVE sequence object on a board at some position in the pulse sequence

This function should be called in the @pg section to place out a KS_WAVE sequence object that creates an arbitrary waveform in the pulse sequence. The same KS_WAVE object can be placed on any board as many times as desired, by only changing the second argument each time (to avoid waveform overlaps). However, the RHO (RF) board should be avoided as this bypasses RF scaling and SAR calculations, providing no control over the flip angle. For RF waveforms, always use KS_RF (or KS_SELRF). The second argument is a KS_SEQLOC struct with three fields:

• .board: Choose between XGRAD, YGRAD, ZGRAD, OMEGA, THETA
• .pos: Absolute time in [us] of the start of the waveform. For RF, OMEGA and THETA, pos_rf_wait will be added to this time to take system delays into account
• .ampscale: For gradient boards, this factor must be in range [-1.0,1.0] that is multiplied with the waveform to yield a per-instance (i.e. per-placement) amplitude ([G/cm]). For THETA, only values of +1.0 and -1.0 is allowed, and for OMEGA only 1.0 is allowed

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

• gradient boards (XGRAD, YGRAD, ZGRAD), the unit is [G/cm]
• THETA board, the unit is [degrees]
• RF (RHO) and OMEGA boards, the units are arbitrary (c.f. ks_eval_rf() and ks_eval_wave()). Don't call ks_pg_wave() directly to place a KS_WAVE on the RF board

When a waveform is placed on OMEGA, neither the waveform amplitude nor the .ampscale (in KS_SEQLOC) affects the final frequency modulation. Instead the run-time amplitude of a KS_WAVE object on the OMEGA board is controlled in scan() via a function called ks_scan_omegawave_hz(), where the largest value in the field .waveform[] in the KS_WAVE will correspond to the value in [Hz] provided.

If the .duration field in the KS_WAVE object is 0, ks_pg_wave() will return SUCCESS and quietly ignore placing it out. This is a part of the mechanism that setting the .duration field to 0 in cveval() should eliminate its existance in both timing calulations and in the pulse sequence generation in @pg

All KS_WAVE objects are double buffered in ks_pg_wave() so that waveforms can be replaced in run-time (scan()) using ks_scan_wave2hardware()

Regardless of the order placed out in the @pg section, and on which boards (XGRAD, YGRAD, ZGRAD) the KS_WAVE object is placed, the instance number of the KS_WAVE is automatically sorted in time. If two instances of one KS_WAVE occur at the same time (.pos) on different boards, XGRAD comes before YGRAD, which comes before ZGRAD. These abstract, sorted, instance numbers are used by ks_scan_***() functions in scan() to refer to a specific instance of a KS_WAVE object in the sequence.

GENERAL NOTE: It is a requirement that the function in the @pg section containing all ks_pg_***() calls is also called exactly once in cveval() after the calls to the corresponding ks_eval_***() functions that design the KS_*** sequence objects. Each ks_pg_***() will throw an error if this has not been done.

Parameters

[in,out]	wave	Pointer to a KS_WAVE sequence object
[in]	loc	KS_SEQLOC struct to specify when and where to place the KS_WAVE
[in,out]	ctrl	Pointer to the KS_SEQ_CONTROL struct corresponding to the sequence module for this KS_WAVE

Return values

STATUS

SUCCESS or FAILURE

                                                                      {
  float boardmax;
  char boardc[8] = "xyzrrto"; /* x,y,z,rho1,rho2,theta,omega */
  float waveamp = ks_wave_absmax(wave); /* maximum amplitude in wave (in its own units, like e.g. [G/cm] or [degrees]) */

  boardmax = ks_syslimits_gradtarget(loggrd, loc.board); /* returns 1.0 for non-gradients boards */

  /* checking for NULL pointers */
  if (wave == NULL) {
    return ks_error("ks_pg_wave: First argument is NULL");
  }
  /* duration of 0 should not throw an error as this is a sign of that it has not been set up
     or has manually been disabled this way */
  if (wave->duration == 0) {
    return SUCCESS;
  }
  if (wave->description == NULL || wave->description[0] == 0 || wave->description[0] == ' ') {
    return ks_error("ks_pg_wave: Invalid description ('%s')", wave->description);
  }

#ifdef IPG
  /* TGT: Don't place anything on hardware if ctrl->duration = 0.
     This is in concert with:
     - not performing createseq() in KS_SEQLENGTH if seqctrl.duration = 0
     - not playing sequence modules in scan() using ks_scan_playsequence() if seqctrl.duration = 0
     */
  if (ctrl->duration == 0) {
    return ks_error("%s(%s): Refusing to place wave since seqctrl.duration = 0 (indicating `%s` not to be played in scan())", __FUNCTION__, wave->description, ctrl->description);
  }

  if (!ctrl->gradrf.is_cleared_on_tgt) /* Reset gradrfctrl on tgt to remove dead pointers copied from host. */
  {
    ks_tgt_reset_gradrfctrl(&ctrl->gradrf);
  }

#endif

  /* input validation */
  if (wave->duration % 4) {
    return ks_error("ks_pg_wave(%s): field 'duration' (%d) must be divisible by 4", wave->description, wave->duration);
  }
  if (wave->res == 0) {
    return ks_error("ks_pg_wave(%s): field 'res' cannot be 0", wave->description);
  }
  if (wave->res % 2) {
    return ks_error("ks_pg_wave(%s): field 'res' (%d) must be even ", wave->description, wave->res);
  }
  if (wave->duration % wave->res) {
    return ks_error("ks_pg_wave(%s): field 'duration' (%d) must be divisible by 'res' %d", wave->description, wave->duration, wave->res);
  }
  if (loc.board == XGRAD || loc.board == YGRAD || loc.board == ZGRAD) {
    if ((wave->duration / wave->res) % GRAD_UPDATE_TIME) {
      return ks_error("ks_pg_wave(%s): field 'duration' (%d) must a multiple of 4 times 'res' (%d) for gradient boards", wave->description, wave->duration, wave->res);
    }
    if (wave->gradwave_units == KS_GRADWAVE_ABSOLUTE && !areSame(loc.ampscale,1.0)) {
      return ks_error("ks_pg_wave(%s): ampscale must be +1.0 for gradwave with absolute units", wave->description);
    }
  } else {
    if ((wave->duration / wave->res) % RF_UPDATE_TIME) {
      return ks_error("ks_pg_wave(%s): field 'duration' (%d) must a multiple of 2 times 'res' (%d) for non-gradient boards", wave->description, wave->duration, wave->res);
    }
  }

  if (isNaN(loc.ampscale)) {
    return ks_error("ks_pg_wave(%s): loc.ampscale NaN", wave->description);
  }
  if (loc.pos < GRAD_UPDATE_TIME || loc.pos > 4e6) {
    return ks_error("ks_pg_wave(%s): Invalid position %d, it must be between 4us and 4s", wave->description, loc.pos);
  }
  if (loc.board == OMEGA && !areSame(loc.ampscale,1.0)) {
    return ks_error("ks_pg_wave(%s): ampscale must be +1.0 for OMEGA", wave->description);
  }
  if (loc.board == THETA && !areSame(loc.ampscale,1.0) && !areSame(loc.ampscale,-1.0)) {
    return ks_error("ks_pg_wave(%s): ampscale must be +1.0 or -1.0 for THETA", wave->description);
  }
  if (loc.ampscale < -1.0 || loc.ampscale > 1.0) {
    return ks_error("ks_pg_wave(%s): Invalid ampscale %g, it must be between -1.0 and 1.0", wave->description, loc.ampscale);
  }
  if (fabs(waveamp * loc.ampscale) > boardmax && loc.board != THETA) {
    return  ks_error("ks_pg_wave(%s): wave amplitude (%.2f) exceeds maximum (%g) for board %c", wave->description, waveamp * loc.ampscale, boardmax, boardc[loc.board]);
  }

  loc.pos = RUP_GRD(loc.pos);


#ifdef HOST_TGT

  /* HOST */

  wave->locs[wave->base.ninst] = loc;

  /* update instance counter on host only. This counter is used to allocate the right amount of WFINSTANCEs on IPG */
  wave->base.ninst++;

  /* for wave, we also need to keep track of #instances per X, Y, Z for gradient heating calculations.
     As this needs to be done in HOST before the IPG (target), we can't use the wfi[...].boardinstance or .loc information above for this */
  if (loc.board == XGRAD || loc.board == YGRAD || loc.board == ZGRAD) {
    wave->gradnum[loc.board]++;
  }

#else

  {

    int i;
    int wave_ptr, isrf, iamp;
    char tmpstr[KS_DESCRIPTION_LENGTH + 7];

    if (wave->base.ngenerated >= wave->base.ninst) {
      ks_error("ks_pg_wave @tgt(%s): the number of instances generated on the target (%d) exceeds the number of ones generated on the host (%d)", wave->description, wave->base.ngenerated + 1, wave->base.ninst);
      return FAILURE;
    }

    /* first call on TGT, allocate WF_PULSE * array where each element corresponds to one board */
    if (wave->wfpulse == NULL) {
      wave->wfpulse = (WF_PULSE **) AllocNode(7 * sizeof(WF_PULSE *)); /* WF pointers for all boards (XGRAD->OMEGA) */
    } /* wfpulse == NULL */


    /* first call on TGT using this loc.board, make waveform memory (double buffered) */
    if (wave->wfpulse[loc.board] == NULL) {
      WF_PULSE wfInit = INITPULSE;
      KS_IWAVE iwave;

      wave->wfpulse[loc.board] = (WF_PULSE *) AllocNode(KS_WF_SIZE * sizeof(WF_PULSE)); /* KS_WF_SIZE (3) to allow for double buffering */

      for (i = KS_WF_MAIN; i < KS_WF_SIZE; i++)
        wave->wfpulse[loc.board][i] = wfInit;

      sprintf(tmpstr, "%s.%c", wave->description, boardc[loc.board]);      pulsename(&(wave->wfpulse[loc.board][KS_WF_MAIN]), tmpstr);
      sprintf(tmpstr, "%s_buf1.%c", wave->description, boardc[loc.board]); pulsename(&(wave->wfpulse[loc.board][KS_WF_BUF1]), tmpstr);
      sprintf(tmpstr, "%s_buf2.%c", wave->description, boardc[loc.board]); pulsename(&(wave->wfpulse[loc.board][KS_WF_BUF2]), tmpstr);

      /* wave -> short int wave for hardware use. All waveforms but THETA are autoscaled to +/- max_pg_wamp (32766)*/
      if (ks_wave2iwave(iwave, wave, loc.board) == FAILURE)
        return FAILURE;

      /* reserve hardware memory to allow for double buffering */
      for (i = KS_WF_MAIN; i <= KS_WF_BUF2; i++) {
        createreserve(&wave->wfpulse[loc.board][i], (WF_PROCESSOR) loc.board, wave->res);
        wave->wfpulse[loc.board][i].type = TYPEXTERNAL;
        movewaveimm(iwave, &wave->wfpulse[loc.board][i], (int) 0, wave->res, TOHARDWARE);
      }

    } /* wfpulse[loc.board] == NULL */


    /* create instruction at the current position */
    isrf = loc.board == RHO || loc.board == RHO2 || loc.board == THETA || loc.board == OMEGA;

    if (loc.board == THETA)
      iamp = (int)(loc.ampscale * MAX_PG_IAMP);
    else
      iamp = (int)((waveamp * loc.ampscale / boardmax) * MAX_PG_IAMP);

    createinstr(&wave->wfpulse[loc.board][KS_WF_MAIN],
                (long) (loc.pos + (psd_rf_wait * isrf)),
                (long) wave->duration,
                (long) iamp);

    /* WF instance bookkeeping */
    if (wave->wfi == NULL) {
      wave->wfi = (KS_WFINSTANCE *) AllocNode(wave->base.ninst * sizeof(KS_WFINSTANCE));
    }
    wave->wfi[wave->base.ngenerated].boardinstance = wave->wfpulse[loc.board][KS_WF_MAIN].ninsts - 1;
    wave->wfi[wave->base.ngenerated].wf = wave->wfpulse[loc.board];
    wave->wfi[wave->base.ngenerated].loc = loc;

    /* After instructions have been set, set the wfpulse[KS_WF_MAIN] to the first waveform buffer (_BUF1) */
    getwave(&wave_ptr, &(wave->wfpulse[loc.board][KS_WF_BUF1]));
    setwave(wave_ptr,  &(wave->wfpulse[loc.board][KS_WF_MAIN]), wave->wfi[wave->base.ngenerated].boardinstance);

    wave->base.ngenerated++;

    /* sort after the last instance is generated */
    if (wave->base.ngenerated == wave->base.ninst) {
      ks_sort_wfi_by_timeboard(wave->wfi, wave->base.ninst);
    }

  }

#endif /* IPG or HOST */

  /* register this KS_WAVE for later heating calculations */
  {
    STATUS status = ks_eval_addwavetogradrfctrl(&ctrl->gradrf, wave);
    if (status != SUCCESS) return status;
  }

  return SUCCESS;

} /* ks_pg_wave */

ks_pg_rf()

STATUS ks_pg_rf	(	KS_RF *	rf,
		KS_SEQLOC	loc,
		KS_SEQ_CONTROL *	ctrl
	)

Places a KS_RF sequence object on a board at some position in the pulse sequence

This function should be called in the @pg section to place out a KS_RF sequence object that creates an RF pulse in the pulse sequence. The same KS_RF object can be placed out as many times as desired, by only changing the second argument each time (to avoid waveform overlaps). The second argument is a KS_SEQLOC struct with three fields:

• .board: Ignored. .rfwave will always be placed on RHO. If the resolution of .omegawave is non-zero it will be placed on OMEGA, and correspondingly for .thetawave on THETA
• .pos: Absolute time in [us] of the start of the waveform
• .ampscale: A factor that must be in range [-1.0,1.0] that is multiplied with .amp to yield a per-instance (i.e. per-placement) amplitude. For KS_RF objects this will cause the flip angle to be reduced on a per-instance basis. This can be used to generate a variable flip-angle train of RF pulses using a single KS_RF object. An .ampscale of -1.0 is equivalent to adding a 180 degree RF phase shift to the RF pulse

If the rfwave.duration field in the KS_RF object is 0, ks_pg_rf() will return SUCCESS and quietly ignore placing it out. This is a part of the mechanism that setting the .duration field to 0 in cveval() should eliminate its existance in both timing calulations and in the pulse sequence generation in @pg

As ks_pg_rf() internally calls ks_pg_wave() for its KS_WAVEs, double buffering will be used for all hardware waveforms, allowing waveforms to be replaced in run-time (scan()) using ks_scan_wave2hardware()

Regardless of the order placed out in the @pg section the KS_RF object is placed, the instance number of the KS_RF is automatically sorted in time. These abstract, sorted, instance numbers are used by ks_scan_***() functions in scan() to refer to a specific instance of a KS_RF object in the sequence.

GENERAL NOTE: It is a requirement that the function in the @pg section containing all ks_pg_***() calls is also called exactly once in cveval() after the calls to the corresponding ks_eval_***() functions that design the KS_*** sequence objects. Each ks_pg_***() will throw an error if this has not been done.

When ks_pg_rf() is run in cveval() (on HOST), the field .rfpulse.activity that was first set to 0 by ks_eval_rf() is now set to PSD_APS2_ON + PSD_MPS2_ON + PSD_SCAN_ON by ks_pg_rf(). This triggers the RF functions used in ks_eval_gradrflimits() to include this KS_RF object in RF scaling and SAR calculations. Each time ks_pg_rf() is called, the field .rfpulse.num is incremented after being first set to 0 by ks_eval_rf(). Hence, it is crucial that the sequence generating function (c.f. KS_SEQ_CONTROL) containing all ks_pg_***() calls is executed between the ks_eval_rf() setup call and the call to ks_eval_gradrflimits()

Parameters

[in,out]	rf	Pointer to a KS_RF sequence object
[in]	loc	KS_SEQLOC struct to specify when to place the KS_RF
[in,out]	ctrl	Pointer to the KS_SEQ_CONTROL struct corresponding to the sequence module for this KS_RF

Return values

STATUS

SUCCESS or FAILURE

                                                                {

  /* input validation */
  if (rf == NULL) {
    return ks_error("%s: First argument is NULL", __FUNCTION__);
  }

  /* duration of 0 should not throw an error as this is a sign of that it has not been set up
     or has manually been disabled this way */
  if (rf->rfwave.duration == 0) {
    return SUCCESS;
  }
  if (rf->rfwave.description == NULL || rf->rfwave.description[0] == 0 || rf->rfwave.description[0] == ' ') {
    return ks_error("ks_pg_rf: Invalid description ('%s')", rf->rfwave.description);
  }

#ifdef IPG
  /* TGT: Don't place anything on hardware if ctrl->duration = 0.
     This is in concert with:
     - not performing createseq() in KS_SEQLENGTH if seqctrl.duration = 0
     - not playing sequence modules in scan() using ks_scan_playsequence() if seqctrl.duration = 0
     */
  if (ctrl->duration == 0) {
    return ks_error("%s(%s): Refusing to place RF since seqctrl.duration = 0 (indicating `%s` not to be played in scan())", __FUNCTION__, rf->rfwave.description, ctrl->description);
  }
  /* TGT: make sure (the RF pulses in) the sequence module were a part of the seqcollection when GEReq_eval_rfscaling() was called */
  if (ctrl->rfscalingdone == FALSE && ctrl->duration > 0) {
    return ks_error("%s(%s): Missing RF scaling for sequence module with non-zero duration. Add `%s` to seqcollection *before* calling GEReq_eval_rfscaling(seqcollection)", __FUNCTION__, rf->rfwave.description, ctrl->description);
  }

  if (!ctrl->gradrf.is_cleared_on_tgt) /* Reset gradrfctrl on tgt to remove dead pointers copied from host. */
  {
    ks_tgt_reset_gradrfctrl(&ctrl->gradrf);
  }

#endif

  loc.pos = RUP_RF(loc.pos);

  RFEnvelopeWaveformGeneratorCheck(rf->rfwave.description, (WF_PROCESSOR) ks_rhoboard);

  if (rf->omegawave.res) {
    if (rf->omegawave.duration != rf->rfwave.duration) {
      ks_error("ks_pg_rf (%s): The duration of the omega waveform must be equal to the RF duration", rf->rfwave.description);
      return FAILURE;
    }
  }
  if (rf->thetawave.res) {
    if (rf->thetawave.duration != rf->rfwave.duration) {
      ks_error("ks_pg_rf (%s): The duration of the theta waveform must be equal to the RF duration", rf->rfwave.description);
      return FAILURE;
    }
  }

  /* Set ctrl->momentstart if this is an excitation pulse */
  if (rf->role == KS_RF_ROLE_EXC) {
    ctrl->momentstart = RUP_GRD(loc.pos + rf->start2iso); /* RUP_GRD: make sure it is on a 4us raster too for gradient timing calcs */
  }

  /* register this KS_RF for later heating calculations - and do this *before* calls to ks_pg_wave() below (in this function) to avoid double registrations (c.f. ks_eval_addwavetogradrfctrl()).
     N.B.: While RF/sar calcs (ks_eval_rfscaling()) are not affected by this, registering the rf->rfwave both as a part of the RF object and as a separate wave in ctrl->gradrf would otherwise lead to problems for
     ks_gnuplot_seqmodule(). This would cause the RF pulse to show up twice in the plot / pdf / image.
     ks_eval_addwavetogradrfctrl() is called in ks_pg_wave() and checks if this wave also belongs to a parent registered RF pulse in which case the wave will not be registered again */
  {
    STATUS status = ks_eval_addrftogradrfctrl(&ctrl->gradrf, rf);
    if (status != SUCCESS) return status;
  }

#ifdef HOST_TGT

  /* update rfpulse.num counter on host only. We can use this ninst variable as info
     for RF heating calculations */
  rf->rfpulse.num++;

  /* now that we have shown that we are really going to use this pulse, set its
     activity flag to SCAN, APS2, MPS2 */
  rf->rfpulse.activity = PSD_APS2_ON + PSD_MPS2_ON + PSD_SCAN_ON;

#else

  if (areSame(rf->rfpulse.num, 0)) {
    ks_error("ks_pg_rf @tgt(%s): pulsegen was never run on HOST (rf->rfpulse.num = 0)", rf->rfwave.description);
    return FAILURE;
  }

  if (rf->rfpulse.activity == 0) {
    ks_error("ks_pg_rf @tgt(%s): RF pulse with zero activity", rf->rfwave.description);
    return FAILURE;
  }

  /* The values in rf->rfwave.waveform[] are relative (unit-less). The actual amplitude of the RF wave
     is only controlled by rf->amp (which in turn is set by GE's setScale() and indirectly by peakB1()).
     Prepare RF waveform with correct amplitude on TGT side that can be used with ks_pg_wave() to give the right
     RF amplitude, after we have done RF scaling on HOST and hence have a final value for rf->amp.
     The units of this RF waveform, before and after calling ks_wave_multiplywal(), are relative (not [G])
     due to GE's RF scaling process involving e.g. xmtaddScan.
     Look in GERequired.e:GEReq_eval_gradrflimits() for more info on how peakB1() and setScale() are used. */

  ks_wave_multiplyval(&rf->rfwave, rf->amp / ks_wave_absmax(&rf->rfwave));

#endif



  /* place the RF wave */
  loc.board = RHO;
  if (ks_pg_wave(&rf->rfwave, loc, ctrl) == FAILURE)
    return FAILURE;

#ifdef IPG
  /* add SSP RF bits that handles the frequency control and blanking/unblanking the receiver */
  addrfbits(&rf->rfwave.wfpulse[RHO][KS_WF_MAIN], 0, loc.pos + psd_rf_wait, rf->rfwave.duration);
  /* set RF frequency offset */
  setfrequency((int)(rf->cf_offset / TARDIS_FREQ_RES), &rf->rfwave.wfpulse[RHO][KS_WF_MAIN], INSTRALL);
#endif

  /* set ampscale to 1. If you want to scale the omega or theata board, do it seperatly */
  loc.ampscale = 1;

  /* place the OMEGA wave */
  loc.board = OMEGA;
  if (rf->omegawave.res) {
    if (ks_pg_wave(&rf->omegawave, loc, ctrl) == FAILURE)
      return FAILURE;
  }

#ifdef IPG
  if (rf->omegawave.res) {
    /* add SSP RF bits that handles the frequency control and blanking/unblanking the receiver */
    addrfbits(&rf->omegawave.wfpulse[OMEGA][KS_WF_MAIN], 0, loc.pos + psd_rf_wait, rf->omegawave.duration);
  }
#endif

  /* place the THETA wave */
  loc.board = THETA;
  if (rf->thetawave.res) {
    if (ks_pg_wave(&rf->thetawave, loc, ctrl) == FAILURE)
      return FAILURE;
  }

#ifdef IPG
  if (rf->thetawave.res) {
    /* add SSP RF bits that handles the frequency control and blanking/unblanking the receiver */
    addrfbits(&rf->thetawave.wfpulse[THETA][KS_WF_MAIN], 0, loc.pos + psd_rf_wait, rf->thetawave.duration);
  }
#endif

  return SUCCESS;

} /* ks_pg_rf */

ks_pg_selrf()

STATUS ks_pg_selrf	(	KS_SELRF *	selrf,
		KS_SEQLOC	loc,
		KS_SEQ_CONTROL *	ctrl
	)

Places a KS_SELRF sequence object on a gradient (and RF) board at some position in the pulse sequence

This function should be called in the @pg section to place out a KS_SELRF sequence object that creates an RF pulse with associated trapezoids in the pulse sequence. The same KS_SELRF object can be placed out as many times as desired, by only changing the second argument each time (to avoid waveform overlaps). The second argument is a KS_SEQLOC struct with three fields:

• .board: Choose between XGRAD, YGRAD, ZGRAD for the board on which .pregrad, .grad (or .gradwave) and .postgrad should be placed
• .pos: Absolute time in [us] of the start of the .pregrad attack ramp. If .pregrad has zero duration, .pos will in effect refer to the start of the .grad attack ramp
• .ampscale: A factor that must be in range [-1.0,1.0] that is multiplied with rf.rfwave.amp to yield a per-instance (i.e. per-placement) amplitude. For KS_SELRF objects the .ampscale value will be passed on its internal call to ks_pg_rf(), but not to its internal ks_pg_trap() calls. Hence .ampscale will have the same effect for ks_pg_selrf() as for ks_pg_rf(), with no per-instance control of the amplitude of the gradients involved. A reduced .ampscale will cause the flip angle to be reduced on a per-instance basis. This can be used to generate a variable flip-angle train of selective RF pulses using a single KS_SELRF object. An .ampscale of -1.0 is equivalent to adding a 180 degree RF phase shift to the RF pulse

If the .gradwave field has a non-zero resolution, ks_pg_selrf() will place out the .gradwave (KS_WAVE) instead of the .grad (KS_TRAP) during the time the RF pulse is played out. An error is thrown if .gradwave.duration (if .gradwave.res > 0) is not equal to the .rf.rfwave.duration. If .pregrad or .postgrad has zero duration, they will not be placed out. The existance of non-zero .pregrad and .postgrad is determined by ks_eval_selrf() based on .rf.role

As ks_pg_selrf() internally calls ks_pg_wave() for its KS_WAVEs, hardware double buffering will be used for all waveforms, allowing waveforms to be replaced in run-time (scan()) using ks_scan_wave2hardware()

Regardless of the order placed out in the @pg section the KS_SELRF object is placed, the instance number of the KS_SELRF is automatically sorted in time. These abstract, sorted, instance numbers are used by ks_scan_***() functions in scan() to refer to a specific instance of a KS_SELRF object in the sequence.

GENERAL NOTE: It is a requirement that the function in the @pg section containing all ks_pg_***() calls is also called exactly once in cveval() after the calls to the corresponding ks_eval_***() functions that design the KS_*** sequence objects. Each ks_pg_***() will throw an error if this has not been done.

Parameters

[in,out]	selrf	Pointer to a KS_SELRF sequence object
[in]	loc	KS_SEQLOC struct to specify when and where to place the KS_SELRF
[in,out]	ctrl	Pointer to the KS_SEQ_CONTROL struct corresponding to the sequence module for this KS_SELRF

Return values

STATUS

SUCCESS or FAILURE

                                                                         {
  KS_SEQLOC rfloc;
  KS_SEQLOC gradloc;

  if (loc.board != XGRAD && loc.board != YGRAD && loc.board != ZGRAD) {
    return ks_error("%s(%s): loc.board (2nd arg) must be a gradient board", __FUNCTION__, selrf->rf.rfwave.description);
  }

  gradloc = loc; gradloc.ampscale = 1.0;
  rfloc = loc; rfloc.board = RHO;

  /* RF starts after the preselgrad (if present) */
  rfloc.pos += selrf->pregrad.duration;

  /* delay the RF pulse start by the ramptime of the slice sel gradient
     when .gradwave is used, .grad.ramptime will be correctly zero  */
  rfloc.pos += selrf->grad.ramptime;


  /************* generate the RF (incl. optional THETA & OMEGA) *************/

  if (ks_pg_rf(&selrf->rf, rfloc, ctrl) == FAILURE)
    return FAILURE;

  /************************ place gradients *********************************/

  gradloc.ampscale = (selrf->rf.role != KS_RF_ROLE_EXC) ? loc.ampscale2 : 1.0;
  /* Pre-slice sel gradient. Roles: e.g. left crusher or dephasing gradient in bSSFP */
  if (ks_pg_trap(&selrf->pregrad, gradloc, ctrl) == FAILURE)
    return FAILURE;
  gradloc.pos += selrf->pregrad.duration;



  /* slice select gradient */
  gradloc.ampscale = 1.0;
  
  if (selrf->gradwave.res) {
    /* use gradwave (not trapezoid) */

    if (selrf->rf.rfwave.duration != (selrf->gradwave.duration) || (selrf->gradwave.res * GRAD_UPDATE_TIME != selrf->gradwave.duration)) {
      return ks_error("%s(%s): The duration of 'gradwave' (%d [us]) must equal the RF duration (%d [us])", __FUNCTION__,
                      selrf->rf.rfwave.description, selrf->gradwave.duration, selrf->rf.rfwave.duration);
    }

    if (ks_pg_wave(&selrf->gradwave, gradloc, ctrl) == FAILURE)
      return FAILURE;

    gradloc.pos += selrf->gradwave.duration;

  } else {
    /* use trapezoid (not gradwave) */

    if (selrf->grad.plateautime != selrf->rf.rfwave.duration) {
      return ks_error("%s(%s): Plateau time of slice select (%d) != RF duration (%d)", __FUNCTION__, selrf->rf.rfwave.description, selrf->grad.plateautime, selrf->rf.rfwave.duration);
    } else {
      if (ks_pg_trap(&selrf->grad, gradloc, ctrl) == FAILURE)
        return FAILURE;

      gradloc.pos += selrf->grad.duration;
    }

  } /* slice select */


  /* post-slice sel gradient. Roles: e.g. right crusher or refocusing gradient */
  gradloc.ampscale = (selrf->rf.role != KS_RF_ROLE_EXC) ? loc.ampscale2 : 1.0;
  if (ks_pg_trap(&selrf->postgrad, gradloc, ctrl) == FAILURE)
    return FAILURE;
  gradloc.pos += selrf->postgrad.duration;


  return SUCCESS;

} /* ks_pg_selrf */

ks_pg_wait()

STATUS ks_pg_wait	(	KS_WAIT *	wait,
		KS_SEQLOC	loc,
		KS_SEQ_CONTROL *	ctrl
	)

Places a KS_WAIT sequence object on all boards at some position in the pulse sequence

This function should be called in the @pg section to place out a KS_WAIT sequence object that creates a wait pulse. The same KS_WAIT object can be placed out as many times as desired, by only changing the second argument each time (to avoid waveform overlaps). The second argument is a KS_SEQLOC struct with three fields:

• .board: Ignored
• .pos: Absolute time in [us] of the start of the wait pulse
• .ampscale: Ignored

This function will insert a deadtime of duration equal to the .duration field in the KS_WAIT object at position .pos. This delay can be changed in run-time by calling ks_scan_wait().

GENERAL NOTE: It is a requirement that the function in the @pg section containing all ks_pg_***() calls is also called exactly once in cveval() after the calls to the corresponding ks_eval_***() functions that design the KS_*** sequence objects. Each ks_pg_***() will throw an error if this has not been done.

Parameters

[in,out]	wait	Pointer to a KS_WAIT sequence object
[in]	loc	KS_SEQLOC struct to specify when and where to place the KS_WAIT
[in,out]	ctrl	Pointer to the KS_SEQ_CONTROL struct corresponding to the sequence module for this KS_WAIT

Return values

STATUS

SUCCESS or FAILURE

                                                                      {
  int i;
  const int first = loc.board == KS_ALL ? XGRAD : loc.board;
  const int last = loc.board == KS_ALL ? SSP : loc.board;

  /* checking for NULL pointers */
  if (wait == NULL) {
    return ks_error("ks_pg_wait: First argument is NULL");
  }

  /* duration of 0 should not throw an error as this is a sign of that it has not been set up
     or has manually been disabled this way */
  if (wait->duration == 0) {
    return SUCCESS;
  }

  if (wait->description == NULL || wait->description[0] == 0 || wait->description[0] == ' ') {
    return ks_error("ks_pg_wait: Invalid description ('%s')", wait->description);
  }

  /* disallow EPI dual boards */
  if (loc.board >= KS_FREQX_PHASEY && loc.board <= KS_XYZ) {
    return ks_error("ks_pg_wait(%s): Invalid board selection: %d", wait->description, loc.board);
  }

  loc.pos = RUP_GRD(loc.pos);


#ifdef IPG
  {

    /* TGT: Don't place anything on hardware if ctrl->duration = 0.
       This is in concert with:
       - not performing createseq() in KS_SEQLENGTH if seqctrl.duration = 0
       - not playing sequence modules in scan() using ks_scan_playsequence() if seqctrl.duration = 0
       */
    if (ctrl->duration == 0) {
      ks_dbg("%s(%s): Refusing to place wait pulse since seqctrl.duration = 0 (indicating `%s` not to be played in scan())", __FUNCTION__, wait->description, ctrl->description);
      return SUCCESS;
    }

    if (wait->base.ngenerated >= wait->base.ninst) {
      return ks_error("ks_pg_wait @tgt(%s): the number of instances generated on the target exceed the number of ones generated on the host", wait->description);
    }

    if (wait->wfpulse == NULL) {
      WF_PULSE wfInit = INITPULSE;

      const char boardc[9] = "xyzrrtos";
      char tmpstr[KS_DESCRIPTION_LENGTH + 4];
      tmpstr[KS_DESCRIPTION_LENGTH + 4 - 1] = 0;

      wait->wfpulse = (WF_PULSE *) AllocNode(8 * sizeof(WF_PULSE));
      for (i = XGRAD; i <= SSP; i++) {
        if (i != RHO2){
          /* init pulse structure */
          wait->wfpulse[i] = wfInit;

          /* Name for WF_PULSEs */
          sprintf(tmpstr, "%s.w%c", wait->description, boardc[i]); pulsename(&(wait->wfpulse[i]), tmpstr);
          createconst(&(wait->wfpulse[i]), (WF_PROCESSOR) i, wait->duration, 0);

        } /* per board */
      }

    } /* wfpulse == NULL */

    if (!wait->wfi) {
      wait->wfi = (KS_WFINSTANCE *) AllocNode(wait->base.ninst * sizeof(KS_WAIT));
    }

    for (i = first; i <= last; ++i) {
      if (i == KS_RHO2) continue; /* skip RHO2 */
      
      loc.board = i;
      int isrf = loc.board == RHO || loc.board == RHO2 || loc.board == THETA || loc.board == OMEGA;
      int isssp = loc.board == SSP;

      createinstr(&(wait->wfpulse[i]), loc.pos + (isrf * psd_rf_wait) + (isssp * psd_grd_wait), wait->duration, 0);
      wait->wfi[wait->base.ngenerated].boardinstance = wait->wfpulse[i].ninsts - 1; /* zero based */
      wait->wfi[wait->base.ngenerated].wf = &(wait->wfpulse[i]);
      wait->wfi[wait->base.ngenerated].loc = loc;
      wait->base.ngenerated++;
    }

    /* sort after the last instance is generated */
    if (wait->base.ngenerated == wait->base.ninst) {
      ks_sort_wfi_by_timeboard(wait->wfi, wait->base.ninst);
    }
  }
#else
  {
    for (i = first; i <= last; ++i) {
      if (i == KS_RHO2) continue; /* skip RHO2 */
      loc.board = i;
      wait->locs[wait->base.ninst] = loc;
      wait->base.ninst++;
    }
  }
#endif

  return SUCCESS;

} /* ks_pg_wait */

ks_pg_isirot()

STATUS ks_pg_isirot	(	KS_ISIROT *	isirot,
		SCAN_INFO	scan_info,
		int	pos,
		void(*)()	rotfun,
		KS_SEQ_CONTROL *	ctrl
	)

Places out an intersequence interrupt at a specific time in the sequence module

This function connects the execution of a psd-specific rotation function in realtime when time passes this point in the sequence. This is done by two KS_WAIT pulses (being part of KS_ISIROT) on the SSP board.

Example of use in a myseqmodule_pg() function of the sequence module (in pulsegen()):

// add some padding time before the SSP pulses (not well tested how much of KS_ISI_predelay that is necessary)
mypos += RUP_GRD(KS_ISI_predelay);

status = ks_pg_isirot(&myisirot, myscaninfo, mypos, myisirotatefun, myseqctrl);
if (status != SUCCESS) return status;

// add some padding time after the SSP pulses (not well tested how much of KS_ISI_postdelay that is necessary)
mypos += RUP_GRD(myisirot.duration + KS_ISI_postdelay);

where the psd-specific rotation function is declared as:

// Intra sequence interrupts placed as WAIT pulses on the SSP board may be used to call for an immediate
// rotation of the logical coordinate system in real time as these WAIT pulses are played out, as
// opposed to during the SSI time for the sequence module.
// The WAIT pulse is assigned a control number (isi number) that is then connected to this void function
// using `isivector()` in ks_pg_isirot(). No input arguments can be passed to this function. Instead the
// rotation information specific to the sequence module is provided in `myscaninfo.oprot`. The acutal
// rotation work, incl. keeping track of number of isi pulses played out is done by ks_scan_isirotate().
void myisirotatefun() {

#ifdef IPG
  ks_scan_isirotate(&myisirot);
#endif

}

Note that the only difference between the psd-specific myisirotatefun() and the general ks_scan_isirotate() is that myisirotatefun() has no input arguments. Input arguments cannot be used as it is called from an interrupt routine, not from some other parent function.

Care must be taken when mixing the use of ks_scan_rotate() (executing during the SSI time) and these ISI interrupts, so that they are executed in the correct order. One way is to consistently avoid the use of ks_scan_rotate() and instead return to the prescribed slice rotation by calling ks_pg_isirot() again, last in the same myseqmodule_pg() function, this time using the prescribed scan_info struct:

status = ks_pg_isirot(&myisirot, ks_scan_info[0], mypos, myisirotatefun, myseqctrl);
if (status != SUCCESS) return status;

Parameters

[in,out]	isirot	Pointer to a KS_ISIROT sequence object
[in]	scan_info	SCAN_INFO struct holding an .oprot matrix to be used for real-time rotation
[in]	pos	Absolute position in [us] in the pulse sequence when this rotation should occur
[in]	rotfun	Function pointer to the psd-specific rotation function
[in,out]	ctrl	Pointer to the KS_SEQ_CONTROL struct corresponding to the sequence module

Return values

STATUS

SUCCESS or FAILURE

                                                                                                             {
  KS_SEQLOC tmploc = KS_INIT_SEQLOC;

  if (! isirot->duration) {
    /* must have called ks_eval_isirot() first */
    return SUCCESS;
  }

  if (rotfun == NULL)
    return ks_error("%s: 4th arg (rotfun) cannot be NULL", __FUNCTION__);


  /* Set the ctrl_word to binary match the isi vector interupt number */
  /* /--------------------------------------------------------------\ */
  /* | interupt number | ctrl_word                                  | */
  /* |--------------------------------------------------------------| */
  /* | 4               | PSD_ISI2_BIT                               | */
  /* | 5               | PSD_ISI0_BIT + PSD_ISI2_BIT                | */
  /* | 6               | PSD_ISI1_BIT + PSD_ISI2_BIT                | */
  /* | 7               | PSD_ISI0_BIT + PSD_ISI1_BIT + PSD_ISI2_BIT | */
  /* \--------------------------------------------------------------/ */

  tmploc.board = SSP;
  tmploc.pos = RUP_GRD(pos);

  if (ks_pg_wait(&isirot->waitfun, tmploc, ctrl) == FAILURE)
    return FAILURE;

  tmploc.pos += RUP_GRD(isirot->waitfun.duration);

  if (ks_pg_wait(&isirot->waitrot, tmploc, ctrl) == FAILURE)
    return FAILURE;


#ifdef IPG
  {
    long ctrl_word = 0;
    int placementindx = isirot->waitfun.base.ngenerated - 1;

    /* SSP ISI number */
    getctrl(&ctrl_word, &isirot->waitfun.wfpulse[SSP], isirot->waitfun.wfpulse[SSP].ninsts - 1);

    if (isirot->isinumber == 4)
      ctrl_word  = ctrl_word | PSD_ISI2_BIT;
    else if (isirot->isinumber == 5)
      ctrl_word  = ctrl_word | PSD_ISI0_BIT | PSD_ISI2_BIT;
    else if (isirot->isinumber == 6)
      ctrl_word  = ctrl_word | PSD_ISI1_BIT | PSD_ISI2_BIT;
    else if (isirot->isinumber == 7)
      ctrl_word  = ctrl_word | PSD_ISI0_BIT | PSD_ISI1_BIT | PSD_ISI2_BIT;

    setctrl(ctrl_word, &isirot->waitfun.wfpulse[SSP], isirot->waitfun.wfpulse[SSP].ninsts - 1);

    /* SSP Rotation */
    getctrl(&ctrl_word, &isirot->waitrot.wfpulse[SSP], isirot->waitrot.wfpulse[SSP].ninsts - 1);
    ctrl_word |= PSD_MTX_UPDT;
    setctrl(ctrl_word, &isirot->waitrot.wfpulse[SSP], isirot->waitrot.wfpulse[SSP].ninsts - 1);

    /* Allocate memory for scan info array */
    if (isirot->scan_info == NULL) {
      isirot->scan_info = (SCAN_INFO *) AllocNode(isirot->numinstances * sizeof(SCAN_INFO));
    }

    /* Store the scan info for current ISI, where scan_info.oprot contains the rotation matrix */
    isirot->scan_info[placementindx] = scan_info;

    /* Reset num ISI and counter */
    isirot->counter = 0; /* make sure it is zero before scan starts */

    /* Connect ths isi number with the function pointer */
    isivector((short) isirot->isinumber, rotfun, (short) FALSE);

  }
#else

  if (0) { /* make sure the WAIT pulses have been placed out in temporal order */
    int i;
    int lastpos = -1;
    WF_INSTR_HDR *instr = isirot->waitfun.wfpulse[SSP].inst_hdr_tail;
    for (i = 0; i < (isirot->waitfun.base.ninst - 1); i++) {
      if (lastpos > instr->start) {
        return ks_error("%s: Must place the ISI pulses in temporal order", __FUNCTION__);
      } else {
        lastpos = instr->start;
        instr = instr->next;
      }
    }
  }

  /* copy for convenience */
  isirot->numinstances = isirot->waitfun.base.ninst;

#endif

    return SUCCESS;

} /* ks_pg_isirot() */

ks_pg_epi_dephasers()

STATUS ks_pg_epi_dephasers	(	KS_EPI *	epi,
		KS_SEQLOC	loc,
		KS_SEQ_CONTROL *	ctrl
	)

Places out the dephasing gradients of a KS_EPI object (used by ks_pg_epi())

This function is called internally by ks_pg_epi() to place out the dephasing gradients of a KS_EPI object. See ks_pg_epi() for more details

For advanced usage of KS_EPI, it is possible to call ks_pg_epi_dephaser(), ks_pg_epi_echo() and ks_pg_epi_rephasers() separately instead of the single call to ks_pg_epi(). This allows the dephasing and rephasing gradients to be detached from the core EPI readout part

Parameters

[in,out]	epi	Pointer to a KS_EPI sequence object
[in]	loc	KS_SEQLOC struct to specify when and where to place the dephasers of the KS_EPI object
[in]	ctrl	Pointer to the KS_SEQ_CONTROL struct corresponding to the sequence module for this KS_EPI

Return values

STATUS

SUCCESS or FAILURE

                                                                             {
  int readaxis, blipaxis, sliceaxis;
  KS_SEQLOC tmploc = KS_INIT_SEQLOC;
  int maxduration;

  if (!epi) { return FAILURE; }

  /* loc.ampscale may only be +1 or -1 and will control the read polarity.
   The blip polarity is controlled in run time with ks_scan_epi_shotcontrol() */
  if (!areSame(loc.ampscale, 1.0) && !areSame(loc.ampscale, -1.0)) {
    return ks_error("ks_pg_epi_dephasers: loc.ampscale must be +1 or -1 (controls read polarity)");
  }

  loc.pos = RDN_GRD(loc.pos);

  switch (loc.board) {
  case KS_FREQX_PHASEY:
    readaxis = XGRAD; blipaxis = YGRAD; sliceaxis = ZGRAD; break;
  case KS_FREQY_PHASEX:
    readaxis = YGRAD; blipaxis = XGRAD; sliceaxis = ZGRAD; break;
  case KS_FREQX_PHASEZ:
    readaxis = XGRAD; blipaxis = ZGRAD; sliceaxis = YGRAD; break;
  case KS_FREQZ_PHASEX:
    readaxis = ZGRAD; blipaxis = XGRAD; sliceaxis = YGRAD; break;
  case KS_FREQY_PHASEZ:
    readaxis = YGRAD; blipaxis = ZGRAD; sliceaxis = XGRAD; break;
  case KS_FREQZ_PHASEY:
    readaxis = ZGRAD; blipaxis = YGRAD; sliceaxis = XGRAD; break;
  default:
    ks_error("ks_pg_epi_dephasers: loc.board is not valid: %d", loc.board);
    return FAILURE;
  }

  /* allocate time corresponding to the longest of the three, but push the dephasers to the right below */
  maxduration = IMax(3, epi->readphaser.duration, epi->blipphaser.grad.duration, epi->zphaser.grad.duration);

  /* read phaser (same KS_TRAP for DE/REphasing => 2 instances per EPI) */
  if (epi->readphaser.duration > 0) {
    tmploc.board = readaxis;
    tmploc.ampscale = loc.ampscale;
    tmploc.pos = loc.pos + maxduration - epi->readphaser.duration;
    if (ks_pg_trap(&epi->readphaser, tmploc, ctrl) == FAILURE)
      return FAILURE;
  }

  /* blip phaser (same KS_PHASER for DE/REphasing => 2 instances per EPI) */
  if (epi->blipphaser.grad.duration > 0) {
    tmploc.board = blipaxis;
    tmploc.ampscale = 1.0;
    tmploc.pos = loc.pos + maxduration - epi->blipphaser.grad.duration;
    if (ks_pg_phaser(&epi->blipphaser, tmploc, ctrl) == FAILURE)
      return FAILURE;
  }

  /* slice phaser (same KS_PHASER for DE/REphasing => 2 instances per EPI) */
  if (epi->zphaser.grad.duration > 0) {
    tmploc.board = sliceaxis;
    tmploc.ampscale = 1.0;
    tmploc.pos = loc.pos + maxduration - epi->zphaser.grad.duration;
    if (ks_pg_phaser(&epi->zphaser, tmploc, ctrl) == FAILURE)
      return FAILURE;
  }

  return SUCCESS;
} /* ks_pg_epi_dephasers */

ks_pg_epi_rephasers()

STATUS ks_pg_epi_rephasers	(	KS_EPI *	epi,
		KS_SEQLOC	loc,
		KS_SEQ_CONTROL *	ctrl
	)

Places out the rephasing gradients of a KS_EPI object (used by ks_pg_epi())

This function is called internally by ks_pg_epi() to place out the rephasing gradients of a KS_EPI object. See ks_pg_epi() for more details

For advanced usage of KS_EPI, it is possible to call ks_pg_epi_dephaser(), ks_pg_epi_echo() and ks_pg_epi_rephasers() separately instead of the single call to ks_pg_epi(). This allows the dephasing and rephasing gradients to be detached from the core EPI readout part

Parameters

[in,out]	epi	Pointer to a KS_EPI sequence object
[in]	loc	KS_SEQLOC struct to specify when to place the rephasers of the KS_EPI object
[in]	ctrl	Pointer to the KS_SEQ_CONTROL struct corresponding to the sequence module for this KS_EPI

Return values

STATUS

SUCCESS or FAILURE

                                                                             {
  int readaxis, blipaxis, sliceaxis;
  KS_SEQLOC tmploc = KS_INIT_SEQLOC;

  if (!epi) { return FAILURE; }

  /* loc.ampscale may only be +1 or -1 and will control the read polarity.
    The blip polarity is controlled in run time with ks_scan_epi_shotcontrol() */
  if (!areSame(loc.ampscale, 1.0) && !areSame(loc.ampscale, -1.0)) {
    return ks_error("ks_pg_epi_rephasers: loc.ampscale must be +1 or -1 (controls read polarity)");
  }

  loc.pos = RDN_GRD(loc.pos);

  switch (loc.board) {
  case KS_FREQX_PHASEY:
    readaxis = XGRAD; blipaxis = YGRAD; sliceaxis = ZGRAD; break;
  case KS_FREQY_PHASEX:
    readaxis = YGRAD; blipaxis = XGRAD; sliceaxis = ZGRAD; break;
  case KS_FREQX_PHASEZ:
    readaxis = XGRAD; blipaxis = ZGRAD; sliceaxis = YGRAD; break;
  case KS_FREQZ_PHASEX:
    readaxis = ZGRAD; blipaxis = XGRAD; sliceaxis = YGRAD; break;
  case KS_FREQY_PHASEZ:
    readaxis = YGRAD; blipaxis = ZGRAD; sliceaxis = XGRAD; break;
  case KS_FREQZ_PHASEY:
    readaxis = ZGRAD; blipaxis = YGRAD; sliceaxis = XGRAD; break;
  default:
    ks_error("ks_pg_epi_rephasers: loc.board is not valid: %d", loc.board);
    return FAILURE;
  }

  /* read phaser (same KS_TRAP for DE/REphasing => 2 instances per EPI) */
  if (epi->readphaser.duration > 0) {
    tmploc.board = readaxis;
    tmploc.pos = loc.pos;
    if (epi->etl % 2) /* same polarity of rephaser as dephaser if odd ETL */
      tmploc.ampscale = loc.ampscale;
    else
      tmploc.ampscale = -loc.ampscale;
    if (ks_pg_trap(&epi->readphaser, tmploc, ctrl) == FAILURE)
      return FAILURE;
  }

  /* blip phaser (same KS_PHASER for DE/REphasing => 2 instances per EPI) */
  if (epi->blipphaser.grad.duration > 0) {
    tmploc.board = blipaxis;
    tmploc.pos = loc.pos;
    tmploc.ampscale = 1.0;
    if (ks_pg_phaser(&epi->blipphaser, tmploc, ctrl) == FAILURE)
      return FAILURE;
  }

  /* slice phaser (same KS_PHASER for DE/REphasing => 2 instances per EPI) */
  if (epi->zphaser.grad.duration > 0) {
    tmploc.board = sliceaxis;
    tmploc.pos = loc.pos;
    tmploc.ampscale = 1.0;
    if (ks_pg_phaser(&epi->zphaser, tmploc, ctrl) == FAILURE)
      return FAILURE;
  }

  return SUCCESS;
} /* ks_pg_epi_rephasers */

ks_pg_epi_echo()

STATUS ks_pg_epi_echo	(	KS_EPI *	epi,
		KS_SEQLOC	loc,
		KS_SEQ_CONTROL *	ctrl
	)

Places out the core part a KS_EPI object (used by ks_pg_epi())

This function is called internally by ks_pg_epi() to place out the core part of a KS_EPI object. The core part is the EPI train without leading dephaser gradients or trailing rephaser gradients. See ks_pg_epi() for more details

For advanced usage of KS_EPI, it is possible to call ks_pg_epi_dephaser(), ks_pg_epi_echo() and ks_pg_epi_rephasers() separately instead of the single call to ks_pg_epi(). This allows the dephasing and rephasing gradients to be detached from the core EPI readout part

Parameters

[in,out]	epi	Pointer to a KS_EPI sequence object
[in]	loc	KS_SEQLOC struct to specify when to place the core part of the KS_EPI object
[in]	ctrl	Pointer to the KS_SEQ_CONTROL struct corresponding to the sequence module for this KS_EPI

Return values

STATUS

SUCCESS or FAILURE

                                                                        {
  int readaxis, blipaxis;
  KS_SEQLOC readloc, bliploc;
  int i;

  if (!epi || !epi->read.grad.description) { return FAILURE; }

  /* loc.ampscale may only be +1 or -1 and will control the read polarity.</
     The blip polarity is controlled in run time with ks_scan_epi_shotcontrol() */
  if (!areSame(loc.ampscale, 1.0) && !areSame(loc.ampscale, -1.0)) {
    return ks_error("ks_pg_epi_echo: loc.ampscale must be +1 or -1 (controls read polarity)");
  }

  loc.pos = RUP_GRD(loc.pos);

  readloc.pos = loc.pos;

  switch (loc.board) {
  case KS_FREQX_PHASEY:
    readaxis = XGRAD; blipaxis = YGRAD; break;
  case KS_FREQY_PHASEX:
    readaxis = YGRAD; blipaxis = XGRAD; break;
  case KS_FREQX_PHASEZ:
    readaxis = XGRAD; blipaxis = ZGRAD; break;
  case KS_FREQZ_PHASEX:
    readaxis = ZGRAD; blipaxis = XGRAD; break;
  case KS_FREQY_PHASEZ:
    readaxis = YGRAD; blipaxis = ZGRAD; break;
  case KS_FREQZ_PHASEY:
    readaxis = ZGRAD; blipaxis = YGRAD; break;
  default:
    ks_error("ks_pg_epi_echo: field 'board' in 2nd arg is not valid: %d", loc.board);
    return FAILURE;
  }

  if (!areSame(fabs(loc.ampscale), 1.0)) {
    return ks_error("ks_pg_epi_echo: field 'ampscale' in 2nd arg must be +1 or -1 (controls read lobe polarity)");
  }


  for (i = 0; i < epi->etl; i++) {

    /* read trapezoid */
    readloc.board = readaxis;
    readloc.ampscale = (float) (i % 2) ? -loc.ampscale : loc.ampscale; /* +1 or -1 */
    if (ks_pg_readtrap(&epi->read, readloc, ctrl) == FAILURE)
      return FAILURE;

    /* phase encoding blip */
    if (i < epi->etl - 1) {
      /* etl-1, since no blip after the last read lobe */
      bliploc.board = blipaxis;
      bliploc.pos = RUP_GRD(readloc.pos + epi->read.grad.duration - epi->blip.duration / 2 + epi->read_spacing / 2);
      bliploc.ampscale = 1.0;
      if (ks_pg_trap(&epi->blip, bliploc, ctrl) == FAILURE)
        return FAILURE;
    }

    /* read_spacing is additional gap between lobes (normally 0) */
    readloc.pos += RUP_GRD(epi->read.grad.duration + epi->read_spacing);

  } /* etl */


  return SUCCESS;

} /* ks_pg_epi_echo */

ks_pg_epi()

STATUS ks_pg_epi	(	KS_EPI *	epi,
		KS_SEQLOC	loc,
		KS_SEQ_CONTROL *	ctrl
	)

Places out a KS_EPI object (EPI train including dephaser and rephaser gradients)

This function should be called in the @pg section to place out a KS_EPI sequence object that creates an EPI readout including dephaser and rephaser gradients. The moments of all trapezoids in the KS_EPI object sum to zero on the two axes the KS_EPI object is placed on. The KS_EPI object is to be placed on two out of three gradients, why special values for the field loc.board must be used. The value should state which logical board (X,Y or Z) that should be used for the readout lobes (FREQ) and which logical board (X, Y or Z) that should be used for the blips (PHASE). One example is KS_FREQX_PHASEY, which will put the EPI readout lobes on XGRAD and the phase encoding blips on YGRAD

The same KS_EPI object can be placed out 16 times per sequence. This limitation is due to the hard limitation on the number of echoes (i.e. different k-spaces per image plane and image volume) that can be acquired per scan. Each time an instance of the KS_EPI object is placed out using ks_pg_epi(), the second argument (the KS_SEQLOC struct) should be modified:

• .board: Choose between KS_FREQX_PHASEY, KS_FREQY_PHASEX, KS_FREQX_PHASEZ, KS_FREQZ_PHASEX, KS_FREQY_PHASEZ, KS_FREQZ_PHASEY
• .pos: Absolute time in [us] of the start of the first dephaser gradient
• .ampscale: For KS_EPI objects, valid values are only +1.0 and -1.0, and this will control the polarity of the first readout gradient. This is rarely needed, and 1.0 should be the standard choice as this does only affect gradient delays and Nyquist ghosting, not the geometric distortion direction.

The sign of the EPI blips will control the direction of the geometric distortions, and this is not done via .ampscale but in run-time using ks_scan_epi_shotcontrol()

For advanced usage of KS_EPI, it is possible to call ks_pg_epi_dephaser(), ks_pg_epi_echo() and ks_pg_epi_rephasers() separately instead of the single call to ks_pg_epi(). This allows the dephasing and rephasing gradients to be detached from the core EPI readout part

Parameters

[in,out]	epi	Pointer to a KS_EPI sequence object
[in]	loc	KS_SEQLOC struct to specify when to place the core part of the KS_EPI object
[in]	ctrl	Pointer to the KS_SEQ_CONTROL struct corresponding to the sequence module for this KS_EPI

Return values

STATUS

SUCCESS or FAILURE

                                                                   {
  KS_SEQLOC tmploc = loc;

  /* loc.ampscale may only be +1 or -1 and will control the read polarity.
    The blip polarity is controlled in run time with ks_scan_epi_shotcontrol() */
  if (!areSame(loc.ampscale, 1.0)  && !areSame(loc.ampscale, -1.0)) {
    return ks_error("ks_pg_epi: loc.ampscale must be +1 or -1 (controls read polarity)");
  }

  if (ks_pg_epi_dephasers(epi, tmploc, ctrl) == FAILURE)
    return FAILURE;

  tmploc.pos += IMax(3, epi->readphaser.duration, epi->blipphaser.grad.duration, epi->zphaser.grad.duration);

  if (ks_pg_epi_echo(epi, tmploc, ctrl) == FAILURE) /* main epi train (w/o DE/REphasers) */
    return FAILURE;

  tmploc.pos += epi->read.grad.duration * epi->etl;
  if (ks_pg_epi_rephasers(epi, tmploc, ctrl) == FAILURE)
    return FAILURE;

  return SUCCESS;
} /* ks_pg_epi */

ks_mat4_zero()

void ks_mat4_zero

(

KS_MAT4x4

m

)

Makes a 4x4 zero matrix

Parameters

[in,out]

m

Matrix (KS_MAT4x4)

Returns

void

                               {
  int i;
  for (i = 0; i < 16; i++) {
    m[i] = 0.0;
  }
}

ks_mat4_identity()

void ks_mat4_identity

(

KS_MAT4x4

m

)

Creates a 4x4 identity matrix

Parameters

[in,out]

m

Matrix (KS_MAT4x4)

Returns

void

                                   {
  int i;
  ks_mat4_zero(m);
  for (i = 0; i < 4; i++) {
    m[i + (i * 4)] = 1.0;
  }
}

ks_mat4_print()

void ks_mat4_print

(

const KS_MAT4x4

m

)

Prints a 4x4 matrix to stdout

Parameters

[in]

m

Matrix (KS_MAT4x4)

Returns

void

                                      {
  int i;
  for (i = 0; i < 4; i++) {
    printf("| %0.4f %0.4f %0.4f %0.4f |\n", m[i], m[i + 4], m[i + 8], m[i + 12]);
  }
  fflush(stdout);
}

ks_mat4_multiply()

void ks_mat4_multiply	(	KS_MAT4x4	lhs,
		const KS_MAT4x4	rhs_left,
		const KS_MAT4x4	rhs_right
	)

Multiplication of two 4x4 matrices

Matrix product: [rhs_left] * [rhs_right]

Parameters

[out]	lhs	Matrix product (KS_MAT4x4)
[in]	rhs_left	Left matrix (KS_MAT4x4)
[in]	rhs_right	Right matrix (KS_MAT4x4)

Returns

void

                                                                                          {

  /* Define local variables */
  int m, n, k;
  int msize = 4;
  KS_MAT4x4 Mtmp;
  double *ptr;

  if (lhs == rhs_left || lhs == rhs_right) { /* Check if output is equal to any input */
    ptr = Mtmp;
  } else {
    ptr = lhs;
  }
  for (k = 0; k < (msize * msize); k++) { /* Zero left-hand side*/
    ptr[k] = 0.0;
  }

  /* Multiply the matrices*/
  for (n = 0; n < msize; n++) {
    for (m = 0; m < msize; m++) {
      for (k = 0; k < msize; k++) {
        ptr[m + (n * msize)] += rhs_left[m + (k * msize)] * rhs_right[k + (n * msize)];
      }
    }
  }

  if (lhs == rhs_left || lhs == rhs_right ) { /* Write back (if needed) */
    for (k = 0; k < (msize * msize); k++) {
      lhs[k] = ptr[k];
    }
  }
}

ks_mat4_invert()

void ks_mat4_invert	(	KS_MAT4x4	lhs,
		const KS_MAT4x4	rhs
	)

Inversion of a 4x4 matrix

4x4 matrix inversion (http://download.intel.com/design/PentiumIII/sml/24504301.pdf

Parameters

[out]	lhs	Inverted matrix (KS_MAT4x4)
[in]	rhs	Matrix to be inverted (KS_MAT4x4)

Returns

void

                                                        {
  double tmp[12]; /* temp array for pairs */
  double src[16]; /* array of transpose source rhsrix */
  double det; /* determinant */
  int i, j;

  /* transpose rhsrix */
  for (i = 0; i < 4; i++) {
    src[i] = rhs[i * 4];
    src[i + 4] = rhs[i * 4 + 1];
    src[i + 8] = rhs[i * 4 + 2];
    src[i + 12] = rhs[i * 4 + 3];
  }

  /* calculate pairs for first 8 elements (cofactors) */
  tmp[0] = src[10] * src[15];
  tmp[1] = src[11] * src[14];
  tmp[2] = src[9] * src[15];
  tmp[3] = src[11] * src[13];
  tmp[4] = src[9] * src[14];
  tmp[5] = src[10] * src[13];
  tmp[6] = src[8] * src[15];
  tmp[7] = src[11] * src[12];
  tmp[8] = src[8] * src[14];
  tmp[9] = src[10] * src[12];
  tmp[10] = src[8] * src[13];
  tmp[11] = src[9] * src[12];

  /* calculate first 8 elements (cofactors) */
  lhs[0] = tmp[0] * src[5] + tmp[3] * src[6] + tmp[4] * src[7];
  lhs[0] -= tmp[1] * src[5] + tmp[2] * src[6] + tmp[5] * src[7];
  lhs[1] = tmp[1] * src[4] + tmp[6] * src[6] + tmp[9] * src[7];
  lhs[1] -= tmp[0] * src[4] + tmp[7] * src[6] + tmp[8] * src[7];
  lhs[2] = tmp[2] * src[4] + tmp[7] * src[5] + tmp[10] * src[7];
  lhs[2] -= tmp[3] * src[4] + tmp[6] * src[5] + tmp[11] * src[7];
  lhs[3] = tmp[5] * src[4] + tmp[8] * src[5] + tmp[11] * src[6];
  lhs[3] -= tmp[4] * src[4] + tmp[9] * src[5] + tmp[10] * src[6];
  lhs[4] = tmp[1] * src[1] + tmp[2] * src[2] + tmp[5] * src[3];
  lhs[4] -= tmp[0] * src[1] + tmp[3] * src[2] + tmp[4] * src[3];
  lhs[5] = tmp[0] * src[0] + tmp[7] * src[2] + tmp[8] * src[3];
  lhs[5] -= tmp[1] * src[0] + tmp[6] * src[2] + tmp[9] * src[3];
  lhs[6] = tmp[3] * src[0] + tmp[6] * src[1] + tmp[11] * src[3];
  lhs[6] -= tmp[2] * src[0] + tmp[7] * src[1] + tmp[10] * src[3];
  lhs[7] = tmp[4] * src[0] + tmp[9] * src[1] + tmp[10] * src[2];
  lhs[7] -= tmp[5] * src[0] + tmp[8] * src[1] + tmp[11] * src[2];

  /* calculate pairs for second 8 elements (cofactors) */
  tmp[0] = src[2] * src[7];
  tmp[1] = src[3] * src[6];
  tmp[2] = src[1] * src[7];
  tmp[3] = src[3] * src[5];
  tmp[4] = src[1] * src[6];
  tmp[5] = src[2] * src[5];
  tmp[6] = src[0] * src[7];
  tmp[7] = src[3] * src[4];
  tmp[8] = src[0] * src[6];
  tmp[9] = src[2] * src[4];
  tmp[10] = src[0] * src[5];
  tmp[11] = src[1] * src[4];

  /* calculate second 8 elements (cofactors) */
  lhs[8] = tmp[0] * src[13] + tmp[3] * src[14] + tmp[4] * src[15];
  lhs[8] -= tmp[1] * src[13] + tmp[2] * src[14] + tmp[5] * src[15];
  lhs[9] = tmp[1] * src[12] + tmp[6] * src[14] + tmp[9] * src[15];
  lhs[9] -= tmp[0] * src[12] + tmp[7] * src[14] + tmp[8] * src[15];
  lhs[10] = tmp[2] * src[12] + tmp[7] * src[13] + tmp[10] * src[15];
  lhs[10] -= tmp[3] * src[12] + tmp[6] * src[13] + tmp[11] * src[15];
  lhs[11] = tmp[5] * src[12] + tmp[8] * src[13] + tmp[11] * src[14];
  lhs[11] -= tmp[4] * src[12] + tmp[9] * src[13] + tmp[10] * src[14];
  lhs[12] = tmp[2] * src[10] + tmp[5] * src[11] + tmp[1] * src[9];
  lhs[12] -= tmp[4] * src[11] + tmp[0] * src[9] + tmp[3] * src[10];
  lhs[13] = tmp[8] * src[11] + tmp[0] * src[8] + tmp[7] * src[10];
  lhs[13] -= tmp[6] * src[10] + tmp[9] * src[11] + tmp[1] * src[8];
  lhs[14] = tmp[6] * src[9] + tmp[11] * src[11] + tmp[3] * src[8];
  lhs[14] -= tmp[10] * src[11] + tmp[2] * src[8] + tmp[7] * src[9];
  lhs[15] = tmp[10] * src[10] + tmp[4] * src[8] + tmp[9] * src[9];
  lhs[15] -= tmp[8] * src[9] + tmp[11] * src[10] + tmp[5] * src[8];

  /* calculate determinant */
  det = src[0] * lhs[0] + src[1] * lhs[1] + src[2] * lhs[2] + src[3] * lhs[3];

  /* calculate rhsrix inverse */
  det = 1 / det;
  for (j = 0; j < 16; j++)
    lhs[j] *= det;
}

ks_mat4_setgeometry()

void ks_mat4_setgeometry	(	KS_MAT4x4	lhs,
		float	x,
		float	y,
		float	z,
		float	xr,
		float	yr,
		float	zr
	)

Set geometry for KS_MAT4x4

Parameters

[out]	lhs	set matrix (KS_MAT4x4)
[in]	x	displacement (mm)
[in]	y	displacement (mm)
[in]	z	displacement (mm)
[in]	xr	rotation (deg)
[in]	yr	rotation (deg)
[in]	zr	rotation (deg)

Returns

void

                                                                                                             {
  double cosa;
  double sina;
  double cosb;
  double sinb;
  double cosg;
  double sing;

  ks_mat4_identity(lhs);

  xr *= PI / 180.0;
  yr *= PI / 180.0;
  zr *= PI / 180.0;

  /*
  Rotation matrices for positive counterclockwise angles about the positive
  coordinate axis for a right handed coordinate system:

                | 1      0       0    |
    R1(xr) =    | 0  cos(xr)  -sin(xr)|
                | 0  sin(xr)   cos(xr)|


                | cos(yr)   0   sin(yr) |
    R2(yr)  =   | 0         1     0     |
                | -sin(yr)  0   cos(yr) |

                | cos(zr) -sin(zr)  0 |
    R3(zr) =    | sin(zr)  cos(zr)  0 |
                |   0        0      1 |
  */

  cosa = cos(xr);
  sina = sin(xr);
  cosb = cos(yr);
  sinb = sin(yr);
  cosg = cos(zr);
  sing = sin(zr);

  /* Rotations: R_z * R_y * R_x */
  lhs[ 0] =  cosb * cosg;
  lhs[ 1] =  sina * sinb * cosg - cosa * sing;
  lhs[ 2] =  cosa * sinb * cosg + sina * sing;
  lhs[ 4] =  cosb * sing;
  lhs[ 5] =  sina * sinb * sing + cosa * cosg;
  lhs[ 6] =  cosa * sinb * sing - sina * cosg;
  lhs[ 8] =  -sinb;
  lhs[ 9] =  sina * cosb;
  lhs[10] =  cosa * cosb;

  /* Translations */
  lhs[ 3] = x;
  lhs[ 7] = y;
  lhs[11] = z;
}

ks_mat4_setrotation1axis()

void ks_mat4_setrotation1axis	(	KS_MAT4x4	rhs,
		float	rot,
		char	axis
	)

Create a new 4x4 matrix with a rotation around a single axis

Parameters

[out]	rhs	Rotation matrix (KS_MAT4x4)
[in]	rot	Amount of rotation around axis [degrees]
[in]	axis	One of (include the quotes): 'x', 'y', 'z'

Returns

void

                                                                   {
  ks_mat4_identity(rhs);

  rot *= PI / 180.0; /* deg->rad */

  switch (axis) {
  case 'x':
    rhs[5]  =  cos(rot);
    rhs[6]  =  sin(rot);
    rhs[9]  = -sin(rot);
    rhs[10] =  cos(rot);
    break;
  case 'y':
    rhs[0]  =  cos(rot);
    rhs[2]  =  sin(rot);
    rhs[8]  = -sin(rot);
    rhs[10] =  cos(rot);
    break;
  case 'z':
    rhs[0]  =  cos(rot);
    rhs[1]  =  sin(rot);
    rhs[4]  = -sin(rot);
    rhs[5]  =  cos(rot);
    break;
  }

}

ks_mat4_extractrotation()

void ks_mat4_extractrotation	(	KS_MAT3x3	R,
		const KS_MAT4x4	M
	)

Extract a 3x3 rotation matrix from a 4x4 transformation matrix

Parameters

[out]	R	3x3 rotation matrix (KS_MAT3x3), row major
[in]	M	Transformation matrix (KS_MAT4x4), row major

Returns

void

                                                             {
  int i, j;
  for (i = 0; i < 3; ++i) {
    for (j = 0; j < 3; ++j) {
      R[3 * i + j] = M[4 * i + j];
    }
  }
}

ks_mat4_extracttranslation()

void ks_mat4_extracttranslation	(	double *	T,
		const KS_MAT4x4	M
	)

Extract a 3 element array with translations from a 4x4 transformation matrix

Parameters

[out]	T	Float array with 3 elements (must be allocated)
[in]	M	Transformation matrix (KS_MAT4x4), row major

Returns

void

                                                              {
  int i;
  for (i = 0; i < 3; ++i) {
    T[i] = M[4 * i + 3];
  }
}

ks_mat3_identity()

void ks_mat3_identity

(

KS_MAT3x3

m

)

Creates a 3x3 identity matrix

Parameters

[in,out]

m

Matrix (KS_MAT3x3)

Returns

void

                                   {
  int i;
  for (i = 0; i < 9; ++i) {
    m[i] = 0;
  }
  m[0] = 1;
  m[4] = 1;
  m[8] = 1;
}

ks_mat3_multiply()

void ks_mat3_multiply	(	KS_MAT3x3	lhs,
		const KS_MAT3x3	rhs_left,
		const KS_MAT3x3	rhs_right
	)

Multiplication of two 3x3 matrices

Matrix product: [rhs_left] * [rhs_right]

Parameters

[out]	lhs	Matrix product (KS_MAT3x3)
[in]	rhs_left	Left matrix (KS_MAT3x3)
[in]	rhs_right	Right matrix (KS_MAT3x3)

Returns

void

                                                                                          {

  /* TODO: add checks for overlapping arrays */

  int i, j, k;
  for (i = 0; i < 3; ++i) {
    for (j = 0; j < 3; ++j) {
      double acc = 0;
      for (k = 0; k < 3; ++k) {
        acc += rhs_left[3 * i + k] * rhs_right[3 * k + j];
      }
      lhs[3 * i + j] = acc;
    }
  }
}

ks_mat3_print()

void ks_mat3_print

(

const KS_MAT3x3

m

)

Prints a 3x3 matrix to stdout

Parameters

[in]

m

Matrix (KS_MAT3x3)

Returns

void

                                      {
  int i;
  for (i = 0; i < 3; ++i) {
    fprintf(stderr, "|%.2f,\t%.2f\t%.2f|\n", m[3 * i], m[3 * i + 1], m[3 * i + 2]);
  }
  fprintf(stderr, "\n");
}

ks_mat3_apply()

void ks_mat3_apply	(	double *	w,
		const KS_MAT3x3	R,
		const double *	v
	)

Rotate a 3x1 vector by a 3x3 rotation matrix (alibi)

Apply an active (alibi) rotation – i.e w = R * v

Parameters

[out]	w	Output vector (float array with 3 elements)
[in]	R	Rotation matrix (KS_MAT3x3)
[in]	v	Input vector (float array with 3 elements)

Returns

void

                                                                  {
  int i, j;
  for (i = 0; i < 3; ++i) {
    double acc = 0;
    for (j = 0; j < 3; ++j) {
      acc += R[3 * i + j] * v[j];
    }
    w[i] = acc;
  }
}

ks_mat3_invapply()

void ks_mat3_invapply	(	double *	w,
		const KS_MAT3x3	R,
		const double *	v
	)

Rotate a 3x1 vector by the inverse of 3x3 rotation matrix (alias)

Apply a passive (alias) rotation – i.e w = R' * v = R^-1 * v

Parameters

[out]	w	Output vector (float array with 3 elements)
[in]	R	Rotation matrix (KS_MAT3x3)
[in]	v	Input vector (float array with 3 elements)

Returns

void

                                                                     {
  int i, j;
  for (i = 0; i < 3; ++i) {
    double acc = 0;
    for (j = 0; j < 3; ++j) {
      acc += v[j] * R[3 * j + i];
    }
    w[i] = acc;
  }
}

ks_scan_update_slice_location()

void ks_scan_update_slice_location	(	SCAN_INFO *	new_loc,
		const SCAN_INFO	orig_loc,
		const KS_MAT4x4	M_physical,
		const KS_MAT4x4	M_logical
	)

Updates a SCAN_INFO struct using physical and logical 4x4 transformation matrices

Updates the slice location – e.g for motion correction (physical space) or propeller rotations (logical space)

M_physical and M_logical are row-major 4x4 matricies that describe rotations (R_physical, R_logical) and translations (T_physical, T_logical) of the FOV in the physical and logical coordinate systems, respectively. If R_slice and T_slice describe the position of the prescribed FOV contained in orig_loc then new_loc will describe the overall rotation R_new and translation T_new of the FOV such that:

R_new = R_physical * R_slice * R_logical

T_new = R_logical^-1 * (R_slice^-1 * R_physical^-1 * T_physical + T_slice + T_logical)

NOTE: All transformations are expected to be active (alibi) that denote a change of position/orientation, not passive (alias) that denote a change of coordinates system. See https://en.wikipedia.org/wiki/Active_and_passive_transformation

SCAN_INFO is defined in $ESE_TOP/psd/include/epic_geometry_types.h and the global scan_info variable is an array of SCAN_INFO structs holding information of the graphically prescribed slices

Parameters

[out]	new_loc	Pointer to a SCAN_INFO struct holding the new slice information
[in]	orig_loc	SCAN_INFO struct holding the original slice information
[in]	M_physical	Transformation matrix (4x4) in the physical space
[in]	M_logical	Transformation matrix (4x4) in the logical (i.e. XGRAD, YGRAD, ZGRAD) space

Returns

void

                                                                                                                                        {
  int i;
  KS_MAT3x3 R_m;
  KS_MAT3x3 R_l;
  KS_MAT3x3 R_ms;
  KS_MAT3x3 R_msl;

  const double T_s[3] = {orig_loc.oprloc, orig_loc.opphasoff, orig_loc.optloc};
  double T_m[3];
  double T_l[3];
  double T_msl[3];
  double T_new[3];

  /* initialize to identity matrix (will be used if NULL in 3rd or 4th arg) */
  KS_MAT4x4 Mphys = KS_MAT4x4_IDENTITY;
  KS_MAT4x4 Mlog = KS_MAT4x4_IDENTITY;

  /* copy slice rotation and translation */
  KS_MAT3x3 R_s;
  for (i = 0; i < 9; i++) {
    R_s[i] = orig_loc.oprot[i];
  }

  /* copy transformation matrices (if they are not NULL) to local matrices */
  if (M_physical != NULL) {
    memcpy(Mphys, M_physical, sizeof(KS_MAT4x4));
  }
  if (M_logical != NULL) {
    memcpy(Mlog, M_logical, sizeof(KS_MAT4x4));
  }

  ks_mat4_extractrotation(R_m, Mphys);
  ks_mat4_extractrotation(R_l, Mlog);

  ks_mat4_extracttranslation(T_m, Mphys);
  ks_mat4_extracttranslation(T_l, Mlog);

  /* R_ms = R_m * R_s */
  ks_mat3_multiply(R_ms, R_m, R_s);

  /* R_ms^-1 * T_m = T_m' * R_ms' */
  ks_mat3_invapply(T_msl, R_ms, T_m);

  for (i = 0; i < 3; ++i) {
    T_msl[i] += T_s[i] + T_l[i];
  }

  ks_mat3_invapply(T_new, R_l, T_msl);
  new_loc->oprloc = T_new[0];
  new_loc->opphasoff = T_new[1];
  new_loc->optloc = T_new[2];

  ks_mat3_multiply(R_msl, R_ms, R_l);
  for (i=0; i<9; ++i) {
    new_loc->oprot[i] = R_msl[i];
  }
} /* ks_scan_update_slice_location */

ks_scan_rotate()

void ks_scan_rotate

(

SCAN_INFO

slice_info

)

Performs a rotation of the logical system on hardware (WARP)

The field .oprot (9-element array) in the SCAN_INFO struct holds the rotation matrix that should be played out

This function performs the necessary scaling of the rotation matrix using loggrd and phygrd and then calls setrotatearray(), which performs the actual rotation on hardware during the next SSI time.

See ks_scan_update_slice_location() for detail on how to create new SCAN_INFO structs in run-time

Parameters

[in]

slice_info

SCAN_INFO struct holding new slice information

Returns

void

                                          {
#ifdef IPG

  /* scale to long int rotation matrix (accounting for gradient scaling) */
  scale(&slice_info.oprot, &rsprot[0], 1, &loggrd, &phygrd, 0);

  setrotatearray(1, rsprot[0]);

#endif
}

ks_scan_isirotate()

void ks_scan_isirotate

(

KS_ISIROT *

isirot

)

Performs an immediate rotation of the logical system on hardware (WARP)

This function needs a psd-specific wrapper function to execute (see ks_pg_isirot()) since the ISI interupt routine is calling a void function without input arguments. This psd-specific wrapper function should only contain the call to ks_scan_isirotate() with the psd-specific KS_ISIROT set up in pulsegen().

For N number of calls to ks_pg_isirot() in the sequence module's pg-function, the field isirot.numinstances will be set to N, and this many ISI interrupt with a corresponding isirot.isinumber exist in the sequence module. Valid ISI numbers are 4-7, and one available number should be linked to one specific wrapper function using ks_eval_isirot() and ks_pg_isirot().

In real-time, ks_scan_isirotate() will increment the isirot.counter field by 1 and restart at 0 after isirot->numinstances. isirot.counter is set to 0 in ks_pg_isirot(). Based on the value of the .counter field, it will assign a pre-stored SCAN_INFO struct corresponding to this counter value. Again, this connection is done by ks_pg_isirot().

ks_scan_isirotate() takes the current SCAN_INFO and converts it to long int, and then calls setrotateimm(..., WARP_UPDATE_ON_SSP_INT);

Parameters

[in]

isirot

Pointer to the KS_ISIROT struct set up by ks_pg_isirot()

Returns

void

                                          {
#ifdef IPG

  if (isirot == NULL || isirot->numinstances < 1)
    return;

  /* wrap around after numinstances interupts */
  isirot->counter = isirot->counter % isirot->numinstances;

  /* scale to long int rotation matrix (accounting for gradient scaling) */
  scale(&isirot->scan_info[isirot->counter++].oprot, &rsprot[0], 1, &loggrd, &phygrd, 0);

  /* rotate on SSP interrupt */
  setrotateimm(rsprot[0], WARP_UPDATE_ON_SSP_INT);

#endif
}

ks_pg_fse_flip_angle_taperoff()

STATUS ks_pg_fse_flip_angle_taperoff	(	double *	flip_angles,
		int	etl,
		double	flip1,
		double	flip2,
		double	flip3,
		double	target_flip,
		int	start_middle
	)

                                                       {

  int i;

  flip_angles[0] = flip1;
  flip_angles[1] = flip2;
  for (i = 2; i < etl; i++) {
    flip_angles[i] = flip3;
  }

  if (flip3 <= target_flip || etl < 5) {
    /* flip3 must be larger than target_flip and etl must be larger than 4 */
    return SUCCESS;
  }

  /* after half of the echo train or third pulse, ramp down flip angles to last_flip */
  double first_flip = flip3;
  double last_flip = target_flip;
  int start_pulse = start_middle ? etl/2 : 2;
  for (i = start_pulse; i < etl; i++) {
    flip_angles[i] = first_flip + (((last_flip - first_flip)/(etl - start_pulse - 1)) * (i - start_pulse));
  }

  return SUCCESS;

} /* ks_pg_fse_flip_angle_taperoff */

ks_pg_mod_fse_rfpulse_structs()

void ks_pg_mod_fse_rfpulse_structs	(	KS_SELRF *	rf1,
		KS_SELRF *	rf2,
		KS_SELRF *	rf3,
		const double *	flip_angles,
		const int	etl
	)

                                                  {

  float SAR_scale_1 = 0.0;
  float SAR_scale_2 = 0.0;
  float SAR_scale_3 = 0.0;
  int i;

  SAR_scale_1 = pow(flip_angles[0] / rf1->rf.flip, 2.0);
  SAR_scale_2 = pow(flip_angles[1] / rf2->rf.flip, 2.0);
  for (i = 2; i < etl; i++) {
    SAR_scale_3 += pow(flip_angles[i] / rf3->rf.flip, 2.0);
  }
  SAR_scale_3 /= etl - 2;

  rf1->rf.rfpulse.effwidth *= SAR_scale_1;
  rf1->rf.rfpulse.max_rms_b1 *= sqrt(SAR_scale_1);
  rf1->rf.rfpulse.abswidth *= sqrt(SAR_scale_1);

  rf2->rf.rfpulse.effwidth *= SAR_scale_2;
  rf2->rf.rfpulse.max_rms_b1 *= sqrt(SAR_scale_2);
  rf2->rf.rfpulse.abswidth *= sqrt(SAR_scale_2);

  rf3->rf.rfpulse.effwidth *= SAR_scale_3;
  rf3->rf.rfpulse.max_rms_b1 *= sqrt(SAR_scale_3);
  rf3->rf.rfpulse.abswidth *= sqrt(SAR_scale_3);

} /* ks_pg_mod_fse_rfpulse_structs */

ks_instancereset_trap()

void ks_instancereset_trap

(

KS_TRAP *

trap

)

Resets the usage counters on TGT for a KS_TRAP sequence object (advanced use)

This function is for advanced use where a single sequence generating function is used in parallel in multiple sequences (i.e. in different SEQLENGTH()). This should be called after calling ks_copy_and_reset_obj()

The function sets .base.ngenerated to 0 (counter for number of times placed out on TGT), and sets .wfpulse and .wfi to NULL to trigger the allocation of new hardware memory, before running the sequence generating function again.

Parameters

[in,out]

trap

Pointer to a KS_TRAP sequence object

Returns

void

                                          {
  if (!trap) { return; }

  trap->base.ngenerated = 0;
  trap->wfpulse = NULL;
  trap->wfi = NULL;
}

ks_instancereset_wait()

void ks_instancereset_wait

(

KS_WAIT *

wait

)

Resets the usage counters on TGT for a KS_WAIT sequence object (advanced use)

This function is for advanced use where a single sequence generating function is used in parallel in multiple sequences (i.e. in different SEQLENGTH()). This should be called after calling ks_copy_and_reset_obj()

The function sets .base.ngenerated to 0 (counter for number of times placed out on TGT), and sets .wfpulse and .wfi to NULL to trigger the allocation of new hardware memory, before running the sequence generating function again.

Parameters

[in,out]

wait

Pointer to a KS_WAIT sequence object

Returns

void

                                          {
  if (!wait) { return; }

  wait->base.ngenerated = 0;
  wait->wfpulse = NULL;
  wait->wfi = NULL;
}

ks_instancereset_phaser()

void ks_instancereset_phaser

(

KS_PHASER *

phaser

)

Resets the usage counters on TGT for a KS_PHASER sequence object (advanced use)

This function is for advanced use where a single sequence generating function is used in parallel in multiple sequences (i.e. in different SEQLENGTH()). This should be called after calling ks_copy_and_reset_obj()

The function sets .base.ngenerated to 0 (counter for number of times placed out on TGT), and sets .wfpulse and .wfi to NULL to trigger the allocation of new hardware memory, before running the sequence generating function again.

Parameters

[in,out]

phaser

Pointer to a KS_PHASER sequence object

Returns

void

                                                {
  if (!phaser) { return; }

  ks_instancereset_trap(&phaser->grad);
}

ks_instancereset_readtrap()

void ks_instancereset_readtrap

(

KS_READTRAP *

readtrap

)

Resets the usage counters on TGT for a KS_READTRAP sequence object (advanced use)

This function is for advanced use where a single sequence generating function is used in parallel in multiple sequences (i.e. in different SEQLENGTH()). This should be called after calling ks_copy_and_reset_obj()

The function sets .base.ngenerated to 0 (counter for number of times placed out on TGT), and sets .wfpulse and .wfi to NULL to trigger the allocation of new hardware memory, before running the sequence generating function again.

Parameters

[in,out]

readtrap

Pointer to a KS_READTRAP sequence object

Returns

void

                                                  {
  if (!read) { return; }

  read->acq.base.ngenerated = 0;
  read->acq.echo = NULL;

  ks_instancereset_trap(&read->grad);
  ks_instancereset_trap(&read->omega);
}

ks_instancereset_rf()

void ks_instancereset_rf

(

KS_RF *

rf

)

Resets the usage counters on TGT for a KS_RF sequence object (advanced use)

This function is for advanced use where a single sequence generating function is used in parallel in multiple sequences (i.e. in different SEQLENGTH()). This should be called after calling ks_copy_and_reset_obj()

The function sets .base.ngenerated to 0 (counter for number of times placed out on TGT), and sets .wfpulse and .wfi to NULL to trigger the allocation of new hardware memory, before running the sequence generating function again.

Parameters

[in,out]

rf

Pointer to a KS_RF sequence object

Returns

void

                                    {
  if (!rf) { return; }

  ks_instancereset_wave(&rf->rfwave);
  ks_instancereset_wave(&rf->omegawave);
  ks_instancereset_wave(&rf->thetawave);

}

ks_instancereset_selrf()

void ks_instancereset_selrf

(

KS_SELRF *

selrf

)

Resets the usage counters on TGT for a KS_SELRF sequence object (advanced use)

This function is for advanced use where a single sequence generating function is used in parallel in multiple sequences (i.e. in different SEQLENGTH()). This should be called after calling ks_copy_and_reset_obj()

The function sets .base.ngenerated to 0 (counter for number of times placed out on TGT), and sets .wfpulse and .wfi to NULL to trigger the allocation of new hardware memory, before running the sequence generating function again.

Parameters

[in,out]

selrf

Pointer to a KS_SELRF sequence object

Returns

void

                                             {
  if (!selrf) { return; }

  ks_instancereset_rf(&selrf->rf);
  ks_instancereset_trap(&selrf->pregrad);
  ks_instancereset_trap(&selrf->grad);
  ks_instancereset_trap(&selrf->postgrad);

  ks_instancereset_wave(&selrf->gradwave);

}

ks_instancereset_epi()

void ks_instancereset_epi

(

KS_EPI *

epi

)

Resets the usage counters on TGT for a KS_EPI sequence object (advanced use)

This function is for advanced use where a single sequence generating function is used in parallel in multiple sequences (i.e. in different SEQLENGTH()). This should be called after calling ks_copy_and_reset_obj()

The function sets .base.ngenerated to 0 (counter for number of times placed out on TGT), and sets .wfpulse and .wfi to NULL to trigger the allocation of new hardware memory, before running the sequence generating function again.

Parameters

[in,out]

epi

Pointer to a KS_EPI sequence object

Returns

void

                                       {
  if (!epi) { return; }

  ks_instancereset_readtrap(&epi->read);
  ks_instancereset_trap(&epi->readphaser);
  ks_instancereset_trap(&epi->blip);
  ks_instancereset_phaser(&epi->blipphaser);
}

ks_compare_wfi_by_timeboard()

int ks_compare_wfi_by_timeboard	(	const KS_WFINSTANCE *	a,
		const KS_WFINSTANCE *	b
	)

Compares two WF_INSTANCEs by time, then board

This function is used by the qsort() routine in ks_compare_wfi_by_timeboard()

If two WF_INSTANCEs occur at the same time, XGRAD will come before YGRAD and YGRAD before ZGRAD

Parameters

[in]	a	Pointer to the first KS_WFINSTANCE
[in]	b	Pointer to the second KS_WFINSTANCE

Return values

value

Larger or less than 0 depending on sorting order

                                                                                {

  return (a->loc.pos > b->loc.pos) - (a->loc.pos < b->loc.pos) +
         (a->loc.pos == b->loc.pos) * ((a->loc.board > b->loc.board) - (a->loc.board < b->loc.board));
}

ks_compare_wfi_by_boardtime()

int ks_compare_wfi_by_boardtime	(	const KS_WFINSTANCE *	a,
		const KS_WFINSTANCE *	b
	)

Compares two WF_INSTANCES by board, then time

This function is used by the qsort() routine in ks_compare_wfi_by_boardtime()

WF_INSTANCEs are sorted first by board. If two WF_INSTANCEs occur on the same board, t they will be sorted in time

Parameters

[in]	a	Pointer to the first KS_WFINSTANCE
[in]	b	Pointer to the second KS_WFINSTANCE

Return values

value

Larger or less than 0 depending on sorting order

                                                                                {

  return (a->loc.board > b->loc.board) - (a->loc.board < b->loc.board) +
         (a->loc.board == b->loc.board) * ((a->loc.pos > b->loc.pos) - (a->loc.pos < b->loc.pos));
}

ks_compare_wfp_by_time()

int ks_compare_wfp_by_time	(	const WF_PULSE *	a,
		const WF_PULSE *	b
	)

Compares two WF_PULSES in time

This function is used by the qsort() routine in ks_sort_wfp_by_time(), which is called from ks_pg_read() for data acquisition sorting purposes. It is assumed both WF_PULSEs have only one instance

Parameters

[in]	a	Pointer to the first WF_PULSE
[in]	b	Pointer to the second WF_PULSE

Return values

value

Larger or less than 0 depending on sorting order

                                                                 {

  return (a->inst_hdr_head->start > b->inst_hdr_head->start) - (a->inst_hdr_head->start < b->inst_hdr_head->start);
}

ks_compare_pint()

int ks_compare_pint	(	const void *	v1,
		const void *	v2
	)

Compares two int pointers

Parameters

[in]	v1	Pointer to the first int pointer
[in]	v2	Pointer to the second int pointer

Return values

value

Larger or less than 0 depending on sorting order

                                                    {
  const int i1 = **(const int **) v1;
  const int i2 = **(const int **) v2;

  return i1 < i2 ? -1 : (i1 > i2);
}

ks_compare_pshort()

int ks_compare_pshort	(	const void *	v1,
		const void *	v2
	)

Compares two short pointers

Parameters

[in]	v1	Pointer to the first short pointer
[in]	v2	Pointer to the second shot pointer

Return values

value

Larger or less than 0 depending on sorting order

                                                      {
  const short i1 = **(const short **) v1;
  const short i2 = **(const short **) v2;

  return i1 < i2 ? -1 : (i1 > i2);
}

ks_compare_pfloat()

int ks_compare_pfloat	(	const void *	v1,
		const void *	v2
	)

Compares two float pointers

Parameters

[in]	v1	Pointer to the first float pointer
[in]	v2	Pointer to the second float pointer

Return values

value

Larger or less than 0 depending on sorting order

                                                      {
  const float i1 = **(const float **) v1;
  const float i2 = **(const float **) v2;

  return i1 < i2 ? -1 : (i1 > i2);
}

ks_compare_int()

int ks_compare_int	(	const void *	v1,
		const void *	v2
	)

Compares two integers (int)

Parameters

[in]	v1	Pointer to the first int
[in]	v2	Pointer to the second int

Return values

value

Larger or less than 0 depending on sorting order

                                                   {
  const int i1 = *(const int *) v1;
  const int i2 = *(const int *) v2;

  return i1 < i2 ? -1 : (i1 > i2);
}

ks_compare_short()

int ks_compare_short	(	const void *	v1,
		const void *	v2
	)

Compares two integers (short)

Parameters

[in]	v1	Pointer to the first short
[in]	v2	Pointer to the second short

Return values

value

Larger or less than 0 depending on sorting order

                                                     {
  const short i1 = *(const short *) v1;
  const short i2 = *(const short *) v2;

  return i1 < i2 ? -1 : (i1 > i2);
}

ks_compare_float()

int ks_compare_float	(	const void *	v1,
		const void *	v2
	)

Compares two floats

Parameters

[in]	v1	Pointer to the first float
[in]	v2	Pointer to the second float

Return values

value

Larger or less than 0 depending on sorting order

                                                     {
  const float i1 = *(const float *) v1;
  const float i2 = *(const float *) v2;

  return i1 < i2 ? -1 : (i1 > i2);
}

ks_sort_getsortedindx()

void ks_sort_getsortedindx	(	int *	sortedindx,
		int *	array,
		int	n
	)

Sort an array of integers (int)

Parameters

[out]	sortedindx	Array of indices into the array to make it sorted
[in,out]	array	Array to be sorted
[in]	n	Number of elements in array

Returns

void

                                                               {
  int i;
  int *parray[n];

  for (i = 0; i < n; i++)
    parray[i] = &array[i];

  qsort(parray, n, sizeof * parray, ks_compare_pint);

  for (i = 0; i < n; i++)
    sortedindx[i] = parray[i] - array;

}

ks_sort_getsortedindx_s()

void ks_sort_getsortedindx_s	(	int *	sortedindx,
		short *	array,
		int	n
	)

Sort an array of integers (short)

Parameters

[out]	sortedindx	Array of indices into the array to make it sorted
[in,out]	array	Array to be sorted
[in]	n	Number of elements in array

Returns

void

                                                                   {
  int i;
  short *parray[n];

  for (i = 0; i < n; i++)
    parray[i] = &array[i];

  qsort(parray, n, sizeof * parray, ks_compare_pshort);

  for (i = 0; i < n; i++)
    sortedindx[i] = parray[i] - array;

}

ks_sort_getsortedindx_f()

void ks_sort_getsortedindx_f	(	int *	sortedindx,
		float *	array,
		int	n
	)

Sort an array of floats

Parameters

[out]	sortedindx	Array of indices into the array to make it sorted
[in,out]	array	Array to be sorted
[in]	n	Number of elements in array

Returns

void

                                                                   {
  int i;
  float *parray[n];

  for (i = 0; i < n; i++)
    parray[i] = &array[i];

  qsort(parray, n, sizeof * parray, ks_compare_pfloat);

  for (i = 0; i < n; i++)
    sortedindx[i] = parray[i] - array;

}

ks_sort_wfi_by_timeboard()

void ks_sort_wfi_by_timeboard	(	KS_WFINSTANCE *	a,
		int	nitems
	)

Sort WF_INSTANCEs in time, then board

This is the sorting method used in all ks_pg_***() functions

Parameters

[in,out]	a	Array of KS_WFINSTANCE elements
[in]	nitems	Number of elements in array

Returns

void

                                                            {
  qsort(a, nitems, sizeof(KS_WFINSTANCE),
        (int(*)(const void *, const void *))ks_compare_wfi_by_timeboard);
}

ks_sort_wfi_by_boardtime()

void ks_sort_wfi_by_boardtime	(	KS_WFINSTANCE *	a,
		int	nitems
	)

Sort WF_INSTANCEs by board, then time

This function is an alternative to ks_sort_wfi_by_timeboard(), which is not used at the moment

Parameters

[in,out]	a	Array of KS_WFINSTANCE elements
[in]	nitems	Number of elements in array

Returns

void

                                                            {
  qsort(a, nitems, sizeof(KS_WFINSTANCE), (int(*)(const void *, const void *))ks_compare_wfi_by_boardtime);
}

ks_sort_wfp_by_time()

void ks_sort_wfp_by_time	(	WF_PULSE *	a,
		int	nitems
	)

Sort WF_PULSEs in time

This is the sorting method used in ks_pg_read()

It is assumed that all a[idx] for idx in [0,nitems) have only one instance each

Parameters

[in,out]	a	Array of WF_PULSE elements
[in]	nitems	Number of elements in array

Returns

void

                                                  {
  qsort(a, nitems, sizeof(WF_PULSE),
        (int(*)(const void *, const void *))ks_compare_wfp_by_time);
}

ks_file_exist()

int ks_file_exist

(

char *

filename

)

                                  {
  struct stat   buffer;   
  return (stat (filename, &buffer) == 0);
}

ks_plot_host_slicetime_delete()

void ks_plot_host_slicetime_delete

(

)

                                     {
  char fname[500];
  ks_plot_host_slicetime_fullfile(fname);
  remove(fname);
}

ks_plot_slicetime_begin()

void ks_plot_slicetime_begin

(

)

                               {
#ifdef IPG
  return;
#endif
  ks_plot_host_slicetime_begin();
}

ks_plot_slicetime()

void ks_plot_slicetime	(	KS_SEQ_CONTROL *	ctrl,
		int	nslices,
		float *	slicepos_mm,
		float	slthick_mm,
		KS_PLOT_EXCITATION_MODE	exctype
	)

                                                                                                                                 {
#ifdef IPG
  return;
#endif
  ks_plot_host_slicetime(ctrl, nslices, slicepos_mm, slthick_mm, excmode);
}

ks_plot_slicetime_endofslicegroup()

void ks_plot_slicetime_endofslicegroup

(

const char *

desc

)

                                                         {
#ifdef IPG
  return;
#endif
  ks_plot_host_slicetime_endofslicegroup(desc, KS_PLOT_SG_NOTSET);
}

ks_plot_slicetime_endofslicegroup_tagged()

void ks_plot_slicetime_endofslicegroup_tagged	(	const char *	desc,
		const KS_PLOT_SLICEGROUP_MODE	tag
	)

                                                                                                   {
#ifdef IPG
  return;
#endif
  ks_plot_host_slicetime_endofslicegroup(desc, tag);
}

ks_plot_slicetime_endofpass()

void ks_plot_slicetime_endofpass

(

KS_PLOT_PASS_MODE

)

                                                              {
#ifdef IPG
  return;
#endif
  ks_plot_host_slicetime_endofpass(pass_mode);
}

ks_plot_slicetime_end()

void ks_plot_slicetime_end

(

)

                             {
#ifdef IPG
  return;
#endif
  ks_plot_host_slicetime_end();
}

ks_plot_host_slicetime_begin()

void ks_plot_host_slicetime_begin

(

)

                                    {
  if (ks_plot_filefmt == KS_PLOT_OFF) {
    return;
  }
  extern int optr;
  extern float pitscan;
  char path[250];
  char fname[500];
  char cmd[300];
  ks_plot_host_slicetime_path(path);
  ks_plot_host_slicetime_fullfile(fname);

  sprintf(cmd, "mkdir -p %s > /dev/null", path);
  system(cmd);
  /* Reset file */
  FILE* fp = fopen(fname, "w");
  fprintf(fp,
   "{\n"
   "\"metadata\": {\n"
   "\t\"psdname\": \"%s\",\n"
   "\t\"optr\": %d,\n"
   "\t\"pitscan\": %.0f\n"
   "},\n"
   "\"passes\": [ {\n"
   "\t\"slicegroups\": [\n\t[{},\n\t",
   ks_psdname, optr, pitscan);
  fclose(fp);
}

ks_plot_host_slicetime()

void ks_plot_host_slicetime	(	KS_SEQ_CONTROL *	ctrl,
		int	nslices,
		float *	slicepos_mm,
		float	slthick_mm,
		KS_PLOT_EXCITATION_MODE	exctype
	)

                                                        {
  if (ks_plot_filefmt == KS_PLOT_OFF || ctrl->duration <= 0) {
    return;
  }
  static FILE *fp;
  int i;
  char excmode_str[50];
  char fname[1000];
  
  ks_plot_host_slicetime_fullfile(fname);
  if (! ks_file_exist(fname)) {
    return;
  }

  switch (excmode) {
  case KS_PLOT_STANDARD: strcpy(excmode_str, "KS_PLOT_STANDARD"); break;
  case KS_PLOT_NO_EXCITATION: strcpy(excmode_str, "KS_PLOT_NO_EXCITATION"); break;
  }

  if (ctrl->duration > 0) {
    fp = fopen(fname, "r+");
    if (fp == NULL) {return;}
    fseek(fp, 0, SEEK_END);
    /* fputs(" {\n", fp); */
    fprintf(fp,
            "{\n"
            "\t\t\"description\": \"%s\",\n"
            "\t\t\"excitationmode\": \"%s\",\n"
            "\t\t\"duration\": %0.3f,\n"
            "\t\t\"nseqinstances\": %d,\n"
            "\t\t\"minduration\": %0.3f,\n"
            "\t\t\"numrf\": %d,\n"
            "\t\t\"numtrap\": %d,\n"
            "\t\t\"numwave\": %d,\n"
            "\t\t\"numacq\": %d,\n"
            "\t\t\"slicethickness\": %0.3f,\n"
            "\t\t\"slicepos\": [",
            ctrl->description, excmode_str, ctrl->duration / 1000.00, ctrl->nseqinstances , ctrl->min_duration / 1000.00, ctrl->gradrf.numrf, ctrl->gradrf.numtrap, ctrl->gradrf.numwave, ctrl->gradrf.numacq, slthick_mm);

    /* SMS slice locations */
    for (i = 0; i < (nslices - 1); i++) {
      fprintf(fp, "%0.3f, ", slicepos_mm == NULL ? 0.0 : slicepos_mm[i]);
    }
    fprintf(fp, "%0.3f]\n\t},", slicepos_mm == NULL ? 0.0 : slicepos_mm[nslices - 1]);
    fflush(fp);
    fclose(fp);
  }
  
}

ks_plot_host_slicetime_endofslicegroup()

void ks_plot_host_slicetime_endofslicegroup	(	const char *	desc,
		const KS_PLOT_SLICEGROUP_MODE	tag
	)

                                                                                                  {
  if (ks_plot_filefmt == KS_PLOT_OFF) {
    return;
  }
  char fname[500];
  ks_plot_host_slicetime_fullfile(fname);
  if (! ks_file_exist(fname)) {
    return;
  }
  char modestr[128];
  if (mode == KS_PLOT_SG_NOTSET) { strcpy(modestr,"KS_PLOT_SG_NOTSET"); }
  else if (mode == KS_PLOT_SG_ACQUISITION) { strcpy(modestr,"KS_PLOT_SG_ACQUISITION"); }
  else if (mode == KS_PLOT_SG_DUMMY) { strcpy(modestr,"KS_PLOT_SG_DUMMY"); }
  else if (mode == KS_PLOT_SG_CALIBRATION) { strcpy(modestr,"KS_PLOT_SG_CALIBRATION"); }
  
  FILE* fp = fopen(fname, "r+");
  if (fp == NULL) {return;}
  fseek(fp, 0, SEEK_END);
  fprintf(fp,
          "{\n\t"
          "\"groupdescription\": \"%s\",\n\t"
          "\"mode\": \"%s\"\n\t"
          "}", desc == NULL ? "N/A" : desc,
          modestr);
  fputs("],[\n\t{},\n\t", fp);
  fflush(fp);
  fclose(fp);
}

ks_plot_host_slicetime_endofpass()

void ks_plot_host_slicetime_endofpass

(

KS_PLOT_PASS_MODE

)

                                                                   {
  if (ks_plot_filefmt == KS_PLOT_OFF) {
    return;
  }
  static FILE *fp;
  char fname[500];
  ks_plot_host_slicetime_fullfile(fname);
  if (! ks_file_exist(fname)) {
    return;
  } 
  
  char passmode_str[50];
  switch (pass_mode) {
    case KS_PLOT_PASS_WAS_DUMMY: strcpy(passmode_str, "KS_PLOT_PASS_WAS_DUMMY"); break;
    case KS_PLOT_PASS_WAS_CALIBRATION: strcpy(passmode_str, "KS_PLOT_PASS_WAS_CALIBRATION"); break;
    case KS_PLOT_PASS_WAS_STANDARD: strcpy(passmode_str, "KS_PLOT_PASS_WAS_STANDARD"); break;
  }
  
  fp = fopen(fname, "r+");
  if (fp == NULL) {return;}
  fseek(fp, -9, SEEK_END);
  fputs("],\n", fp);
  fprintf(fp,
            "\t\"passmode\": \"%s\"\n"
            "\t},{\n"
            "\t\"slicegroups\": [\n\t[{},\n\t", passmode_str);
  fflush(fp);
  fclose(fp);
}

ks_plot_host_slicetime_end()

void ks_plot_host_slicetime_end

(

)

                                  {
  if (ks_plot_filefmt == KS_PLOT_OFF) {
    return;
  }
  char outputdir_uid[250];
  char cmd[1000];

  char fname[500];
  ks_plot_host_slicetime_fullfile(fname);
  if (! ks_file_exist(fname)) {
    return;
  }
  
  FILE *fp = fopen(fname, "r+");
  int fd = fileno(fp);
  if (!fp) {return;}
  fseek(fp, -28, SEEK_END);
  fprintf(fp, "]\n}");
  fflush(fp);
  ftruncate(fd, ftell(fp));
  fclose(fp);
  
  outputdir_uid[0] = '\0';
#ifdef PSD_HW
  /* on MR-scanner */
  char outputdir[250];
  char pythonpath[] = "/usr/local/bin/apython";
  char psdplotpath[] = "/usr/local/bin/psdplot_slicetime.py";
  sprintf(outputdir, "/usr/g/mrraw/plot/%s/", ks_psdname);
  if (ks_plot_kstmp) {
    sprintf(outputdir_uid, "/usr/g/mrraw/kstmp/%010d/plot/", rhkacq_uid);
  }
#else
  /* in Simulation */
  char outputdir[] = "./plot/";
  char pythonpath[] = "apython";
  char psdplotpath[] = "../KSFoundation/psdplot/psdplot_slicetime.py";
#endif

    sprintf(cmd, "%s %s "
                 "%s "
                 "--outputdir %s %s &",
            pythonpath, psdplotpath, fname, outputdir, outputdir_uid);
    system(cmd);

  return;
}

ks_plot_host()

void ks_plot_host	(	KS_SEQ_COLLECTION *	seqcollection,
		KS_PHASEENCODING_PLAN *	plan
	)

                                                                                 {
  int i;
  for (i = 0; i < seqcollection->numseq; i++) {
    ks_plot_host_seqctrl(seqcollection->seqctrlptr[i], plan);
  }
  return;
}

ks_plot_host_seqctrl()

void ks_plot_host_seqctrl	(	KS_SEQ_CONTROL *	ctrl,
		KS_PHASEENCODING_PLAN *	plan
	)

                                                                             {
  ks_plot_host_seqctrl_manyplans(ctrl, &plan, 1);
}

ks_plot_host_seqctrl_manyplans()

void ks_plot_host_seqctrl_manyplans	(	KS_SEQ_CONTROL *	ctrl,
		KS_PHASEENCODING_PLAN **	plan,
		const int	num_plans
	)

                                                                                                              {

  char boardc[8] = "xyzrRto"; /* x,y,z,rho1, theta, omega */
  char fname[1000];
  char cmd[250];
  char outputdir_uid[250];
  FILE* fp;
  int plan_idx, i, j, w;
  KS_SEQLOC loc;
  KS_PHASEENCODING_PLAN* plan;

  if (ks_plot_filefmt == KS_PLOT_OFF || ctrl->duration == 0 || ctrl->nseqinstances ==  0) {
    return;
  }

  char fileformat_str[10];
  if (ks_plot_filefmt == KS_PLOT_MAKEPDF) { strcpy(fileformat_str, "pdf"); }
  else if (ks_plot_filefmt == KS_PLOT_MAKEPNG ) { strcpy(fileformat_str, "png"); }
  else if (ks_plot_filefmt == KS_PLOT_MAKESVG ) { strcpy(fileformat_str, "svg"); }

  outputdir_uid[0] = '\0';

#ifdef PSD_HW
  /* on MR-scanner */
  char path[250];
  sprintf(path,  "/usr/g/mrraw/plot/%s/host/", ks_psdname);
  if (ks_plot_kstmp) {
    sprintf(outputdir_uid, "/usr/g/mrraw/kstmp/%010d/plot/", rhkacq_uid);
  }
  sprintf(cmd, "mkdir -p %s > /dev/null", outputdir_uid);
  system(cmd);
  char outputdir[250];
  sprintf(outputdir, "/usr/g/mrraw/plot/%s/", ks_psdname);
  char pythonpath[] = "/usr/local/bin/apython";
  char psdplotpath[] = "/usr/local/bin/psdplot.py";
#ifdef IPG
  /* on IPG and on scanner, i.e. we are actually scanning. return quietly */
  return;
#endif
#else
  /* in Simulation */
  char path[] = "./plot/host/";
  char outputdir[] = "./plot/";
  char pythonpath[] = "apython";
  char psdplotpath[] = "../KSFoundation/psdplot/psdplot.py";
#endif
  sprintf(cmd, "mkdir -p %s > /dev/null", path);
  system(cmd);
  if (ctrl->duration <= 0) {
    return;
  }
  /* open files */
  sprintf(fname, "%spsdplot_%s_%s.json", path, ks_psdname, ctrl->description);
  fp = fopen(fname, "w");  
  fprintf(fp, "{\n");
  fprintf(fp, "\"metadata\": {\n");
  fprintf(fp, "\t\"mode\": \"host\",\n");
  fprintf(fp, "\t\"psdname\":  \"%s\",\n", ks_psdname);
  fprintf(fp, "\t\"sequence\": \"%s\",\n", ctrl->description);
  fprintf(fp, "\t\"duration\": %0.3f,\n", ctrl->duration/1000.0);
  fprintf(fp, "\t\"min_duration\": %0.3f,\n", ctrl->min_duration/1000.0);
  fprintf(fp, "\t\"ssi_time\": %0.3f,\n", ctrl->ssi_time/1000.0);
  fprintf(fp, "\t\"momentstart\": %.3f,\n", ctrl->momentstart/1000.0);
  fprintf(fp, "\t\"optr_desc\": \"%s\"\n", _optr.descr); /* optr declared as extern int in epic.ext.h included by KSFoundation_private.h */
  fprintf(fp, "},\n");

  /* PHASE ENCODING PLANS */
  fprintf(fp, "\"phaseencplans\": [\n");
  for (plan_idx = 0; plan_idx < num_plans; plan_idx++) {
    plan = plans[plan_idx];
    if (plan) {
      fprintf(fp, "{\n");
      fprintf(fp, "\t\"description\": \"%s\",\n", plan->description);
      fprintf(fp, "\t\"num_shots\": %d,\n", plan->num_shots);
      fprintf(fp, "\t\"etl\": %d,\n", plan->etl);
      fprintf(fp, "\t\"entries\": [\n");
      int echo, shot;
      for (shot = 0; shot < plan->num_shots; shot++) {
        fprintf(fp, "\t\t[");
        for (echo = 0; echo < plan->etl; echo++) {
          KS_PHASEENCODING_COORD coord = ks_phaseencoding_get(plan, echo, shot);
          fprintf(fp, "[%d, %d]", coord.ky, coord.kz);
          if (echo < (plan->etl - 1)) {
            fprintf(fp, ", ");
          }
        }
        fprintf(fp, "]");
        if (shot < (plan->num_shots - 1)) {
          fprintf(fp, ",\n");
        }
      }
      fprintf(fp, "]\n");

      if (plan_idx < (num_plans-1)) {
        fprintf(fp, "},\n");
      } else {
        fprintf(fp, "}\n");
      }
    }
  }
  fprintf(fp, "],\n");

  /* TRAPEZOIDS */
  fprintf(fp, "\"frames\": [\n");
  fprintf(fp, "{},\n");
  fprintf(fp, "{\n\"trapz\": {\n");
  for (i = 0; i < ctrl->gradrf.numtrap; i++) { /* each unique trap object */
    KS_TRAP* trap = ctrl->gradrf.trapptr[i];
    fprintf(fp, "\t\"%s\": {\n", trap->description);
    fprintf(fp, "\t\t\"ramptime\": %0.3f,\n", trap->ramptime / 1000.0);
    fprintf(fp, "\t\t\"plateautime\": %0.3f,\n", trap->plateautime / 1000.0);
    fprintf(fp, "\t\t\"duration\": %0.3f,\n", trap->duration / 1000.0);
    fprintf(fp, "\t\t\"amp\": %0.6f,\n", isnan(trap->amp) ? 0.0f : trap->amp);
    fprintf(fp, "\t\t\"instances\": [{\n");

    for (j = 0; j < trap->base.ninst; j++) { /* each instance of the trap */
      loc = trap->locs[j];
      fprintf(fp, "\t\t\t\"board\": \"%c\",\n", boardc[loc.board]);
      fprintf(fp,"\t\t\t\"time\": %0.3f,\n", loc.pos / 1000.0);
      fprintf(fp,"\t\t\t\"rtscale\": %0.6f,\n", (trap->rtscale == NULL) ? 1.0f : trap->rtscale[j]);
      fprintf(fp,"\t\t\t\"ampscale\": %0.6f\n", loc.ampscale);
      if (j == (trap->base.ninst -1)) {
        fprintf(fp, "\t\t}]\n");
      } else {
        fprintf(fp, "\t\t},{\n");
      }

    }
    if (i == (ctrl->gradrf.numtrap -1)) {
      fprintf(fp, "\t}\n");
    } else {
      fprintf(fp, "\t},\n");
    }
  }
  fprintf(fp, "},\n");

  /* ACQUISITIONS */
  fprintf(fp, "\"acquisitions\": [\n");
  for (i = 0; i < ctrl->gradrf.numacq; i++) { /* Each unique KS_READ object */
    KS_READ* acq = ctrl->gradrf.readptr[i];
    fprintf(fp, "\t{\n");
    fprintf(fp, "\t\t\"description\": \"%s\",\n", acq->description);
    fprintf(fp, "\t\t\"duration\": %0.3f,\n", acq->duration / 1000.0);
    fprintf(fp, "\t\t\"rbw\": %0.3f,\n", acq->rbw);
    fprintf(fp, "\t\t\"samples\": %d,\n", acq->filt.outputs);
    fprintf(fp, "\t\t\"time\": [");
    for (j = 0; j < acq->base.ninst; ++j) {
      fprintf(fp, "%0.3f", acq->pos[j] / 1000.0);
      if (j == (acq->base.ninst -1)) {
        fprintf(fp, "]\n");
      } else {
        fprintf(fp, ", ");
      }
    }
    if (i == (ctrl->gradrf.numacq -1)) {
      fprintf(fp, "\t}\n");
    } else {
      fprintf(fp, "\t},\n");
    }
  }
  fprintf(fp, "],\n");

  /* RF (RHO1) */
  fprintf(fp, "\"rf\": {\n");
  for (i = 0; i < ctrl->gradrf.numrf; i++) { /* each unique RF object */
    KS_RF* rfptr = ctrl->gradrf.rfptr[i];
    if (rfptr->rfwave.res > 0) {
      char roledesc[50];
      if (rfptr->role == KS_RF_ROLE_EXC) {
        strcpy(roledesc,"KS_RF_ROLE_EXC");
      } else if (rfptr->role ==  KS_RF_ROLE_REF) {
        strcpy(roledesc,"KS_RF_ROLE_REF");
      } else if (rfptr->role ==  KS_RF_ROLE_SPSAT) {
        strcpy(roledesc,"KS_RF_ROLE_SPSAT");
      } else if (rfptr->role == KS_RF_ROLE_CHEMSAT) {
        strcpy(roledesc, "KS_RF_ROLE_CHEMSAT");
      } else if (rfptr->role == KS_RF_ROLE_INV) {
        strcpy(roledesc, "KS_RF_ROLE_INV");
      } else if (rfptr->role == KS_RF_ROLE_SPSAT) {
        strcpy(roledesc, "KS_RF_ROLE_SPSAT");
      } else {
        strcpy(roledesc,"NONE");
      }
      fprintf(fp, "\t\"%s\": {\n", rfptr->rfwave.description);
      fprintf(fp, "\t\t\"description\": \"%s\",\n", rfptr->rfwave.description);
      fprintf(fp, "\t\t\"flipangle\": %0.3f,\n", rfptr->flip);
      fprintf(fp, "\t\t\"nominal_flipangle\": %0.3f,\n", rfptr->rfpulse.nom_fa);
      fprintf(fp, "\t\t\"max_b1\": %0.6f,\n", rfptr->rfpulse.max_b1);
      fprintf(fp, "\t\t\"amp\": %0.6f,\n", rfptr->amp);
      fprintf(fp, "\t\t\"isodelay\": %0.3f,\n", rfptr->start2iso / 1000.0);
      fprintf(fp, "\t\t\"duration\": %0.3f,\n", rfptr->rfwave.duration / 1000.0);
      fprintf(fp, "\t\t\"role\": \"%s\",\n", roledesc);

      fprintf(fp, "\t\t\"omega\": {\n");
      if (rfptr->omegawave.res > 0) {
        fprintf(fp, "\t\t\t\"description\": \"%s\",\n", rfptr->omegawave.description);
        fprintf(fp, "\t\t\t\"duration\": %0.3f,\n", rfptr->omegawave.duration / 1000.0);
        fprintf(fp, "\t\t\t\"waveform\": [0.0,");
        for (w = 0; w < rfptr->omegawave.res; w++) {
          fprintf(fp, "%0.6f,", rfptr->omegawave.waveform[w]);
        }
        fprintf(fp, "0.0],\n");
        fprintf(fp, "\t\t\t\"instances\": [{\n");
        for (j = 0; j < rfptr->omegawave.base.ninst; j++) {
          loc = rfptr->omegawave.locs[j];
          fprintf(fp, "\t\t\t\t\"time\": %0.3f,\n", loc.pos/1000.0);
          fprintf(fp, "\t\t\t\t\"board\": \"%c\",\n", boardc[loc.board]);
          fprintf(fp,"\t\t\t\t\"rtscale\": %0.6f,\n", (rfptr->omegawave.rtscale == NULL) ? 1.0f : rfptr->omegawave.rtscale[j]);
          fprintf(fp, "\t\t\t\t\"ampscale\": %0.6f\n", loc.ampscale);
          if (j == (rfptr->omegawave.base.ninst -1)) {
            fprintf(fp, "\t\t\t}]\n");
          } else {
            fprintf(fp, "\t\t\t},{\n");
          }
        }
      }
      fprintf(fp, "\t\t},\n"); /* Omega */

      fprintf(fp, "\t\t\"theta\": {\n");
      if (rfptr->thetawave.res > 0) {
        fprintf(fp, "\t\t\t\"description\": \"%s\",\n", rfptr->thetawave.description);
        fprintf(fp, "\t\t\t\"duration\": %0.3f,\n", rfptr->thetawave.duration / 1000.0);
        fprintf(fp, "\t\t\t\"waveform\": [0.0,");
        for (w = 0; w < rfptr->thetawave.res; w++) {
          fprintf(fp, "%0.6f,", rfptr->thetawave.waveform[w]);
        }
        fprintf(fp, "0.0],\n");
        fprintf(fp, "\t\t\t\"instances\": [{\n");
        for (j = 0; j < rfptr->thetawave.base.ninst; j++) {
          loc = rfptr->thetawave.locs[j];
          fprintf(fp, "\t\t\t\t\"time\": %0.3f,\n", loc.pos/1000.0);
          fprintf(fp, "\t\t\t\t\"board\": \"%c\",\n", boardc[loc.board]);
          fprintf(fp,"\t\t\t\t\"rtscale\": %0.6f,\n", (rfptr->omegawave.rtscale == NULL) ? 1.0f : rfptr->omegawave.rtscale[j]);
          fprintf(fp, "\t\t\t\t\"ampscale\": %0.6f\n", loc.ampscale);
          if (j == (rfptr->thetawave.base.ninst -1)) {
            fprintf(fp, "\t\t\t}]\n");
          } else {
            fprintf(fp, "\t\t\t},{\n");
          }
        }
      }
      fprintf(fp, "\t\t},\n");  /* Theta */

      fprintf(fp, "\t\t\"waveform\": [0.0,");
      for (w = 0; w <= rfptr->rfwave.res; w++) {
          fprintf(fp, "%0.6f,", rfptr->rfwave.waveform[w]);
      }
      fprintf(fp, "0.0],\n");
      fprintf(fp, "\t\t\"instances\": [{\n");
      for (j = 0; j < rfptr->rfwave.base.ninst; j++) { /* each instance of the wave (RHO1) */
        loc = rfptr->rfwave.locs[j];
        fprintf(fp, "\t\t\t\"time\": %0.3f,\n", loc.pos/1000.0);
        fprintf(fp, "\t\t\t\"board\": \"%c\",\n", boardc[loc.board]);
        fprintf(fp,"\t\t\t\"rtscale\": %0.6f,\n", (rfptr->rfwave.rtscale == NULL) ? 1.0f : rfptr->rfwave.rtscale[j]);
        fprintf(fp, "\t\t\t\"ampscale\": %0.6f\n", loc.ampscale);
        if (j == (rfptr->rfwave.base.ninst -1)) {
          fprintf(fp, "\t\t}]\n");
        } else {
          fprintf(fp, "\t\t},{\n");
        }
      }

      if (i == (ctrl->gradrf.numrf -1)) {
        fprintf(fp, "\t}\n");
      } else {
        fprintf(fp, "\t},\n");
      }
    } /* res > 0 */
  } /* rf */
  fprintf(fp, "},\n");

    fprintf(fp, "\"waves\": {\n");
    /* other (non-RF) waves */
    for (i = 0; i < ctrl->gradrf.numwave; i++) {
      KS_WAVE* waveptr = ctrl->gradrf.waveptr[i];
      if (waveptr->res > 0) {
        fprintf(fp, "\t\"%s\": {\n", waveptr->description);
        fprintf(fp, "\t\t\"description\": \"%s\",\n", waveptr->description);
        fprintf(fp, "\t\t\"duration\": %0.3f,\n", waveptr->duration / 1000.0);
        fprintf(fp, "\t\t\"waveform\": [0.0,");
        for (w = 0; w < waveptr->res; w++) {
            fprintf(fp, "%0.6f,", waveptr->waveform[w]);
        }
        fprintf(fp, "0.0],\n");

        fprintf(fp, "\t\t\"instances\": [{\n");
        for (j = 0; j < waveptr->base.ninst; j++) { /* each instance of the wave */
          loc = waveptr->locs[j];
          fprintf(fp, "\t\t\t\"board\": \"%c\",\n", boardc[loc.board]);
          fprintf(fp, "\t\t\t\"time\": %0.3f,\n", loc.pos/1000.0);
          fprintf(fp,"\t\t\t\"rtscale\": %0.6f,\n", (waveptr->rtscale == NULL) ? 1.0f : waveptr->rtscale[j]);
          fprintf(fp, "\t\t\t\"ampscale\": %0.6f\n", loc.ampscale);
          if (j == (waveptr->base.ninst -1)) {
            fprintf(fp, "\t\t}]\n");
          } else {
            fprintf(fp, "\t\t},{\n");
          }
        }
        if (i == (ctrl->gradrf.numwave -1)) {
          fprintf(fp, "\t}\n");
        } else {
          fprintf(fp, "\t},\n");
        }
      } /* res > 0 */
    }
  fprintf(fp, "}\n"); /* End waves */
  fprintf(fp, "}\n"); /* End frame */
  fprintf(fp, "]\n"); /* End frames */
  fprintf(fp, "}"); /* End */
  fflush(fp);
  fclose(fp);

  {
    char cmd[1000];
    sprintf(cmd, "%s %s %s "
                 "--outputdir %s &",
            pythonpath, psdplotpath, fname,
            outputdir);
    ks_dbg("%s", cmd);
    system(cmd);
 #ifdef PSD_HW
/* on MR-scanner */
    if (ks_plot_kstmp) {
      sprintf(outputdir_uid, "/usr/g/mrraw/kstmp/%010d/plot/", rhkacq_uid);
      sprintf(cmd, "cp %s%s_%s.html %s",
            outputdir, ks_psdname, ctrl->description,
            outputdir_uid);
      ks_dbg("%s", cmd);
      system(cmd);
      sprintf(cmd, "cp %s*.json %s > /dev/null", path, outputdir_uid);
      ks_dbg("%s", cmd);
      system(cmd);
    }
#endif
  }
  return;
}

ks_plot_tgt_reset()

void ks_plot_tgt_reset

(

KS_SEQ_CONTROL *

ctrl

)

                                             {
  FILE *fp;
  char fname_json[1000];
  char cmd[200];
  #ifdef PSD_HW
    return;
  #endif


  if (ks_plot_filefmt == KS_PLOT_OFF) {
    return;
  }

  system("mkdir -p ./plot/tgt/");
  sprintf(fname_json, "./plot/tgt/psdplot_tgt_%s_%s.json", ks_psdname, ctrl->description);
  sprintf(cmd, "rm -f %s ./plot/tgt/%s_%s_*_tgt.*",
          fname_json, ks_psdname, ctrl->description);
  system(cmd);
  fp = fopen(fname_json, "w");
  fprintf(fp, "{\n"
              "\"metadata\": {\n"
              "\t\"mode\": \"tgt\",\n"
              "\t\"psdname\":  \"%s\",\n"
              "\t\"sequence\": \"%s\",\n"
              "\t\"duration\": %0.3f,\n"
              "\t\"min_duration\": %0.3f,\n"
              "\t\"ssi_time\": %0.3f,\n"
              "\t\"momentstart\": %.3f\n"
              "},\n"
              "\"frames\": [\n"
              "{}]}",
              ks_psdname,
              ctrl->description,
              ctrl->duration/1000.0,
              ctrl->min_duration/1000.0,
              ctrl->ssi_time/1000.0,
              ctrl->momentstart/1000.0
          );
  fclose(fp);
}

ks_plot_tgt_addframe()

void ks_plot_tgt_addframe

(

KS_SEQ_CONTROL *

ctrl

)

Writes a plot frame to file

Parameters

ctrl	Pointer to sequence control

                                                {
  #if (!(defined(SIM) && defined(IPG)))
    return;
  #endif

  if (ks_plot_filefmt == KS_PLOT_OFF) {
    return;
  }

  char boardc[8] = "xyzrRto"; /* x,y,z,rho1, rho2, theta, omega*/
  char fname[1000];
  sprintf(fname, "./plot/tgt/psdplot_tgt_%s_%s.json", ks_psdname, ctrl->description);
  FILE *fp;
  int i, w, inst, boardinstance;
  KS_SEQLOC loc;
  fp = fopen(fname, "r+");
  fseek(fp, -2, SEEK_END);
  fputs(",{\n", fp);
  short iamp;
  float gradmax;
  float amp;

  /* TRAPEZOIDS */
  fprintf(fp, "\"trapz\": {\n");
  fflush(fp);
  KS_TRAP* trap;
  for (i = 0; i < ctrl->gradrf.numtrap; i++) { /* Each unique trap object */
    trap = ctrl->gradrf.trapptr[i];
    fprintf(fp, "\t\"%s\": {\n", trap->description);
    fprintf(fp, "\t\t\"ramptime\": %0.3f,\n", trap->ramptime / 1000.0);
    fprintf(fp, "\t\t\"plateautime\": %0.3f,\n", trap->plateautime / 1000.0);
    fprintf(fp, "\t\t\"duration\": %0.3f,\n", trap->duration / 1000.0);
    fprintf(fp, "\t\t\"amp\": %0.6f,\n", 1.0);
    fprintf(fp, "\t\t\"instances\": [{\n");
    fflush(fp);
    for (inst = 0; inst < ctrl->gradrf.trapptr[i]->base.ngenerated; inst++) { /* Each instance of this trap */
      loc = trap->locs[inst];
      fprintf(fp, "\t\t\t\"board\": \"%c\",\n", boardc[loc.board]);
      fprintf(fp, "\t\t\t\"time\": %0.3f,\n", loc.pos / 1000.0);

      WF_PULSE* plateau_ptr = trap->wfi[inst].wf;
      boardinstance = trap->wfi[inst].boardinstance;
       /* Get the linked list of the plateau (used to get the position of all wf instances) */
      /* WF_INSTR_HDR instr_plateau = plateau_ptr->inst_hdr_tail; */
      /* WF_INSTR_HDR instr_attack = plateau_ptr->assoc_pulse->inst_hdr_tail; */ /* Attack is the associated pulse of the plateau */
      /* WF_INSTR_HDR instr_decay = plateau_ptr->assoc_pulse->assoc_pulse->inst_hdr_tail; */ /* Decay is the associated pulse of the attack */
      /*
      for (idx = 0; idx < (boardinstance); idx++) {
        instr_plateau = instr_plateau->next;
        instr_attack = instr_attack->next;
        instr_decay = instr_decay->next;
      }
      */
      /* Plateau amplitude is written in G/cm */
      getiamp(&iamp, plateau_ptr, boardinstance);
      fprintf(fp, "\t\t\t\"ampscale\": 1.0,\n");
      gradmax = ks_syslimits_gradtarget(loggrd, trap->wfi[inst].loc.board);
      if (loc.board == OMEGA || loc.board == THETA) {
        gradmax = 1;
      }
      amp = gradmax * (float)iamp / MAX_PG_IAMP;
      fprintf(fp, "\t\t\t\"rtscale\": %.12f\n", amp);

      /* char pulsename[100]; */
      /* (float)pbeg(plateau_ptr, pulsename, boardinstance)/1000.0 */
      /* sprintf(pulsename, "%s%s", plateau_ptr->pulsename, "a"); */

      if (inst == (trap->base.ngenerated -1)) {
        fprintf(fp, "\t\t}]\n");
      } else {
        fprintf(fp, "\t\t},{\n");
      }
    } /* inst */
    if (i == (ctrl->gradrf.numtrap -1)) {
      fprintf(fp, "\t}\n");
    } else {
      fprintf(fp, "\t},\n");
    }
  }
  fprintf(fp, "},\n"); /* Trapezoids */

  fprintf(fp, "\"acquisitions\": [\n");
  /* ACQUISITIONS */
  for (i = 0; i < ctrl->gradrf.numacq; i++) { /* Each unique KS_READ object */
    KS_READ* acq = ctrl->gradrf.readptr[i];
    fprintf(fp, "\t{\n");
    fprintf(fp, "\t\t\"description\": \"%s\",\n", acq->description);
    fprintf(fp, "\t\t\"duration\": %0.3f,\n", acq->duration / 1000.0);
    fprintf(fp, "\t\t\"rbw\": %0.3f,\n", acq->rbw);
    fprintf(fp, "\t\t\"samples\": %d,\n", acq->filt.outputs);
    fprintf(fp, "\t\t\"time\": [");
    for (inst = 0; inst < acq->base.ngenerated; ++inst) {
      fprintf(fp, "%0.3f", acq->pos[inst] / 1000.0);
      if (inst == (acq->base.ninst -1)) {
        fprintf(fp, "]\n");
      } else {
        fprintf(fp, ", ");
      }
    } /* inst */
    if (i == (ctrl->gradrf.numacq -1)) {
      fprintf(fp, "\t}\n");
    } else {
      fprintf(fp, "\t},\n");
    }
  } /* ACQUISITIONS */
  fprintf(fp, "],\n"); /* End acquisitions */

  /* RF */
  WF_PULSE* rf_wf;
  WF_PULSE* omega_wf;
  WF_PULSE* theta_wf;
  short new_wave_iamp;
  KS_IWAVE acquired_wave; /* short int array */
  fprintf(fp, "\"rf\": {\n");
  for (i = 0; i < ctrl->gradrf.numrf; ++i) { /* Each unique KS_RF object */
    KS_RF* rfptr = ctrl->gradrf.rfptr[i];

    if (rfptr->rfwave.res > 0) {
      /* RHO */
      char roledesc[50];
      if (rfptr->role == KS_RF_ROLE_EXC) {
        strcpy(roledesc,"KS_RF_ROLE_EXC");
      } else if (rfptr->role ==  KS_RF_ROLE_REF) {
        strcpy(roledesc,"KS_RF_ROLE_REF");
      } else if (rfptr->role == KS_RF_ROLE_CHEMSAT) {
        strcpy(roledesc, "KS_RF_ROLE_CHEMSAT");
      } else if (rfptr->role == KS_RF_ROLE_INV) {
        strcpy(roledesc, "KS_RF_ROLE_INV");
      } else if (rfptr->role == KS_RF_ROLE_SPSAT) {
        strcpy(roledesc, "KS_RF_ROLE_SPSAT");
      } else {
        strcpy(roledesc,"NONE");
      }
      fprintf(fp, "\t\"%s\": {\n", rfptr->rfwave.description);
      fprintf(fp, "\t\t\"description\": \"%s\",\n", rfptr->rfwave.description);
      fprintf(fp, "\t\t\"flipangle\": %0.3f,\n", rfptr->flip);
      fprintf(fp, "\t\t\"nominal_flipangle\": %0.3f,\n", rfptr->rfpulse.nom_fa);
      fprintf(fp, "\t\t\"max_b1\": %0.6f,\n", rfptr->rfpulse.max_b1);
      fprintf(fp, "\t\t\"isodelay\": %0.3f,\n", rfptr->start2iso / 1000.0);
      fprintf(fp, "\t\t\"duration\": %0.3f,\n", rfptr->rfwave.duration / 1000.0);
      fprintf(fp, "\t\t\"role\": \"%s\",\n", roledesc);
      fprintf(fp, "\t\t\"amp\": %.3f,\n", rfptr->amp);
      /* OMEGA */
      fprintf(fp, "\t\t\"omega\": {\n");
      if (rfptr->omegawave.res > 0) {
        fprintf(fp, "\t\t\t\"description\": \"%s\",\n", rfptr->omegawave.description);
        fprintf(fp, "\t\t\t\"duration\": %0.3f,\n", rfptr->omegawave.duration / 1000.0);
        fprintf(fp, "\t\t\t\"instances\": [{\n");
        for (inst = 0; inst < rfptr->omegawave.base.ngenerated; ++inst) {
          loc = rfptr->omegawave.locs[inst];
          boardinstance = rfptr->omegawave.wfi[inst].boardinstance;
          omega_wf = &(rfptr->omegawave.wfpulse[OMEGA][KS_WF_MAIN]);
          movewaveimm(acquired_wave, omega_wf, boardinstance, rfptr->omegawave.res, FROMHARDWARE);
          getiamp(&new_wave_iamp, omega_wf, boardinstance);
          fprintf(fp, "\t\t\t\t\"waveform\": [0,");
          for (w = 0; w < rfptr->omegawave.res; w++) {
            fprintf(fp, "%d,", acquired_wave[w]);
          }
          fprintf(fp, "0],\n");
          fprintf(fp, "\t\t\t\t\"time\": %0.3f,\n", loc.pos/1000.0);
          fprintf(fp, "\t\t\t\t\"board\": \"%c\",\n", boardc[loc.board]);
          fprintf(fp, "\t\t\t\t\"ampscale\": 1.0,\n");
          fprintf(fp, "\t\t\t\t\"rtscale\": %0.12f\n", (float)(new_wave_iamp) / (max_pg_wamp * max_pg_wamp));
          if (inst == (rfptr->omegawave.base.ngenerated -1)) {
            fprintf(fp, "\t\t\t}]\n");
          } else {
            fprintf(fp, "\t\t\t},{\n");
          }
        }
      }
      fprintf(fp, "\t\t},\n"); /* Omega */

      /* THETA */
      fprintf(fp, "\t\t\"theta\": {\n");
      if (rfptr->thetawave.res > 0) {
        fprintf(fp, "\t\t\t\"description\": \"%s\",\n", rfptr->thetawave.description);
        fprintf(fp, "\t\t\t\"duration\": %0.3f,\n", rfptr->thetawave.duration / 1000.0);
        fprintf(fp, "\t\t\t\"instances\": [{\n");
        for (inst = 0; inst < rfptr->thetawave.base.ngenerated; ++inst) {
          loc = rfptr->thetawave.locs[inst];
          boardinstance = rfptr->thetawave.wfi[inst].boardinstance;
          theta_wf = &(rfptr->thetawave.wfpulse[THETA][KS_WF_MAIN]);
          movewaveimm(acquired_wave, theta_wf, boardinstance, rfptr->thetawave.res, FROMHARDWARE);
          getiamp(&new_wave_iamp, theta_wf, boardinstance);
          fprintf(fp, "\t\t\t\t\"waveform\": [0");
          for (w = 0; w < rfptr->thetawave.res; w++) {
            fprintf(fp, "%d,", acquired_wave[w]);
          }
          fprintf(fp, "0],\n");
          fprintf(fp, "\t\t\t\t\"time\": %0.3f,\n", loc.pos/1000.0);
          fprintf(fp, "\t\t\t\t\"board\": \"%c\",\n", boardc[loc.board]);
          fprintf(fp, "\t\t\t\t\"ampscale\": 1.0,\n");
          fprintf(fp, "\t\t\t\t\"rtscale\": %0.12f\n", (float)(new_wave_iamp) / (max_pg_wamp * max_pg_wamp));
          if (inst == (rfptr->thetawave.base.ngenerated -1)) {
            fprintf(fp, "\t\t\t}]\n");
          } else {
            fprintf(fp, "\t\t\t},{\n");
          }
        }
      }
      fprintf(fp, "\t\t},\n"); /* Theta */

      fprintf(fp, "\t\t\"instances\": [{\n");
      for (inst = 0; inst < rfptr->rfwave.base.ngenerated; ++inst) {
        loc = rfptr->rfwave.locs[inst];
        boardinstance = rfptr->rfwave.wfi[inst].boardinstance;
        rf_wf = &(rfptr->rfwave.wfpulse[RHO][KS_WF_MAIN]);
        /* Get waveform from hardware */
        movewaveimm(acquired_wave, rf_wf, boardinstance, rfptr->rfwave.res, FROMHARDWARE);
        /* B1max recalculations */
        getiamp(&new_wave_iamp, rf_wf, boardinstance);
        fprintf(fp, "\t\t\t\"waveform\": [0,");
        for (w = 0; w < rfptr->rfwave.res; w++) {
          fprintf(fp, "%d,", acquired_wave[w]);
        }
        fprintf(fp, "0],\n");
        fprintf(fp, "\t\t\t\"board\": \"%c\",\n", boardc[loc.board]);
        fprintf(fp, "\t\t\t\"time\": %0.3f,\n", loc.pos/1000.0);
        fprintf(fp, "\t\t\t\"ampscale\": 1.0,\n");
        fprintf(fp, "\t\t\t\"rtscale\": %0.12f\n", (float)new_wave_iamp / (rfptr->amp * max_pg_wamp * max_pg_wamp));
        if (inst == (rfptr->rfwave.base.ngenerated -1)) {
          fprintf(fp, "\t\t}]\n");
        } else {
          fprintf(fp, "\t\t},{\n");
        }
      }
      if (i == (ctrl->gradrf.numrf -1)) {
        fprintf(fp, "\t}\n");
      } else {
        fprintf(fp, "\t},\n");
      }
    } /* res > 0 */


  } /* End RF */
  fprintf(fp, "},\n"); /* End RF */
  /* other (non-RF) waves */
  fprintf(fp, "\"waves\": {\n");

  for (i = 0; i < ctrl->gradrf.numwave; i++) { /* each unique wave object */
    KS_WAVE* waveptr = ctrl->gradrf.waveptr[i];
    if (waveptr->res > 0) {
      fprintf(fp, "\t\"%s\": {\n", waveptr->description);
      fprintf(fp, "\t\t\"description\": \"%s\",\n", waveptr->description);
      fprintf(fp, "\t\t\"duration\": %0.3f,\n", waveptr->duration / 1000.0);
      fprintf(fp, "\t\t\"instances\": [{\n");
      for (inst = 0; inst < waveptr->base.ninst; inst++) { /* each instance of the wave */
        loc = waveptr->locs[inst];
        boardinstance = waveptr->wfi[inst].boardinstance;
        WF_PULSE* other_wf = &(waveptr->wfpulse[loc.board][KS_WF_MAIN]);
        movewaveimm(acquired_wave, other_wf, boardinstance, waveptr->res, FROMHARDWARE);
        getiamp(&new_wave_iamp, other_wf, boardinstance);
        fprintf(fp, "\t\t\t\"waveform\": [0,");
        for (w = 0; w < waveptr->res; w++) {
          fprintf(fp, "%d,", acquired_wave[w]); /* Or just waveptr->waveform[w] ? */
        }
        fprintf(fp, "0],\n");
        fprintf(fp, "\t\t\t\"board\": \"%c\",\n", boardc[loc.board]);
        fprintf(fp, "\t\t\t\"time\": %0.3f,\n", loc.pos/1000.0);
        fprintf(fp, "\t\t\t\"ampscale\": 1.0,\n");
        fprintf(fp, "\t\t\t\"rtscale\": %0.12f\n", ks_syslimits_gradtarget(loggrd, loc.board) * (float)new_wave_iamp / (max_pg_wamp * max_pg_wamp));
        if (inst == (waveptr->base.ninst -1)) {
          fprintf(fp, "\t\t}]\n");
        } else {
          fprintf(fp, "\t\t},{\n");
        }
      }
      if (i == (ctrl->gradrf.numwave -1)) {
        fprintf(fp, "\t}\n");
      } else {
        fprintf(fp, "\t},\n");
      }
    } /* res > 0 */
  }
  fprintf(fp, "}\n"); /* End waves */
  fprintf(fp, "}\n"); /* End frame */
  fprintf(fp,"]}"); /* End frames*/

  fflush(fp);
  fclose(fp);
  return;
}

ks_scan_rf_ampscale()

void ks_scan_rf_ampscale	(	KS_RF *	rf,
		int	instanceno,
		float	ampscale
	)

Changes the amplitude of one or all instances of an RF pulse (KS_RF)

This function multiplies one instance of a KS_RF object with an amplitude scale factor (3rd arg) that must be in range [-1.0,1.0]. To change all instances of a KS_RF object, use INSTRALL as the 2nd argument.

The actual flip angle for an instance of a KS_RF object is the multiplication of the three factors:

1. The designed flip angle
2. The per-instance .ampscale in the KS_SEQLOC struct passed to ks_pg_rf()
3. The ampscale value passed in as 3rd argument to this function. Since both ampscale factors are forced to be in range [-1.0,1.0], it is not possible to increase the flip angle beyond the designed value (.flip)

Parameters

[in,out]	rf	Pointer to KS_RF
[in]	instanceno	Instance of KS_RF to change (INSTRALL changes all instances)
[in]	ampscale	RF amplitude scale factor in range [-1.0,1.0]

                                                                    {
  int firstinstance, lastinstance, i;
#ifdef IPG
  int instramp;
  KS_WFINSTANCE *wfi;
  int numplaced = rf->rfwave.base.ngenerated;
#else
  int numplaced = rf->rfwave.base.ninst;
  if (!numplaced) {
    return;
  }
  float* tmp = (float*)realloc(rf->rfwave.rtscale, numplaced * sizeof(float));
  if (!tmp) {
    ks_error("%s: rtscale realloc failed", __FUNCTION__);
    return;
  }
  rf->rfwave.rtscale = tmp;
#endif

  if (instanceno == INSTRALL) {
    firstinstance = 0;
    lastinstance = numplaced - 1;
  } else {
    firstinstance = instanceno;
    lastinstance = instanceno;
  }

  /* input validation */
  if (numplaced == 0) {
    return;
  }

  if (firstinstance < 0 || lastinstance >= numplaced) {
    ks_error("ks_scan_rf_ampscale(%s): instanceno (%d) out of range [0,%d]", rf->rfwave.description, instanceno, numplaced - 1);
    return;
  }

  if (fabs(ampscale) > 1.0) {
    ks_error("ks_scan_rf_ampscale(%s): ampscale too large (%f)", rf->rfwave.description, ampscale);
    return;
  }

#ifdef IPG

  /* set amplitude(s) */
  for (i = firstinstance; i <= lastinstance; i++) {
    wfi = &rf->rfwave.wfi[i];
    instramp = (int)(rf->amp * wfi->loc.ampscale * ampscale * MAX_PG_IAMP);
    setiamp(instramp, wfi->wf, wfi->boardinstance);
  } /* for */

#else
  for (i = firstinstance; i <= lastinstance; i++) {
    rf->rfwave.rtscale[i] = ampscale;
  }
#endif

} /* ks_scan_rf_ampscale */

ks_scan_rf_on()

void ks_scan_rf_on	(	KS_RF *	rf,
		int	instanceno
	)

Resets the amplitude of one or all instances of an RF pulse (KS_RF)

This function (re)sets the RF amplitude to the state given by ks_pg_rf()

Parameters

[in,out]	rf	Pointer to KS_RF
[in]	instanceno	Instance of KS_RF to change (INSTRALL changes all instances)

                                              {

  ks_scan_rf_ampscale(rf, instanceno, 1.0);

}

ks_scan_rf_on_chop()

void ks_scan_rf_on_chop	(	KS_RF *	rf,
		int	instanceno
	)

Resets the amplitude of one or all instances of an RF pulse (KS_RF) and toggles the sign (chopping)

Everytime this function is called, the magnitude of the RF amplitude will be (re)set the RF amplitude to the state given by ks_pg_rf() and the polarity of the RF amplitude will be changed. If this function is called each TR (RF chopping) for a linear single-line k-space acquisition, a FOV/2 shift will occur in the image with any DC component shifted out to the edges of the image FOV.

Parameters

[in,out]	rf	Pointer to KS_RF
[in]	instanceno	Instance of KS_RF to change (INSTRALL changes all instances)

                                                   {
  static float chopsign = 1.0;

  ks_scan_rf_ampscale(rf, instanceno, chopsign);

  chopsign *= -1.0;

}

ks_scan_rf_off()

void ks_scan_rf_off	(	KS_RF *	rf,
		int	instanceno
	)

Sets the amplitude of one or all instances of an RF pulse (KS_RF) to zero

This can be undone by calling ks_scan_rf_on(), ks_scan_rf_on_chop(), or ks_scan_rf_ampscale()

Parameters

[in,out]	rf	Pointer to KS_RF
[in]	instanceno	Instance of KS_RF to change (INSTRALL changes all instances)

                                               {

  ks_scan_rf_ampscale(rf, instanceno, 0.0);

}

ks_scan_selrf_setfreqphase()

void ks_scan_selrf_setfreqphase	(	KS_SELRF *	selrf,
		int	instanceno,
		SCAN_INFO	sliceinfo,
		float	rfphase
	)

Updates the frequency and phase of one or all instances of a slice selective RF pulse (KS_SELRF)

This function alters the frequency of the RF pulse in a KS_SELRF object to excite a spatial location corresponding to the information in sliceinfo.tloc. The phase of the RF pulse is also updated

Parameters

[in,out]	selrf	Pointer to KS_SELRF
[in]	instanceno	Instance of KS_RF to change (INSTRALL changes all instances)
[in]	sliceinfo	SCAN_INFO struct for the current slice to be played out
[in]	rfphase	Phase of the RF pulse in [degrees]

Return values

STATUS

SUCCESS or FAILURE

                                                                                                       {
  int firstinstance, lastinstance;
  int i;
  float freqoffHz, hertzPerMm, ampscale;
#ifdef IPG
  float tloc = sliceinfo.optloc;
  int numplaced = selrf->rf.rfwave.base.ngenerated;
#else
  float tloc = 1.0; /* Simulate offset of 1 mm for plotting in units of [Hz/mm] */
  int numplaced = selrf->rf.rfwave.base.ninst;
#endif

  if (instanceno == INSTRALL) {
    firstinstance = 0;
    lastinstance = numplaced - 1;
  } else {
    firstinstance = instanceno;
    lastinstance = instanceno;
  }

  if (numplaced == 0) {
    return;
  }
  if (firstinstance < 0 || lastinstance >= numplaced) {
    ks_error("ks_scan_selrf_setfreqphase(%s): instanceno (%d) out of range [0,%d]", selrf->rf.rfwave.description, instanceno, numplaced - 1);
    return;
  }

  /* set frequency */
  for (i = firstinstance; i <= lastinstance; i++) {
#ifdef IPG
  if (!(i < selrf->rf.rfwave.base.ngenerated &&
        selrf->rf.rfwave.wfi[i].wf->wavegen_type == TYPRHO1 &&
        selrf->rf.rfwave.wfi[i].wf->assoc_pulse->tag == SSPFREQ)) { /* make sure it has been set up properly */
    ks_error("ks_scan_rf_setfreqphase(%s): RF pulse not properly set up or instance # too high", selrf->rf.rfwave.description);
    return;
  }
  if (selrf->gradwave.res > 0) {
    /* gradwave */
    if (selrf->gradwave.wfi != NULL) {
      ampscale = selrf->gradwave.wfi[i].loc.ampscale;
    } else {
      ks_error("ks_scan_rf_setfreqphase(%s): no gradwave has been set up, setting ampscale = 0", selrf->rf.rfwave.description);
      ampscale = 0;
    }
  } else {
    /* trapezoid */
    if (selrf->grad.wfi != NULL) {
      ampscale = selrf->grad.wfi[i].loc.ampscale;
    } else {
      ks_error("ks_scan_rf_setfreqphase(%s): no grad has been set up, setting ampscale = 0", selrf->rf.rfwave.description);
      ampscale = 0; /* protect against wfi[i] = NULL, then return 0 amp */
    }
  }
#else
  ampscale = (selrf->gradwave.res > 0) ? selrf->gradwave.locs[i].ampscale
                                             : selrf->grad.locs[i].ampscale;
#endif

    /* ampscale (a.u.) * GAM [Hz/G] / 10.0 [cm->mm] * gradamp [G/cm] = [Hz/mm] */
    hertzPerMm = ampscale * GAM / 10.0 *
                 ((selrf->gradwave.res > 0) ? ks_calc_selgradamp(selrf->rf.bw, selrf->slthick) /* gradwave slice selection */
                                             : selrf->grad.amp); /* trapezoid slice selection */
    freqoffHz = selrf->rf.cf_offset; /* [Hz] */

    /* optloc-dependent freq offset */
    if (selrf->rf.omegawave.res > 0) {
      ks_scan_omegawave_hz(&selrf->rf.omegawave, i, hertzPerMm * tloc /* [Hz] */);
    } else {
      freqoffHz += hertzPerMm * tloc; /* [Hz] */
    }

#ifdef IPG
    /* set RF frequency offset */
    setfrequency((int)(freqoffHz / TARDIS_FREQ_RES), selrf->rf.rfwave.wfi[i].wf, selrf->rf.rfwave.wfi[i].boardinstance);

    /* calculate phase */
    {
      double ftime_delay;           /* floating point time delay in seconds */
      double temp_freq;             /* frequency offset */
      long tmpphase;
      int syncpos, rfstartpos, time_delay;

      /* start of RF pulse wave form (for 1st boardinstance) */
      rfstartpos = selrf->rf.rfwave.wfi[i].wf->inst_hdr_tail->start;
      /* start of RF SSP frq pulse  (for 1st boardinstance) */
      syncpos = selrf->rf.rfwave.wfi[i].wf->assoc_pulse->inst_hdr_tail->start;

      /* time difference between SSP frq and isocenter of RF pulse */
      time_delay = rfstartpos - syncpos - 9 /* frq2sync_dly */ + RUP_FACTOR(selrf->rf.rfwave.duration - selrf->rf.iso2end, 2);

      /*** Modified from GE's setupphases() ***/
      ftime_delay = ((double)time_delay) / ((double) 1.0e6);
      temp_freq = (double) freqoffHz;
      tmpphase = (ks_degrees_to_iphase(rfphase) /* deg->iphase */ + ks_cycles_to_iphase( - temp_freq * ftime_delay )) % FS_2PI; /* radians */
      setiphase(tmpphase,  selrf->rf.rfwave.wfi[i].wf, selrf->rf.rfwave.wfi[i].boardinstance);
    }
#endif
  } /* for each instance */
} /* ks_scan_selrf_setfreqphase */

ks_scan_selrf_setfreqphase_pins()

void ks_scan_selrf_setfreqphase_pins	(	KS_SELRF *	selrf,
		int	instanceno,
		SCAN_INFO	sliceinfo,
		int	sms_multiband_factor,
		float	sms_slice_gap,
		float	rfphase
	)

Updates the off-center phase-modulation of one or all instances of a PINS RF pulse (KS_SELRF)

This function alters the phase of the PINS RF pulse in a KS_SELRF object to excite spatial locations corresponding to the information in sliceinfo.tloc.

Parameters

[in,out]	selrf	Pointer to KS_SELRF
[in]	instanceno	Instance of KS_RF to change (INSTRALL changes all instances)
[in]	sliceinfo	SCAN_INFO struct for the current slice to be played out
[in]	sms_multiband_factor
[in]	sms_slice_gap	in [mm]
[in]	rfphase	Phase of the RF pulse in [degrees]

Return values

STATUS

SUCCESS or FAILURE

                                                      {

  int firstinstance, lastinstance, j;
  int phaseIndex = 1;
  KS_WAVE newwave = KS_INIT_WAVE;
  float locOffset;
  float phaseIncrement;
#ifdef IPG
  int i;
  int numplaced = selrf->rf.rfwave.base.ngenerated;
#else
  int numplaced = selrf->rf.rfwave.base.ninst;
#endif

  if (instanceno == INSTRALL) {
    firstinstance = 0;
    lastinstance = numplaced - 1;
  } else {
    firstinstance = instanceno;
    lastinstance = instanceno;
  }

  if (numplaced == 0) {
    return;
  }

  if (firstinstance < 0 || lastinstance >= numplaced) {
    ks_error("ks_scan_selrf_setfreqphase_pins(%s): instanceno (%d) out of range [0,%d]", selrf->rf.rfwave.description, instanceno, numplaced - 1);
    return;
  }

  newwave = selrf->rf.thetawave;

  locOffset = sliceinfo.optloc;
  phaseIncrement = (360.0 / sms_slice_gap) * locOffset;

  /* If the MB-factor is even, center the slice group */
  if (sms_multiband_factor % 2 == 0) {
    phaseIncrement += 180.0;
  }

  for (j = 0; j < selrf->rf.thetawave.res; j++) {

    if (!areSame(selrf->rf.rfwave.waveform[j], 0.0)) {
      newwave.waveform[j] = selrf->rf.thetawave.waveform[j] + ((float)phaseIndex * phaseIncrement) + rfphase;
    }

    if (j < selrf->rf.thetawave.res - 1) {
      if (!areSame(selrf->rf.rfwave.waveform[j], 0.0) && areSame(selrf->rf.rfwave.waveform[j + 1], 0.0)) {
        phaseIndex++;
      }
    }
  }

#ifdef IPG

  for (i = firstinstance; i <= lastinstance; i++) {
    /* set RF frequency & phase offset to zero */
    setfrequency(0, selrf->rf.rfwave.wfi[i].wf, selrf->rf.rfwave.wfi[i].boardinstance);
    setphase(0.0, selrf->rf.rfwave.wfi[i].wf, selrf->rf.rfwave.wfi[i].boardinstance);

    /* move modified thetawave to hardware */
    ks_scan_wave2hardware(&selrf->rf.thetawave, newwave.waveform);
  }

#endif

} /* ks_scan_selrf_setfreqphase_pins */

ks_scan_rf_setphase()

void ks_scan_rf_setphase	(	KS_RF *	rf,
		int	instanceno,
		float	rfphase
	)

Updates the phase of one or all instances of an RF pulse (KS_RF)

This function sets the phase of an RF pulse object (KS_RF). Can be used for RF spoiling

Parameters

[in,out]	rf	Pointer to KS_SEL
[in]	instanceno	Instance of KS_RF to change (INSTRALL changes all instances)
[in]	rfphase	Phase of the RF pulse in [degrees]

                                                                     {
  int firstinstance, lastinstance;
  #ifdef IPG
    int i;
    int numplaced = rf->rfwave.base.ngenerated;
  #else
    int numplaced = rf->rfwave.base.ninst;
  #endif

  if (instanceno == INSTRALL) {
    firstinstance = 0;
    lastinstance = numplaced - 1;
  } else {
    firstinstance = instanceno;
    lastinstance = instanceno;
  }

  if (numplaced == 0) {
    return;
  }
  if (firstinstance < 0 || lastinstance >= numplaced) {
    ks_error("%s(%s): instanceno (%d) out of range [0,%d]", __FUNCTION__, rf->rfwave.description, instanceno, numplaced - 1);
    return;
  }

  #ifdef IPG
  /* set frequency */
  for (i = firstinstance; i <= lastinstance; i++) {
    /* calculate phase */
    {
      double ftime_delay;           /* floating point time delay in seconds */
      double cf_offset = (double) rf->cf_offset;             /* frequency offset */
      long tmpphase;
      int syncpos, rfstartpos, time_delay;

      /* start of RF pulse wave form (for 1st boardinstance) */
      rfstartpos = rf->rfwave.wfi[i].wf->inst_hdr_tail->start;
      /* start of RF SSP frq pulse  (for 1st boardinstance) */
      syncpos = rf->rfwave.wfi[i].wf->assoc_pulse->inst_hdr_tail->start;

      /* time difference between SSP frq and isocenter of RF pulse */
      time_delay = rfstartpos - syncpos - 9 /* frq2sync_dly */ + RUP_FACTOR(rf->rfwave.duration - rf->iso2end, 2);

      /*** Modified from GE's setupphases() ***/
      ftime_delay = ((double)time_delay) / ((double) 1.0e6);
      tmpphase = (ks_degrees_to_iphase(rfphase) /* deg->iphase */ + ks_cycles_to_iphase( - cf_offset * ftime_delay )) % FS_2PI; /* radians */
      setiphase(tmpphase,  rf->rfwave.wfi[i].wf, rf->rfwave.wfi[i].boardinstance);
    }

  } /* for each instance */

  #endif


} /* ks_scan_rf_setphase */

ks_scan_wave2hardware()

void ks_scan_wave2hardware	(	KS_WAVE *	wave,
		const KS_WAVEFORM	newwave
	)

Moves a waveform belonging to a KS_WAVE sequence object to hardware

This function copies a waveform to one of the two hardware waveform buffers (belonging to the KS_WAVE object) that is currently not in use for the current sequence playout. The selection of which buffer to update is handled automatically by the function, which will also change the waveform pointer to the updated buffer so it will be used for the next sequence playout

If the 2nd argument (newwave, of type KS_WAVEFORM (float array)) is

1. not NULL, the content of newwave is used
2. NULL, it is assumed that the .waveform field of KS_WAVE has been updated with new contents and is copied to hardware instead of newwave

Parameters

[in,out]	wave	Pointer to KS_WAVE
[in]	newwave	KS_WAVEFORM to copy to hardware (if NULL, the .waveform field in KS_WAVE will be used instead)

                                                                     {
#ifdef IPG
  KS_IWAVE iwave;
  WF_PULSE *wfpulse;
  LONG current_wave_ptrs[KS_WF_SIZE];
  LONG wave_ptr;
  int i,j;
  STATUS status;
  int numplaced = wave->base.ngenerated;
#else
  int numplaced = wave->base.ninst;
#endif

  if (numplaced == 0) {
    return;
  }

#ifdef IPG

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

    wfpulse = wave->wfpulse[i];

    if (!wfpulse) {
      continue;
    }

    if (newwave != NULL) {
      /* use the new float array passed in as 3rd argument */
      status = ks_waveform2iwave(iwave, newwave, wave->res, i);
    } else {
      /* use the data in the `.waveform` field of the KS_WAVE (1st arg) */
      status = ks_wave2iwave(iwave, wave, i); /* iwave is waveform memory */
    }

    /* Extract current wave pointers */
    for (j = KS_WF_MAIN; j < KS_WF_SIZE; j++) {
      getwave(&current_wave_ptrs[j], &wfpulse[j]);
    }

    /* Compare the main pointer with the buffers and find wich buffer was used 
       last time, then move the new waveform to the other one. Also, get the new pointer. 
       movewaveimm might take some time to compute if the wave is long, consider increasing
       the SSI-time if you expericence any problems */
    if (current_wave_ptrs[KS_WF_MAIN] == current_wave_ptrs[KS_WF_BUF2]) {
      movewaveimm(iwave, &wfpulse[KS_WF_BUF1], (int) 0, wave->res, TOHARDWARE);
      getwave(&wave_ptr, &wfpulse[KS_WF_BUF1]);
    } else {
      movewaveimm(iwave, &wfpulse[KS_WF_BUF2], (int) 0, wave->res, TOHARDWARE);
      getwave(&wave_ptr, &wfpulse[KS_WF_BUF2]);
    }

    /* Make the new pointer the main one */
    setwave(wave_ptr, &wfpulse[KS_WF_MAIN], -1);

  } /* for */

#endif

} /* ks_scan_wave2hardware */

ks_scan_offsetfov_iso()

void ks_scan_offsetfov_iso	(	KS_READTRAP *	readtrap,
		int	instanceno,
		SCAN_INFO	sliceinfo,
		double	ky,
		double	kz,
		double	rcvphase
	)

Updates the frequency and phase to create a FOV shift assuming that the k-space voxels/pixels are isometric

Parameters

[in,out]	readtrap	Pointer to KS_READTRAP
[in]	instanceno	Instance of KS_RF to change (INSTRALL changes all instances)
[in]	sliceinfo	SCAN_INFO struct for the current slice to be played out
[in]	ky	phase offset in k-space measured in voxels/pixels
[in]	kz	phase offset in k-space measured in voxels/pixels
[in]	rcvphase	Receiver phase in [degrees] of the acquisition window corresponding to the KS_READTRAP and instanceno

                                                                                                                              {
  /* Warning: We never have more than one instance (i.e. instruction) per readtrap.echo[i] (see ks_pg_readtrap())
     unlike KS_TRAP and KS_RF. This means that the 2nd input arg here ('instanceno') means the instanceno'th echo. */

#ifdef IPG
    const int numplaced = readtrap->acq.base.ngenerated;
#else
    const int numplaced = readtrap->acq.base.ninst;
#endif

  int firstreadout, lastreadout;
  if (instanceno == INSTRALL) {
    firstreadout = 0;
    lastreadout = numplaced - 1;
  } else {
    firstreadout = instanceno;
    lastreadout = instanceno;
  }
  
  if (numplaced == 0) {
    return;
  }

  if (firstreadout < 0 || lastreadout >= numplaced) {
    ks_error("ks_scan_offsetfov(%s): readout instance (%d) out of range [0,%d]", readtrap->grad.description, instanceno, numplaced - 1);
    return;
  }

  int i;
  for (i = firstreadout; i <= lastreadout; i++) {
#ifdef IPG
    /* gradient amplitude for this instance -> Hz */
    const double mmtoHz = readtrap->grad.amp * readtrap->grad.wfi[i].loc.ampscale * GAM / 10.0; /* [Hz/mm]. designed amp [G/cm] * instance amp * GAM [Hz/G] / 10.0 [cm->mm] */
    float rloc = sliceinfo.oprloc;
#else
    const double mmtoHz = readtrap->grad.amp * readtrap->grad.locs[i].ampscale * GAM / 10.0;
    float rloc = 1;
#endif
    

    /* omega offset for rampsampled cases */
    if (readtrap->omega.duration > 0) {
      ks_scan_omegatrap_hz(&readtrap->omega, i,  mmtoHz * rloc /* [Hz] */);
    }

#ifdef IPG

    const int gradsign = (mmtoHz >= 0) ? 1 : -1;
    /* Frequency offsets [Hz]:
       - cfreceiveroffsetfreq: GE's standard frequency offset
       - readtrap->freqoffHz: Additional frequency offset for current KS_READTRAP. This value is multiplied with the gradient polarity sign
       - mmtoHz * sliceinfo.oprloc: Slice-dependent and gradient polarity dependent frequency offset (when omega is off) */
    const double freqoffHz = cfreceiveroffsetfreq + readtrap->freqoffHz * gradsign + (readtrap->omega.duration == 0) * (mmtoHz * rloc); /* [Hz] */

    /* set readout frequency offset */
    if (i < readtrap->acq.base.ngenerated && readtrap->acq.echo[i].tag == SSPDAB) { /* make sure it has been set up properly */
      setfrequency((int)(freqoffHz / TARDIS_FREQ_RES), &readtrap->acq.echo[i], 0);
    }
    /* set phase offset */
    if (i < readtrap->acq.base.ngenerated && readtrap->acq.echo[i].tag == SSPDAB) {

      const double time2echo = (double)(readtrap->time2center - readtrap->acqdelay);
      /* The clock source at setfrequency() starts before the first readout of the ADC, we need to account for the phase that accunmulates during this time.
         acqq.cpp - the RBA packet [ADC sync time?] has a fixed delay of RBA_length[PSD_XCVR2] which is set in EpicConf.cpp to RBA_LENGTH (= 4)
         It seems that all known hardware uses PSD_XCVR2 as the index and RBA_length isn't included in the scope of this file.*/
      int adcstartpos = readtrap->acq.echo[i].assoc_pulse->assoc_pulse->inst_hdr_tail->start + RBA_LENGTH;
      /* start of ADC SSP frq pulse  (for 1st boardinstance) */
      int syncpos = readtrap->acq.echo[i].assoc_pulse->inst_hdr_tail->start;
      /* time difference between SSP frq and start of the ADC readout */
      int time_delay = adcstartpos - syncpos - 10;

      const unsigned int iphase_due_to_freqoffset = ks_cycles_to_iphase(- freqoffHz * ((double)time_delay + time2echo) * 1e-6);
      const unsigned int iphase_ky = ks_cycles_to_iphase(- ky * sliceinfo.opphasoff / readtrap->fov);
      const unsigned int iphase_kz = ks_cycles_to_iphase(- kz * sliceinfo.optloc / readtrap->fov);
      const unsigned int ircvphase = ks_degrees_to_iphase(rcvphase);
      long iphase = (iphase_ky + iphase_kz + ircvphase + iphase_due_to_freqoffset) % FS_2PI;
      setiphase(iphase,  &readtrap->acq.echo[i], 0);

    }
#endif

  } /* for */
} /* ks_scan_offsetfov_iso */

ks_scan_offsetfov()

void ks_scan_offsetfov	(	KS_READTRAP *	readtrap,
		int	instanceno,
		SCAN_INFO	sliceinfo,
		float	view,
		float	phasefovratio,
		float	rcvphase
	)

Updates the frequency and phase of one or all instances of a KS_READTRAP to create a FOV shift

This function can be used by 2D Cartesian pulse sequences to build up the phase ramp in k-space necessary to shift the image FOV. The desired image FOV shift is given by the SCAN_INFO struct passed in as 3rd argument. The view field and the phasefovratio arguments are necessary to know where in the physical k-space the acquired data is placed. Knowing this and the FOV offset in the phase encoding direction, the necessary receiver phase for the current view can be set. After this function has been called for all view numbers, the necessary phase ramp has been set up in k-space to perform the phase FOV shift in the image domain. The rcvphase is added to the receive phase required for the FOV shift. In general, the rcvphase should be the same as the phase of the RF excitation pulse.

For rampsampled acquisitions (.rampsampling = 1 in KS_READTRAP), the ks_scan_offsetfov_iso() function called will internally call ks_scan_omegatrap_hz() for FOV shifts in the readout direction. Both ks_scan_offsetfov() and ks_scan_offsetfov3D() calls the same ks_scan_offsetfov_iso() function after performing unit conversions of the input arguments.

Parameters

[in,out]	readtrap	Pointer to KS_READTRAP
[in]	instanceno	Instance of KS_RF to change (INSTRALL changes all instances)
[in]	sliceinfo	SCAN_INFO struct for the current slice to be played out
[in]	view	Phase encoding line to acquire with index corresponding to a fully sampled k-space [0, res-1]
[in]	phasefovratio	The ratio of FOVphase/FOVfreq (as opphasefov)
[in]	rcvphase	Receiver phase in [degrees] of the acquisition window corresponding to the KS_READTRAP and instanceno

                                                                                                                                    {
  const double koffset = (double)(ky) / phasefovratio;
  ks_scan_offsetfov_iso(readtrap, instanceno, sliceinfo, koffset, 0, rcvphase);
}

ks_scan_offsetfov3D()

void ks_scan_offsetfov3D	(	KS_READTRAP *	readtrap,
		int	instanceno,
		SCAN_INFO	sliceinfo,
		float	kyview,
		float	phasefovratio,
		float	kzview,
		float	zphasefovratio,
		float	rcvphase
	)

Updates the frequency and phase of one or all instances of a KS_READTRAP to create a FOV shift

This function can be used by 3D Cartesian pulse sequences to build up the phase ramp in k-space necessary to shift the image FOV. The desired image FOV shift is given by the SCAN_INFO struct passed in as 3rd argument. The kyview/kzview field and the phasefovratio/zphasefovratio arguments are necessary to know where in the physical k-space the acquired data is placed. Knowing this and the FOV offset in both phase encoding directions, the necessary receiver phase for the current kyview/kzview can be set. After this function has been called for all kyview/kzview numbers, the necessary phase ramp has been set up in k-space to perform the phase FOV shift in the image domain. The rcvphase is added to the receive phase required for the FOV shift. In general, the rcvphase should be the same as the phase of the RF excitation pulse.

For rampsampled acquisitions (.rampsampling = 1 in KS_READTRAP), the ks_scan_offsetfov_iso() function called will internally call ks_scan_omegatrap_hz() for FOV shifts in the readout direction. Both ks_scan_offsetfov() and ks_scan_offsetfov3D() calls the same ks_scan_offsetfov_iso() function after performing unit conversions of the input arguments.

Parameters

[in,out]	readtrap	Pointer to KS_READTRAP
[in]	instanceno	Instance of KS_RF to change (INSTRALL changes all instances)
[in]	sliceinfo	SCAN_INFO struct for the current slice to be played out
[in]	kyview	Phase encoding line to acquire with index corresponding to a fully sampled k-space [0, res-1] (YGRAD)
[in]	phasefovratio	The ratio of FOVphase/FOVfreq (as opphasefov)
[in]	kzview	Z Phase encoding line to acquire with index corresponding to a fully sampled k-space [0, res-1] (ZGRAD)
[in]	zphasefovratio	The ratio of FOVslice/FOVfreq (as (opslquant * opslthick) / opfov)
[in]	rcvphase	Receiver phase in [degrees] of the acquisition window corresponding to the KS_READTRAP and instanceno

                                                                                                                                                                      {
  const double kyoffset = (double)(ky) / phasefovratio;
  const double kzoffset = (double)(kz) / zphasefovratio;
  ks_scan_offsetfov_iso(readtrap, instanceno, sliceinfo, kyoffset, kzoffset, rcvphase);
}

ks_scan_offsetfov_readwave()

void ks_scan_offsetfov_readwave	(	KS_READWAVE *	readwave,
		int	instanceno,
		SCAN_INFO	sliceinfo,
		float	kyview,
		float	phasefovratio,
		float	rcvphase
	)

                                                                                                                                           {
  const double koffset = (double)(ky) / phasefovratio;
  ks_scan_offsetfov_iso_readwave(readwave, instanceno, sliceinfo, koffset, 0, rcvphase);
}

ks_scan_omegatrap_hz()

void ks_scan_omegatrap_hz	(	KS_TRAP *	trap,
		int	instanceno,
		float	Hz
	)

Updates a KS_TRAP object on the OMEGA board to produce a frequency offset

A KS_TRAP object on OMEGA is used for rampsampled acquisitions and is placed out using ks_pg_readtrap() for a KS_READTRAP object if the field .rampsampling = 1. This will cause a trapezoidal frequency shift during the readout instead of a fixed frequency offset when rampsampling is not used. An error is returned if the current instance of the KS_TRAP is on another board than OMEGA

For Cartesian applications, there is no need to call this function directly, since ks_scan_offsetfov() already calls this function

Special note for OMEGA: Neither the .amp field nor the .ampscale field passed in to ks_pg_trap() has an effect. Only the Hz argument controls the frequency shift

Parameters

[in,out]	trap	Pointer to KS_TRAP
[in]	instanceno	Instance of KS_RF to change (INSTRALL changes all instances)
[in]	Hz	Desired frequency offset in [Hz] at the plateau of the trapezoid

Return values

STATUS

SUCCESS or FAILURE

                                                                  {
  int iamp;
  float omega_scale = 256.0;

  iamp = (int) (Hz / (TARDIS_FREQ_RES * omega_scale));
  if (abs(iamp) > 32768) {
    ks_error("ks_scan_omegatrap_hz(%s): the integer amplitude is too large (%d) for instance %d", trp->description, iamp, instanceno);
    return;
  }

#ifdef IPG

  if (trp->wfi[instanceno].loc.board != OMEGA) {
    ks_error("ks_scan_omegatrap_hz(%s): Wrong function - use ks_scan_trap_ampscale() KS_TRAPs on XGRAD, YGRAD, ZGRAD", trp->description);
    return;
  }

  /* input validation */
  if (instanceno < 0 || instanceno >= trp->base.ngenerated) {
    ks_error("ks_scan_omegatrap_hz(%s): instanceno (%d) out of range [0,%d)", trp->description, instanceno, trp->base.ngenerated);
    return;
  }

  if (setiampt((short) iamp, trp->wfi[instanceno].wf, trp->wfi[instanceno].boardinstance) != SUCCESS) {
    ks_error("ks_scan_omegatrap_hz(%s): An error occurred calling 'setiampt()'", trp->description);
    return;
  }

#else
  int numplaced = trp->base.ninst;
  if (!numplaced) {
    return;
  }
  float* tmp = (float*)realloc(trp->rtscale, numplaced * sizeof(float));
  if (!tmp) {
    ks_error("%s: rtscale realloc failed", __FUNCTION__);
    return;
  }
  trp->rtscale = tmp;
  trp->rtscale[instanceno] = Hz;
#endif

} /* ks_scan_omegatrap_hz */

ks_scan_omegawave_hz()

void ks_scan_omegawave_hz	(	KS_WAVE *	wave,
		int	instanceno,
		float	Hz
	)

Updates a KS_WAVE object on the OMEGA board to produce a frequency offset

A KS_WAVE object on OMEGA can be used to perform a dynamic frequency offset

1. while an RF pulse is played out. One example is Spectral-Spatial RF pulses
2. during data acquisition

Parameters

[in,out]	wave	Pointer to KS_WAVE
[in]	instanceno	Instance of KS_RF to change (INSTRALL changes all instances)
[in]	Hz	Desired frequency offset in [Hz] for the point in the KS_WAVE with the largest absolute amplitude

Return values

STATUS

SUCCESS or FAILURE

                                                                   {
  int iamp;
  float omega_scale = 256.0;

  iamp = (int) (Hz / (TARDIS_FREQ_RES * omega_scale));

  if (abs(iamp) > 32768) {
    ks_error("ks_scan_omegawave_hz(%s): the integer amplitude is too large (%d) for instance %d", wave->description, iamp, instanceno);
    return;
  }

#ifdef IPG

  if (wave->wfi[instanceno].loc.board != OMEGA) {
    ks_error("ks_scan_omegawave_hz(%s): Only omega board is supported", wave->description);
    return;
  }

  /* input validation */
  if (instanceno < 0 || instanceno >= wave->base.ngenerated) {
    ks_error("ks_scan_omegawave_hz(%s): instanceno (%d) out of range [0,%d)", wave->description, instanceno, wave->base.ngenerated);
    return;
  }

  if (setiamp((short) iamp, wave->wfi[instanceno].wf, wave->wfi[instanceno].boardinstance) != SUCCESS) {
    ks_error("ks_scan_omegawave_hz(%s): An error occurred calling 'setiampt()'", wave->description);
    return;
  }

#else
  int numplaced = wave->base.ninst;
  if (!numplaced) {
    return;
  }
  float* tmp = (float*)realloc(wave->rtscale, numplaced * sizeof(float));
  if (!tmp) {
    ks_error("%s: rtscale realloc failed", __FUNCTION__);
    return;
  }
  wave->rtscale = tmp;
  wave->rtscale[instanceno] = Hz;

#endif

} /* ks_scan_omegawave_hz */

ks_scan_wait()

void ks_scan_wait	(	KS_WAIT *	wait,
		int	waitperiod
	)

Updates the wait period of all instances of a KS_WAIT sequence object. The value of waitperiod must not exceed

.duration.

Parameters

[in,out]	wait	Pointer to KS_WAIT
[in]	waitperiod	Time in [us] to wait

Return values

STATUS

SUCCESS or FAILURE

                                                 {

#ifdef IPG
  int i;
  int numplaced = wait->base.ngenerated;
#else
  int numplaced = wait->base.ninst;
#endif

  if (numplaced == 0) {
    return;
  }

  /* input validation */
  if (waitperiod < 0) {
    ks_error("ks_scan_wait(%s): wait period %d is negative", wait->description, waitperiod);
    return;
  }
  if (waitperiod < GRAD_UPDATE_TIME) {
    waitperiod = GRAD_UPDATE_TIME;
  }
  if (waitperiod % GRAD_UPDATE_TIME) {
    ks_error("ks_scan_wait(%s): waitperiod (3rd arg) on gradient boards must be divisible by 4", wait->description);
    return;
  }

#ifdef IPG

  if (wait->wfi == NULL) {
    ks_error("ks_scan_wait(%s): WF_INSTANCE of trap is NULL", wait->description);
  }

  /* set amplitude(s) */
  for (i = 0; i < numplaced; i++) {

    if (setperiod(waitperiod, wait->wfi[i].wf, wait->wfi[i].boardinstance) != SUCCESS) {
      ks_error("ks_scan_wait(%s): An error occurred calling 'setperiod()'", wait->description);
      return;
    }
  }

#endif

} /* ks_scan_wait */

ks_scan_trap_ampscale()

void ks_scan_trap_ampscale	(	KS_TRAP *	trap,
		int	instanceno,
		float	ampscale
	)

Updates the amplitude of one or all instances of a KS_TRAP sequence object

This function multiplies one instance of a KS_TRAP object with an amplitude scale factor (3rd arg) that should be in range [-1.0,1.0] to avoid slewrate issues. To change all instances of a KS_TRAP object, use INSTRALL as the 2nd argument.

The actual amplitude for an instance of a KS_TRAP object is the multiplication of the three factors:

1. The designed amplitude [G/cm]
2. The per-instance .ampscale in the KS_SEQLOC struct passed to ks_pg_trap()
3. The ampscale value passed in as 3rd argument to this function.

Parameters

[in,out]	trap	Pointer to KS_TRAP
[in]	instanceno	Instance of KS_TRAP to change (INSTRALL changes all instances)
[in]	ampscale	Gradient amplitude scale factor, normally in range [-1.0,1.0], but the range [-1.2, 1.2] is allowed to allow certain run-time gradient corrections

Return values

STATUS

SUCCESS or FAILURE

                                                                         {
  int firstinstance, lastinstance, i;
#ifdef IPG
  int iamp;
  float gradmax;
  int numplaced = trp->base.ngenerated;
#else
  int numplaced = trp->base.ninst;
  if (!numplaced) {
    return;
  }
  float* tmp = (float*)realloc(trp->rtscale, numplaced * sizeof(float));
  if (!tmp) {
    ks_error("%s: rtscale realloc failed", __FUNCTION__);
    return;
  }
  trp->rtscale = tmp;
#endif

  if (instanceno == INSTRALL) {
    firstinstance = 0;
    lastinstance = numplaced - 1;
  } else {
    firstinstance = instanceno;
    lastinstance = instanceno;
  }

  /* input validation */
  if (numplaced == 0) {
    return;
  }
  if (firstinstance < 0 || lastinstance >= numplaced) {
    ks_error("ks_scan_trap_ampscale(%s): instanceno (%d) out of range [0,%d]", trp->description, instanceno, numplaced - 1);
    return;
  }

  /* Allow ampscale to be 20% larger than 1. This, to allow future minor runtime changes of trapezoid amplitudes
     for e.g. (future possible implementations):
     - oblique ghost correction for EPI, where odd/even blip amps need to be made smaller/larger depending on slice angle and delays
     - eddy current correction for DW-EPI, where readout lobe amp needs to be changed per diffusion direction etc.
     If 'ampscale' is larger than 1.0 (i.e. between 1.0 and 1.2), the trapezoid must have been designed with a slewrate that is slightly
     under the very limit of the system (and the dB/dt limits for PNS). Use with caution. */

  if (fabs(ampscale) > sqrt(3)) {
    ks_error("ks_scan_trap_ampscale(%s): ampscale too large (%f)", trp->description, ampscale);
    return;
  }

  /*
    - trp->amp: The amplitude that was initially designed for the KS_TRAP. Should never be exceeded, or slew rate issues will occur
    - trp->wfi[i].loc.ampscale: -1.0 -> +1.0. Amp scale factor for each instance of the KS_TRAP placed in the sequence.
    - ampscale (3rd input arg): -1.0 -> +1.0 (in normal cases). The dynamic amp scale (i.e. over time, or TRs).
   The product [trp->wfi[i].loc.ampscale * ampscale] should be in range [-1, 1] to avoid slew rate issues.
  */

#ifdef IPG

  if (trp->wfi == NULL) {
    ks_error("ks_scan_trap_ampscale(%s): WF_INSTANCE of trap is NULL", trp->description);
    return;
  }

  /* set amplitude(s) */
  for (i = firstinstance; i <= lastinstance; i++) {
    gradmax = ks_syslimits_gradtarget(loggrd, trp->wfi[i].loc.board);
    iamp = (int)((ampscale * trp->wfi[i].loc.ampscale * trp->amp / gradmax) * MAX_PG_IAMP);

    if (abs(iamp) > 32768) {
      ks_error("ks_scan_trap_ampscale(%s): the integer amplitude is too large (%d) for instance %d", trp->description, iamp, i);
      return;
    }
    if (trp->wfi[i].loc.board == OMEGA) {
      ks_error("ks_scan_trap_ampscale(%s): Instance %d on board OMEGA. Please use ks_scan_omegatrap_hz() instead", trp->description, i);
      return;
    }
    if (setiampt((short) iamp, trp->wfi[i].wf, trp->wfi[i].boardinstance) != SUCCESS) {
      ks_error("ks_scan_trap_ampscale(%s): An error occurred calling 'setiampt()'", trp->description);
      return;
    }

  }

#else
  for (i = firstinstance; i <= lastinstance; i++) {
    trp->rtscale[i] = ampscale;
  }
#endif
} /* ks_scan_trap_ampscale */

ks_scan_trap_ampscale_slice()

void ks_scan_trap_ampscale_slice	(	KS_TRAP *	trap,
		int	start,
		int	skip,
		int	count,
		float	ampscale
	)

Updates the amplitude of a selection of instances of a KS_TRAP sequence object

This function multiplies some instances of a KS_TRAP object with an amplitude scale factor (5th arg) that should be in range [-1.0,1.0] to avoid slewrate issues.

The instances to change are start + i * skip, where i goes from 0 to count. FAILURE is returned if either start or start + count * skip out of range or count is negative

Parameters

[in,out]	trap	Pointer to KS_TRAP
[in]	start	First instance number of the KS_TRAP
[in]	skip	Difference in instance number between consecutive instances
[in]	count	Number of instances to change in total
[in]	ampscale	Gradient amplitude scale factor, normally in range [-1.0,1.0], but the range [-1.2, 1.2] is allowed to allow certain run-time gradient corrections

Return values

STATUS

SUCCESS or FAILURE

                                                                                               {
  int i;
#ifdef IPG
  int numplaced = trp->base.ngenerated;
#else
  int numplaced = trp->base.ninst;
#endif

  if (numplaced == 0) {
    return;
  }
  
  /* check range */
  const int end = start + (count - 1) * skip;

  if (start < 0 || start >= numplaced || end < 0 || end >= numplaced || count < 0) {
    ks_error("ks_scan_trap_ampscale_slice(%s): slice with start = %d, skip = %d and count = %d has endpoints outside [0,%d)", trp->description, start, skip, count, numplaced);
    return;
  }

  for (i = 0; i < count; ++i) {
    ks_scan_trap_ampscale(trp, start + i * skip, ampscale);
  }

} /* ks_scan_trap_ampscale_slice */

ks_scan_phaser_kmove()

void ks_scan_phaser_kmove	(	KS_PHASER *	phaser,
		int	instanceno,
		double	pixelunits
	)

Updates the amplitude of a KS_PHASER sequence object to move some arbitrary distance in k-space

This function sets the amplitude of the gradient for a KS_PHASER object so that a shift in k-space of pixelunits number of pixels is produced. If pixelunits is 1.0, the gradient area corresponds to one pixel shift in a fully sampled k-space (no parallel imaging) along the board the KS_PHASER object is placed on. pixelunits is of type float and any non-integer value is accepted, and the sign of pixelunits determines the direction of k-space shift

Parameters

[in,out]	phaser	Pointer to KS_PHASER
[in]	instanceno	Instance of KS_TRAP to change (INSTRALL changes all instances)
[in]	pixelunits	Non-integer pixel units in a fully sampled k-space to move

Return values

STATUS

SUCCESS or FAILURE

                                                                                {
  double phasepixelarea = (double) ks_calc_fov2gradareapixel(phaser->fov);
  double newarea = pixelunits * phasepixelarea + (double) phaser->areaoffset;
  double ampscale = newarea / phaser->grad.area;

  if (phaser == NULL)
    return;

  if (fabs(ampscale) > 1.00003) {  /* 1.00003 corresponds to 32768 / 32767, i.e. excess of one short int */
#ifndef IPG
    ks_error("ks_scan_phaser_kmove(%s): Too large value (%g) in 3rd arg", phaser->grad.description, pixelunits);
#endif
  } else if (fabs(ampscale) > 1.0) {
    /* small round-off fix when ampscale is in range [1.0, 1.00003] */
    ampscale = ampscale < 0 ? -1.0 : 1.0;
  }

  ks_scan_trap_ampscale(&phaser->grad, instanceno, ampscale);

} /* ks_scan_phaser_kmove */

ks_scan_phaser_toline()

void ks_scan_phaser_toline	(	KS_PHASER *	phaser,
		int	instanceno,
		int	view
	)

Updates the amplitude of a KS_PHASER sequence object to move from the k-space center to a desired k-space line

This function sets the amplitude of the gradient for a KS_PHASER object to produce a k-space shift from the center of k-space to the view number (3rd arg). The view number must be an integer in range [0, .res-1], and the number refers to a fully sampled k-space (without parallel imaging)

Parameters

[in,out]	phaser	Pointer to KS_PHASER
[in]	instanceno	Instance of KS_TRAP to change (INSTRALL changes all instances)
[in]	view	Phase encoding line to acquire with index corresponding to a fully sampled k-space [0, res-1]

Return values

STATUS

SUCCESS or FAILURE

                                                                        {
  double kmax;

  if (phaser == NULL)
    return;

  if (view < 0 || view >= phaser->res) {
    ks_scan_phaser_kmove(phaser, instanceno, 0.0);
    return;
  }

  /* KSFoundation 'view' is always 0-based: e.g. res = 256: view = 0->255. */
  kmax = ((phaser->res - 1.0) / 2.0);
  ks_scan_phaser_kmove(phaser, instanceno, kmax - view);

} /* ks_scan_phaser_toline */

ks_scan_phaser_fromline()

void ks_scan_phaser_fromline	(	KS_PHASER *	phaser,
		int	instanceno,
		int	view
	)

Updates the amplitude of a KS_PHASER sequence object to move from a k-space line to the k-space center

This function sets the amplitude of the gradient for a KS_PHASER object to produce a k-space shift from the view number (3rd arg) to the k-space center. The view number must be an integer in range [0, .res-1], and the number refers to a fully sampled k-space (without parallel imaging)

Parameters

[in,out]	phaser	Pointer to KS_PHASER
[in]	instanceno	Instance of KS_TRAP to change (INSTRALL changes all instances)
[in]	view	Phase encoding line to acquire with index corresponding to a fully sampled k-space [0, res-1]

Return values

STATUS

SUCCESS or FAILURE

                                                                          {
  double kmax;

  if (phaser == NULL)
    return;

  if (view < 0 || view >= phaser->res) {
    ks_scan_phaser_kmove(phaser, instanceno, 0.0);
    return;
  }

  /* KSFoundation 'view' is always 0-based: e.g. res = 256: view = 0->255. */
  kmax = ((phaser->res - 1.0) / 2.0);
  ks_scan_phaser_kmove(phaser, instanceno, view - kmax);

} /* ks_scan_phaser_fromline */

ks_scan_getsliceloc()

int ks_scan_getsliceloc	(	const KS_SLICE_PLAN *	slice_plan,
		int	passindx,
		int	sltimeinpass
	)

Returns the spatially sorted slice index from a DATA_ACQ_ORDER struct array

This function finds the spatially sorted slice index (.slloc) in range [0, nslices-1] given the sequence's DATA_ACQ_ORDER struct array (in slice_plan.acq_order)

Parameters

[in]	slice_plan	Pointer to the slice plan (KS_SLICE_PLAN) for the sequence
[in]	passindx	Current pass index ([0, acqs-1])
[in]	sltimeinpass	Temporal index of the n slices acquired in each pass ([0, n-1])

Return values

slloc

Spatially sorted slice index

                                                                                         {
  int i;
  for (i = 0; i < slice_plan->nslices; i++) {
    if (slice_plan->acq_order[i].slpass == passindx && slice_plan->acq_order[i].sltime == sltimeinpass) {
      return slice_plan->acq_order[i].slloc;
    }
  }

  return KS_NOTSET;

}

ks_scan_getslicetime()

int ks_scan_getslicetime	(	const KS_SLICE_PLAN *	slice_plan,
		int	passindx,
		int	slloc
	)

Returns the temporally sorted slice index from a DATA_ACQ_ORDER struct array

This function finds the temporally sorted slice index (.sltime) in range [0, nslices-1] given the sequence's DATA_ACQ_ORDER struct array (in slice_plan.acq_order)

Parameters

[in]	slice_plan	Pointer to the slice plan (KS_SLICE_PLAN) for the sequence
[in]	passindx	Current pass index ([0, acqs-1])
[in]	slloc	Spatially sorted slice index [0, nslices-1]

Return values

sltimeinpass

Temporal index of the n slices acquired in each pass ([0, n-1])

                                                                                   {
  int i;
  for (i = 0; i < slice_plan->nslices; i++) {
    if (slice_plan->acq_order[i].slpass == passindx && slice_plan->acq_order[i].slloc == slloc) {
      return slice_plan->acq_order[i].sltime;
    }
  }

  return KS_NOTSET;

}

ks_scan_epi_verify_phaseenc_plan()

ks_enum_epiblipsign ks_scan_epi_verify_phaseenc_plan	(	KS_EPI *	epi,
		KS_PHASEENCODING_PLAN *	phaseenc_plan,
		int	shot
	)

                                                                                                                  {
  int i;
  int kystep[epi->etl];
  ks_enum_epiblipsign blipsign = KS_EPI_NOBLIPS;
  KS_PHASEENCODING_COORD coord = KS_INIT_PHASEENCODING_COORD;

  if (phaseenc_plan == NULL) {
    return blipsign;
  }

  /* verify phase encoding plan has equidistant ky step size */
  /* first store ky coords */
  for (i = 0; i < epi->etl; i++) {
    coord = ks_phaseencoding_get(phaseenc_plan, i, shot);
    kystep[i] = coord.ky;
  }

  for (i = 0; i < epi->etl-1; i++) {
    kystep[i] = kystep[i+1] - kystep[i]; /* calculate ky step */
    if (i > 0) {
      /* check that kystep is consistent */
      if (kystep[i] != kystep[0]) {
        ks_error("%s(%s): KS_EPI does not support varying ky step size", __FUNCTION__, phaseenc_plan->description);
        return KS_EPI_NOBLIPS;
      }
    }
  }

  if (kystep[0] < 0) {
    blipsign = KS_EPI_POSBLIPS;
  } else if (kystep[0] > 0) {
    blipsign = KS_EPI_NEGBLIPS;
  }

  return blipsign;
}

ks_scan_epi_shotcontrol()

void ks_scan_epi_shotcontrol	(	KS_EPI *	epi,
		int	echo,
		SCAN_INFO	sliceinfo,
		KS_PHASEENCODING_PLAN *	phaseenc_plan,
		int	shot,
		int	exc,
		float	rcvphase
	)

Changes the gradient state of a KS_EPI object for the given slice information

This function has two different tasks. First, it controls the EPI blips and sets the EPI dephaser and rephaser amplitude given the current phaseshot and blipsign. If phaseshot is outside the valid range ([0, .blipphaser.R-1], all gradient amplitudes on the blip (phase encoding) axis will be zero. This can be useful to acquire a refscan for Nyquist ghost correction. Second, it sets up the proper frequency and phase modulation per readout lobe to produce the desired FOV offset in both the frequency and phase encoding directions

Parameters

[in,out]	epi	Pointer to KS_EPI
[in]	echo	EPI echo index (up to 16 EPI trains supported)
[in]	sliceinfo	SCAN_INFO struct for the current slice to be played out
[in]	phaseenc_plan	Pointer to the phase encoding plan
[in]	shot	Linear ky kz shot index in range [0, (phaseenc_plan.num_shots-1)]
[in]	exc	Zero-based NEX index
[in]	rcvphase	Receiver phase in degrees, for RF spoiling.

Return values

STATUS

SUCCESS or FAILURE

                                                                                                                                                  {
  float blipampscale = 1.0;
  float yfovratio, zfovratio;
  int i, readindx, blipindx, kyview, kzview;
  int numblips = (epi->etl - 1);
  int isrefscan = (exc < 0);  /* exc < 0 => data acquisition ON, EPI blips OFF (to make RefScan for Nyquist ghost correction) */
  KS_PHASEENCODING_COORD coord = KS_INIT_PHASEENCODING_COORD;

  ks_enum_epiblipsign blipsign = ks_scan_epi_verify_phaseenc_plan(epi, phaseenc_plan, shot);

  if (phaseenc_plan != NULL && (epi->etl != phaseenc_plan->etl)) {
    ks_error("%s(%s): ETL of KS_EPI (%d) and KS_PHASEENCODING_PLAN (%d) do not match", __FUNCTION__, phaseenc_plan->description, epi->etl, phaseenc_plan->etl);
    blipsign = KS_EPI_NOBLIPS;
  }

  if (isrefscan) {
    blipsign = KS_EPI_NOBLIPS;
  }

  /* EPI read & blips for current 'echo' = EPI train. */
  for (i = 0; i < epi->etl; i++) {
    coord = ks_phaseencoding_get(phaseenc_plan, i, shot);
    kyview = (blipsign != KS_EPI_NOBLIPS) ? coord.ky : KS_NOTSET;
    kzview = (blipsign != KS_EPI_NOBLIPS) ? coord.kz : KS_NOTSET;

    if (i == 0) { /* EPI dephaser. From k-space center to this line */
      ks_scan_phaser_toline(&epi->blipphaser, 0 + 2 * echo, kyview); /* KS_NOTSET => zero amplitude */
      if (epi->zphaser.grad.duration > 0) {
        /* 3D epi z dephaser(s) for even instances '2*echo' */
        ks_scan_phaser_toline(&epi->zphaser, 0 + 2 * echo, kzview);
      }
    }
    
    if (i == epi->etl-1) { /* EPI rephaser. From this line to k-space center */
      ks_scan_phaser_fromline(&epi->blipphaser, 1 + 2 * echo, kyview); /* KS_NOTSET => zero amplitude */
      if (epi->zphaser.grad.duration > 0) {
        /* 3D epi z rephaser(s) for odd instances '1+2*echo' */
        ks_scan_phaser_fromline(&epi->zphaser, 1 + 2 * echo, kzview);
      }
    }

    readindx = i + echo * epi->etl; /* ETL# of readouts */
    blipindx = i + echo * numblips;  /* (ETL-1)# of blips */

    if (i < numblips) {
      /* FUTURE: at this point, we could increase/decrease blipampscale for odd/even blips for oblique ghost correction */
      blipampscale = blipsign / epi->blipoversize;
      ks_scan_trap_ampscale(&epi->blip, blipindx, blipampscale);
    }

    /* FOV offsets (by changing freq/phase of epi.read) */
    float ky_centred, kz_centred;
    if (kyview < 0) {
      ky_centred = 0.0f;
    } else {
      ky_centred = (float)kyview - ((epi->blipphaser.res - 1) / 2.0f);
    }
    yfovratio = epi->blipphaser.fov / epi->read.fov;
    if (epi->zphaser.grad.duration > 0) {
      if (kzview < 0) {
        kz_centred = 0.0f;
      } else {
        kz_centred = (float)kzview - ((epi->zphaser.res - 1) / 2.0f);
      }
      zfovratio = epi->zphaser.fov / epi->read.fov;
      ks_scan_offsetfov3D(&epi->read, readindx, sliceinfo, ky_centred, yfovratio, kz_centred, zfovratio, rcvphase);
    } else {
      ks_scan_offsetfov(&epi->read, readindx, sliceinfo, ky_centred, yfovratio, rcvphase);
    }

  } /* for etl */

} /* ks_scan_epi_shotcontrol */

ks_scan_epi_loadecho_with_tag()

void ks_scan_epi_loadecho_with_tag	(	KS_EPI *	epi,
		int	echo,
		int	storeecho,
		int	slice,
		KS_PHASEENCODING_PLAN *	phaseenc_plan,
		int	shot,
		KSEPI_DATATAG *	datatag,
		KS_DATASTORETAG *	datastoretag
	)

Loads the data storage information to hardware for the acquisition windows in a KS_EPI sequence object

This function specifies where to store the data acquired for each readout lobe in the KS_EPI train given current:

• echo: First instance of the KS_EPI train is 0
• slice: Slice index, 0-based
• shot: Linear ky kz shot index in range [0, (phaseenc_plan.num_shots-1)]
• phaseenc_plan: phaseenc_plan Pointer to the phase encoding plan

If shot is outside the valid range, a baseline view (view 0 in loaddab()) will be acquired.

If slice is < 0, data acquisition is turned off in loaddab()

Parameters

[in,out]	epi	Pointer to KS_EPI
[in]	echo	EPI echo index to work on (up to 16 EPI trains supported)
[in]	storeecho	EPI echo index for storing (usually the same as echo)
[in]	slice	Slice index where to store the data (0-based)
[in]	phaseenc_plan	Pointer to the phase encoding plan
[in]	shot	Linear ky kz shot index in range [0, (phaseenc_plan.num_shots-1)]
[in]	datastoretag	Tag (unsigned int) passed to loaddabwithangle(). This can be filled with whatever content to inform recon. Will be a part of each control packet on the recon side.

Return values

STATUS

SUCCESS or FAILURE

                                                                                                                                                                                           {
  if ((datastoretag != NULL) && (datatag != NULL)) {
    ks_error("%s: either datastoretag or custom_dab_array must be NULL, but both were supplied.", __FUNCTION__);
    return;
  }
  
  int i, readindx;
#ifdef IPG
  int validsliceindx = (slice >= 0 && slice < 2048);
  int validshotindx = (shot >= 0 && (phaseenc_plan == NULL || shot < phaseenc_plan->num_shots));
  KS_PHASEENCODING_COORD coord = KS_INIT_PHASEENCODING_COORD;
  ks_enum_epiblipsign blipsign = ks_scan_epi_verify_phaseenc_plan(epi, phaseenc_plan, shot);
  int centerecho = epi->time2center / epi->read.grad.duration; /* etl index corresponding to k-space center */
  int numplaced = epi->read.acq.base.ngenerated;

  /* 'pscR1' is the R1 receive gain made by prescan */
  int currentR1 = (epi->read.acq.override_R1 > 0 && epi->read.acq.override_R1 <= 11) ? epi->read.acq.override_R1 : pscR1;

  TYPDAB_PACKETS dabacqctrl;
  if (validsliceindx && validshotindx) {
    dabacqctrl = DABON; /* turn receiver on */
  } else {
    dabacqctrl = DABOFF; /* turn receiver off */
    slice = 0; /* necessary? */
  }
#else
  int numplaced = epi->read.acq.base.ninst;
#endif

  if (numplaced == 0) {
    return;
  }
  if (storeecho < 0 || storeecho > 15) {
    ks_error("%s: storeecho must be in range [0:15]", __FUNCTION__);
    return;
  }
  if (echo < 0 || (echo + 1) * epi->etl > numplaced) {
    ks_error("%s: echo (%d) must be in range [0:%d]", __FUNCTION__, echo, numplaced/epi->etl-1);
    return;
  }
  
  for (i = 0; i < epi->etl; i++) {

    readindx = i + echo * epi->etl; /* N.B.: 'echo' is # of EPI trains, not EPI readout lobes (up to 16 possible, set by opnecho) */

    if (readindx >= numplaced) {
      ks_error("%s(%s): Readout lobe index %d has not been placed in PG", __FUNCTION__, epi->read.grad.description, readindx);
      return;
    }

#ifdef IPG
    int kyview = KS_NOTSET;
    if (validshotindx && (blipsign != KS_EPI_NOBLIPS)) {
      coord = ks_phaseencoding_get(phaseenc_plan, i, shot);
      kyview = coord.ky;
      if (rhasset == ASSET_SCAN && epi->blipphaser.R > 1 && epi->blipphaser.nacslines == 0) {
        /* Auto-detect ASSET scan, which uses compressed storage of accelerated data, i.e. only
           storing the acquired lines, without inteleaving with blank unacquired lines */
        if (blipsign == KS_EPI_POSBLIPS) {
          kyview = epi->etl-1 - i;
        } else if (blipsign == KS_EPI_NEGBLIPS) {
          kyview = i;
        }
      }
    }

    if (rspent == L_APS2 || rspent == L_MPS2) {
      /* Prescan (R1 & R2) */
      if (readindx == centerecho && echo == 0) {
        loaddab(&epi->read.acq.echo[readindx], slice, storeecho, DABSTORE, 0, dabacqctrl, PSD_LOAD_DAB_ALL); /* turn on acquisition for center echo of 1st EPI train */
      } else {
        loaddab(&epi->read.acq.echo[readindx], slice, storeecho, DABSTORE, 0, DABOFF, PSD_LOAD_DAB_ALL); /* turn off acquisition for all other lobes (and all later EPI trains) */
      }
    } else {
      if (datastoretag != NULL) {
        /* Storing additional data in the dab pulse, in datastoretag.dab_array is space for up to KS_CUSTOM_DATASTORE_LENGTH byte */
        ks_loaddab_datastoretag(&epi->read.acq.echo[readindx], datastoretag);
      }
      if (datatag != NULL) {
        datatag->readout = i;
        ks_loaddab(&epi->read.acq.echo[readindx], (char*) datatag);
      }
      /* N.B.: kyview = KS_NOTSET (-1) if shot = KS_NOTSET. Hence kyview + 1 = dabview = 0 without phase encodes */      
      loaddab_hub_r1(&epi->read.acq.echo[readindx], slice, storeecho, DABSTORE, kyview + 1 /* GE's views are 1-based */, 0, currentR1, dabacqctrl, PSD_LOAD_DAB_ALL_WITH_HUB_R1);
    }
#endif

  } /* per acq window (readout lobe) */

} /* ks_scan_epi_loadecho_with_tag */

ks_scan_epi_loadecho_with_datastoretag()

void ks_scan_epi_loadecho_with_datastoretag	(	KS_EPI *	epi,
		int	echo,
		int	storeecho,
		int	slice,
		KS_PHASEENCODING_PLAN *	phaseenc_plan,
		int	shot,
		KS_DATASTORETAG *	datastoretag
	)

Wrappers around ks_scan_epi_loadecho_withtag_or_dabarray.

                                                                                                                                                                            {
  ks_scan_epi_loadecho_with_tag(epi, echo, storeecho, slice, phaseenc_plan, shot, NULL, datastoretag);
}

ks_scan_epi_loadecho_with_epidatatag()

void ks_scan_epi_loadecho_with_epidatatag	(	KS_EPI *	epi,
		int	echo,
		int	storeecho,
		int	slice,
		KS_PHASEENCODING_PLAN *	phaseenc_plan,
		int	shot,
		KSEPI_DATATAG *	datatag
	)

                                                                                                                                                                   {
  ks_scan_epi_loadecho_with_tag(epi, echo, storeecho, slice, phaseenc_plan, shot, datatag, NULL);
}

ks_scan_epi_loadecho()

void ks_scan_epi_loadecho	(	KS_EPI *	epi,
		int	echo,
		int	storeecho,
		int	slice,
		KS_PHASEENCODING_PLAN *	phaseenc_plan,
		int	shot
	)

                                                                                                                           {
  ks_scan_epi_loadecho_with_tag(epi, echo, storeecho, slice, phaseenc_plan, shot, NULL, NULL);
}

ks_loaddab()

void ks_loaddab	(	WF_PULSE_ADDR	echo,
		char *	dab_array
	)

                                                            {
  int i;
  static const int dab_indices[KS_CUSTOM_DATASTORE_LENGTH] = {2,3,4,5,6,7,14,15,16,17,18,19,20,21,22,23,24,25,26,27,28,29};

  for (i=0; i<KS_CUSTOM_DATASTORE_LENGTH; i++){
    short dabbyte = custom_dab_array[i];
#ifdef IPG
    sspload(&dabbyte, echo, dab_indices[i], 1, (HW_DIRECTION)TOHARDWARE, (SSP_S_ATTRIB)SSPS1);
#else
    (void) dabbyte;
    (void) dab_indices;
#endif
  }
}

ks_loaddab_datastoretag()

void ks_loaddab_datastoretag	(	WF_PULSE_ADDR	echo,
		KS_DATASTORETAG *	datastoretag
	)

                                                                                {
  if (datastoretag == NULL) {
    return;
  }

  if (datastoretag->info.load_custom_dab_array == TRUE) {
    /* if the psd provides  */
    if (datastoretag->fill_dab_array_fct != NULL){
      datastoretag->fill_dab_array_fct(datastoretag);
    }
    ks_loaddab(echo, datastoretag->dab_array);
  }
}

ks_scan_acq_to_rtp()

void ks_scan_acq_to_rtp	(	KS_READ *	read,
		TYPDAB_PACKETS	dabacqctrl,
		float	fatoffset
	)

Data routing control for RTP

Parameters

[in,out]	read	Pointer to KS_READ
[in]	dabacqctrl	DABON or DABOFF
[in]	fatoffset	Frequency offset in [Hz] for the current data acquisition window

Returns

void

                                                                                  {
#ifdef IPG

  WF_PULSE *echo_ptr;
  WF_PULSE *xtr_ptr;
  WF_PULSE *rba_ptr;

  int i;
  for (i = 0; i < acq->base.ngenerated; ++i) {
    echo_ptr = &acq->echo[i];
    setrfltrs((int) acq->filt.fslot, echo_ptr);

    getssppulse(&rba_ptr, echo_ptr, "rba", 0);
    getssppulse(&xtr_ptr, echo_ptr, "xtr", 0);
    acqctrl(dabacqctrl, (RECEIVER_SPEED_E)0, rba_ptr);

    setfreqphase((int)(fatoffset / TARDIS_FREQ_RES), /* freq ctrl */
                 0, /* phase ctrl */
                 xtr_ptr);

    /* TODO: Add r1 scaling here! */
    /*if (r1_scale != 1.0 && (rspent==L_SCAN)) {
      newR1 = ceil(pscR1 * r1_scale);
      if (newR1 > 13)
    newR1 = 13;
      else if (newR1 < 1)
    newR1 = 1;

      loaddab_hub_r1(echo_ptr, dabslice, dabecho, DABSTORE, dabview, 0, newR1, dabacqctrl, PSD_LOAD_DAB_ALL | PSD_LOAD_DAB_R1);
      }*/ /* if R1 change */
    routeDataFrameDab(echo_ptr, ROUTE_TO_RTP, cfcoilswitchmethod);
  }

#endif

}

ks_scan_switch_to_sequence()

void ks_scan_switch_to_sequence

(

KS_SEQ_CONTROL *

ctrl

)

                                                      {
#ifdef IPG
  if (ctrl->duration > 0) {
    boffset(ctrl->handle.offset);
  }
#endif
}

ks_scan_playsequence()

int ks_scan_playsequence

(

KS_SEQ_CONTROL *

ctrl

)

                                               {

  if (ctrl->duration > 0) {

#ifdef IPG
    {
      ks_scan_switch_to_sequence(ctrl);
      setssitime(ctrl->ssi_time / cfhwgut);
      startseq(0, (short) MAY_PAUSE); /* play out the sequence in real time */
    }
#else
    /* HOST */
    ctrl->nseqinstances++;
#endif
  } /* ctrl->duration > 0 */

  return ctrl->duration;
}

ks_scan_loaddabwithindices()

STATUS ks_scan_loaddabwithindices	(	WF_PULSE_ADDR	pulse,
		LONG	slice,
		LONG	echo,
		LONG	view,
		uint8_t	acq,
		uint8_t	vol,
		TYPDAB_PACKETS	acqon_flag
	)

loaddab() with extra arguments for current acquisition and image volume

Parameters

[in]	pulse	Pointer to WF_PULSE in a KS_READ
[in]	slice	0-based temporal slice index (2D) or kz encoding step typically (3D)
[in]	echo	0-based echo in the echo train
[in]	view	1-based ky view number
[in]	acq	0-based acquisition index (always 0 if all slices fit in one TR)
[in]	vol	0-based volume index (always 0 if only one volume)
[in]	acqon_flag	DABON or DABOFF

Return values

STATUS

SUCCESS or FAILURE

                                                             {
  return ks_scan_loaddabwithindices_nex(pulse, slice, echo, view, acq, vol, DABSTORE, acqon_flag);
}

ks_scan_loaddabwithindices_nex()

STATUS ks_scan_loaddabwithindices_nex	(	WF_PULSE_ADDR	pulse,
		LONG	slice,
		LONG	echo,
		LONG	view,
		uint8_t	acq,
		uint8_t	vol,
		LONG	operation,
		TYPDAB_PACKETS	acqon_flag
	)

loaddab() with extra arguments for current acquisition and image volume and current excitation (NEX)

Parameters

[in]	pulse	Pointer to WF_PULSE in a KS_READ
[in]	slice	0-based temporal slice index (2D) or kz encoding step typically (3D)
[in]	echo	0-based echo in the echo train
[in]	view	1-based ky view number
[in]	acq	0-based acquisition index (always 0 if all slices fit in one TR)
[in]	vol	0-based volume index (always 0 if only one volume)
[in]	operation	DABSTORE, DABADD (for 2nd to last excitation)
[in]	acqon_flag	DABON or DABOFF

Return values

STATUS

SUCCESS or FAILURE

                                                             {

  union Indices idx;
  idx.c[0] = acq;
  idx.c[1] = vol;
  return loaddabwithangle(pulse, idx.i, slice, echo, operation, view, acqon_flag, PSD_LOAD_DAB_ALL);
}

ks_scan_wait_for_rtp()

int ks_scan_wait_for_rtp	(	void *	rtpmsg,
		int	maxmsgsize,
		int	maxwait,
		KS_SEQ_CONTROL *	waitctrl
	)

play a wait sequence in a loop untill a RTP message is received.

Parameters

[out]	rtpmsg	pointer to memory that will be filled by the RTP message
[in]	maxmsgsize	size in bytes of the memory pointed by rtpmsg
[in]	maxwait	timing out period in [ms]
[in]	waitctrl	pointer to the KS_SEQ_CONTROL of a wait sequence. If NULL, the provided maxwait is ignored and a value of zero used instead.

Return values

size	of the received message, zero if timed out

                                                                                              {
  int maxplayouts;
  int nBytes = 0;
  int i;
  n32 packed = 1;
#ifdef IPG
  setscantimestop();
#endif

  maxplayouts =  waitctrl ? maxwait / waitctrl->duration : 0;
  if (maxplayouts < 1) {
    waitctrl = NULL;
    maxplayouts = 0;
  }

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

#ifdef IPG
    if (i != 0 && waitctrl) {
      ks_scan_playsequence(waitctrl);
    }
#endif

    nBytes = 0;

#if defined(MGD_TGT) && defined(PSD_HW)


  nBytes = rtp_get_feedback_data(rtpmsg, maxmsgsize, &packed, 2, RTP_QUEUE_NEWEST);  /*according to RTP_RESULT_PROMO=2, defined in lx/include/PromoCommon.h*/


#endif

    if (nBytes>0 && !packed) {
      break;
    }
  }

#ifdef IPG
  setscantimestart();
#endif

  return nBytes;
}

ks_copy_and_reset_obj()

void ks_copy_and_reset_obj

(

void *

pobj

)

Create a copy of any sequence object with a KS_BASE as first member

Create a copy of the object pointed by pobj and insert it into the linked list in second position. finally reset the (base part of) original object.

It is required that pobj can be casted to (KS_BASE *), which is the pointed object should have a KS_BASE as first member. Note that other, object-specific, actions may need to be performed to finalize the reset. This includes calls to ks_instancereset_***() functions on each member of the current pobj

Parameters

[in]

pobj

Pointer to a sequence object of some kind

Returns

void

                                       {

  KS_BASE *head = (KS_BASE*) pobj;

  /* create a copy */
  KS_BASE *copy = (KS_BASE*) AllocNode(head->size);
  memcpy(copy, head, head->size);

  /* link to the copy */
  head->next = copy;

  /* reset the count of generated instances */
  head->ngenerated = 0;
}

ks_show_clock()

void ks_show_clock

(

FLOAT

scantime

)

Show the clock in the UI with the remaining scan time

                                   {
#ifdef IPG
  setscantimestop();
  setscantimeimm(PSD_CLOCK_NORM, (float)scantime, piviews, (float)pitslice, opslicecnt);
  setscantimestart();
#endif
}

ks_scan_rf_phase_spoiling()

float ks_scan_rf_phase_spoiling

(

int

counter

)

Returns spoiling phase for a given RF counter

Parameters

[in]

counter

[RF number]

Returns

phase [Phase in degrees]

                                             {
  double phase = 117.0 * ((double) counter * ((double) counter + 1.0)) / 2.0;

  /* fmod() does not seem to work on TGT on hardware (MR scanner) */

  int phase_fulllaps = (int) (phase / 360.0);

  phase = phase - (phase_fulllaps * 360.0);

  return ((float) phase);
}

ks_tgt_reset_gradrfctrl()

void ks_tgt_reset_gradrfctrl

(

KS_GRADRFCTRL *

gradrfctrl

)

Clears KS_GRADRFCTRL on TGT. Called in ks_pg_trap, ks_pg_wave, and ks_pg_rf if the field is_cleared_on_tgt is false.

Parameters

gradrfctrl

[pointer to KS_GRADRFCTRL]

                                                        {
  int i = 0;
  for (i = 0; i < gradrfctrl->numrf; ++i) {
    gradrfctrl->rfptr[i] = NULL;
  }
  for (i = 0; i < gradrfctrl->numtrap; ++i) {
    gradrfctrl->trapptr[i] = NULL;
  }
  for (i = 0; i < gradrfctrl->numwave; ++i) {
    gradrfctrl->waveptr[i] = NULL;
  }
  for (i = 0; i < gradrfctrl->numacq; ++i) {
    gradrfctrl->readptr[i] = NULL;
  }
  gradrfctrl->numrf = 0;
  gradrfctrl->numtrap = 0;
  gradrfctrl->numwave = 0;
  gradrfctrl->numacq = 0;
  gradrfctrl->is_cleared_on_tgt = TRUE;
}

ks_eval_clear_readwave()

int ks_eval_clear_readwave

(

KS_READWAVE *

readwave

)

                                                  {
  KS_READWAVE def_readwave;
  ks_init_readwave(&def_readwave);
  def_readwave.freqoffHz = readwave->freqoffHz;
  def_readwave.fov  = readwave->fov;
  def_readwave.res = readwave->res;
  *readwave = def_readwave;
  return SUCCESS;
}

ks_eval_clear_dualreadtrap()

int ks_eval_clear_dualreadtrap

(

KS_DIXON_DUALREADTRAP *

dual_read

)

                                                                 {
  ks_eval_clear_readwave(&dual_read->readwave);
  KS_DIXON_DUALREADTRAP def_dualread;
  ks_init_dixon_dualreadtrap(&def_dualread);
  def_dualread.readwave = dual_read->readwave;
  def_dualread.available_acq_time = dual_read->available_acq_time;
  def_dualread.spare_time_pre = dual_read->spare_time_pre;
  def_dualread.spare_time_post = dual_read->spare_time_post;
  def_dualread.allowed_overflow_post = dual_read->allowed_overflow_post;
  def_dualread.paddingarea = dual_read->paddingarea;
  def_dualread.min_nover = dual_read->min_nover;
  *dual_read = def_dualread;
  return SUCCESS;
}

ks_polyval()

void ks_polyval	(	const double *	coeffs,
		const int	order,
		const float *	x,
		const int	numx,
		float *	values
	)

Variable Documentation

abort_on_kserror

int abort_on_kserror

ks_rhoboard

int ks_rhoboard

loggrd

LOG_GRAD loggrd

phygrd

PHYS_GRAD phygrd

pscR1

int pscR1

rspent

int rspent