Data Structures
struct	KS_SEQLOC

struct	KS_RT_SCALE_LOG

struct	KS_WFINSTANCE

struct	KS_BASE

struct	KS_WAIT

struct	KS_ISIROT

struct	KS_TRAP

struct	KS_WAVE

struct	KS_READ_RESAMPLER

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	kscommon_wave_params

struct	KSCOMMON_RESAMPLER

struct	KS_PHASER

struct	KS_PHASEENCODING_COORD

struct	KS_PHASEENCODING_SHOTCOORDS

struct	KS_PHASEENCODING_PLAN

struct	KS_DYNAMIC_STATE

struct	KS_EPI

struct	KS_READCONTROL_STATE

struct	KS_READCONTROL_PULSEGEN

struct	KS_READCONTROL

struct	KS_ECHOTRAIN

struct	KS_ECHOTRAIN_READOUT_TIMING

struct	KS_DIXON_ASYMREADWAVE

struct	KS_PEPLAN_SHOT_DISTRIBUTION

struct	KS_KCOORD

struct	KS_VIEW

struct	KS_KSPACE_ACQ

struct	KS_PHASEENCODING_REPEAT_DESIGN

struct	KS_KACQ_RECONSHEDULE_ENTRY

struct	ks_crusher_constraints

Macros
#define	WARN_UNUSED_RESULT

#define	KS_GOLDEN_MEANS_1D (1.0+sqrt(5.0))/2.0 /* approx. 1.618033988749895 */

#define	KS_GOLDEN_MEANS_2D_1 1.0/pow((1.0/pow((sqrt(3.1E+1)sqrt(1.08E+2))/1.08E+2+2.9E+1/5.4E+1,1.0/3.0)/9.0+pow((sqrt(3.1E+1)sqrt(1.08E+2))/1.08E+2+2.9E+1/5.4E+1,1.0/3.0)+1.0/3.0),2.0) /* approx. 0.4655712319 */

#define	KS_GOLDEN_MEANS_2D_2 1.0/(1.0/pow((sqrt(3.1E+1)sqrt(1.08E+2))/1.08E+2+2.9E+1/5.4E+1,1.0/3.0)/9.0+pow((sqrt(3.1E+1)sqrt(1.08E+2))/1.08E+2+2.9E+1/5.4E+1,1.0/3.0)+1.0/3.0) /* approx. 0.6823278038 */

#define	KS_ANGLE_PER_INT_16_MAX_180 (180.0 / 0x8000)

#define	KS_ANGLE_PER_UINT_16_MAX_180 (180.0 / 0xF000)

#define	KS_SIGN(x) ((x < 0) ? -1 : 1)

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

#define	INT_MAX 2147483647

#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	KS_EXPAND_OPUSER(number) number, &_opuser ## number

#define	KS_EXPAND_CVFLOAT(number) &_opuser ## number

#define	KS_OPUSER_FROM_NUM(number) opuser_from_number(KS_EXPAND_CVFLOAT(number));

#define	KS_OPUSER_VALUE_FROM_NUM(number) *opuser_from_number(KS_EXPAND_CVFLOAT(number))->addr;

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

#define	areWithinTol(a, b, tol) (fabs((a) - (b)) < tol)

#define	areSameRelative(a, b, r) (fabs((a) - (b)) < r * (fabs((a)) + fabs((b))))

#define	isNotSet(a) areSame((a), KS_NOTSET)

#define	isSet(a) !isNotSet(a)

#define	ks_abs(x) (x)<0 ? -(x) : (x)

#define	ks_round(x) ((x)>=0?(int)((x)+0.5):(int)((x)-0.5))

#define	KS_RUP_GRD_FLOAT(X) ( fmod((X), GRAD_UPDATE_TIME) > 0 ? RUP_GRD( (X) + 1 ) : RUP_GRD( (X) ) )

#define	KS_SRC_FILE (__builtin_strrchr (__FILE__, '/') ? __builtin_strrchr (__FILE__, '/') + 1 : __FILE__)

#define	KS_THROW(format, ...) ks_error("%s (%s:%d): " format, __FUNCTION__, KS_SRC_FILE, __LINE__, ##__VA_ARGS__)

#define	KS_RAISE_TRACE_FN ks_error

#define	KS_RAISE(status) if ((status) != SUCCESS) { KS_RAISE_TRACE_FN("===> %s (%s:%d)", __FUNCTION__, KS_SRC_FILE, __LINE__); return ADVISORY_FAILURE; }

#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_EPI_MIN_INTERTRAIN_SSPGAP 80

#define	L_REF 10

#define	KS_SSP_PRE_READ_TIME 256

#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_PLANE_AX ((exist(opplane) == PSD_AXIAL) \|\| (exist(opplane) == PSD_OBL && exist(opobplane) == PSD_AXIAL))

#define	KS_PLANE_COR ((exist(opplane) == PSD_COR) \|\| (exist(opplane) == PSD_OBL && exist(opobplane) == PSD_COR))

#define	KS_PLANE_SAG ((exist(opplane) == PSD_SAG) \|\| (exist(opplane) == PSD_OBL && exist(opobplane) == PSD_SAG))

#define	KS_DESCRIPTION_LENGTH 128

#define	KS_MAXWAVELEN 10000

#define	KS_MAXUNIQUE_RF 30

#define	KS_MAXUNIQUE_TRAP 200

#define	KS_MAXUNIQUE_WAVE 100

#define	KS_MAXUNIQUE_WAIT 10

#define	KS_READCONTROL_MAXSTATE 2

#define	KS_MAXUNIQUE_READWAVE 2

#define	KS_MAXUNIQUE_SEQUENCES 200

#define	KS_MAX_SEQUENCE_PLAYOUTS 200

#define	KS_MAX_PHASEDYN 2049

#define	KS_MAXUNIQUE_READ 2048

#define	KS_MAX_NUM_KSPACES 16

#define	KS_MAX_NUM_USERDATA 10

#define	KS_EPI_MINBLIPAREA 100

#define	KS_ECHOTRAIN_MAX_TRAPS 4

#define	KS_ECHOTRAIN_MAX_WAVES 2

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

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

#define	KS_INIT_BASE(OBJECT) {0,0,0,NULL,sizeof(OBJECT)}

#define	KS_INIT_FINFO {0.0, 0, 0.0, 0.0, KS_NOTSET, 0, 0, 0}

#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_RT_SCALE_LOG {NULL, NULL, 0, 0, 0, 0}

#define	KS_INIT_WAVEVALUE 0

#define	KS_WAVE_MAXNSTATES 16

#define	KS_INIT_WAVEFORM KS_INITVALUE(KS_MAXWAVELEN, KS_INIT_WAVEVALUE)

#define	KS_INIT_WAVE {KS_INIT_BASE(KS_WAVE), KS_INIT_DESC, 0, 0, KS_INIT_WAVEFORM, {NULL}, {0,0,0}, KS_NOTSET, NULL, NULL, NULL, KS_INIT_RT_SCALE_LOG, 1.0, 0.0, 0.0, 0.0, 0.0, 0.0, NULL, NULL}

#define	KS_INIT_WAIT {KS_INIT_BASE(KS_WAIT), KS_INIT_DESC, 0, KS_NOTSET, NULL, NULL, NULL, KS_INIT_RT_SCALE_LOG }

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

#define	KS_INIT_TRAP {KS_INIT_BASE(KS_TRAP), KS_INIT_DESC, 0.0, 0.0, 0, 0, 0, {0, 0, 0}, {0, 0, 0}, {1, 1, 1}, 1.0f, NULL, NULL, NULL, KS_INIT_RT_SCALE_LOG}

#define	KS_INIT_READ_RESAMPLER {NULL, NULL, NULL, 0, 0, {0}, 0, 0}

#define	KS_INIT_READ {KS_INIT_BASE(KS_READ), KS_INIT_DESC, 0, KS_NOTSET, KS_INIT_FINFO, NULL, 0, NULL, KS_INIT_READ_RESAMPLER}

#define	KS_INIT_READ_EPI {KS_INIT_BASE(KS_READ), KS_INIT_DESC, 0, 250.0, KS_INIT_FINFO, NULL, 0, NULL, KS_INIT_READ_RESAMPLER}

#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_WAVE, 0}

#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_WAVE, 0}

#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, FALSE}

#define	KS_INIT_PHASEENCODING_COORD {KS_NOTSET, KS_NOTSET}

#define	KS_INIT_PHASEENCODING_PLAN {KS_NOTSET, KS_NOTSET, 0, KS_INIT_DESC, 0, {CARTESIAN_COORD, CARTESIAN_COORD}}

#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_TRAP, KS_INIT_TRAP, KS_INIT_PHASER, KS_INIT_PHASER, KS_EPI_BIPOLAR, 1, 0, 0, 0, 0, 1.0, KS_EPI_MINBLIPAREA, 0}

#define	KS_INIT_READWAVE {KS_INIT_WAVE, KS_INIT_WAVE, KS_INIT_READ, 0, 0, 0.0, 0.0, 0, 0, 0.0, 0, 0, {KS_INIT_WAVEFORM}, {KS_INIT_WAVEFORM}}

#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, 0}

#define	KS_INIT_SELRF {KS_INIT_RF, KS_NOTSET, 2.0, 0, 0.0, 0.0, KS_INIT_TRAP, KS_INIT_TRAP, KS_INIT_TRAP, KS_INIT_WAVE, KS_NOTSET, KS_NOTSET, 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, KS_INITZEROS(KS_MAXUNIQUE_WAIT), 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_DISCRETE_REPRESENTATION_SYMMETRIC, KS_INIT_DESC, KS_INIT_SEQ_HANDLE, KS_INIT_GRADRFCTRL, NULL, 0}

#define	KS_INIT_SEQ_COLLECTION {0, KS_SEQ_COLLECTION_ALLOWNEW, FALSE, KS_INITVALUE(KS_MAXUNIQUE_SEQUENCES, NULL), 0, KS_INITVALUE(KS_MAX_SEQUENCE_PLAYOUTS, 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_SPOIL_X 1

#define	KS_SPOIL_Y 2

#define	KS_SPOIL_Z 4

#define	ANYINVERSION (opirprep \|\| opt1flair \|\| opt2flair)

#define	KSCOMMON_INIT_GRAD_PARAMS {0, 0, 0, 0}

#define	KSCOMMON_INIT_RESAMPLER {0, 0, 0.0, KSCOMMON_INIT_GRAD_PARAMS, KSCOMMON_INIT_GRAD_PARAMS, KSCOMMON_INIT_GRAD_PARAMS}

#define	KS_INIT_PHASEENCODING_SHOTCOORDS {0, NULL}

#define	KS_INIT_DYNAMIC_STATE {0, 0, 0, 0, 0, 0, KS_INIT_PHASEENCODING_SHOTCOORDS, 0, 0, 0, 0, 0, 0, 0, 0, {0.0}, 0, 0, KS_MAT4x4_IDENTITY, KS_MAT4x4_IDENTITY}

#define	KS_DABARRAY_KS_RECON_RESERVED 2

#define	KS_DABARRAY_ONLINE_RECON_RESERVED 6

#define	KS_DABARRAY_FULL_LENGTH 28

#define	KS_DABARRAY_AVAILABLE_BYTES (KS_DABARRAY_FULL_LENGTH - KS_DABARRAY_ONLINE_RECON_RESERVED - KS_DABARRAY_KS_RECON_RESERVED)

#define	KS_DEFAULT_READ_TYPE KS_READ_NOTSET

#define	KS_INIT_READCONTROL_STATE {KS_NOTSET, KS_NOTSET}

#define	KS_INIT_READCONTROL_PULSEGEN {KS_DEFAULT_READ_TYPE, 0, 0, 1.0, KS_NOTSET}

#define	KS_INIT_READ_CONTROL {{KS_INIT_READCONTROL_STATE}, KS_INIT_READCONTROL_PULSEGEN}

#define	KS_INIT_ECHOTRAIN {KS_INITVALUE(KS_MAXUNIQUE_READ,KS_INIT_READ_CONTROL), KS_INITVALUE(KS_ECHOTRAIN_MAX_TRAPS,KS_INIT_READTRAP), KS_INITVALUE(KS_ECHOTRAIN_MAX_WAVES,KS_INIT_READWAVE), 0, 0, 0, {0}, 1}

#define	KS_INIT_KSPACE_ACQ {NULL, KS_NOTSET, {KS_NOTSET, KS_NOTSET, KS_NOTSET}}

#define	KS_INIT_PHASEENCODING_REPEAT_DESIGN {NO_REPEAT, KS_NOTSET}

#define	KS_DEFAULT_KSACQ_RECONSHEDULE_ENTRY {0, 0, -1, -1}

#define	KS_INIT_CRUSHER_CONSTRAINT {0, 0, 0, 0, KS_MINPLATEAUTIME, KS_CRUSHER_STRATEGY_FASTEST}

#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 float	KS_MAT3x3f[9]

typedef double	KS_MAT4x4[16]

typedef float	KS_MAT4x4f[16]

Enumerations
enum	KS_PF_EARLYLATE { KS_PF_EARLY = -1, KS_PF_NO = 0, KS_PF_LATE = 1 }

enum	KS_PLOT_FILEFORMATS { KS_PLOT_OFF = 0, KS_PLOT_MAKEPDF, KS_PLOT_MAKESVG, KS_PLOT_MAKEPNG }

enum	KS_PLOT_EXCITATION_MODE { KS_PLOT_STANDARD = 0, KS_PLOT_NO_EXCITATION }

enum	KS_PLOT_PASS_MODE { KS_PLOT_PASS_WAS_DUMMY = 0, KS_PLOT_PASS_WAS_CALIBRATION, KS_PLOT_PASS_WAS_STANDARD }

enum	KS_PLOT_SLICEGROUP_MODE { KS_PLOT_SG_DUMMY = 0, KS_PLOT_SG_CALIBRATION, KS_PLOT_SG_ACQUISITION, KS_PLOT_SG_NOTSET }

enum	KS_DISCRETE_REPRESENTATION { KS_DISCRETE_REPRESENTATION_SYMMETRIC = 0, KS_DISCRETE_REPRESENTATION_GE }

enum	KS_COORDINATE_TYPE { CARTESIAN_COORD = 0, RADIAL_COORD = 1 }

enum	KS_READ_TYPE { KS_READ_NOTSET = 0, KS_READ_TRAP, KS_READ_WAVE }

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_COVERAGE { ELLIPTICAL = 0, RECTANGULAR = 1 }

enum	KS_MTF_DIRECTION { MTF_Y = 0, MTF_Z = 1, MTF_R = 2, MTF_T = 3 }

enum	KS_VIEW_SORT_ORDER { Y_Z = 0, Z_Y = 1, R_T = 2, T_R = 3, Y_R = 4, Z_R = 5, SEC_T = 6 }

enum	KS_VIEW_MTF_PROFILE { LINEAR_SWEEP = -1, PIVOT_CENTER_OUTER_LINEAR = 0, LCPO = 1, SPLIT_SHOTS_LCPO = 2, LINEAR_ROLL = 3, PIVOT_ROLL = 4, SPLIT_SHOTS_AMERICAN = 5, SPLIT_SHOTS_DUTCH = 6 }

enum	RADIUS_PATTERN { LINEAR = 0, EXPONENTIAL = 1 }

enum	KS_REPEAT_MODE { NO_REPEAT = 0, INTERLEAVED_LONGER_SHOTS = 1, SEQUENTIAL_LONGER_SHOTS = 2, INTERLEAVED_EXTRA_SHOTS = 3, SEQUENTIAL_EXTRA_SHOTS = 4 }

enum	KS_RADIAL_SAMPLING_MODE { CARTESIAN = 0, RADIAL_THROUGH_CENTER = 1, RADIAL_SOS = 2 }

enum	KS_RADIAL_SAMPLING_COVERAGE { SAMPLE_180 = 0, SAMPLE_360 = 1 }

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_epitrain_mode { KS_EPI_BIPOLAR = 0, KS_EPI_SPLITODDEVEN = 1, KS_EPI_FLYBACK = 2 }

enum	ks_enum_epiblipsign { KS_EPI_POSBLIPS = 1, KS_EPI_NOBLIPS = 0, KS_EPI_NEGBLIPS = -1 }

enum	ks_enum_diffusion { KS_EPI_DIFFUSION_OFF, KS_EPI_DIFFUSION_ON }

enum	ks_enum_imsize { KS_IMSIZE_NATIVE = 0, 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_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 = 0, 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 = 0, KS_GRADWAVE_RELATIVE = 1 }

enum	ks_enum_crusher_strategy { KS_CRUSHER_STRATEGY_FASTEST = 0, KS_CRUSHER_STRATEGY_EXACT, KS_CRUSHER_STRATEGY_MIN_SLEW, KS_CRUSHER_STRATEGY_MAX_AREA, KS_CRUSHER_STRATEGY_PLATEAU }

Functions
_cvfloat *	opuser_from_number (_cvfloat *cv)

int	isNaN (float a)

STATUS	ks_bitmask_set (unsigned int out, const unsigned int in, const unsigned int size, const unsigned int offset)

unsigned int	ks_bitmask_get (const unsigned int in, const unsigned int size, const unsigned int offset)

int	ks_isIceHardware ()

int	ks_default_ssitime ()

KS_PEPLAN_SHOT_DISTRIBUTION	ks_peplan_distribute_shots (const int etl, const int num_coords, const int center)

void	ks_init_read (KS_READ *read)

void	ks_init_trap (KS_TRAP *trap)

void	ks_init_rtscalelog (KS_RT_SCALE_LOG *const rtscale)

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_readwave (KS_READWAVE *readwave)

void	ks_init_phaser (KS_PHASER *phaser)

void	ks_init_epi (KS_EPI *epi)

void	ks_init_gradrfctrl (KS_GRADRFCTRL *gradrfctrl)

void	ks_init_seqcontrol (KS_SEQ_CONTROL *seqcontrol)

void	ks_init_seqcollection (KS_SEQ_COLLECTION *seqcollection)

void	ks_init_echotrain (KS_ECHOTRAIN *const echotrain)

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_addwaittogradrfctrl (KS_GRADRFCTRL gradrfctrl, KS_WAIT wait) WARN_UNUSED_RESULT

STATUS	ks_eval_wait (KS_WAIT wait, const char const desc, int pg_duration, 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_trap_rotation_invariant_75_max_slewrate (KS_TRAP trap, const char const desc)

STATUS	ks_eval_crusher (KS_WAVE *crusher, const float end_amp, const ks_crusher_constraints crusher_constraints)

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_readwave_constrained (KS_READWAVE readwave, KS_WAVE acq_waves, const int numstates, int flag_symmetric_padding, ks_crusher_constraints pre_crusher_constraints, ks_crusher_constraints post_crusher_constraints)

STATUS	ks_eval_readwave (KS_READWAVE readwave, KS_WAVE acq_wave, float pre_crusher_area, float post_crusher_area, int flag_symmetric_padding, ks_enum_crusher_strategy pre_strategy, ks_enum_crusher_strategy post_strategy)

STATUS	ks_eval_readwave_multistated (KS_READWAVE readwave, KS_WAVE acq_waves, const int num_waves, float pre_crusher_area, float post_crusher_area, int flag_symmetric_padding, ks_enum_crusher_strategy pre_strategy, ks_enum_crusher_strategy post_strategy)

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

int	ks_eval_kynover_fromnex (int yres, float partial_ky, 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, const int res, const int duration, const KS_WAVEFORM waveform) WARN_UNUSED_RESULT

STATUS	ks_eval_mirrorwave (KS_WAVE *wave)

STATUS	ks_eval_mirrorwaveform (KS_WAVEFORM waveform, int res)

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, int MTreduction) WARN_UNUSED_RESULT

STATUS	ks_eval_mt_rf_binomial (KS_RF rf, const char const desc, int sub_pulse_dur, int nPulses, int prp)

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, int nslices, float slthick, float slspace)

float	ks_eval_sms_calc_slice_gap_from_scan_info (int sms_multiband_factor, int nslices, const SCAN_INFO *org_slice_positions)

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_coords2wave (KS_WAVE wave, float t, float G, int num_coords, int dwell, const char desc) WARN_UNUSED_RESULT

STATUS	ks_eval_append_two_waves (KS_WAVE first_wave, KS_WAVE second_wave) WARN_UNUSED_RESULT

STATUS	ks_eval_append_two_waveforms (KS_WAVEFORM first_waveform, KS_WAVEFORM second_waveform, int res1, int res2) 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

STATUS	ks_eval_echotrain (KS_ECHOTRAIN *const echotrain)

int	ks_echotrain_get_max_kspace_index (KS_ECHOTRAIN *echotrain)

PSD_FILTER_GEN	ks_get_maxsize_finfo (PSD_FILTER_GEN my_psd_filter_spec[])

void	ks_grad_heat_reset ()

void	ks_grad_heat_init (KS_SEQ_COLLECTION seqcollection_p, STATUS(play)(const INT max_encode_mode, int nargs, void args), int nargs, void args)

int	ks_eval_rflimits (KS_SAR sar, KS_SEQ_COLLECTION seqcollection)

STATUS	ks_eval_gradlimits (int newtime, KS_SEQ_COLLECTION seqcollection, const LOG_GRAD log_grad, STATUS(play)(const INT max_encode_mode, int nargs, void args), int nargs, void args)

STATUS	ks_eval_hwlimits (int newtime, KS_SEQ_COLLECTION seqcollection, const LOG_GRAD log_grad, STATUS(play)(const INT max_encode_mode, int nargs, void args), int nargs, void args)

s64	ks_eval_getduration (KS_SEQ_COLLECTION seqcollection, STATUS(play)(const INT max_encode_mode, int nargs, void args), int nargs, void args)

int	ks_eval_mintr (int nslices, KS_SEQ_COLLECTION seqcollection, int(play_loop)(int, int, void ), int nargs, void args)

int	ks_eval_maxslicespertr (int TR, KS_SEQ_COLLECTION seqcollection, 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)

s64	ks_eval_seqcollection_gettotalduration (KS_SEQ_COLLECTION *seqcollection)

s64	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_create_suffixed_description (char const out, const char const prefix, const char *suffix,...) __attribute__((format(printf

void void	ks_read_header_pool (int exam_number, int series_number, int *run_number)

float	ks_rt_scale_log_get (const KS_RT_SCALE_LOG *log, int instance_idx, int playout_idx)

int	ks_rt_scale_log_get_state (const KS_RT_SCALE_LOG *log, int instance_idx, int playout_idx)

void	ks_rt_scale_log_set (KS_RT_SCALE_LOG *log, int instance_idx, float ampscale)

void	ks_rt_scale_log_set_state (KS_RT_SCALE_LOG *log, int instance_idx, int state)

void	ks_rt_scale_log_next (KS_RT_SCALE_LOG *log)

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)

STATUS	ks_phaseencoding_memorypool_init (KS_PHASEENCODING_COORD *entries, uint64_t size)

void	ks_init_dynamic (KS_DYNAMIC_STATE *dynamic)

int	ks_phaseencoding_isvalid (const KS_PHASEENCODING_PLAN *phaseenc_plan_ptr)

KS_PHASEENCODING_COORD	ks_phaseencoding_get (const KS_PHASEENCODING_PLAN *phaseenc_plan_ptr, int encode, int shot)

KS_PHASEENCODING_SHOTCOORDS	ks_phaseencoding_get_shot (const KS_PHASEENCODING_PLAN *phaseenc_plan_ptr, int shot)

STATUS	ks_repeat_peplan (KS_PHASEENCODING_PLAN peplan, const KS_PHASEENCODING_REPEAT_DESIGN const repeat)

void	ks_phaseencoding_set (KS_PHASEENCODING_PLAN *phaseenc_plan_ptr, int encode, int shot, int ky, int kz)

void	ks_phaseencoding_print (const KS_PHASEENCODING_PLAN *phaseenc_plan_ptr)

STATUS	ks_phaseencoding_alloc (KS_PHASEENCODING_PLAN *phaseenc_plan_ptr, int etl, int num_shots) WARN_UNUSED_RESULT

STATUS	ks_phaseencoding_generate_simple (KS_PHASEENCODING_PLAN phaseenc_plan_ptr, const char const desc, KS_PHASER phaser, KS_PHASER zphaser, int encodes_per_shot) WARN_UNUSED_RESULT

STATUS	ks_phaseencoding_generate_simple_ellipse (KS_PHASEENCODING_PLAN phaseenc_plan_ptr, const char const desc, KS_PHASER phaser, KS_PHASER zphaser) WARN_UNUSED_RESULT

STATUS	ks_phaseencoding_generate_2d_singleshot_cal (KS_PHASEENCODING_PLAN *phaseenc_plan_ptr, int yres) WARN_UNUSED_RESULT

int	ks_comp_kcoord_r_t (const void a, const void b)

int	ks_comp_kcoord_z_y (const void a, const void b)

int	ks_comp_kcoord_y_z (const void a, const void b)

int	ks_comp_kview_r_t (const void a, const void b)

int	ks_comp_kview_y_z (const void a, const void b)

int	ks_comp_kview_e_t (const void a, const void b)

int	ks_comp_kview_e_z (const void a, const void b)

int	ks_cal_from_nacslines (int R, int nacslines)

int	ks_get_ry_from_kcoords (KS_KCOORD *coord, const int num_coords)

int	ks_get_rz_from_kcoords (KS_KCOORD *coord, const int num_coords)

void	ks_get_matrix_from_kcoords (KS_KCOORD K, const int num_coords, int y, int *z)

STATUS	ks_generate_3d_coords_caipi (KS_KSPACE_ACQ *kacq, int Ny, int Nz, int nover_y, int nover_z, int Ry, int Rz, int cal_y, int cal_z, KS_COVERAGE cal_coverage, KS_COVERAGE acq_coverage, int dy, int dz, int step_y, int step_z) WARN_UNUSED_RESULT

STATUS	ks_generate_3d_coords_radial (KS_KSPACE_ACQ *kacq, int tiny_level, int Ny, int Nz, int Ry, int Rz, KS_RADIAL_SAMPLING_MODE radial_mode, KS_RADIAL_SAMPLING_COVERAGE radial_sampling_coverage) WARN_UNUSED_RESULT

STATUS	ks_generate_3d_coords_simple (KS_KSPACE_ACQ *kacq, int Ny, int Nz, int nover_y, int nover_z, int Ry, int Rz, int cal_y, int cal_z, KS_COVERAGE cal_coverage, KS_COVERAGE acq_coverage) WARN_UNUSED_RESULT

STATUS	ks_generate_2d_coords_cal (KS_KSPACE_ACQ *kacq, int num_desired_coords, int yres) WARN_UNUSED_RESULT

STATUS	ks_generate_3d_coords_poisson_disc (KS_KSPACE_ACQ *kacq, int Ny, int Nz, float min_spacing, float max_spacing, KS_COVERAGE cal_coverage, int cal_y, int cal_z, RADIUS_PATTERN pattern) WARN_UNUSED_RESULT

STATUS	ks_generate_3d_coords_poisson_disc_R (KS_KSPACE_ACQ *kacq, int Ny, int Nz, float R, KS_COVERAGE cal_coverage, int cal_y, int cal_z, RADIUS_PATTERN pattern) WARN_UNUSED_RESULT

STATUS	ks_generate_3d_coords_epi (KS_KSPACE_ACQ kacq, const KS_EPI epitrain, const ks_enum_epiblipsign blipsign, const int Ry, const int caipi_delta) WARN_UNUSED_RESULT

void	ks_pe_linear (int *view_order, int ETL)

void	ks_pe_linear_roll (int *view_order, int ETL, int c)

void	ks_pe_pivot_roll (int *view_order, int ETL, int c)

void	ks_pivot_linear_center_symk (int *view_order, int ETL, int c)

STATUS	ks_pe_permute_pclo_rad (int *view_order, const int etl, const int center)

void	ks_pivot_specific_center_symk (int *view_order, int ETL, int c)

void	ks_pivot_specific_center_radk (int *view_order, int ETL, int c)

STATUS	ks_generate_peplan_from_kcoords (const KS_KSPACE_ACQ kacq, KS_PHASEENCODING_PLAN peplan, KS_MTF_DIRECTION mtf_direction, KS_VIEW_SORT_ORDER encode_shot_assignment_order, KS_VIEW_MTF_PROFILE mtf_profile, const int etl, int center, const KS_COORDINATE_TYPE *const coord_types) WARN_UNUSED_RESULT

STATUS	ks_generate_peplan_from_kcoords_american (const KS_KSPACE_ACQ kacq, KS_PHASEENCODING_PLAN peplan, const KS_MTF_DIRECTION mtf_direction, const int etl, const int center) WARN_UNUSED_RESULT

STATUS	ks_fse_calcecho (double bestecho, double optecho, int nacqlines_to_kspacecenter, const KS_PHASER const pe, KS_PF_EARLYLATE 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_PF_EARLYLATE pf_direction, const int numileavestoacq, ks_enum_sweep_order sweep_order, int numsegments, const int caipi_delta) WARN_UNUSED_RESULT

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)

STATUS	ks_sms_check_divisibility (int *inpass_interleaves, const int sms_factor, const int nslices_per_pass, const int nslices)

int	ks_calc_slice_acquisition_order_smssingleacq (DATA_ACQ_ORDER *dacq, int nslices)

float	ks_calc_integrate_coords (float t, float G, int num_coords)

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)

STATUS	ks_print_acqwaves (KS_SEQ_COLLECTION *seqcollection)

void	ks_print_readwave (const KS_READWAVE const readwave, const char filename)

void	ks_print_wave_part (const KS_WAVE const wave, const char filename, int startidx, int stopidx)

void	ks_print_wave (const KS_WAVE const wave, const char filename)

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_readwaves (KS_ECHOTRAIN const echotrain, const char suffix, int rhkacq_uid)

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 ()

unsigned short	ks_cycles_to_iphase (double cycles)

unsigned short	ks_degrees_to_iphase (double degrees)

unsigned short	ks_radians_to_iphase (double radians)

float	ks_calc_selgradamp (float rfbw, float slthick)

void	ks_wave_compute_params (KS_WAVE *const wave)

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, int *index)

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)

int	ks_wave_time2area (const KS_WAVE *wave, float area_in)

float	ks_waveform_area (const KS_WAVEFORM waveform, int start, int end, int dwelltime)

long	ks_iwave_area (const KS_IWAVE iwave, int start, int end, int dwelltime)

float	ks_wave_area (const KS_WAVE *wave, int start, int end)

float	ks_wave_full_area (const KS_WAVE *wave)

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_eval_readwave_negatestate (KS_READWAVE *readwave, int state)

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, float max, float fs_factor) 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_addwaveformstate (KS_WAVE *wave, KS_WAVEFORM waveform, int state_index)

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

KS_SEQLOC	ks_pg_get_trap_loc (KS_TRAP *trap, int instance)

KS_SEQLOC	ks_pg_get_wave_loc (KS_WAVE *wave, int instance)

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_double_to_float (KS_MAT4x4f out, const KS_MAT4x4 in)

void	ks_mat4_float_to_double (KS_MAT4x4 out, const KS_MAT4x4f in)

void	ks_mat4_setgeometry (KS_MAT4x4 lhs, float x, float y, float z, float xr, float yr, float zr)

void	ks_mat4f_setgeometry (KS_MAT4x4f 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_mat3f_apply (float w, const KS_MAT3x3f R, const float v)

void	ks_mat3_invapply (double w, const KS_MAT3x3 R, const double v)

void	ks_mat3f_invapply (float w, const KS_MAT3x3f R, const float 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_update_slice_location_float (SCAN_INFO *new_loc, const SCAN_INFO orig_loc, const KS_MAT4x4f M_physical, const KS_MAT4x4f M_logical)

void	ks_scan_rotate (SCAN_INFO slice_pos)

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_loc_by_timeboard (KS_SEQLOC *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 (const 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 pass_mode)

void	ks_plot_slicetime_end ()

void	ks_plot_write_peplans (const KS_PHASEENCODING_PLAN const plans, const int num_plans, FILE *fp)

void	ks_plot_host_slicetime_begin ()

void	ks_plot_host_slicetime (const 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 pass_mode)

void	ks_plot_host_slicetime_end ()

void	ks_plot_host (const KS_SEQ_COLLECTION seqcollection, const KS_PHASEENCODING_PLAN plan)

void	ks_plot_host_seqctrl (const KS_SEQ_CONTROL ctrl, const KS_PHASEENCODING_PLAN plan)

void	ks_plot_host_seqctrl_manyplans (const KS_SEQ_CONTROL ctrl, const KS_PHASEENCODING_PLAN *plan, const int num_plans)

void	ks_plot_tgt_reset (KS_SEQ_CONTROL *ctrl)

void	ks_plot_filename (char fname, char path, char outputdir, char outputdir_uid, const char *const seq_desc)

void	ks_plot_saveconfig (KS_SEQ_CONTROL *ctrl)

void	ks_plot_tgt_addframe (KS_SEQ_CONTROL *ctrl)

int	ks_get_center_encode (const KS_PHASEENCODING_PLAN *const peplan, int shot, int yres, int zres)

int	ks_peplan_find_center_from_linear_sweep (KS_KCOORD const K, KS_VIEW view, const int num_coords, const KS_MTF_DIRECTION mtf_direction, const int sweep_sign, const int segment_size, const int start_encode)

int	ks_get_center_encode_linearsweep (const KS_KSPACE_ACQ *kacq, const int etl, const KS_PF_EARLYLATE pf_earlylate_te)

float	ks_calc_caipi_scale (const int ky, const int R, const int caipi_factor)

float	ks_calc_caipi_phase (const float sms_slice_gap, const int sms_multiband_factor, const SCAN_INFO *slice_info, const float caipi_blip_area, const int slice_encode_dir)

float	ks_calc_caipi_offset_phase (const float sms_slice_gap, const int sms_multiband_factor, const SCAN_INFO *slice_info, const int caipi_factor, const float caipi_blip_area, const int ky, const int R, const int slice_encode_dir)

STATUS	ks_eval_caipiblip (KS_TRAP *caipiblip, const int caipi_factor, const float sms_slice_gap, const KS_DESCRIPTION seq_desc)

int	ks_eval_sms_rf_scan_info (SCAN_INFO sms_slice_positions, const SCAN_INFO org_slice_positions, int sms_multiband_factor, int nslices)

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 newwaveform, int state)

void	ks_scan_setwavestate (KS_WAVE *wave, int state, int instance)

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_offsetfov3D_readwave (KS_READWAVE *readwave, int instanceno, SCAN_INFO sliceinfo, float ky, float phasefovratio, float kz, float zphasefovratio, float rcvphase)

void	ks_scan_offsetfov_iso_readwave (KS_READWAVE *readwave, int instanceno, SCAN_INFO sliceinfo, double ky, double kz, double rcvphase)

void	ks_scan_offsetfov_iso_readwave_oneread (KS_READWAVE readwave, KS_READ read, int gradinstanceno, int readinstanceno, SCAN_INFO sliceinfo, double ky, double kz, double rcvphase)

void	ks_scan_offsetfov_readwave (KS_READWAVE *readwave, int instanceno, SCAN_INFO sliceinfo, float ky, float phasefovratio, float rcvphase)

int	ks_eval_append_blip (KS_WAVE *wave, const float s, const int max_points, const float area)

unsigned short	ks_scan_omegatrap_hz (KS_TRAP *trap, int instanceno, float Hz, int omega_iwave_phase_at_null)

unsigned short	ks_scan_omegawave_hz (KS_WAVE *wave, int instanceno, float Hz, int omega_iwave_phase_at_null)

void	ks_scan_wait (KS_WAIT *wait, int waitperiod)

void	ks_scan_trap_ampscale (KS_TRAP *trap, int instanceno, float ampscale)

void	ks_scan_wave_ampscale (KS_WAVE *wave, 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)

void	ks_scan_phaser_average (KS_PHASER *phaser, int instanceno)

void	ks_scan_phaser_max (KS_PHASER *phaser, int instanceno)

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_sms (KS_EPI *epi, int echo, SCAN_INFO sliceinfo, KS_PHASEENCODING_COORD starting_coord, ks_enum_epiblipsign blipsign, float rcvphase, int sms_factor, float sms_slice_gap, int caipi_factor, int sms_slice_encoding_direction)

void	ks_scan_epi_shotcontrol (KS_EPI *epi, int echo, SCAN_INFO sliceinfo, KS_PHASEENCODING_COORD starting_coord, ks_enum_epiblipsign blipsign, float rcvphase)

void	ks_scan_epi_loadecho (KS_EPI epi, int echo, int storeecho, int slice, KS_PHASEENCODING_COORD starting_coord, ks_enum_epiblipsign blipsign, KS_DYNAMIC_STATE dynamic)

void	ks_loaddab_reserved (WF_PULSE_ADDR echo, short state, short resampler_index)

void	ks_loaddab (WF_PULSE_ADDR echo, const char *dab_array)

void	ks_loaddab_full (WF_PULSE_ADDR echo, const char *custom_dab_array)

const KS_READ *	ks_get_read_in_echotrain (const KS_ECHOTRAIN *echotrain, const int readout_index)

WF_PULSE_ADDR	ks_get_wf_pulse (KS_ECHOTRAIN *echotrain, const int readout_index)

LONG	ks_get_override_R1 (KS_ECHOTRAIN *echotrain, const int readout_index)

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)

int	ks_scan_gettherightshot (const KS_DYNAMIC_STATE *dynamic)

float	ks_get_trapamp_instance (const KS_TRAP *trap, int instance)

void	ks_tgt_reset_gradrfctrl (KS_GRADRFCTRL *gradrfctrl)

int	ks_eval_clear_readwave (KS_READWAVE *readwave)

void	ks_polyder (const double coeffs, const int order, double der_coeffs)

void	ks_polyval (const double coeffs, const int order, const double x, const int numx, double *values)

void	ks_polyval_f (const double coeffs, const int order, const float x, const int numx, float *values)

double	ks_Newtons_method (const double *coeffs, const int order, const double x0, const int num_iter)

int	ks_pg_readwave (KS_READWAVE readwave, KS_SEQLOC loc, KS_SEQ_CONTROL ctrl)

STATUS	ks_pg_echotrain_readout (KS_ECHOTRAIN echotrain, int readout_index, int echo_time, KS_ECHOTRAIN_READOUT_TIMING timing, KS_SEQ_CONTROL *ctrl)

int	ks_numplaced (KS_BASE *base)

void	ks_set_opcode (WF_PULSE_ADDR echo, short opcode)

int	ks_write_vector_bf (float vec, uint32_t numel, const char fname)

FILE *	ks_open_file_in_embed (const char fname, const char write_mode)

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

◆ KS_GOLDEN_MEANS_1D

#define KS_GOLDEN_MEANS_1D (1.0+sqrt(5.0))/2.0 /* approx. 1.618033988749895 */

◆ KS_GOLDEN_MEANS_2D_1

#define KS_GOLDEN_MEANS_2D_1 1.0/pow((1.0/pow((sqrt(3.1E+1)*sqrt(1.08E+2))/1.08E+2+2.9E+1/5.4E+1,1.0/3.0)/9.0+pow((sqrt(3.1E+1)*sqrt(1.08E+2))/1.08E+2+2.9E+1/5.4E+1,1.0/3.0)+1.0/3.0),2.0) /* approx. 0.4655712319 */

◆ KS_GOLDEN_MEANS_2D_2

#define KS_GOLDEN_MEANS_2D_2 1.0/(1.0/pow((sqrt(3.1E+1)*sqrt(1.08E+2))/1.08E+2+2.9E+1/5.4E+1,1.0/3.0)/9.0+pow((sqrt(3.1E+1)*sqrt(1.08E+2))/1.08E+2+2.9E+1/5.4E+1,1.0/3.0)+1.0/3.0) /* approx. 0.6823278038 */

◆ KS_ANGLE_PER_INT_16_MAX_180

#define KS_ANGLE_PER_INT_16_MAX_180 (180.0 / 0x8000)

◆ KS_ANGLE_PER_UINT_16_MAX_180

#define KS_ANGLE_PER_UINT_16_MAX_180 (180.0 / 0xF000)

◆ KS_SIGN

#define KS_SIGN ( x ) ((x < 0) ? -1 : 1)

◆ 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

◆ INT_MAX

#define INT_MAX 2147483647

◆ 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;\
    }\
}

◆ KS_EXPAND_OPUSER

#define KS_EXPAND_OPUSER ( number ) number, &_opuser ## number

expand opuser number. For instance KS_EXPAND_OPUSER(5) becomes 5 and &_opuser5

◆ KS_EXPAND_CVFLOAT

#define KS_EXPAND_CVFLOAT ( number ) &_opuser ## number

◆ KS_OPUSER_FROM_NUM

#define KS_OPUSER_FROM_NUM ( number ) opuser_from_number(KS_EXPAND_CVFLOAT(number));

◆ KS_OPUSER_VALUE_FROM_NUM

#define KS_OPUSER_VALUE_FROM_NUM ( number ) *opuser_from_number(KS_EXPAND_CVFLOAT(number))->addr;

◆ areSame

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

◆ areWithinTol

#define areWithinTol	(	a,
		b,
		tol
	)	(fabs((a) - (b)) < tol)

◆ areSameRelative

#define areSameRelative	(	a,
		b,
		r
	)	(fabs((a) - (b)) < r * (fabs((a)) + fabs((b))))

◆ isNotSet

#define isNotSet ( a ) areSame((a), KS_NOTSET)

◆ isSet

#define isSet ( a ) !isNotSet(a)

◆ ks_abs

#define ks_abs ( x ) (x)<0 ? -(x) : (x)

◆ ks_round

#define ks_round ( x ) ((x)>=0?(int)((x)+0.5):(int)((x)-0.5))

◆ KS_RUP_GRD_FLOAT

#define KS_RUP_GRD_FLOAT ( X ) ( fmod((X), GRAD_UPDATE_TIME) > 0 ? RUP_GRD( (X) + 1 ) : RUP_GRD( (X) ) )

◆ KS_SRC_FILE

#define KS_SRC_FILE (__builtin_strrchr (__FILE__, '/') ? __builtin_strrchr (__FILE__, '/') + 1 : __FILE__)

◆ KS_THROW

#define KS_THROW	(	format,
		...
	)	ks_error("%s (%s:%d): " format, __FUNCTION__, KS_SRC_FILE, __LINE__, ##__VA_ARGS__)

◆ KS_RAISE_TRACE_FN

#define KS_RAISE_TRACE_FN ks_error

◆ KS_RAISE

#define KS_RAISE ( status ) if ((status) != SUCCESS) { KS_RAISE_TRACE_FN("===> %s (%s:%d)", __FUNCTION__, KS_SRC_FILE, __LINE__); return ADVISORY_FAILURE; }

◆ 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_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

◆ KS_SSP_PRE_READ_TIME

#define KS_SSP_PRE_READ_TIME 256

◆ 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_PLANE_AX

#define KS_PLANE_AX ((exist(opplane) == PSD_AXIAL) || (exist(opplane) == PSD_OBL && exist(opobplane) == PSD_AXIAL))

◆ KS_PLANE_COR

#define KS_PLANE_COR ((exist(opplane) == PSD_COR) || (exist(opplane) == PSD_OBL && exist(opobplane) == PSD_COR))

◆ KS_PLANE_SAG

#define KS_PLANE_SAG ((exist(opplane) == PSD_SAG) || (exist(opplane) == PSD_OBL && exist(opobplane) == PSD_SAG))

◆ 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 30

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 100

Maximum number of different KS_WAVEs in the sequence

◆ KS_MAXUNIQUE_WAIT

#define KS_MAXUNIQUE_WAIT 10

Maximum number of different KS_WAITs in the sequence

◆ KS_READCONTROL_MAXSTATE

#define KS_READCONTROL_MAXSTATE 2

Maximum number of states in a KS_ECHOTRAIN object

◆ KS_MAXUNIQUE_READWAVE

#define KS_MAXUNIQUE_READWAVE 2

Maximum number of different KS_READWAVEs 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_SEQUENCE_PLAYOUTS

#define KS_MAX_SEQUENCE_PLAYOUTS 200

Maximum number of pulses sequence modules, played during a TR

◆ 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 2048

Maximum number of readout instances

◆ KS_MAX_NUM_KSPACES

#define KS_MAX_NUM_KSPACES 16

◆ KS_MAX_NUM_USERDATA

#define KS_MAX_NUM_USERDATA 10

◆ 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_ECHOTRAIN_MAX_TRAPS

#define KS_ECHOTRAIN_MAX_TRAPS 4

Maximum number of different KS_READTRAP objects in a KS_ECHOTRAIN

◆ KS_ECHOTRAIN_MAX_WAVES

#define KS_ECHOTRAIN_MAX_WAVES 2

Maximum number of different KS_READWAVE objects in a KS_ECHOTRAIN

◆ 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_BASE

#define KS_INIT_BASE ( OBJECT ) {0,0,0,NULL,sizeof(OBJECT)}

◆ KS_INIT_FINFO

#define KS_INIT_FINFO {0.0, 0, 0.0, 0.0, KS_NOTSET, 0, 0, 0}

◆ 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_RT_SCALE_LOG

#define KS_INIT_RT_SCALE_LOG {NULL, NULL, 0, 0, 0, 0}

◆ KS_INIT_WAVEVALUE

#define KS_INIT_WAVEVALUE 0

Default value for one element in a KS_WAVEFORM

◆ KS_WAVE_MAXNSTATES

#define KS_WAVE_MAXNSTATES 16

◆ 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 {KS_INIT_BASE(KS_WAVE), KS_INIT_DESC, 0, 0, KS_INIT_WAVEFORM, {NULL}, {0,0,0}, KS_NOTSET, NULL, NULL, NULL, KS_INIT_RT_SCALE_LOG, 1.0, 0.0, 0.0, 0.0, 0.0, 0.0, NULL, NULL}

Default values for KS_WAVE sequence objects

◆ KS_INIT_WAIT

#define KS_INIT_WAIT {KS_INIT_BASE(KS_WAIT), KS_INIT_DESC, 0, KS_NOTSET, NULL, NULL, NULL, KS_INIT_RT_SCALE_LOG }

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 {KS_INIT_BASE(KS_TRAP), KS_INIT_DESC, 0.0, 0.0, 0, 0, 0, {0, 0, 0}, {0, 0, 0}, {1, 1, 1}, 1.0f, NULL, NULL, NULL, KS_INIT_RT_SCALE_LOG}

Default values for KS_TRAP sequence objects

◆ KS_INIT_READ_RESAMPLER

#define KS_INIT_READ_RESAMPLER {NULL, NULL, NULL, 0, 0, {0}, 0, 0}

◆ KS_INIT_READ

#define KS_INIT_READ {KS_INIT_BASE(KS_READ), KS_INIT_DESC, 0, KS_NOTSET, KS_INIT_FINFO, NULL, 0, NULL, KS_INIT_READ_RESAMPLER}

Default values for KS_READ sequence objects

◆ KS_INIT_READ_EPI

#define KS_INIT_READ_EPI {KS_INIT_BASE(KS_READ), KS_INIT_DESC, 0, 250.0, KS_INIT_FINFO, NULL, 0, NULL, KS_INIT_READ_RESAMPLER}

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_WAVE, 0}

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_WAVE, 0}

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, FALSE}

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, 0, KS_INIT_DESC, 0, {CARTESIAN_COORD, CARTESIAN_COORD}}

◆ 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_TRAP, KS_INIT_TRAP, KS_INIT_PHASER, KS_INIT_PHASER, KS_EPI_BIPOLAR, 1, 0, 0, 0, 0, 1.0, KS_EPI_MINBLIPAREA, 0}

Default values for KS_EPI sequence objects

◆ KS_INIT_READWAVE

#define KS_INIT_READWAVE {KS_INIT_WAVE, KS_INIT_WAVE, KS_INIT_READ, 0, 0, 0.0, 0.0, 0, 0, 0.0, 0, 0, {KS_INIT_WAVEFORM}, {KS_INIT_WAVEFORM}}

◆ 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, 0}

Default values for KS_RF sequence objects

◆ KS_INIT_SELRF

#define KS_INIT_SELRF {KS_INIT_RF, KS_NOTSET, 2.0, 0, 0.0, 0.0, KS_INIT_TRAP, KS_INIT_TRAP, KS_INIT_TRAP, KS_INIT_WAVE, KS_NOTSET, KS_NOTSET, 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, KS_INITZEROS(KS_MAXUNIQUE_WAIT), 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_DISCRETE_REPRESENTATION_SYMMETRIC, KS_INIT_DESC, KS_INIT_SEQ_HANDLE, KS_INIT_GRADRFCTRL, NULL, 0}

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), 0, KS_INITVALUE(KS_MAX_SEQUENCE_PLAYOUTS, 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_SPOIL_X

#define KS_SPOIL_X 1

Toggle spoiling on X

◆ KS_SPOIL_Y

#define KS_SPOIL_Y 2

Toggle spoiling on Y

◆ KS_SPOIL_Z

#define KS_SPOIL_Z 4

Toggle spoiling on Z

◆ ANYINVERSION

#define ANYINVERSION (opirprep || opt1flair || opt2flair)

◆ KSCOMMON_INIT_GRAD_PARAMS

#define KSCOMMON_INIT_GRAD_PARAMS {0, 0, 0, 0}

◆ KSCOMMON_INIT_RESAMPLER

#define KSCOMMON_INIT_RESAMPLER {0, 0, 0.0, KSCOMMON_INIT_GRAD_PARAMS, KSCOMMON_INIT_GRAD_PARAMS, KSCOMMON_INIT_GRAD_PARAMS}

◆ KS_INIT_PHASEENCODING_SHOTCOORDS

#define KS_INIT_PHASEENCODING_SHOTCOORDS {0, NULL}

◆ KS_INIT_DYNAMIC_STATE

#define KS_INIT_DYNAMIC_STATE {0, 0, 0, 0, 0, 0, KS_INIT_PHASEENCODING_SHOTCOORDS, 0, 0, 0, 0, 0, 0, 0, 0, {0.0}, 0, 0, KS_MAT4x4_IDENTITY, KS_MAT4x4_IDENTITY}

◆ KS_DABARRAY_KS_RECON_RESERVED

#define KS_DABARRAY_KS_RECON_RESERVED 2

◆ KS_DABARRAY_ONLINE_RECON_RESERVED

#define KS_DABARRAY_ONLINE_RECON_RESERVED 6

◆ KS_DABARRAY_FULL_LENGTH

#define KS_DABARRAY_FULL_LENGTH 28

◆ KS_DABARRAY_AVAILABLE_BYTES

#define KS_DABARRAY_AVAILABLE_BYTES (KS_DABARRAY_FULL_LENGTH - KS_DABARRAY_ONLINE_RECON_RESERVED - KS_DABARRAY_KS_RECON_RESERVED)

◆ KS_DEFAULT_READ_TYPE

#define KS_DEFAULT_READ_TYPE KS_READ_NOTSET

◆ KS_INIT_READCONTROL_STATE

#define KS_INIT_READCONTROL_STATE {KS_NOTSET, KS_NOTSET}

◆ KS_INIT_READCONTROL_PULSEGEN

#define KS_INIT_READCONTROL_PULSEGEN {KS_DEFAULT_READ_TYPE, 0, 0, 1.0, KS_NOTSET}

◆ KS_INIT_READ_CONTROL

#define KS_INIT_READ_CONTROL {{KS_INIT_READCONTROL_STATE}, KS_INIT_READCONTROL_PULSEGEN}

◆ KS_INIT_ECHOTRAIN

#define KS_INIT_ECHOTRAIN {KS_INITVALUE(KS_MAXUNIQUE_READ,KS_INIT_READ_CONTROL), KS_INITVALUE(KS_ECHOTRAIN_MAX_TRAPS,KS_INIT_READTRAP), KS_INITVALUE(KS_ECHOTRAIN_MAX_WAVES,KS_INIT_READWAVE), 0, 0, 0, {0}, 1}

◆ KS_INIT_KSPACE_ACQ

#define KS_INIT_KSPACE_ACQ {NULL, KS_NOTSET, {KS_NOTSET, KS_NOTSET, KS_NOTSET}}

◆ KS_INIT_PHASEENCODING_REPEAT_DESIGN

#define KS_INIT_PHASEENCODING_REPEAT_DESIGN {NO_REPEAT, KS_NOTSET}

◆ KS_DEFAULT_KSACQ_RECONSHEDULE_ENTRY

#define KS_DEFAULT_KSACQ_RECONSHEDULE_ENTRY {0, 0, -1, -1}

◆ KS_INIT_CRUSHER_CONSTRAINT

#define KS_INIT_CRUSHER_CONSTRAINT {0, 0, 0, 0, KS_MINPLATEAUTIME, KS_CRUSHER_STRATEGY_FASTEST}

◆ 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_MAT3x3f

typedef float KS_MAT3x3f[9]

Array to store a row major 3x3 matrix (float)

◆ KS_MAT4x4

typedef double KS_MAT4x4[16]

Array to store a row major 4x4 matrix

◆ KS_MAT4x4f

typedef float KS_MAT4x4f[16]

Array to store a row major 4x4 matrix (float)

Enumeration Type Documentation

◆ KS_PF_EARLYLATE

enum KS_PF_EARLYLATE

Enumerator
KS_PF_EARLY
KS_PF_NO
KS_PF_LATE

              {KS_PF_EARLY = -1,
               KS_PF_NO = 0,
               KS_PF_LATE = 1} KS_PF_EARLYLATE;

◆ KS_PLOT_FILEFORMATS

enum KS_PLOT_FILEFORMATS

Enumerator
KS_PLOT_OFF
KS_PLOT_MAKEPDF
KS_PLOT_MAKESVG
KS_PLOT_MAKEPNG

              {
   KS_PLOT_OFF = 0,
   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 = 0,
   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 = 0,
   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 = 0,
   KS_PLOT_SG_CALIBRATION,
   KS_PLOT_SG_ACQUISITION,
   KS_PLOT_SG_NOTSET
 } KS_PLOT_SLICEGROUP_MODE;

◆ KS_DISCRETE_REPRESENTATION

enum KS_DISCRETE_REPRESENTATION

Enumerator
KS_DISCRETE_REPRESENTATION_SYMMETRIC
KS_DISCRETE_REPRESENTATION_GE

              {
   KS_DISCRETE_REPRESENTATION_SYMMETRIC = 0,
   KS_DISCRETE_REPRESENTATION_GE
 } KS_DISCRETE_REPRESENTATION;

◆ KS_COORDINATE_TYPE

enum KS_COORDINATE_TYPE

ADDTITLEHERE

Enumerator
CARTESIAN_COORD
RADIAL_COORD

              {
   CARTESIAN_COORD = 0,
   RADIAL_COORD = 1
 } KS_COORDINATE_TYPE;

◆ KS_READ_TYPE

enum KS_READ_TYPE

The read object type, used in KS_READCONTROL_PULSEGEN

Enumerator
KS_READ_NOTSET
KS_READ_TRAP
KS_READ_WAVE

              {
   KS_READ_NOTSET = 0,
   KS_READ_TRAP,
   KS_READ_WAVE
 } KS_READ_TYPE;

◆ ks_enum_sweep_order

enum ks_enum_sweep_order

k-space 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_COVERAGE

enum KS_COVERAGE

ADDTITLEHERE

Enumerator
ELLIPTICAL
RECTANGULAR

              {
   ELLIPTICAL = 0,
   RECTANGULAR = 1
 } KS_COVERAGE;

◆ KS_MTF_DIRECTION

enum KS_MTF_DIRECTION

ADDTITLEHERE

Enumerator
MTF_Y
MTF_Z
MTF_R
MTF_T

              {
   MTF_Y = 0,
   MTF_Z = 1,
   MTF_R = 2, /* Radius in ky/kz plane. For isotropic point spread function */
   MTF_T = 3, /* Azimuthal in ky/kz plane. You would rarely want this */
 } KS_MTF_DIRECTION;

◆ KS_VIEW_SORT_ORDER

enum KS_VIEW_SORT_ORDER

ADDTITLEHERE

Enumerator
Y_Z
Z_Y
R_T
T_R
Y_R
Z_R
SEC_T

              {
   /* Cartesian coordinates */
   Y_Z = 0,
   Z_Y = 1,
   /* Polar coordinates R = radius T = theta*/
   R_T = 2,
   T_R = 3,
   /* Mixing coords */
   Y_R = 4,
   Z_R = 5,
   /* Sectors for continuous time */
   SEC_T = 6
 
 } KS_VIEW_SORT_ORDER;

◆ KS_VIEW_MTF_PROFILE

enum KS_VIEW_MTF_PROFILE

ADDTITLEHERE

Enumerator
LINEAR_SWEEP
PIVOT_CENTER_OUTER_LINEAR
LCPO
SPLIT_SHOTS_LCPO
LINEAR_ROLL
PIVOT_ROLL
SPLIT_SHOTS_AMERICAN
SPLIT_SHOTS_DUTCH

              {
   LINEAR_SWEEP = -1,
   PIVOT_CENTER_OUTER_LINEAR = 0,
   LCPO = 1,
   SPLIT_SHOTS_LCPO = 2,
   LINEAR_ROLL = 3,
   PIVOT_ROLL = 4,
   SPLIT_SHOTS_AMERICAN = 5,
   SPLIT_SHOTS_DUTCH = 6,
 } KS_VIEW_MTF_PROFILE;

◆ RADIUS_PATTERN

enum RADIUS_PATTERN

ADDTITLEHERE

Enumerator
LINEAR
EXPONENTIAL

              {
   LINEAR = 0,
   EXPONENTIAL = 1,
 } RADIUS_PATTERN;

◆ KS_REPEAT_MODE

enum KS_REPEAT_MODE

KS_REPEAT_MODE - Controls how the phase encoding shots are repeated

Enumerator
NO_REPEAT
INTERLEAVED_LONGER_SHOTS
SEQUENTIAL_LONGER_SHOTS
INTERLEAVED_EXTRA_SHOTS
SEQUENTIAL_EXTRA_SHOTS

              {
   NO_REPEAT = 0,
   INTERLEAVED_LONGER_SHOTS = 1, /* For two repeats: [0, 1, 3, 2] -> [0, 0, 1, 1, 3, 3, 2, 2] */
   SEQUENTIAL_LONGER_SHOTS = 2,  /* For two repeats: [0, 1, 3, 2] -> [0, 1, 3, 2, 0, 1, 3, 2] */
   INTERLEAVED_EXTRA_SHOTS = 3, /* For two repeats: [0, 1, 3, 2] -> [0, 1, 3, 2], next shot same encodes [0, 1, 3, 2] */
   SEQUENTIAL_EXTRA_SHOTS = 4 /* Repeat all shots after they have been played out once */
 } KS_REPEAT_MODE;

◆ KS_RADIAL_SAMPLING_MODE

enum KS_RADIAL_SAMPLING_MODE

ADDTITLEHERE

Enumerator
CARTESIAN
RADIAL_THROUGH_CENTER
RADIAL_SOS

                                      {
   CARTESIAN = 0,
   RADIAL_THROUGH_CENTER = 1,
   RADIAL_SOS = 2,
 } KS_RADIAL_SAMPLING_MODE;

◆ KS_RADIAL_SAMPLING_COVERAGE

enum KS_RADIAL_SAMPLING_COVERAGE

ADDTITLEHERE

Enumerator
SAMPLE_180
SAMPLE_360

                                          {
   SAMPLE_180 = 0,
   SAMPLE_360 = 1,  
 } KS_RADIAL_SAMPLING_COVERAGE;

◆ ks_snr_mode

enum ks_snr_mode

Enumerator
KS_SNR_MEAS_OFF
KS_SNR_MEAS_FREQUENCY
KS_SNR_MEAS_PHASE

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

KS_SNR_MEAS_FREQUENCY

Definition: KSFoundation.h:2307

KS_SNR_MEAS_OFF

Definition: KSFoundation.h:2307

KS_SNR_MEAS_PHASE

Definition: KSFoundation.h:2307

◆ ks_enum_trapparts

enum ks_enum_trapparts

Enumerator
G_ATTACK
G_PLATEAU
G_DECAY

2310 {G_ATTACK, G_PLATEAU, G_DECAY};

G_PLATEAU

Definition: KSFoundation.h:2310

G_ATTACK

Definition: KSFoundation.h:2310

G_DECAY

Definition: KSFoundation.h:2310

◆ 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_epitrain_mode

enum ks_enum_epitrain_mode

Enumerator
KS_EPI_BIPOLAR
KS_EPI_SPLITODDEVEN
KS_EPI_FLYBACK

2329 {KS_EPI_BIPOLAR = 0, KS_EPI_SPLITODDEVEN = 1, KS_EPI_FLYBACK = 2} ks_enum_epitrain_mode;

ks_enum_epitrain_mode

Definition: KSFoundation.h:2329

KS_EPI_SPLITODDEVEN

Definition: KSFoundation.h:2329

KS_EPI_BIPOLAR

Definition: KSFoundation.h:2329

KS_EPI_FLYBACK

Definition: KSFoundation.h:2329

◆ ks_enum_epiblipsign

enum ks_enum_epiblipsign

Enumerator
KS_EPI_POSBLIPS
KS_EPI_NOBLIPS
KS_EPI_NEGBLIPS

2330 {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_EPI_POSBLIPS

Definition: KSFoundation.h:2330

ks_enum_epiblipsign

Definition: KSFoundation.h:2330

KS_EPI_NOBLIPS

Definition: KSFoundation.h:2330

KS_EPI_NEGBLIPS

Definition: KSFoundation.h:2330

◆ ks_enum_diffusion

enum ks_enum_diffusion

Enumerator
KS_EPI_DIFFUSION_OFF
KS_EPI_DIFFUSION_ON

2332 {KS_EPI_DIFFUSION_OFF, KS_EPI_DIFFUSION_ON};

KS_EPI_DIFFUSION_OFF

Definition: KSFoundation.h:2332

KS_EPI_DIFFUSION_ON

Definition: KSFoundation.h:2332

◆ ks_enum_imsize

enum ks_enum_imsize

Enumerator
KS_IMSIZE_NATIVE
KS_IMSIZE_POW2
KS_IMSIZE_MIN256

2335 {KS_IMSIZE_NATIVE = 0, KS_IMSIZE_POW2, KS_IMSIZE_MIN256} ks_enum_imsize;

KS_IMSIZE_POW2

Definition: KSFoundation.h:2335

ks_enum_imsize

Definition: KSFoundation.h:2335

KS_IMSIZE_MIN256

Definition: KSFoundation.h:2335

KS_IMSIZE_NATIVE

Definition: KSFoundation.h:2335

◆ ks_enum_datadestination

enum ks_enum_datadestination

Enumerator
KS_DONT_SEND
KS_SENDTOBAM
KS_SENDTORTP

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

KS_SENDTORTP

Definition: KSFoundation.h:2336

KS_SENDTOBAM

Definition: KSFoundation.h:2336

KS_DONT_SEND

Definition: KSFoundation.h:2336

◆ ks_enum_accelmenu

enum ks_enum_accelmenu

Enumerator
KS_ACCELMENU_FRACT
KS_ACCELMENU_INT

2337 {KS_ACCELMENU_FRACT, KS_ACCELMENU_INT};

KS_ACCELMENU_INT

Definition: KSFoundation.h:2337

KS_ACCELMENU_FRACT

Definition: KSFoundation.h:2337

◆ 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

2340 {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_REF

Definition: KSFoundation.h:2340

KS_RF_ROLE_INV

Definition: KSFoundation.h:2340

KS_RF_ROLE_EXC

Definition: KSFoundation.h:2340

KS_RF_ROLE_NOTSET

Definition: KSFoundation.h:2340

KS_RF_ROLE_CHEMSAT

Definition: KSFoundation.h:2340

KS_RF_ROLE_SPSAT

Definition: KSFoundation.h:2340

◆ 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

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

KS_RF_SINCWIN_HAMMING

Definition: KSFoundation.h:2341

KS_RF_SINCWIN_OFF

Definition: KSFoundation.h:2341

KS_RF_SINCWIN_BARTLETT

Definition: KSFoundation.h:2341

KS_RF_SINCWIN_BLACKMAN

Definition: KSFoundation.h:2341

KS_RF_SINCWIN_HANNING

Definition: KSFoundation.h:2341

◆ 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 = 0,
   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_ENUM_SMS_PHASE_MOD;

◆ anonymous enum

anonymous enum

Enumerator
KS_SEQ_COLLECTION_ALLOWNEW
KS_SEQ_COLLECTION_LOCKED

2358 {KS_SEQ_COLLECTION_ALLOWNEW, KS_SEQ_COLLECTION_LOCKED};

KS_SEQ_COLLECTION_ALLOWNEW

Definition: KSFoundation.h:2358

KS_SEQ_COLLECTION_LOCKED

Definition: KSFoundation.h:2358

◆ ks_enum_grad_scaling_policy

enum ks_enum_grad_scaling_policy

Enumerator
KS_GRADWAVE_ABSOLUTE
KS_GRADWAVE_RELATIVE

2359 {KS_GRADWAVE_ABSOLUTE = 0, KS_GRADWAVE_RELATIVE = 1};

KS_GRADWAVE_ABSOLUTE

Definition: KSFoundation.h:2359

KS_GRADWAVE_RELATIVE

Definition: KSFoundation.h:2359

◆ ks_enum_crusher_strategy

enum ks_enum_crusher_strategy

Enumerator
KS_CRUSHER_STRATEGY_FASTEST
KS_CRUSHER_STRATEGY_EXACT
KS_CRUSHER_STRATEGY_MIN_SLEW
KS_CRUSHER_STRATEGY_MAX_AREA
KS_CRUSHER_STRATEGY_PLATEAU

              {
   KS_CRUSHER_STRATEGY_FASTEST = 0, /* Achieve area as fast as possible (batwing) */
   KS_CRUSHER_STRATEGY_EXACT, /* Add negative blip if necessary. Guarantees area */
   KS_CRUSHER_STRATEGY_MIN_SLEW, /* Prolong ramp */
   KS_CRUSHER_STRATEGY_MAX_AREA, /* Use entire min_duration to get max area */
   KS_CRUSHER_STRATEGY_PLATEAU /* Same as FASTEST but plateau amp = end amp */
 } ks_enum_crusher_strategy;

Function Documentation

◆ opuser_from_number()

_cvfloat* opuser_from_number ( _cvfloat * cv )

                                            {
   return cv;
 }

◆ isNaN()

int isNaN ( float a )

                    {
   return a != a;
 }

◆ ks_bitmask_set()

STATUS ks_bitmask_set	(	unsigned int	out,
		const unsigned int	in,
		const unsigned int	size,
		const unsigned int	offset
	)

Tool to set certain bits in an integer

                                                  {
 
   if (size + offset >= sizeof(unsigned int)) {
     return ks_error("%s: the sum of size (%d) and offset (%d) must be less than %d", __FUNCTION__, size, offset, sizeof(unsigned int));
   }
 
   /* we need to copy an amount of bits equal to size from the input  */
   const unsigned int mask_in = (1ULL << size) - 1ULL;
 
   /* shift the input mask */
   const unsigned int mask_out = mask_in << offset;
 
   out = ((in & mask_in) << offset) | (out & ~mask_out);
 
   return SUCCESS;
 
 } /* ks_bitmask_set() */

◆ ks_bitmask_get()

unsigned int ks_bitmask_get	(	const unsigned int	in,
		const unsigned int	size,
		const unsigned int	offset
	)

Tool to get certain bits in an integer

                                                        {
   if (size + offset >= sizeof(unsigned int)) {
     ks_error("%s: the sum of size (%d) and offset (%d) must be less than %d", __FUNCTION__, size, offset, sizeof(unsigned int));
     return 0;
   }
 
   const unsigned int mask_in = ((1ULL << size) - 1ULL) << offset;
 
   return (in & mask_in) >> offset;
 }

◆ ks_isIceHardware()

int ks_isIceHardware ( )

Function that returns 1 if it is an ICE realtime computer and 0 if not

                        {
 #if EPIC_RELEASE >= 27
   if (isIceHardware() == TRUE) {
     return TRUE;
   }
 #endif
 return FALSE;
 }

◆ ks_default_ssitime()

int ks_default_ssitime ( )

Function that returns the default SSI time (to be improved)

                          {
 
   if (ks_isIceHardware() == TRUE) {
     return KS_DEFAULT_SSI_TIME_ICE;
   }
 
   return KS_DEFAULT_SSI_TIME;
 /*
 #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_OTHERWISE 1500
 */
 
 }

◆ ks_peplan_distribute_shots()

KS_PEPLAN_SHOT_DISTRIBUTION ks_peplan_distribute_shots	(	const int	etl,
		const int	num_coords,
		const int	center
	)

ADDTITLEHERE

ADDDESCHERE

Parameters

[in]	etl	ADDTEXTHERE
[in]	num_coords	ADDTEXTHERE
[in]	center	ADDTEXTHERE

Return values

KS_PEPLAN_SHOT_DISTRIBUTION ADDTEXTHERE

                                                                                                               {
   KS_PEPLAN_SHOT_DISTRIBUTION shot_distribution;
 
   shot_distribution.shots = CEIL_DIV(num_coords, etl);
 
   const int num_echoes = shot_distribution.shots * etl;
   const int num_extra_per_train = FLOOR_DIV(num_echoes - num_coords, shot_distribution.shots);
 
   shot_distribution.encodes_per_shot = etl - num_extra_per_train;
 
   shot_distribution.readout_start = center == KS_NOTSET ? KS_NOTSET
                                                         : ks_readout_start_index(center, etl, shot_distribution.encodes_per_shot);
 
   const int second_blocks = shot_distribution.encodes_per_shot * shot_distribution.shots - num_coords;
   shot_distribution.first_blocks = shot_distribution.shots - second_blocks;
 
   return shot_distribution;
 }

◆ 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_rtscalelog()

void ks_init_rtscalelog ( KS_RT_SCALE_LOG *const rtscale )

Resets a KS_RT_SCALE_LOG instance

Parameters

[in,out] rtscale Pointer to a KS_RT_SCALE_LOG instance

Returns: void

                                                         {
   if (!rtscale) {return; }
 
   float *ampscales = rtscale->ampscales;
   int *states = rtscale->states;
   int num_instances = rtscale->num_instances;
 
   /* Use a temp object to be consistent with the default values */
   KS_RT_SCALE_LOG tmp_rtscale = KS_INIT_RT_SCALE_LOG;
   *rtscale = tmp_rtscale;
 
   rtscale->ampscales = ampscales;
   rtscale->states = states;
   rtscale->buffer_size = ampscales ? num_instances : 0;
   rtscale->buffer_size_states = states ? num_instances : 0;
 }

◆ 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_readwave()

void ks_init_readwave ( KS_READWAVE * readwave )

Resets a KS_READWAVE sequence object to its default value (KS_INIT_READWAVE)

Parameters

[out] readwave Pointer to KS_READWAVE

Returns: void

                                              {
   *readwave = (KS_READWAVE)KS_INIT_READWAVE;
 }

◆ 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_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

                                                    {
   *gradrfctrl = (KS_GRADRFCTRL)KS_INIT_GRADRFCTRL;
 }

◆ 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_echotrain()

void ks_init_echotrain ( KS_ECHOTRAIN *const echotrain )

Reinitialises an echotrain structure

Parameters

[in,out] echotrain pointer to the structure you want to initialise with (KS_INIT_ECHOTRAIN).

Returns: void

                                                        {
   *echotrain = (KS_ECHOTRAIN)KS_INIT_ECHOTRAIN;
   int readout;
   int state;
   for (state = 0; state < KS_READCONTROL_MAXSTATE; state++) {
     for (readout = 0; readout < KS_MAXUNIQUE_READ; readout++) {
       echotrain->controls[readout] = (KS_READCONTROL)KS_INIT_READ_CONTROL;
       echotrain->controls[readout].state[state] = (KS_READCONTROL_STATE)KS_INIT_READCONTROL_STATE;
     }
   }
 }

◆ 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__);
   }
 
   seqctrl->collection = seqcollection;
 
   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_rfscaling() and GEReq_eval_checkTR_SAR_calcs()", __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_hwlimits()

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_hwlimits()

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_hwlimits()

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_addwaittogradrfctrl()

STATUS ks_eval_addwaittogradrfctrl	(	KS_GRADRFCTRL *	gradrfctrl,
		KS_WAIT *	wait
	)

Internal use. Adds a wait pulse to the KS_GRADRFCTRL struct. Used for plotting

Parameters

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

Return values

STATUS SUCCESS or FAILURE

                                                                              {
   int i;
   if (wait == NULL) {
     return SUCCESS;
   }
 
   if (gradrfctrl == NULL) {
     return ks_error("%s: gradrfctrl is NULL", __FUNCTION__);
   }
 
   if (gradrfctrl->numwait >= KS_MAXUNIQUE_WAIT) {
     return ks_error("%s: ERROR - too many unique KS_WAIT in sequence (max %d)", __FUNCTION__, KS_MAXUNIQUE_WAIT);
   }
 
   /* check for previous registrations of this wait's memory address. If found, return */
   if (gradrfctrl->numwait > 0) {
     for (i = 0; i < gradrfctrl->numwait; i++) {
       if (gradrfctrl->waitptr[i] == wait)
         return SUCCESS;
     }
   }
 
   gradrfctrl->waitptr[gradrfctrl->numwait++] = wait;
 
   return SUCCESS;
 
 }

◆ ks_eval_wait()

STATUS ks_eval_wait	(	KS_WAIT *	wait,
		const char *const	desc,
		int	pg_duration,
		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]	pg_duration	ADDTEXTHERE
[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("%s: desc (2nd arg) cannot be NULL or begin with a space", __FUNCTION__);
   } else {
     strncpy(wait->description, desc, KS_DESCRIPTION_LENGTH - 1);
   }
 
 
   wait->max_duration = max_duration;
   wait->pg_duration = pg_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__);
   }
 
   ks_create_suffixed_description(tmpdesc, desc, "_isirotfun");
   status = ks_eval_wait(&isirot->waitfun, tmpdesc, RUP_GRD(KS_ISI_time), RUP_GRD(KS_ISI_time));
   KS_RAISE(status);
 
   ks_create_suffixed_description(tmpdesc, desc, "_isirotupdate");
   status = ks_eval_wait(&isirot->waitrot, tmpdesc, RUP_GRD(KS_ISI_rotupdatetime), RUP_GRD(KS_ISI_time));
   KS_RAISE(status);
 
   isirot->isinumber = isinumber;
   isirot->duration = isirot->waitfun.max_duration + isirot->waitrot.max_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) */
   STATUS status = ks_calc_filter(&read->filt, tsp, read->duration);
   KS_RAISE(status);
 
   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_dbg("%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_trap_rotation_invariant_75_max_slewrate()

STATUS ks_eval_trap_rotation_invariant_75_max_slewrate	(	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)

and the slewrate limited to 75 T/m/s to avoid unecessary PNS

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 the gradient amplitude limited to 1/sqrt(3) of the weakest amplifier (rotation invariant even if played on all boards simultanously). The slewrate is limited to 1/sqrt(3) of the weakest amplifier or 75 T/m/s to avoid unessesary PNS. This trapezoid setup is a good choice for not so timing sensitive situations (spoiler, SPGR phasers, ...)

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

                                                                                                {
   const float max_slewrate = 75.0/10000; /* 75 T/m/s converted to G/cm/us */
   return ks_eval_trap_constrained(trap, desc,
                                   ks_syslimits_ampmax_phys()/sqrt(3),
                                   FMin(3, ks_syslimits_slewrate_phys()/sqrt(3), ks_syslimits_slewrate(loggrd), max_slewrate),
                                   0);
 }

◆ ks_eval_crusher()

STATUS ks_eval_crusher	(	KS_WAVE *	crusher,
		const float	end_amp,
		const ks_crusher_constraints	crusher_constraints
	)

Sets up a KS_WAVE object that ramps from zero to the specified amplitude and ensures you obtain the minimum area.

The amplitude of the KS_WAVE object returned by this function has the same sign as the taget amplitude (end_amp).

Parameters

[out]	crusher	Pointer to the KS_WAVE object to be set up
[in]	end_amp	ADDTEXTHERE
[in]	crusher_constraints	ADDTEXTHERE

Return values

STATUS SUCCESS or FAILURE

                                                                                                                 {
 
   STATUS status;
 
   float G[6] = {0};
   float t[6] = {0}; 
   int num_points;
 
   const float amp_sign = end_amp >= 0 ? 1 : -1;
 
   switch(crusher_constraints.strategy) {
   case KS_CRUSHER_STRATEGY_EXACT:
     status = ks_calc_exact_transition(G, t, &num_points,
                                       amp_sign*crusher_constraints.area, amp_sign*end_amp,
                                       crusher_constraints.min_duration,
                                       crusher_constraints.slew, crusher_constraints.ampmax,
                                       crusher_constraints.min_plateau);
     break;
   case KS_CRUSHER_STRATEGY_MIN_SLEW:
     status = ks_calc_minslew_transition(G, t, &num_points,
                                         amp_sign*crusher_constraints.area, amp_sign*end_amp,
                                         crusher_constraints.min_duration,
                                         crusher_constraints.slew, crusher_constraints.ampmax,
                                         crusher_constraints.min_plateau);
     break;
   case KS_CRUSHER_STRATEGY_MAX_AREA:
     status = ks_calc_maxarea_transition(G, t, &num_points,
                                         amp_sign*crusher_constraints.area, amp_sign*end_amp,
                                         crusher_constraints.min_duration,
                                         crusher_constraints.slew, crusher_constraints.ampmax,
                                         crusher_constraints.min_plateau);
     break;
   case KS_CRUSHER_STRATEGY_PLATEAU:
     status = ks_calc_unconstrained_transition(G, t, &num_points,
                                               amp_sign*crusher_constraints.area, amp_sign*end_amp,
                                               crusher_constraints.slew, amp_sign*end_amp,
                                               crusher_constraints.min_plateau);
     break;
     default:
     status = ks_calc_unconstrained_transition(G, t, &num_points,
                                               amp_sign*crusher_constraints.area, amp_sign*end_amp,
                                               crusher_constraints.slew, crusher_constraints.ampmax,
                                               crusher_constraints.min_plateau);
   }
   KS_RAISE(status);
 
   /* Flip coordinates if the sign was negative */
   int i=0;
   for (; i<num_points; ++i) {
     G[i] *= amp_sign;
   }
 
   status = ks_eval_coords2wave(crusher, t, G, num_points, GRAD_UPDATE_TIME, "crusher");
   if (status != SUCCESS) {
     ks_dbg("strategy: %d", crusher_constraints.strategy);
     ks_dbg("area: %f", crusher_constraints.area);
     ks_dbg("end_amp: %f", end_amp);
     ks_dbg("min_duration: %d", crusher_constraints.min_duration);
     ks_dbg("min_plateau: %d", crusher_constraints.min_plateau);
     ks_dbg("slew: %f", crusher_constraints.slew);
     for (i=0; i<num_points; ++i) {
       ks_dbg("%f: %f", t[i], G[i]);
     }
   }
   KS_RAISE(status);
 
   return SUCCESS;
 }

◆ 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:

.fov: Desired image Field-of-View (FOV) in [mm] along the sequence board one intends to place the KS_READTRAP on (typically XGRAD)
.res: Number of pixels within the FOV
.acq.rbw: Receiver bandwidth (rBW) in [kHz/FOV]. Maximum is 250
.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.
.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
.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;
   STATUS status;
 
   /* 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_wave(&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 we need to ensure the XTR pulses of
        consecutive readouts don't overlap eg. EPI train */
     int min_acqdelay = (int)(XTRSETLNG + XTR_TAIL + 1) / 2;
     if (readtrap->acqdelay < min_acqdelay) {
       readtrap->acqdelay = min_acqdelay;
     }
     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;
 
     status =ks_eval_trap_constrained(&readtrap->grad, desc, ampmax_kspace_speedlimit, slewrate, 0);
     KS_RAISE(status);
 
 
     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;
   ks_create_suffixed_description(read_description, readtrap->grad.description, ".echo");
   status = ks_eval_read(&readtrap->acq, read_description);
   KS_RAISE(status);
 
   /* for rampsampling, create an omega waveform (for FOV shifts in the freq (read) direction for rampsampling) */
   if (readtrap->rampsampling) {
     float ramp_sample_period = readtrap->grad.ramptime - readtrap->acqdelay;
     float t[4] = {0.0f, ramp_sample_period, (float)readtrap->acq.duration - ramp_sample_period, (float)readtrap->acq.duration};
     float start_amp = readtrap->grad.amp / readtrap->grad.ramptime * readtrap->acqdelay; 
     float G[4] = {start_amp, readtrap->grad.amp, readtrap->grad.amp, start_amp};
     int k;
     /*ensure 150 mm fov offset is possible*/
     for (k = 0; k < 4; k++) G[k] *= GAM / 10.0; 
     KS_DESCRIPTION omega_description;
     ks_create_suffixed_description(omega_description, readtrap->grad.description, ".omega");
     STATUS status;
     status = ks_eval_coords2wave(&readtrap->omega, t, G, 4, GRAD_UPDATE_TIME, omega_description);
     KS_RAISE(status);
     readtrap->omega.fs_factor = 0.1; /* so 1 bit of iamp = 0.1 mm */
   } else {
     readtrap->omega.duration = 0;
   }
 
 
   return SUCCESS;
 } /* ks_eval_readtrap_constrained() */

◆ 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_readwave_constrained()

STATUS ks_eval_readwave_constrained	(	KS_READWAVE *	readwave,
		KS_WAVE *	acq_waves,
		const int	numstates,
		int	flag_symmetric_padding,
		ks_crusher_constraints	pre_crusher_constraints,
		ks_crusher_constraints	post_crusher_constraints
	)

Sets up an readwave acquisition window with the maximum sampling bandwidth.

The following members of the readwave object are treated as inputs to this function: fov - Desired image Field-of-View (FOV) in [mm] along the sequence board one intends to place the KS_READWAVE on (typically XGRAD) res - Number of pixels within the FOV 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.

Parameters

[in,out]	readwave	- Pointer to KS_READWAVE
[in]	acq_waves	- an array of KS_WAVE objects describing the gradient amplitude while the ADC is on.
[in]	numstates	- number of KS_WAVES in acq_waves
[in]	flag_symmetric_padding	- match pre and post areas and duration
[in]	pre_crusher_constraints	- how to optimise the pre crusher waveform shape (fastest, exact area, maximum area)
[in]	post_crusher_constraints	- how to optimise the post crusher waveform shape (fastest, exact area, maximum area)

Return values

STATUS SUCCESS or FAILURE

                                                                                      {
   STATUS status;
 
   typedef struct max {
     float amp;
     int index;
   } max;
 
   int i = 0;
   KS_WAVE *precrushers = (KS_WAVE*)alloca(numstates*sizeof(KS_WAVE));
   KS_WAVE *postcrushers = (KS_WAVE*)alloca(numstates*sizeof(KS_WAVE));
   int max_precrusher_res = 0;
   int max_postcrusher_res = 0;
 
   max acq_max = {0, -1};
   max acq_start_max = {0, -1};
   max acq_end_max = {0, -1};
 
   int acq_res = acq_waves[0].res;
   int acq_duration = acq_waves[0].duration;
 
   /* Programmer's error */
   if (acq_res <= 0) {
     return ks_error("%s (%s): invalid res (%d)", __FUNCTION__, acq_waves[i].description, acq_res);
   }
 
   if (readwave->fov < 10 || readwave->fov > 600) {
     return ks_error("%s (%s): field 'fov' must be in the range 10-600 mm", __FUNCTION__, acq_waves[i].description);
   }
   if (readwave->res % 2 || readwave->res <= 0 || readwave->res > 2048) {
     return ks_error("%s (%s): field 'res' must be even and in the range 2-2048", __FUNCTION__, acq_waves[i].description);
   }
   if (abs(readwave->nover) > readwave->res / 2) {
     return ks_error("%s (%s): field 'nover' may not exceed res/2", __FUNCTION__, acq_waves[i].description);
   }
 /*   if (abs(readwave->nover) % 2) {
     return ks_error("%s (%s): nover must be even (%d)", __FUNCTION__, acq_waves[i].description, abs(readwave->nover));
   } */
   if ( (acq_waves[i].duration / acq_waves[i].res) != GRAD_UPDATE_TIME) {
     return ks_error("%s: acq_waves[i] must have dwell = GRAD_UPDATE_TIME", __FUNCTION__);
   }
   int polarity[numstates];
   for (; i < numstates; i++) {
     polarity[i] = 1;
     if ( acq_waves[i].res != acq_res ) {
       return ks_error("%s: acq_waves[%d] does not match res of acq_waves[0] (%d != %d)", __FUNCTION__, i, acq_waves[i].res, acq_waves[0].res);
     }
     if (acq_waves[i].duration != acq_duration) {
       return ks_error("%s: acq_waves[%d] does not match duration of acq_waves[0] (%d != %d)", __FUNCTION__, i, acq_waves[i].duration, acq_waves[0].duration);
     }
     if (acq_waves[i].waveform[0] < 0 && acq_waves[i].waveform[acq_waves[i].res - 1] < 0) {
       /* Assume entire wave is negative. Negate the wave, continue, and re-negate the state later */
       polarity[i] = -1;
       ks_wave_multiplyval(&acq_waves[i], -1.0);
     } else if (acq_waves[i].waveform[acq_waves[i].res - 1] < 0 || acq_waves[i].waveform[0] < 0){
       return ks_error("%s: acq_waves[%d] changes polarity", __FUNCTION__, i);
     }
     if (acq_waves[i].abs_max_amp > acq_max.amp) {
        acq_max.amp = acq_waves[i].abs_max_amp;
        acq_max.index = i;
     }
 
     const float start_amp = 1.5f * acq_waves[i].waveform[0] - 0.5f * acq_waves[i].waveform[1];
     if (acq_start_max.amp < start_amp) {
       acq_start_max.amp = start_amp;
       acq_start_max.index = i;
     }
 
     const float end_amp = 1.5f * acq_waves[i].waveform[acq_waves[i].res - 1] - 0.5f * acq_waves[i].waveform[acq_waves[i].res - 2];
     if (acq_end_max.amp < end_amp) {
       acq_end_max.amp = end_amp;
       acq_end_max.index = i;
     }
   }
 
   /* Set ampmax and slew if no preference */
   for (i = 0; i < 2; i++) {
     ks_crusher_constraints* constraints = i == 0 ? &pre_crusher_constraints
                                                  : &post_crusher_constraints;
     constraints->ampmax = constraints->ampmax > 0 ? constraints->ampmax : ks_syslimits_ampmax(loggrd);
     constraints->slew = constraints->slew > 0 ? constraints->slew : ks_syslimits_slewrate(loggrd);
   }
 
   max grad_max = acq_max;
 
   KS_WAVE max_precrusher = KS_INIT_WAVE;
   KS_WAVE max_postcrusher = KS_INIT_WAVE;
   status = ks_eval_crusher(&max_precrusher, acq_start_max.amp, pre_crusher_constraints);
   KS_RAISE(status);
   status = ks_eval_crusher(&max_postcrusher, acq_end_max.amp, post_crusher_constraints);
   KS_RAISE(status);
 
   for (i=0; i < numstates; i++) {  
 
     const float start_amp = 1.5f * acq_waves[i].waveform[0] - 0.5f * acq_waves[i].waveform[1];
     const float end_amp = 1.5f * acq_waves[i].waveform[acq_waves[i].res - 1] - 0.5f * acq_waves[i].waveform[acq_waves[i].res - 2]; 
 
     const float max_crusher_area = fabs(max_precrusher.area) > fabs(max_postcrusher.area) ?
       max_precrusher.area : max_postcrusher.area;
 
     pre_crusher_constraints.area = flag_symmetric_padding ? max_crusher_area : max_precrusher.area;
     pre_crusher_constraints.strategy = KS_CRUSHER_STRATEGY_EXACT;
     status = ks_eval_crusher(&precrushers[i], start_amp, pre_crusher_constraints);
     KS_RAISE(status);
 
     post_crusher_constraints.area = flag_symmetric_padding ? max_crusher_area : max_postcrusher.area;
     post_crusher_constraints.strategy = KS_CRUSHER_STRATEGY_EXACT;
     status = ks_eval_crusher(&postcrushers[i], end_amp, post_crusher_constraints);
     KS_RAISE(status);
 
 
     if (precrushers[i].abs_max_amp > grad_max.amp) {
       grad_max.amp = precrushers[i].abs_max_amp;
       grad_max.index = i;
     }
     if (postcrushers[i].abs_max_amp > grad_max.amp) {
       grad_max.amp = precrushers[i].abs_max_amp;
       grad_max.index = i;
     }
 
     status = ks_eval_mirrorwave(&postcrushers[i]);
     KS_RAISE(status);
     max_precrusher_res = IMax(2, max_precrusher_res, precrushers[i].res);
     max_postcrusher_res = IMax(2, max_postcrusher_res, postcrushers[i].res);
   }
 
   /* zeropad crushers to make them equally long */
   float pad_array[KS_MAXWAVELEN/2] = {0};
   int res ;
   for (i=0; i < numstates; i++) {
     readwave->grad.p_waveformstates[i] = readwave->grad_states[i];
     readwave->omega.p_waveformstates[i] = readwave->omega_states[i];
     float* dest_grad = readwave->grad.p_waveformstates[i];
     float* dest_omega = readwave->omega.p_waveformstates[i];
     res = 0;
     int res_diff_pre = max_precrusher_res - precrushers[i].res;
     int res_diff_post = max_postcrusher_res - postcrushers[i].res;
 
     status = ks_eval_append_two_waveforms(dest_grad, pad_array, 0, res_diff_pre);
     KS_RAISE(status);
     res += res_diff_pre;
     status = ks_eval_append_two_waveforms(dest_grad, precrushers[i].waveform, res, precrushers[i].res);
     KS_RAISE(status);
     res += precrushers[i].res;
     status = ks_eval_append_two_waveforms(dest_grad, acq_waves[i].waveform, res, acq_res);
     KS_RAISE(status);
     res += acq_res;
 
     status = ks_eval_append_two_waveforms(dest_omega, acq_waves[i].waveform, 0, acq_res);
     KS_RAISE(status);
     ks_waveform_multiplyval(dest_omega, GAM / 10.0, acq_res); /* [Gauss / cm] -> [Hz / mm] */
 
     status = ks_eval_append_two_waveforms(dest_grad, postcrushers[i].waveform, res, postcrushers[i].res);
     KS_RAISE(status);
     res += postcrushers[i].res;
     status = ks_eval_append_two_waveforms(dest_grad, pad_array, res, res_diff_post);
     KS_RAISE(status);
     res += res_diff_post;
   }
 
   /* Eval the biggest wave (maxamp) in readwave->grad */
   /* copy the waveform */
   KS_DESCRIPTION description;
   memcpy(readwave->grad.waveform, readwave->grad.p_waveformstates[grad_max.index], sizeof(float) * res);
   ks_create_suffixed_description(description, acq_waves[grad_max.index].description, ".grad");
 
   strcpy(readwave->grad.description, description);
   readwave->grad.res = res;
   readwave->grad.duration = res * GRAD_UPDATE_TIME;
 
 
   ks_wave_compute_params(&readwave->grad);
 
 
   float sample_area2center;
   if (readwave->nover > 0) {
     /* nover > 0 results in early echo */
     sample_area2center = readwave->nover * ks_calc_fov2gradareapixel(readwave->fov);
   } else {
     sample_area2center = (readwave->res/2) * ks_calc_fov2gradareapixel(readwave->fov);
   }
   readwave->acqdelay = max_precrusher_res * GRAD_UPDATE_TIME;
   readwave->area2center = precrushers[acq_start_max.index].area + sample_area2center;
   readwave->time2center = ks_wave_time2area(&readwave->grad, readwave->area2center);
   if (readwave->time2center == KS_NOTSET) {
     return ks_error("%s: The read wave can't get to the center!",  __FUNCTION__);
   }
 
   ks_create_suffixed_description(description, acq_waves[acq_max.index].description, ".omega");
 
 
   memcpy(readwave->omega.waveform, readwave->omega.p_waveformstates[acq_max.index], sizeof(float) * res);
   strcpy(readwave->omega.description, description);
   readwave->omega.res = acq_res;
   readwave->omega.duration = acq_res * GRAD_UPDATE_TIME;
 
   ks_wave_compute_params(&readwave->omega);
 
   readwave->omega.fs_factor = 0.1; /* so 1 bit of iamp = 0.1 mm */
 
   readwave->acq.duration = acq_duration;
   if (readwave->acq.rbw <= 0.0) {
     const int sysmintsp = 2;
     float dwell = 1.0 / (GAM * acq_waves[acq_max.index].abs_max_amp * 1e-6) * (10.0 / readwave->fov);
     int tsp = (int) (dwell);
     tsp -= tsp % sysmintsp;
     for (; tsp >= sysmintsp; tsp -= sysmintsp) {
       if((acq_duration % (2 * tsp)) == 0) {
         break; /* duration must be even multiple of tsp */
       }
     }
     if (tsp < sysmintsp) {
       return ks_error("%s: readwave amplitude exceeds bw required to sample this fov", __FUNCTION__);
     }
     readwave->acq.rbw = ks_calc_tsp2bw(tsp);
   }
   ks_create_suffixed_description(description, acq_waves[0].description, ".readout");
   status = ks_eval_read(&readwave->acq, description);
   KS_RAISE(status);
 
   /* Setup the resampler parameters for the read object */
   readwave->acq.resampler.ndims = 1;
   readwave->acq.resampler.xwave = &readwave->grad;
   readwave->acq.resampler.wave_st_idx = readwave->acqdelay / GRAD_UPDATE_TIME;
   readwave->acq.resampler.target_res = readwave->nover ? readwave->res/2 + fabs(readwave->nover)
                                                        : readwave->res;
   readwave->acq.resampler.samples2center = (readwave->time2center - readwave->acqdelay) / readwave->acq.filt.tsp;
 
   /* Re-negate the negative states */
   for (i = 0; i < numstates; i++) {
     if (polarity[i] == -1) {
       ks_eval_readwave_negatestate(readwave, i);
     }
   }
 
   return SUCCESS;
 }

◆ ks_eval_readwave()

STATUS ks_eval_readwave	(	KS_READWAVE *	readwave,
		KS_WAVE *	acq_wave,
		float	pre_crusher_area,
		float	post_crusher_area,
		int	flag_symmetric_padding,
		ks_enum_crusher_strategy	pre_strategy,
		ks_enum_crusher_strategy	post_strategy
	)

A wrapper of ks_eval_readwave_constrained

Sets up a KS_READWAVE with one state and converts the crusher statergies into constraints

Parameters

[out]	readwave	- Pointer to an initialised KS_READWAVE object.
[in]	acq_wave	- Pointer to a KS_WAVE that defines the read gradient shape during the ADC sampling.
[in]	pre_crusher_area	- desired area before the readout starts
[in]	post_crusher_area	- desired area after the readout is complete
[in]	flag_symmetric_padding	- match pre and post areas
[in]	pre_strategy	- how to optimise the pre crusher waveform shape (fastest, exact area, maximum area)
[in]	post_strategy	- how to optimise the post crusher waveform shape (fastest, exact area, maximum area)

Return values

STATUS SUCCESS or FAILURE

                                                                                                                                                                                                                               {
 
   ks_crusher_constraints pre_crusher_constraints = KS_INIT_CRUSHER_CONSTRAINT;
   pre_crusher_constraints.ampmax = ks_syslimits_ampmax(loggrd);
   pre_crusher_constraints.slew = ks_syslimits_slewrate(loggrd);
   pre_crusher_constraints.min_duration = 0;
   pre_crusher_constraints.area = pre_crusher_area;
   pre_crusher_constraints.strategy = pre_strategy;
   ks_crusher_constraints post_crusher_constraints = pre_crusher_constraints;
   post_crusher_constraints.area = post_crusher_area;
   post_crusher_constraints.strategy = post_strategy;
 
   return ks_eval_readwave_constrained(readwave, acq_wave, 1,
                                       flag_symmetric_padding,
                                       pre_crusher_constraints,
                                       post_crusher_constraints);
 }

◆ ks_eval_readwave_multistated()

STATUS ks_eval_readwave_multistated	(	KS_READWAVE *	readwave,
		KS_WAVE *	acq_waves,
		const int	num_waves,
		float	pre_crusher_area,
		float	post_crusher_area,
		int	flag_symmetric_padding,
		ks_enum_crusher_strategy	pre_strategy,
		ks_enum_crusher_strategy	post_strategy
	)

A wrapper of ks_eval_readwave_constrained

Converts the crusher statergies into constraints

Parameters

[out]	readwave	- Pointer to an initialised KS_READWAVE object.
[in]	acq_waves	- Pointer to a KS_WAVE that defines the read gradient shape during the ADC sampling.
[in]	num_waves	- Number of waves
[in]	pre_crusher_area	- desired area before the readout starts
[in]	post_crusher_area	- desired area after the readout is complete
[in]	flag_symmetric_padding	- match pre and post areas
[in]	pre_strategy	- how to optimise the pre crusher waveform shape (fastest, exact area, maximum area)
[in]	post_strategy	- how to optimise the post crusher waveform shape (fastest, exact area, maximum area)

Return values

STATUS SUCCESS or FAILURE

                                                                                                                                                                                                                                                                 {
   /* TODO: Remove ? */
   ks_crusher_constraints pre_crusher_constraints = KS_INIT_CRUSHER_CONSTRAINT;
   pre_crusher_constraints.ampmax = ks_syslimits_ampmax(loggrd);
   pre_crusher_constraints.slew = ks_syslimits_slewrate(loggrd);
   pre_crusher_constraints.min_duration = 0;
   pre_crusher_constraints.area = pre_crusher_area;
   pre_crusher_constraints.strategy = pre_strategy;
   ks_crusher_constraints post_crusher_constraints = pre_crusher_constraints;
   post_crusher_constraints.area = post_crusher_area;
   post_crusher_constraints.strategy = post_strategy;
 
   return ks_eval_readwave_constrained(readwave, acq_waves, numstates,
                                       flag_symmetric_padding,
                                       pre_crusher_constraints,
                                       post_crusher_constraints);
 }

◆ 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	partial_ky,
		int	minkynover
	)

                                                                         {
   int kynover;
 
   if (partial_ky < 1) {
     kynover = yres * (partial_ky - 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

.numlinestoacq: Number of phase encoding lines to acquire
.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;
   }
 
 
   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_THROW("(%s): R cannot exceed %d", 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 */
   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);
       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);
       invalidnover = phaser->nover < phaser->R || phaser->nover > (phaser->res / 2);
     }
     phaser->nover *= sign_nover;
 
     if (invalidnover) {
       return KS_THROW("(%s): Valid #overscans not found with res=%d and nover=%d", desc, phaser->res, phaser->nover);
     }
 
   } else {
     /* full Fourier */
     if (phaser->shotresalign == TRUE) {
       int tmp_res = 0;
 
       tmp_res = RUP_FACTOR( phaser->res - phaser->R/2, phaser->R);
 
       if (tmp_res % 2 > 0) {
         phaser->res = RUP_FACTOR(phaser->res - phaser->R, 2 * phaser->R);
       } else {
         phaser->res = tmp_res;
       }
     } else {
       phaser->res = RUP_FACTOR(phaser->res, 2);
     }
 
   }
 
   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:

.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)
.res: The number of pixels within the FOV
.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
.R: The parallel imaging acceleration factor
.nacslines: If .R > 1, the value of .nacslines is the number of calibration lines around k-space center for parallel imaging calibration
.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

                                                                                  {
 
   STATUS status;
   float phasepixelarea;
 
   ks_init_trap(&phaser->grad);
 
   if (phaser->fov < 0.1 || phaser->fov > 2000.0) {
     return ks_error("%s(%s): field 'fov' (%g) must be in the range 0.1-2000 mm", __FUNCTION__, phasername, phaser->fov);
   }
 
   /* adjust res and possibly nover to allow both ARC and ASSET scans with full and partial ky Fourier */
   status = ks_eval_phaser_adjustres(phaser, phasername);
   KS_RAISE(status);
 
   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)) {
     status = ks_eval_trap_constrained(&phaser->grad, phasername, ampmax, slewrate, minduration);
     KS_RAISE(status);
   }
 
   /* 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,
		const int	res,
		const int	duration,
		const 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:

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())
THETA, the waveform needs to be scaled to units of [degrees]
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_THROW("wave name (2nd arg) cannot be NULL or leading space");
   }
 
   if (duration < 0 || res < 0) {
     return KS_THROW("%s: 'res' and 'duration' must be positive", desc);
   }
   if (res > KS_MAXWAVELEN) {
     return KS_THROW("%s: 'res' cannot exceed %d", wave->description, KS_MAXWAVELEN);
   }
   if (duration > 0 && (duration % res)) {
     return KS_THROW("%s: 'duration' (%d) [us] must be divisible by 'res' (%d)", desc, duration, res);
   }
   if (duration > 0 && (duration / res) < 2) {
     return KS_THROW("%s: 'duration' (%d) [us] must be at least 2x 'res' (%d)", desc, duration, res);
   }
   if ((waveform == wave->waveform) || (waveform == NULL) ) {
     return KS_THROW("%s: cannot eval a wave with its own or NULL waveform", desc);
   }
 
   /* reset wave object */
   ks_init_wave(wave);
 
   /* copy the waveform */
   memcpy(wave->waveform, waveform, sizeof(float) * res);
 
   /* fill in wave object */
   strcpy(wave->description, tmpdesc);
   wave->res = res;
   wave->duration = duration;
 
   ks_wave_compute_params(wave);
 
   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) 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_mirrorwaveform()

STATUS ks_eval_mirrorwaveform	(	KS_WAVEFORM	waveform,
		int	res
	)

Mirror in the res (time) domain a KS_WAVEFORM object

Parameters

[in]	waveform	pointer to an array of floats
[in]	res	the number of points in the wave shape you want to mirrow

Return values

STATUS SUCCESS or FAILURE

                                                              {
   KS_WAVEFORM tmpwave;
   int i;
 
   memcpy(tmpwave, waveform, sizeof(float) * res);
 
   for (i = 0; i < res; i++) {
     waveform[i] = tmpwave[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:

"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
"short": Plain short integer format. The data will be divided by a factor of MAX_PG_WAMP (32766) before copied to KS_WAVE
"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:

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())
THETA, the waveform needs to be scaled to units of [degrees]
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_THROW("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 */
   ks_create_suffixed_description(rf->rfwave.description, tmpdesc, ".wave");
 
   if (bw < 2 || bw > 100000) {
     return KS_THROW("%s: 'bw' (%g, 3rd arg) must be in range [2,100000] Hz", rf->rfwave.description, bw);
   }
   if (tbw < 2 || tbw > 100) {
     return KS_THROW("%s: 'tbw' (%g, 4th arg) must be in range [2,100]", rf->rfwave.description, tbw);
   }
   if (res > KS_MAXWAVELEN || res < 4) {
     return KS_THROW("%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_THROW("%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 */
   ks_create_suffixed_description(rf->rfwave.description, tmpdesc, ".wave");
 
   if (A0 < 0 || 0.25 < A0) {
     return KS_THROW("%s: 'A0' (%g, 3rd arg) must be in range [0,0.25] Gauss", rf->rfwave.description, A0);
   }
   if (tbw < 2 || 20 < tbw) {
     return KS_THROW("%s: 'tbw' (%g, 4th arg) must be in range [2,20]", rf->rfwave.description, tbw);
   }
   if (bw < 100 || 10000 < bw) {
     return KS_THROW("%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_THROW("%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_THROW("%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);
   KS_RAISE(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_THROW("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 */
   ks_create_suffixed_description(rf->rfwave.description, tmpdesc, ".wave");
 
   if (duration > KS_MAXWAVELEN * RF_UPDATE_TIME || duration < 4) {
     return KS_THROW("%s: 'duration' (3rd arg) must be in range [4, %d]", rf->rfwave.description, KS_MAXWAVELEN * RF_UPDATE_TIME);
   }
   if (duration % 2) {
     return KS_THROW("%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);
   KS_RAISE(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_THROW("%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,
		int	MTreduction
	)

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
[in]	MTreduction	[0=OFF,1=ON] reduces offresonace excitation and therefore MT effects

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_THROW("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 */
   ks_create_suffixed_description(rf->rfwave.description, tmpdesc, ".wave");
   sprintf(rf->designinfo, "%s", tmpdesc);
 
   if (offResExc < 0 || offResExc > 1) {
     return KS_THROW("%s: 'offResExc' (3rd arg) must be either 0 or 1", rf->rfwave.description);
   }
   if (nPulses < 2 || nPulses > 10) {
     return KS_THROW("%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 ntps[10];
   for (i = 0; i < nPulses; i++) {
     subArea[i] = (P[i] * pulseArea) / (pulseSum * 2.0 * PI * GAM); /* Gauss * sec */
     if (MTreduction) {
       ntps[i] = ceil(tau / dt); 
     } else {
       ntps[i] = ceil(subArea[i] / (maxB1 * dt)); /* number of time points in sub pulse */
       if (ntps[i] < 32 ) {
         ntps[i] = 32;
       }
     }
   }
 
   int ntp = 0;
   for (i = 0; i < nPulses; i++) {
     if (ntps[i]>ntp) {
       ntp = ntps[i];
     }
   }
 
   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 * 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; 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);
       if (MTreduction) {
         ntp_gap = 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);
   KS_RAISE(status);
 
   /* Put back the correct waveform */
   if (offResExc) {
     memcpy(rf->rfwave.waveform, saveWave, rf->rfwave.res * sizeof(float));
   }
 
   return SUCCESS;
 
 }

◆ ks_eval_mt_rf_binomial()

STATUS ks_eval_mt_rf_binomial	(	KS_RF *	rf,
		const char *const	desc,
		int	sub_pulse_dur,
		int	nPulses,
		int	prp
	)

Sets up a KS_RF object as a Binomial MT RF pulse

The major features of binomial-pulse-train frequency spectra are as follows: a series of sinc functions at frequency intervals of 1/PRP, whose width is inversely related to the overall pulse train duration (nPulses-1)*PRP, modulated by the single-binomial-pulse spectrum. Hence, the width of the sinc functions, or “spikes” in the frequency spectrum becomes narrower as the number of pulses is increased, and they become closer together as the pulse repetition period is increased.

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]	sub_pulse_dur
[in]	nPulses
[in]	prp

Return values

STATUS SUCCESS or FAILURE

                                                                                                            {
   KS_DESCRIPTION tmpdesc;
   int i, j, k;
 
   if (prp < sub_pulse_dur) {
     return ks_error("ks_eval_mt_rf_binomial: PRP(=%d) must be bigger than sub_pulse_dur(=%d)", prp, sub_pulse_dur);
   }
 
   double offsetFreq = 421.5420;
   if (cffield != 30000) {
     offsetFreq *= 0.5;
   }
 
   /* constraining the pulse repetition period to be greater or less than 1/(2 x chemical shift). */
   double nogo = 1.0/(2.0*offsetFreq)*1000000.0;
   if (areSameRelative(prp, nogo, 0.01)) {
     return ks_error("ks_eval_mt_rf_binomial: PRP(=%d) is too similar to %f (would cause artifacts)", prp, nogo);
   }
 
   /* Don't allow empty description or a description with leading space */
   if (desc == NULL || desc[0] == ' ') {
     return ks_error("ks_eval_mt_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);
   sprintf(rf->designinfo, "%s", tmpdesc);
 
   double dt = 2e-6; /* sec */
   float pulseArea = (float) 90.0 * 4.0 * (PI / 180.0); /* radians or Hz (depending on how you look at it) */
   double subArea = (pulseArea) / (4.0 * 2.0 * PI * GAM); /* Gauss * sec */
   int ntps = ceil(sub_pulse_dur/4/RF_UPDATE_TIME); /* number of time points in sub pulse */
   float maxB1 = subArea/(ntps * dt); /* Gauss */
 
   /* 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 */
   double currentSubArea = ntps * dt * maxB1; /* Gauss * sec */
   float amp = maxB1 * (subArea / currentSubArea); /* Gauss */
 
   int ntp_gap = ceil((prp/RF_UPDATE_TIME) - (float)ntps); 
 
   int idx = 0, sub_dir = 1, dir = 1;
   for (i = 0; i < nPulses; i++) {
 
      dir = pow(-1.0, (float)(i + nPulses/2 % 2));
 
     for (k = 0; k < 4; k++) { 
 
       if (k == 1 || k == 2) {
         sub_dir = -1;
       } else {
         sub_dir = 1;
       }
 
       /* Stitch on the sub pulse */
       for (j = 0; j < ntps; j++) {
         rf->rfwave.waveform[idx] = amp * sub_dir * dir;
         idx++;
       }
 
     }
     if ((nPulses > 1) && (i != nPulses-1)) {
       /* Stitch on the pause */
       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 = 90 + 180 + 90;
 
   /* 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));
   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 */
   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()

.rfwave: Must contain the RF pulse waveform. An error is return if either .thetawave or .omegawave are non-empty (complex RF pulses not allowed)
.bw: The bandwidth of the RF pulse [Hz]
.iso2end: Time from the magnetic center of the RF pulse to the end, in [us]
.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];
   ks_create_suffixed_description(description, rf->rfwave.description, "_stretched");
   status = ks_eval_rf(rf, description);
   KS_RAISE(status);
 
   status = ks_eval_rfstat(rf);
   KS_RAISE(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:

A ready KS_RF object, with a proper .rf.role (see below for details)
.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);
   KS_RAISE(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 [%f] not in range [0,600] mm", __FUNCTION__, desc, selrf->slthick);
   }
 
   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 violation (desired - %.2f [mm] min - %.2f [mm])", __FUNCTION__, desc, selrf->slthick, minthick);
   }
 
   /* If bridged crushers are wanted, add a constant gradwave as slice slelection */
   if (selrf->rf.role == KS_RF_ROLE_REF && selrf->bridge_crushers && selrf->gradwave.res == 0) {
     ks_init_wave(&selrf->gradwave);
     ks_eval_selwave(&selrf->gradwave, selname, selrf->slthick, selrf->rf.bw, selrf->rf.rfwave.duration); 
     KS_RAISE(status);
   }
 
   /* 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);
     }
     ks_create_suffixed_description(selrf->gradwave.description, selrf->rf.rfwave.description, ".gradwave");
   }
 
   /* Setup the gradients (trapezoid case) */
   ks_create_suffixed_description(selname, selrf->rf.rfwave.description, "_trap"); /* suffix '.x' is added automatically in ks_pg_wave(), where 'x' is the 1st letter of the board , ".trap"*/
 
 
   /* 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);
     KS_RAISE(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);
     }
 
     ks_wave_compute_params(&selrf->gradwave);
   }
 
 
   switch (selrf->rf.role) {
 
   /********************************************************************************/
   /*********************** RF SEL EXCITATION **************************************/
   /********************************************************************************/
   case KS_RF_ROLE_EXC: {
 
     int gradwave_ramp_duration = 0;
 
     ks_create_suffixed_description(postselname, selrf->rf.rfwave.description, ".reph");
     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;
 
       /* if gradwave starts at non-zeoro, add ramps */
       if (selrf->gradwave.waveform[0] > 0) {
 
         if (areSame(selrf->gradwave.waveform[selrf->gradwave.res - 1], 0)) {
           return ks_error("%s: exc-gradwave starts at non-zero and ends at zero",__FUNCTION__);
         }
 
         KS_WAVE ramp;
         status = ks_eval_ramp(&ramp, slewrate*0.99, selrf->gradwave.waveform[0], grad_dwell);
         KS_RAISE(status);
 
         /* Append ramp to slice selective gradwave (including some mirror gymnastics) */
         status = ks_eval_mirrorwave(&ramp);
         KS_RAISE(status);
 
         status = ks_eval_mirrorwave(&selrf->gradwave);
         KS_RAISE(status);
 
         status = ks_eval_append_two_waves(&selrf->gradwave, &ramp);
         KS_RAISE(status);
 
         status = ks_eval_mirrorwave(&selrf->gradwave);
         KS_RAISE(status);
 
         status = ks_eval_append_two_waves(&selrf->gradwave, &ramp);
         KS_RAISE(status);
 
         /* calculate usefull params */
         ks_wave_compute_params(&selrf->gradwave);
         gradwave_ramp_duration = ramp.duration;
       }
 
       /* 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;
       }
       isostart -= gradwave_ramp_duration / grad_dwell;
       for (i = isostart; i < selrf->gradwave.res; i++) {
         selrf->postgrad.area -= selrf->gradwave.waveform[i] * grad_dwell;
       }
     }
 
     /* add off-set area */
     selrf->postgrad.area += selrf->postgrad_area_offset;
 
     /* setup rephaser trapezoid */
     status = ks_eval_trap_constrained(&selrf->postgrad, postselname, ampmax, slewrate, 0);
     KS_RAISE(status);
 
     selrf->grad2rf_start = selrf->grad.ramptime + gradwave_ramp_duration;
     selrf->rf2grad_end = selrf->postgrad.duration + selrf->grad.ramptime + gradwave_ramp_duration;
 
     break;
   }
   /********************************************************************************/
   /*********************** RF SEL REFOCUSING **************************************/
   /********************************************************************************/
   case KS_RF_ROLE_REF: {
     float grad_area = (selrf->gradwave.res==0) ? selrf->grad.area : selrf->gradwave.area;
 
     /* area [(G/cm)*us], GAM [Hz/G], slthick [mm] */
     const float slthick = selrf->slthick > 0 ? selrf->slthick : 10; /* dafault to 10mm if not selective */
     float crusher_area;
     if (areSame(selrf->crusher_dephasing, -1.0)) { /* flowcomp z negative crushers using slicesel area */
       crusher_area = -grad_area; /* negative flowcomp z crushers */
     } else {
       crusher_area = 1e7 * selrf->crusher_dephasing / (GAM * slthick);
       crusher_area -= grad_area / 2.0;
       if (crusher_area < 0.0) {crusher_area = 0.0;}
     }
 
     float pregrad_area = crusher_area + selrf->pregrad_area_offset;
     float postgrad_area = crusher_area + selrf->postgrad_area_offset;
 
 
     if (selrf->gradwave.res==0) {
       /* KS_TRAP crushers (non-bridged) */
       selrf->pregrad.area = pregrad_area;
       selrf->postgrad.area = postgrad_area;
 
       ks_create_suffixed_description(preselname, selrf->rf.rfwave.description, ".LC");
       ks_create_suffixed_description(postselname, selrf->rf.rfwave.description, ".RC");
 
       status = ks_eval_trap_constrained(&selrf->pregrad,  preselname, ampmax, slewrate, 0);
       KS_RAISE(status);
       status = ks_eval_trap_constrained(&selrf->postgrad, postselname, ampmax, slewrate, 0);
       KS_RAISE(status);
 
       selrf->grad2rf_start = selrf->pregrad.duration + selrf->grad.ramptime;
       selrf->rf2grad_end = selrf->postgrad.duration + selrf->grad.ramptime;
 
     } else {
       /* KS_WAVE crushers (bridged) */
       ks_crusher_constraints crusher_constraints = KS_INIT_CRUSHER_CONSTRAINT;
       crusher_constraints.ampmax = ampmax;
       crusher_constraints.slew = slewrate;
       crusher_constraints.min_duration = 0;
       crusher_constraints.strategy = KS_CRUSHER_STRATEGY_EXACT;
       KS_WAVE precrusher;
       KS_WAVE postcrusher;
 
       const float start_amp = 1.5f * selrf->gradwave.waveform[0] - 0.5f * selrf->gradwave.waveform[1];
       crusher_constraints.area = pregrad_area;
       status = ks_eval_crusher(&precrusher,start_amp, crusher_constraints);
       KS_RAISE(status);
 
       const float end_amp = 1.5f * selrf->gradwave.waveform[selrf->gradwave.res - 1] - 0.5f * selrf->gradwave.waveform[selrf->gradwave.res - 2];
       crusher_constraints.area = postgrad_area;
       status = ks_eval_crusher(&postcrusher, end_amp, crusher_constraints);
       KS_RAISE(status);
 
       /* Append crushers to slice selective gradwave (including some mirror gymnastics) */
       status = ks_eval_mirrorwave(&selrf->gradwave);
       KS_RAISE(status);
 
       status = ks_eval_mirrorwave(&precrusher);
       KS_RAISE(status);
 
       status = ks_eval_append_two_waves(&selrf->gradwave, &precrusher);
       KS_RAISE(status);
 
       status = ks_eval_mirrorwave(&selrf->gradwave);
       KS_RAISE(status);
 
       status = ks_eval_mirrorwave(&postcrusher);
       KS_RAISE(status);
 
       status = ks_eval_append_two_waves(&selrf->gradwave, &postcrusher);
       KS_RAISE(status);
 
       /* calculate usefull params */
       ks_wave_compute_params(&selrf->gradwave);
       selrf->grad2rf_start = precrusher.duration;
       selrf->rf2grad_end = postcrusher.duration;
 
     }
 
     break;
   }
   /********************************************************************************/
   /*********************** RF SEL INVERSION ***************************************/
   /********************************************************************************/
   case KS_RF_ROLE_INV:
 
     if (selrf->gradwave.res!=0) {
       return ks_error("%s(%s): KS_RF_ROLE_INV does not support gradwaves yet.",__FUNCTION__,desc);
     }
 
     selrf->grad2rf_start = selrf->grad.ramptime;
     selrf->rf2grad_end = selrf->grad.ramptime;
 
     break;
   /********************************************************************************/
   /*********************** RF SPATIAL SATURATION **********************************/
   /********************************************************************************/
   case KS_RF_ROLE_SPSAT:
 
     if (selrf->gradwave.res!=0) {
       return ks_error("%s(%s): KS_RF_ROLE_SPSAT does not support gradwaves yet.",__FUNCTION__,desc);
     }
 
     selrf->grad2rf_start = selrf->grad.ramptime;
     selrf->rf2grad_end = selrf->grad.ramptime;
 
     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  */
 
     /* we use config variables because loggrd or physgrd may be derated for silent scanning purposes selrf waves are timing sensitive */
     extern float cfxfs, cfyfs, cfzfs;
     extern int cfrmp2xfs, cfrmp2yfs, cfrmp2zfs;
     float max_sys_slewrate = FMin(3, cfxfs, cfyfs, cfzfs)/IMax(3,cfrmp2xfs,cfrmp2yfs,cfrmp2zfs);
     float max_gradwave_slewrate = ks_wave_maxslew(&selrf->gradwave);
     if (max_gradwave_slewrate > 1.00001 * 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);
     }
 
   }
 
   if (selrf->rf.omegawave.res) {
     ks_wave_compute_params(&selrf->rf.omegawave);
     float grad_absmax;
     if (selrf->gradwave.res) {
       ks_wave_compute_params(&selrf->gradwave);
       grad_absmax = selrf->gradwave.abs_max_amp;
     } else if (selrf->grad.duration) {
       grad_absmax = fabs(selrf->grad.amp);
     } else {
       return ks_error("ks_eval_selrf(%s): no grads for the omega, this shouldn't be possible", desc);
     }
     ks_wave_multiplyval(&selrf->rf.omegawave, grad_absmax / selrf->rf.omegawave.abs_max_amp * GAM / 10.0);
     selrf->rf.omegawave.fs_factor = 0.1; /* so 1 bit of iamp = 0.1 mm */
   }
 
   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
	)

ADDTITLEHERE

ADDDESCHERE

Parameters

	FA_train	ADDTEXTHERE
	MZ_train	ADDTEXTHERE
[in]	N	ADDTEXTHERE
[in]	E1	ADDTEXTHERE
[in]	target_MT	ADDTEXTHERE
[in]	n	ADDTEXTHERE

Returns: void

                                                                                                                           {
   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
	)

ADDTITLEHERE

ADDDESCHERE

Parameters

	FA_train	ADDTEXTHERE
	MZ_train	ADDTEXTHERE
[in]	N	ADDTEXTHERE
[in]	E1	ADDTEXTHERE
[in]	MTlo	ADDTEXTHERE
[in]	MThi	ADDTEXTHERE
[in]	total_FA	ADDTEXTHERE

Returns: void

                                                                                                                                               {
   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
	)

ADDTITLEHERE

ADDDESCHERE

Parameters

[in]	N	ADDTEXTHERE
	FA_train	ADDTEXTHERE
	MZ_train	ADDTEXTHERE
[in]	total_FA	ADDTEXTHERE

Return values

STATUS ADDTEXTHERE

                                                                                        {
   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
	)

ADDTITLEHERE

ADDDESCHERE

Parameters

	FA_train	ADDTEXTHERE
[in]	N	ADDTEXTHERE
[in]	TR	ADDTEXTHERE
[in]	T1	ADDTEXTHERE
[in]	total_FA	ADDTEXTHERE

Return values

STATUS ADDTEXTHERE

                                                                                                    {
   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 ks_error("Ops");
   } 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;
   float sms_phase_modulation[16] = KS_INITZEROS(16);
   STATUS status;
 
   /* Debug stuff */
   int single_band_mode = -1; /* -1 = off */
   char fname[KS_DESCRIPTION_LENGTH + 64];
   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];
     snprintf(outputdir_uid, 250, "/usr/g/mrraw/kstmp/%010d/", rhkacq_uid);
     snprintf(cmd, 250, "mkdir -p %s > /dev/null", outputdir_uid);
     system(cmd);
 #endif
 
     snprintf(fname, KS_DESCRIPTION_LENGTH + 64, "%s%s_mb_rf_Real.txt", outputdir_uid, selrfMB->rf.rfwave.description);
     asciiWaveReal = fopen(fname,"w");
     snprintf(fname, KS_DESCRIPTION_LENGTH + 64, "%s%s_mb_rf_Imag.txt", outputdir_uid, selrfMB->rf.rfwave.description);
     asciiWaveImag = fopen(fname,"w");
     snprintf(fname, KS_DESCRIPTION_LENGTH + 64, "%s%s_mb_rfMB_Real.txt", outputdir_uid, selrfMB->rf.rfwave.description);
     asciiWaveRealMB = fopen(fname,"w");
     snprintf(fname, KS_DESCRIPTION_LENGTH + 64, "%s%s_mb_rfMB_Imag.txt", outputdir_uid, selrfMB->rf.rfwave.description);
     asciiWaveImagMB = fopen(fname,"w");
     snprintf(fname, KS_DESCRIPTION_LENGTH + 64, "%s%s_mod_rfMB_Real.txt", outputdir_uid, selrfMB->rf.rfwave.description);
     asciiWaveRealMod = fopen(fname,"w");
     snprintf(fname, KS_DESCRIPTION_LENGTH + 64, "%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) && (selrf->gradwave.res == 0)) {
     return ks_error("ks_eval_sms_make_multiband: Need a pre calculated gradient");
   }
 
   /* 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);
     KS_RAISE(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 and interpolate, since MB pulses require high res */
   int newRes = selrf->rf.rfwave.duration/RF_UPDATE_TIME;
   float *newGrid = (float*)alloca(newRes * sizeof(float));
   for (idx = 0; idx < newRes; idx++) {
       newGrid[idx] = (float) idx / (newRes-1);
   }
   KS_WAVEFORM sb_rf = KS_INIT_WAVEFORM;
   KS_WAVEFORM sb_th = KS_INIT_WAVEFORM;
   if (newRes/selrf->rf.rfwave.res > 1) {
     /* create index for interpolation */
     float *orgGrid = (float*)alloca(selrf->rf.rfwave.res * sizeof(float));
     for (idx = 0; idx < selrf->rf.rfwave.res; idx++) {
       orgGrid[idx] = (float) idx / (selrf->rf.rfwave.res-1);
     }
     /* perform linear interpolation */
     ks_eval_linear_interp1(orgGrid, selrf->rf.rfwave.res, selrf->rf.rfwave.waveform, newGrid, newRes, sb_rf);
     ks_eval_linear_interp1(orgGrid, selrf->rf.thetawave.res, selrf->rf.thetawave.waveform, newGrid, newRes, sb_th);
 
   } else {
     for (idx=0; idx < newRes; idx++) {
       sb_rf[idx] = selrf->rf.rfwave.waveform[idx]; 
       sb_th[idx] = selrf->rf.thetawave.waveform[idx];
     }
   }
 
   /* If gradwave is used calc modulation and offset to account for ramps and crushers */
   KS_WAVEFORM kt = KS_INIT_WAVEFORM;
   if (selrf->gradwave.res != 0) {
 
     /* Find slice selective grad in gradwave */
     int gradWaveOffset_start = 0, gradWaveOffset_end = 0;
     int grad_update_time = selrf->gradwave.duration/selrf->gradwave.res;
     int gradWaveRes = selrf->gradwave.res;
     if (selrf->bridge_crushers) {
       gradWaveOffset_start = selrf->grad2rf_start/grad_update_time;
       gradWaveOffset_end = selrf->gradwave.res - selrf->rf2grad_end/grad_update_time;
     } else {
       int ramp_dur = (selrf->gradwave.duration - selrf->rf.rfwave.duration)/2;
       gradWaveOffset_start = ramp_dur/grad_update_time;
       gradWaveOffset_end = selrf->gradwave.res - gradWaveOffset_start;
     }
     gradWaveRes = gradWaveOffset_end-gradWaveOffset_start;
     KS_WAVEFORM grad = KS_INIT_WAVEFORM;
     for (idx=0; idx < gradWaveRes; idx++) {
       grad[idx] = selrf->gradwave.waveform[gradWaveOffset_start + idx];
     }
 
     /* interpolate if needed */
     if (grad_update_time/RF_UPDATE_TIME > 1) {
       /* create index for interpolation */
       float *orgGrid = (float*)alloca(gradWaveRes * sizeof(float));
       for (idx = 0; idx < gradWaveRes; idx++) {
         orgGrid[idx] = (float) idx / (gradWaveRes-1);
       }
       /* perform linear interpolation */
       ks_eval_linear_interp1(orgGrid, gradWaveRes, grad, newGrid, newRes, grad);
     }
     if (debug) {sprintf(fname, "%s%s_mb_gradwave.txt", outputdir_uid, selrfMB->rf.rfwave.description); ks_print_waveform(grad, fname, newRes); }
 
     /* calc kt modulation */
     ks_eval_mirrorwaveform(grad, newRes);
     ks_waveform_cumsum(kt, grad, newRes);
 
     /* center the modualtion */
     float kt_max = ks_waveform_max(kt, newRes);
     for (idx=0; idx < newRes; idx++) {
       kt[idx] = kt[idx] - kt_max/2.0;
     }
   } else if (debug) {
     KS_WAVEFORM grad = KS_INIT_WAVEFORM;
     for (idx=0; idx < newRes; idx++) {
       grad[idx] = selrf->grad.amp;
     }
     sprintf(fname, "%s%s_mb_gradwave.txt", outputdir_uid, selrfMB->rf.rfwave.description); ks_print_waveform(grad, fname, newRes);
   }
 
   /* 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));  
   for (idx=0; idx < newRes; idx++) {
 
     double wave_real, wave_imag, sms_modulation_real = 0, sms_modulation_imag = 0, p, slice_offset, wave_grad = 0;
 
     /* Convert base pulse from polar to cartesian */
     wave_real = sb_rf[idx] * cos(sb_th[idx]*(PI/180.0));
     wave_imag = sb_rf[idx] * sin(sb_th[idx]*(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);
     }
 
     /* Grad */
     if (selrf->gradwave.res == 0) {
       double centeredIndex = idx - (newRes-1) * 0.5;
       wave_grad = selrf->grad.amp * centeredIndex;
     } else {
       wave_grad = kt[idx];
     }
 
     /* Calc sms modulation */
     for (jdx = 0; jdx < sms_multiband_factor; jdx++) {
 
       slice_offset = (sms_slice_gap / 10.0) * (1.0 + jdx - (sms_multiband_factor / 2.0) - 0.5);
       p = 2.0 * PI * GAM * slice_offset * wave_grad * 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);
     fclose(asciiWaveRealMod);
     fclose(asciiWaveImagMod);
     /*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);*/
   }
 
   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);
 
     }
   }
 
   /* 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); }
   if (debug && selrf->gradwave.res) {sprintf(fname, "%s%s_mb_grad.txt", outputdir_uid, selrfMB->rf.rfwave.description); ks_print_waveform(selrfMB->gradwave.waveform, fname, selrfMB->gradwave.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];
   ks_create_suffixed_description(description, selrfMB->rf.rfwave.description, "_sms");
   status = ks_eval_rf(&selrfMB->rf, description);
   KS_RAISE(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,
		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]	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 SMS factor (%d, 1st arg)", nslices, sms_multiband_factor);
   }
 
   /* gap between MB slices mm */
   gap = (float)((nslices + sms_multiband_factor - 1) / sms_multiband_factor) * (float)(slthick + slspace);
 
   return gap;
 
 } /* EOF */

◆ ks_eval_sms_calc_slice_gap_from_scan_info()

float ks_eval_sms_calc_slice_gap_from_scan_info	(	int	sms_multiband_factor,
		int	nslices,
		const SCAN_INFO *	org_slice_positions
	)

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

Parameters

[in]	sms_multiband_factor	The multi-band acceleration factor
[in]	nslices	Prescribed number of slices
[in]	org_slice_positions	Prescribed slice positions

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 SMS factor (%d, 1st arg)", nslices, sms_multiband_factor);
   }
 
   gap = fabs(org_slice_positions[nslices/sms_multiband_factor].optloc - org_slice_positions[0].optloc);
 
   return gap;
 }

◆ 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.0) || (caipi_fov_shift <= 1)) {
     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"); KS_RAISE(status);
   status = ks_eval_trap2wave(&gzBlipWave, &gzblip); KS_RAISE(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); KS_RAISE(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 */
   KS_DESCRIPTION description;
   ks_create_suffixed_description(description,                     selrfPINS->rf.rfwave.description, "_PINS");
   ks_create_suffixed_description(selrfPINS->gradwave.description, selrfPINS->rf.rfwave.description, "_PINS");
   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
	)

ADDTITLEHERE

ADDDESCHERE

Parameters

	selrfPINS	ADDTEXTHERE
	selrf	ADDTEXTHERE
[in]	sms_slice_gap	ADDTEXTHERE

Return values

STATUS ADDTEXTHERE

                                                                                                     {
   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"); KS_RAISE(status);
   status = ks_eval_trap2wave(&gzBlipWave, &gzblip); KS_RAISE(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); KS_RAISE(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 */
   KS_DESCRIPTION description;
   ks_create_suffixed_description(description,                     selrfPINS->rf.rfwave.description, "_PINSDANTE");
   ks_create_suffixed_description(selrfPINS->gradwave.description, selrfPINS->rf.rfwave.description, "_PINSDANTE");
   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);
   }
 
   ks_create_suffixed_description(wave->description, trap->description, "_wave");
 
   return SUCCESS;
 
 } /* EOF */

◆ ks_eval_coords2wave()

STATUS ks_eval_coords2wave	(	KS_WAVE *	wave,
		float *	t,
		float *	G,
		int	num_coords,
		int	dwell,
		const char *	desc
	)

                                                                                                            {
   int i, bin;
 
   if (num_coords < 2) {
     return KS_THROW("%s: At least two coords must be provided, not %d", desc, num_coords);
   }
   if (fabs(t[0]) > 0.0f) {
     return KS_THROW("%s: First coord must be t=0, not %f", desc, t[0]);
   }
 
   for (i = 1; i < num_coords; i++) {
     if (t[i] < t[i-1]) {
       return KS_THROW("%s: Coords must be in time order (%f < %f)", desc, t[i], t[i-1]);
     }
   }
 
   int duration = (int)(t[num_coords-1]);
   if ((duration % (dwell)) || (fabs(t[num_coords-1] - (float)(duration)) > 0)) {
     return KS_THROW("%s: Last coord must be a multiple of %d, not %f", desc, dwell, t[num_coords-1]);
   }
   int res = duration / dwell;
 
   KS_WAVEFORM waveform = KS_INIT_WAVEFORM;
 
   /* loop over line segments */
   for (i = 1; i < num_coords; i++) {
     if ((t[i] - t[i-1]) <= 0) {
       continue; /* empty segment */
     }
     float slope = (G[i] - G[i-1]) / (t[i] - t[i-1]);
     int startbin = (int) floor(t[i-1] / dwell);
     int endbin = (int) floor(t[i] / dwell);
 
     /* startbin */
     float dur = FMin(2, t[i], (float)((startbin+1) * dwell)) - t[i-1];
     waveform[startbin] += dur * (G[i-1] + dur * slope / 2.0) / dwell;
 
     /* middle bins */
     for (bin = startbin + 1; bin < endbin; bin++) {
       waveform[bin] = G[i-1] + (dwell * ((float)(bin) + 0.5) - t[i-1]) * slope;
     }
 
     /* endbin */
     if ((startbin != endbin) && (endbin < res)) {
       dur = t[i] - dwell * (float)(endbin);
       waveform[endbin] += dur * (G[i] - dur * slope / 2.0) / dwell;
     }
   }
 
   return ks_eval_wave(wave, desc, res, duration, waveform);
 }

◆ ks_eval_append_two_waves()

STATUS ks_eval_append_two_waves	(	KS_WAVE *	first_wave,
		KS_WAVE *	second_wave
	)

                                                                            {
   STATUS status;
   /* check inputs */
   if (first_wave->res > 0 && second_wave->res > 0 &&
       (first_wave->duration / first_wave->res) != (second_wave->duration / second_wave->res)) {
     return ks_error("%s: can't append waves with different dwell periods.", __FUNCTION__);
   }
 
   status = ks_eval_append_two_waveforms(first_wave->waveform, second_wave->waveform, first_wave->res, second_wave->res);
   KS_RAISE(status);
 
   /* fill in params */
   first_wave->res += second_wave->res;
   first_wave->duration += second_wave->duration;
   first_wave->area += second_wave->area;
   if (second_wave->max_amp > first_wave->max_amp) {
     first_wave->max_amp = second_wave->max_amp;
   }
   if (second_wave->abs_max_amp > first_wave->abs_max_amp) {
     first_wave->abs_max_amp = second_wave->abs_max_amp;
   }
   if (second_wave->abs_max_slew > first_wave->abs_max_slew) {
     first_wave->abs_max_slew = second_wave->abs_max_slew;
   }
   if (second_wave->min_amp < first_wave->min_amp) {
     first_wave->min_amp = second_wave->min_amp;
   }
 
   return SUCCESS;
 
 }

◆ ks_eval_append_two_waveforms()

STATUS ks_eval_append_two_waveforms	(	KS_WAVEFORM	first_waveform,
		KS_WAVEFORM	second_waveform,
		int	res1,
		int	res2
	)

                                                                                                                  {
   if ((res1 + res2) > KS_MAXWAVELEN) {
     return ks_error("%s: cannot append - the combined waveform exceeds KS_MAXWAVELEN.", __FUNCTION__);
   }
   memcpy( &(first_waveform[res1]), second_waveform, sizeof(float) * res2);
   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;
   STATUS status;
 
   for(idx = 0; idx < num_waves; idx++) {
     status = ks_eval_append_two_waves(target_wave, waves_to_append[idx]);
     KS_RAISE(status);
   }
 
   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:

.read.fov: The Field-of-View (FOV) in the frequency encoding (readout) direction
.read.res: The number of pixels within the FOV along the frequency encoding direction
.blipphaser.fov: The Field-of-View (FOV) in the phase encoding direction
.blipphaser.res: The number of pixels within the FOV along the phase encoding direction
.blipphaser.R: Either the number of EPI shots or the parallel imaging factor
.read.rampsampling: Whether rampsampling should be used (see KS_READTRAP). Value of 1 is recommended for EPI
.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

                                                                                                    {
 
   STATUS status;
   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 */
   epi->blipphaser.shotresalign = TRUE; /* make .res is divisible by 2*R in ks_eval_phaser_adjustres() */
   /* blip DE/REphaser (KS_PHASER) */
   sprintf(tmpstr, "%s.blipphaser", desc);
   status = ks_eval_phaser_constrained(&epi->blipphaser, tmpstr, ampmax_phasers, slewrate_phasers, 0);
   KS_RAISE(status);
 
   /************************** Step 3: z phaser ***************************/
   epi->blipphaser.shotresalign = FALSE; /* do not force .res to be divisible by 2*R in ks_eval_phaser_adjustres() */
   /* blip DE/REphaser (KS_PHASER) */
   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) {
     status = ks_eval_phaser_constrained(&epi->zphaser, tmpstr, ampmax_phasers, slewrate_phasers, 0);
     KS_RAISE(status);
   } 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);
 
   status = ks_eval_trap_constrained(&epi->blip, tmpstr, ampmax, slewrate, 0);
   KS_RAISE(status);
 
   /************************** Step 6: CAIPI-blips **************************/
   if (epi->etl > 1) {
     sprintf(tmpstr, "%s.caipiblip", desc);
     status = ks_eval_trap_constrained(&epi->caipiblip, tmpstr, ampmax, slewrate, 0);
     KS_RAISE(status);
   }
 
   /************************** Step 7: Read width and amp **************************/
 
   /* rampsampling (normal case): We don't want to acquire data during half the blips duration (straddling two readouts) */
   int half_max_blip_dur = IMax(2, epi->blip.duration, epi->caipiblip.duration) / 2;
   if (epi->read.rampsampling)
     epi->read.acqdelay = half_max_blip_dur;
 
   sprintf(tmpstr, "%s.read", desc);
   status = ks_eval_readtrap_constrained(&epi->read, tmpstr, ampmax, slewrate);
   KS_RAISE(status);
 
   if (!epi->read.rampsampling) {
     /* non-rampsampling (unusual case) */
     if (epi->read.grad.ramptime < half_max_blip_dur) {
       /* blip-duration limited: Prolong the read gradient ramps to fit the blip, reduce PNS and acoustic noise */
       epi->read.grad.ramptime = half_max_blip_dur;
       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;
     }
   }
 
   if (epi->epi_readout_mode == KS_EPI_FLYBACK) {
     sprintf(tmpstr, "%s.read_flyback", desc);
     epi->read_flyback.area = epi->read.grad.area;
     if (ks_eval_trap_constrained(&epi->read_flyback, desc, ampmax, slewrate, 0) == FAILURE){
       return FAILURE;
     };
   }
 
   /************************** Step 8: 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);
     status = ks_eval_trap_constrained(&epi->readphaser, tmpstr, ampmax_phasers, slewrate_phasers, 0);
     KS_RAISE(status);
   }
 
 
 
   /**************************** Step 9: 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

                                         {
   const int readfact = (epi->epi_readout_mode == KS_EPI_SPLITODDEVEN) ? 2 : 1;
 
   epi->duration = (epi->etl * readfact) * epi->read.grad.duration + \
                   ((epi->etl * readfact) - 1) * (epi->read_spacing + epi->read_flyback.duration) + \
                   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_flyback.duration + epi->read_spacing) * readfact * (epi->blipphaser.nover / epi->blipphaser.R)) - (epi->read_spacing + epi->read_flyback.duration) / 2;
   } else {
     epi->time2center = ((epi->read.grad.duration + epi->read_flyback.duration + epi->read_spacing) * readfact * (epi->etl / 2)) - (epi->read_spacing + epi->read_flyback.duration) / 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

                                                                                 {
 
   STATUS status;
   float ampmax, slewrate;
 
   status = ks_eval_epi_maxamp_slewrate(&ampmax, &slewrate, epi->read.res, quietnessfactor);
   KS_RAISE(status);
 
   return ks_eval_epi_constrained(epi, desc, ampmax, slewrate);
 
 } /* ks_eval_epi */

◆ ks_eval_echotrain()

STATUS ks_eval_echotrain ( KS_ECHOTRAIN *const echotrain )

Evaluates the echotrain design

Ensures the echotrain design is resonable and counts the number of unique KS_READTRAPS and KS_READWAVES used. The array of KS_READCONTROL controls[KS_MAXUNIQUE_READ] and eval'd KS_READWAVES/KS_READTRAPS are the inputs.

Parameters

[in,out] echotrain - A pointer to a KS_ECHOTRAIN structure

Return values

STATUS SUCCESS or FAILURE

                                                          {
   int readout = 0;
 
   echotrain->numtraps = -1;
   echotrain->numwaves = -1;
 
   int kspaces[KS_MAX_NUM_KSPACES];
   int kspace_encodes_per_shot[KS_MAX_NUM_KSPACES];
 
   int s;
   int i;
   echotrain->numstates = 0;
   for (s=0; s < KS_READCONTROL_MAXSTATE; s++){
     if (echotrain->controls[0].state[s].kspace_index == KS_NOTSET) {
       break;
     } else {
       echotrain->numstates++;
     }
   }
 
   for (s = 0; s < echotrain->numstates; s++) {
 
     echotrain->numkspaces[s] = 0;
     for (i = 0; i < KS_MAX_NUM_KSPACES; i++) {
       kspaces[i] = 0;
       kspace_encodes_per_shot[i] = 0;
     }
 
     for (readout = 0; readout < KS_MAXUNIQUE_READ; readout++) { /* readouts */
 
       /* We assume that the first readout with a uninitialized type marks the end of the array */
       if (echotrain->controls[readout].pg.read_type == KS_READ_NOTSET) {
         break;
       }
 
       KS_READCONTROL* control = &echotrain->controls[readout];
       KS_READ_TYPE type = control->pg.read_type;
       int object_index = control->pg.object_index;
       if (type == KS_READ_TRAP) {
         if (object_index > echotrain->numtraps) {
           echotrain->numtraps = object_index;
         }
       } else if (type == KS_READ_WAVE) {
         if (control->state[s].wave_state == KS_NOTSET) {
           return KS_THROW("Readout %d shot state %d has no wave_state. You probably forgot to set it", readout, s);
         }
         if (object_index > echotrain->numwaves) {
           echotrain->numwaves = object_index;
         }
         /*TODO if (echotrain->readwaves[object_index].grad.base.nstates != echotrain->numstates) {
           return ks_error("echotrain->readwaves[%i]: mismatch in wavestates [echotrain: %i != readwave: %i]", object_index, echotrain->numstates, echotrain->readwaves[object_index].grad.base.nstates);
         }*/
       }
 
       KS_READCONTROL_STATE * state = &control->state[s];
       /* Attempt finding kspace_index in the kspaces array */
       for(i = 0; i < echotrain->numkspaces[s]; i++) {
         if(kspaces[i] == state->kspace_index) {
           break;
         }
       }
       if (i == echotrain->numkspaces[s]) { 
         /* not found: append at the end */
         kspaces[i] = state->kspace_index;
         echotrain->numkspaces[s]++;
         if (echotrain->numkspaces[s] > KS_MAX_NUM_KSPACES) {
           return KS_THROW("Echotrain supports up to %d unique kspaces.", KS_MAX_NUM_KSPACES);
         }
       }
       /* increase the count of how many times each kspace_index occurs in the echotrain */
       kspace_encodes_per_shot[kspaces[i]]++;
 
     } /* readout loop */
 
   if (echotrain->numkspaces[s] > echotrain->numkspaces[0]) {
     return KS_THROW("ariable numkspaces per readstate not supported -- state[0] = %i : state[%i] = %i.", echotrain->numkspaces[0], s, echotrain->numkspaces[s]);
   }
   for (i = 0; i < echotrain->numkspaces[s]; i++) {
     if(kspace_encodes_per_shot[kspaces[i]] != kspace_encodes_per_shot[kspaces[0]]) {
       return KS_THROW("Variable encodes per shot for kspaces is not supported (%d != %d)", kspace_encodes_per_shot[kspaces[i]], kspace_encodes_per_shot[kspaces[0]]);
     }
   }
 
   } /* state loop */
 
   echotrain->numtraps++;
   echotrain->numwaves++;
   echotrain->numreadouts = readout;
 
   return SUCCESS;
 } /* ks_eval_echotrain */

◆ ks_echotrain_get_max_kspace_index()

int ks_echotrain_get_max_kspace_index ( KS_ECHOTRAIN * echotrain )

Retrieve the total number of echoes this echotrain will produce

Parameters

echotrain - A pointer to a KS_ECHOTRAIN structure that has been eval'ed

Return values

int	- The maximum kspace(echo) index.

                                                                {
   int readout;
   int kspace_index;
   int max_kspace_index = 0;
   int s;
   for(s = 0; s < echotrain->numstates; s++) {
     for(readout = 0; readout < echotrain->numreadouts; readout++) {
       kspace_index = echotrain->controls[readout].state[s].kspace_index;
       if (kspace_index > max_kspace_index) {
         max_kspace_index = kspace_index;
       }
     }
   }
   return max_kspace_index;
 } /* ks_echotrain_get_max_kspace_index() */

◆ ks_get_maxsize_finfo()

PSD_FILTER_GEN ks_get_maxsize_finfo ( PSD_FILTER_GEN my_psd_filter_spec[] )

Loops through all filter slots and returns the one that has the most time points (length)

Parameters

[in] my_psd_filter_spec - typically GE's global array of filters

Return values

PSD_FILTER_GEN - the filter with the maximum length

◆ ks_grad_heat_reset()

void ks_grad_heat_reset ( )

                           {
   grad_heat_handle.seqcollection_p = NULL;
   grad_heat_handle.play = NULL;
   grad_heat_handle.nargs = 0;
   grad_heat_handle.args = NULL;
 }

◆ ks_grad_heat_init()

void ks_grad_heat_init	(	KS_SEQ_COLLECTION *	seqcollection_p,
		STATUS()(const INT max_encode_mode, int nargs, void *args)	play,
		int	nargs,
		void **	args
	)

                                     {
   grad_heat_handle.seqcollection_p = seqcollection_p;
   grad_heat_handle.play = play;
   grad_heat_handle.nargs = nargs;
   grad_heat_handle.args = args;
 }

◆ ks_eval_rflimits()

int ks_eval_rflimits	(	KS_SAR *	sar,
		KS_SEQ_COLLECTION *	seqcollection
	)

Returns the time required to play out a certain number of sequence modules over some interval, honoring SAR and RF power constraints

This function uses one KS_SEQ_COLLECTION struct holding the RF 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_hwlimits() 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.

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

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)

                                                                     {
   extern int tmin;
   int old_tmin;
   int i, j, k;
   int rfindx = 0;
   int numuniquerf = 0;
   int nettime = 0;
   int newtime_rfamp = 0;
   int newtime_gradheat = 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;
 
   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++) {
     for (j = 0; j < seqcollection->seqctrlptr[i]->gradrf.numrf; j++) {
       numuniquerf += seqcollection->seqctrlptr[i]->gradrf.rfptr[j]->rfpulse.num;
     }
   }
 
   nettime = ks_eval_seqcollection_gettotalduration(seqcollection);
   if (nettime <= 0) {
     return nettime;
   }
 
   RF_PULSE *myrfpulse = (RF_PULSE*)alloca(numuniquerf * sizeof(RF_PULSE));
   float *myrfflip = (float*)alloca(numuniquerf * sizeof(float));
 
   for (i = 0; i < seqcollection->numseq; i++) {
 
     for (j = 0; j < seqcollection->seqctrlptr[i]->gradrf.numrf; j++) {
         ks_eval_rf_relink(seqcollection->seqctrlptr[i]->gradrf.rfptr[j]);
 
         /* Point to the current KS_RF (e.g. excitation, refocusing etc) */
         KS_RF *myrf = seqcollection->seqctrlptr[i]->gradrf.rfptr[j];
 
         for (k = 0; k < myrf->rfpulse.num; k++) { /* or myrf->rfpulse.num */
 
           /* Deep copy of RF_PULSE structure (incl pointers to KS_RF fields .flip and .amp etc) */
           myrfpulse[rfindx] = myrf->rfpulse;
 
           myrfflip[rfindx] = myrf->flip * fabs(myrf->rfwave.locs[k].ampscale);
 
           /* Update the rfpulse.act_fa pointers so that are unique to each instance. */
           myrfpulse[rfindx].act_fa = &(myrfflip[rfindx]);      
 
           /* Each RF pulse instance is unique within a module so the total number is equal to the number 
             of times this sequence module is played out in the time period considered. */
           myrfpulse[rfindx].num = seqcollection->seqctrlptr[i]->nseqinstances;
 
           rfindx++;
 
         } /* for each RF instance */
 
       } /* for each unique KS_RF */
 
   }
 
   /* 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 **********/
   /* tmin is used in minseqrfamp, this will fail if tmin is set to zero*/
   old_tmin = tmin;
   tmin = nettime;
   status = minseqrfamp(&newtime_rfamp, numuniquerf, myrfpulse, L_SCAN);
   tmin = old_tmin;
   ks_dbg("%s: minseqrfamp = %dus; nettime = %dus", __FUNCTION__, newtime_rfamp, nettime);
   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(3, nettime, 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 above */
   }
 
   /* return the maximum value (rounded up to nearest divisible by 8) */
   return RUP_GRD(newtime_allconstraints);
 
 } /* ks_eval_rflimits */

◆ ks_eval_gradlimits()

STATUS ks_eval_gradlimits	(	int *	newtime,
		KS_SEQ_COLLECTION *	seqcollection,
		const LOG_GRAD *	log_grad,
		STATUS()(const INT max_encode_mode, int nargs, void *args)	play,
		int	nargs,
		void **	args
	)

                                                   {
   STATUS s;
 
   if (!seqcollection) {
     return KS_THROW("NULL pointer to sequence collection");
   }
 
   /* Run the gradient heating model */
   ks_grad_heat_init(seqcollection, play, nargs, args);
 
   gradHeatMethod = TRUE;
   enforce_minseqseg = PSD_ON;
 
   if (seqcollection->numseq < 1 || seqcollection->numplayouts < 1) {
     return KS_THROW("No sequence entries to evaluate");
   }
 
   if (!seqcollection->seqctrlptr[0]) {
     return KS_THROW("NULL pointer to the first sequence entry");
   }
 
   /*ks_dbg("Running gradlimits on index %d", seqcollection->seqctrlptr[0]->handle.index);*/
 
   s = minseq(newtime,
              NULL, 0, NULL, 0, NULL, 0,
              log_grad, seqcollection->seqctrlptr[0]->handle.index,
              GRAD_UPDATE_TIME, 0 /* oldtime, unused */, 0, 0);
 
   /* revert to the old method for subsequent calls to minseq
      that are executed in prescan's entry points.
    */
   gradHeatMethod = FALSE;
   enforce_minseqseg = PSD_OFF;
 
   ks_grad_heat_reset();
 
   if (s != SUCCESS) {
     KS_THROW("minseq failed");
 #ifndef SIM
     /* Don't return if in WTools */
     return FAILURE;
 #endif
 
   }
 
   seqcollection->hwlimitsdone = 1;
 
   return SUCCESS;
 }

◆ ks_eval_hwlimits()

STATUS ks_eval_hwlimits	(	int *	newtime,
		KS_SEQ_COLLECTION *	seqcollection,
		const LOG_GRAD *	log_grad,
		STATUS()(const INT max_encode_mode, int nargs, void *args)	play,
		int	nargs,
		void **	args
	)

                                                 {
 
   STATUS s;
 
   s = ks_eval_gradlimits(newtime, seqcollection, log_grad, play, nargs, args);
   KS_RAISE(s);
 
   int newtime_rf;
 
   ks_eval_seqcollection_resetninst(seqcollection);
   play(AVERAGE_POWER, nargs, args);
   newtime_rf = ks_eval_rflimits(NULL, seqcollection);
   KS_RAISE(newtime_rf < 0 ? FAILURE : SUCCESS);
   *newtime = IMax(2, *newtime, newtime_rf);
 
   ks_eval_seqcollection_resetninst(seqcollection);
   play(MAXIMUM_POWER, nargs, args);
   newtime_rf = ks_eval_rflimits(NULL, seqcollection);
   KS_RAISE(newtime_rf < 0 ? FAILURE : SUCCESS);
   *newtime = IMax(2, *newtime, newtime_rf);
 
   return SUCCESS;
 }

◆ ks_eval_getduration()

s64 ks_eval_getduration	(	KS_SEQ_COLLECTION *	seqcollection,
		STATUS()(const INT max_encode_mode, int nargs, void *args)	play,
		int	nargs,
		void **	args
	)

                                                 {
   ks_eval_seqcollection_resetninst(seqcollection);
   play(AVERAGE_POWER, nargs, args);
   return ks_eval_seqcollection_gettotalduration(seqcollection);
 }

◆ ks_eval_mintr()

int ks_eval_mintr	(	int	nslices,
		KS_SEQ_COLLECTION *	seqcollection,
		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_hwlimits() 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:

nslices
nargs (number of extra arguments)
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);

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]	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_seqcollection_gettotalduration(seqcollection);
 
 } /* ks_eval_mintr() */

◆ ks_eval_maxslicespertr()

int ks_eval_maxslicespertr	(	int	TR,
		KS_SEQ_COLLECTION *	seqcollection,
		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]	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

                                                                                               {
   (void)seqcollection;
 
   int max_slquant1 = 0;
   int i, acqtime;
   for (i = 1; i < 1024; i++) {
 
     acqtime = play_loop(i, 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:

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
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.
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 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 (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, j;
    if (seqcollection != NULL) {
     for (i = 0; i < seqcollection->numseq; i++) {
 #ifndef IPG
       KS_SEQ_CONTROL *ctrl = seqcollection->seqctrlptr[i];
 
       if (!ctrl) { continue; }
 
       ctrl->nseqinstances = 0;
       for (j = 0; j < ctrl->gradrf.numrf; ++j) {
         ks_init_rtscalelog(&ctrl->gradrf.rfptr[j]->rfwave.rtscaling);
         ks_init_rtscalelog(&ctrl->gradrf.rfptr[j]->omegawave.rtscaling);
         ks_init_rtscalelog(&ctrl->gradrf.rfptr[j]->thetawave.rtscaling);
       }
       for (j = 0; j < ctrl->gradrf.numtrap; ++j) {
         ks_init_rtscalelog(&ctrl->gradrf.trapptr[j]->rtscaling);
       }
       for (j = 0; j < ctrl->gradrf.numwave; ++j) {
         ks_init_rtscalelog(&ctrl->gradrf.waveptr[j]->rtscaling);
       }
       for (j = 0; j < ctrl->gradrf.numwait; ++j) {
         ks_init_rtscalelog(&ctrl->gradrf.waitptr[j]->rtscaling);
       }
 #endif
     }
     for (i = 0; i < seqcollection->numplayouts; i++) {
       seqcollection->seqplayouts[i] = NULL;
     }
     seqcollection->numplayouts = 0;
   }
 }

◆ 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 = %u\n", seqcollection->seqctrlptr[i]->description, seqcollection->seqctrlptr[i]->nseqinstances, seqcollection->seqctrlptr[i]->duration,
       (unsigned int) (seqcollection->seqctrlptr[i]->nseqinstances * seqcollection->seqctrlptr[i]->duration));
   }
   fprintf(fp, "Sum of durations: %lld us\n", (s64)  (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()

s64 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_hwlimits() 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;
  s64 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 += (s64)seqcollection->seqctrlptr[i]->duration * (s64)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()

s64 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_hwlimits() 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;
  s64 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 += (s64)seqcollection->seqctrlptr[i]->min_duration * (s64)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_hwlimits() 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_hwlimits())

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_hwlimits()), 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_create_suffixed_description()

void ks_create_suffixed_description	(	char *const	out,
		const char *const	prefix,
		const char *	suffix,
			...
	)

◆ ks_read_header_pool()

void void ks_read_header_pool	(	int *	exam_number,
		int *	series_number,
		int *	run_number
	)

ADDTITLEHERE

ADDDESCHERE

Parameters

exam_number	ADDTEXTHERE
series_number	ADDTEXTHERE
run_number	ADDTEXTHERE

Returns: void

◆ ks_rt_scale_log_get()

float ks_rt_scale_log_get	(	const KS_RT_SCALE_LOG *	log,
		int	instance_idx,
		int	playout_idx
	)

                                                                                          {
 
   if (instance_idx < 0 || instance_idx >=log->num_instances || !log->ampscales) {
     return 1.0f;
   }
   if (playout_idx >=log->num_completed_playouts) {
     KS_THROW("playout number (%d) must be less than %d", playout_idx, log->num_completed_playouts);
     return 1.0f;
   }
 
   /* negative -> last */
   if (playout_idx < 0) {
     playout_idx = log->num_completed_playouts - 1;
   }
 
   const float ampscale = log->ampscales[playout_idx*log->num_instances + instance_idx];
   const float absscale = fabs(ampscale);
 
   if (absscale <= 0 || (absscale <= sqrt(3) && absscale > 1.0f/(1 << 15))) {
     return ampscale;
   }
 
   /* If it is too big, too small (but non zero) or NaN we should end up here.
      This check is necessary because entries might be left uninitialized if
      no scaling is applied during the relevant playout. */
   KS_THROW("abnormal amplitude scale (%f), maybe it was not set", ampscale);
   return 1.0f;
 }

◆ ks_rt_scale_log_get_state()

int ks_rt_scale_log_get_state	(	const KS_RT_SCALE_LOG *	log,
		int	instance_idx,
		int	playout_idx
	)

                                                                                              {
 
   if (instance_idx < 0 || instance_idx >=log->num_instances) {
     return 0;
   }
   if (playout_idx >=log->num_completed_playouts) {
     KS_THROW("playout number (%d) must be less than %d", playout_idx, log->num_completed_playouts);
     return 0;
   }
 
   /* negative -> last */
   if (playout_idx < 0) {
     playout_idx = log->num_completed_playouts - 1;
   }
 
   return log->states[playout_idx*log->num_instances + instance_idx];
 }

◆ ks_rt_scale_log_set()

void ks_rt_scale_log_set	(	KS_RT_SCALE_LOG *	log,
		int	instance_idx,
		float	ampscale
	)

                                                                                  {
 
   if (!log) {
     KS_THROW("null input");
     return;
   }
 
   if (log->num_completed_playouts > 0 && log->num_instances < 1) {
     KS_THROW("inconsistent state");
     return;
   }
 
   if (instance_idx < 0 || instance_idx >=log->num_instances) {
     KS_THROW("instance number (%d) out of range [0,%d]", instance_idx, log->num_instances);
     return;
   }
 
   const int prev_buffer_size = log->buffer_size;
   log->buffer_size = (log->num_completed_playouts + 1)*log->num_instances;
 
   float *p = (float*)realloc(log->ampscales, log->buffer_size*sizeof(float));
   if (!p) {
     KS_THROW("Reallocation failed");
     return;
   }
 
   log->ampscales = p;
   int i = prev_buffer_size;
   for (; i < log->buffer_size; i++) {
     /* Initialize to the last used ampscale for the same instance, if available */
     const int last_idx = i - log->num_instances;
     log->ampscales[i] = last_idx < 0 ? 1.0f : log->ampscales[last_idx];
   }
   log->ampscales[log->num_completed_playouts*log->num_instances + instance_idx] = ampscale;
 }

◆ ks_rt_scale_log_set_state()

void ks_rt_scale_log_set_state	(	KS_RT_SCALE_LOG *	log,
		int	instance_idx,
		int	state
	)

                                                                                   {
 
   if (!log) {
     KS_THROW("null input");
     return;
   }
 
   if (log->num_completed_playouts > 0 && log->num_instances < 1) {
     KS_THROW("inconsistent state");
     return;
   }
 
   if (instance_idx < 0 || instance_idx >=log->num_instances) {
     KS_THROW("instance number (%d) out of range [0,%d]", instance_idx, log->num_instances);
     return;
   }
 
   const int prev_buffer_size = log->buffer_size_states;
   log->buffer_size_states = (log->num_completed_playouts + 1) * log->num_instances;
 
   int* p = (int*)realloc(log->states, log->buffer_size_states * sizeof(int));
   if (!p) {
     KS_THROW("Reallocation failed");
     return;
   }
 
   log->states = p;
   int i = prev_buffer_size;
   for (; i < log->buffer_size_states; i++) {
     /* Initialize to the last used state for the same instance, if available */
     const int last_idx = i - log->num_instances;
     log->states[i] = last_idx < 0 ? 0 : log->states[last_idx];
   }
 
   log->states[log->num_completed_playouts * log->num_instances + instance_idx] = state;
 }

◆ ks_rt_scale_log_next()

void ks_rt_scale_log_next ( KS_RT_SCALE_LOG * log )

                                                 {
   if (!log) {
     KS_THROW("null input");
     return;
   }
 
   log->num_completed_playouts = IMax(2, log->num_completed_playouts + 1, 1);
 }

◆ 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 )

ADDTITLEHERE

ADDDESCHERE

Parameters

[in] rbw ADDTEXTHERE

Return values

float ADDTEXTHERE

                                    {
   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 )

ADDTITLEHERE

ADDDESCHERE

Parameters

[in] rbw ADDTEXTHERE

Return values

float ADDTEXTHERE

                                     {
   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

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]

                                                {
   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_phaseencoding_memorypool_init()

STATUS ks_phaseencoding_memorypool_init	(	KS_PHASEENCODING_COORD *	entries,
		uint64_t	size
	)

Internal use for correct migration of KS_PHASEENCODING_PLAN from HOST to TGT (IPG)

Parameters

[in]	entries	Pointer to KS_PHASEENCODING_COORD array with phase encoding coordinates
[in]	size	Size of memory pool

Returns: void

                                                                                          {
 #ifdef IPG
   _phaseencoding_coord_pool.size = size;
   _phaseencoding_coord_pool.entries = entries;
   _phaseencoding_coord_pool.is_cleared_on_tgt = 1;
 #else
   _phaseencoding_coord_pool.epoch++;
   _phaseencoding_coord_pool.size = size;
   _phaseencoding_coord_pool.entries = entries;
   _phaseencoding_coord_pool.used_size = 0;
 #endif
   return SUCCESS;
 }

◆ ks_init_dynamic()

void ks_init_dynamic ( KS_DYNAMIC_STATE * dynamic )

Initialise the dynamic structure

It is important to have dynamic in a known state at the start of any scan function.

Parameters

dynamic The current state of the scan (used by ksscan)

Returns: void

                                                 {
   KS_MAT4x4 physical;
   memcpy(physical, dynamic->Mphysical, sizeof(KS_MAT4x4));
   KS_DYNAMIC_STATE defdynamic = KS_INIT_DYNAMIC_STATE;
   *dynamic = defdynamic;
   memcpy(dynamic->Mphysical, physical, sizeof(KS_MAT4x4));
 }

◆ ks_phaseencoding_isvalid()

int ks_phaseencoding_isvalid ( const KS_PHASEENCODING_PLAN * phaseenc_plan_ptr )

ADDTITLEHERE

ADDDESCHERE

Parameters

phaseenc_plan_ptr ADDTEXTHERE

Return values

int	ADDTEXTHERE

                                                                              {
 
   const int valid_epoch =
 #ifndef IPG
     phaseenc_plan_ptr->epoch == _phaseencoding_coord_pool.epoch;
 #else
     1;
 #endif
 
   return (!phaseenc_plan_ptr &&
           phaseenc_plan_ptr->encodes_per_shot > 0 &&
           phaseenc_plan_ptr->num_shots > 0 &&
           valid_epoch);
 }

◆ ks_phaseencoding_get()

KS_PHASEENCODING_COORD ks_phaseencoding_get	(	const KS_PHASEENCODING_PLAN *	phaseenc_plan_ptr,
		int	encode,
		int	shot
	)

Get [ky,kz] coordinate from KS_PHASEENCODING_PLAN for given encode and shot

If the .ky and .kz values returned by this function is = KS_NOTSET (-1), it indicates that this encode/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]	encode	Phase encoding index in the sequence echo train in range `[0,encodes_per_shot-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 oktoget = (phaseenc_plan_ptr != NULL) && _phaseencoding_coord_pool.is_cleared_on_tgt;
 #else
   int oktoget = (phaseenc_plan_ptr != NULL) && phaseenc_plan_ptr->epoch == _phaseencoding_coord_pool.epoch;
 #endif
 
   if (!oktoget ||
       phaseenc_plan_ptr->encodes_per_shot == KS_NOTSET ||
       !(phaseenc_plan_ptr->entries_offset) ||
       shot >= phaseenc_plan_ptr->num_shots ||
       encode < 0 || encode >= phaseenc_plan_ptr->encodes_per_shot) {
 
     KS_PHASEENCODING_COORD fake_coords = KS_INIT_PHASEENCODING_COORD;
     return fake_coords;
   }
 
    const int shot_start_index = phaseenc_plan_ptr->entries_offset - 1 + phaseenc_plan_ptr->encodes_per_shot * shot;
 
   return _phaseencoding_coord_pool.entries[shot_start_index + encode];
 }

◆ ks_phaseencoding_get_shot()

KS_PHASEENCODING_SHOTCOORDS ks_phaseencoding_get_shot	(	const KS_PHASEENCODING_PLAN *	phaseenc_plan_ptr,
		int	shot
	)

ADDTITLEHERE

ADDDESCHERE

Parameters

	phaseenc_plan_ptr	ADDTEXTHERE
[in]	shot	ADDTEXTHERE

Return values

KS_PHASEENCODING_SHOTCOORDS ADDTEXTHERE

                                                                                                                 {
 
 #ifdef IPG
   int oktoget = (phaseenc_plan_ptr != NULL) && _phaseencoding_coord_pool.is_cleared_on_tgt;
 #else
   int oktoget = (phaseenc_plan_ptr != NULL) && phaseenc_plan_ptr->epoch == _phaseencoding_coord_pool.epoch;
 #endif
 
   if (!oktoget ||
       phaseenc_plan_ptr->encodes_per_shot == KS_NOTSET ||
       !(phaseenc_plan_ptr->entries_offset) ||
       shot < 0 ||
       shot >= phaseenc_plan_ptr->num_shots) {
 
     KS_PHASEENCODING_SHOTCOORDS fake_shot = KS_INIT_PHASEENCODING_SHOTCOORDS;
     return fake_shot;
   }
 
   const int shot_start_index = phaseenc_plan_ptr->entries_offset - 1 + phaseenc_plan_ptr->encodes_per_shot * shot;
 
   KS_PHASEENCODING_SHOTCOORDS shot_coords = {
     phaseenc_plan_ptr->encodes_per_shot,
     _phaseencoding_coord_pool.entries + shot_start_index
   };
   return shot_coords;
 }

◆ ks_repeat_peplan()

STATUS ks_repeat_peplan	(	KS_PHASEENCODING_PLAN *	peplan,
		const KS_PHASEENCODING_REPEAT_DESIGN *const	repeat
	)

ADDTITLEHERE

ADDDESCHERE

Parameters

peplan	ADDTEXTHERE
repeat	ADDTEXTHERE

Return values

STATUS ADDTEXTHERE

                                                                                                             {
   if (repeat->num_repeats < 2 || repeat->mode == NO_REPEAT) {
     return SUCCESS;
   }
 
   /* Figure out size of new plan */
   int new_encodes_per_shot = peplan->encodes_per_shot;
   int new_num_shots = peplan->num_shots;
   switch (repeat->mode) {
   case INTERLEAVED_LONGER_SHOTS:
   case SEQUENTIAL_LONGER_SHOTS: {
     new_encodes_per_shot *= repeat->num_repeats;
     break;
   }
   case INTERLEAVED_EXTRA_SHOTS:
   case SEQUENTIAL_EXTRA_SHOTS: {
     new_num_shots *= repeat->num_repeats;
     break;
   }
   default:
     return KS_THROW("Repeat mode (%d) not supported", (int)repeat->mode);
     break;
   }
 
   /* Allocate new plan */
   KS_PHASEENCODING_PLAN new_peplan = *peplan;
   new_peplan.encodes_per_shot = new_encodes_per_shot;
   new_peplan.num_shots = new_num_shots;
   STATUS status = ks_phaseencoding_alloc(&new_peplan, new_encodes_per_shot, new_num_shots);
   KS_RAISE(status);
 
   /* Copy according to mode */
   int shot, encode, rep;
   for (shot = 0; shot < peplan->num_shots; shot++) {
     for (encode = 0; encode < peplan->encodes_per_shot; encode++) {
       KS_PHASEENCODING_COORD coord = ks_phaseencoding_get(peplan, encode, shot);
 
       int encode_index = encode;
       int shot_index = shot;
       for (rep = 0; rep < repeat->num_repeats; rep++) {
         switch (repeat->mode) {
           case INTERLEAVED_LONGER_SHOTS: {
             encode_index = encode * repeat->num_repeats + rep;
             break;
           } case SEQUENTIAL_LONGER_SHOTS: {
             encode_index = encode + peplan->encodes_per_shot * rep;
             break;
           } case INTERLEAVED_EXTRA_SHOTS: {
             shot_index = shot * repeat->num_repeats + rep;
             break;
           } case SEQUENTIAL_EXTRA_SHOTS: {
             shot_index = shot + peplan->num_shots * rep;
             break;
           } default: {
             return KS_THROW("Repeat mode (%d) not implemented", (int)repeat->mode);
             break;
           }
         }
 
         ks_phaseencoding_set(&new_peplan, encode_index, shot_index, coord.ky, coord.kz);
       }
     }
   }
   *peplan = new_peplan;
   return SUCCESS;
 }

◆ ks_phaseencoding_set()

void ks_phaseencoding_set	(	KS_PHASEENCODING_PLAN *	phaseenc_plan_ptr,
		int	encode,
		int	shot,
		int	ky,
		int	kz
	)

Set [ky,kz] coordinate from KS_PHASEENCODING_PLAN for given encode and shot

If the .ky and .kz values passed to this function is = KS_NOTSET (-1), it indicates that this encode/shot combination should have zero phase encoding and should be ignored. However, ignored encode/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 encode/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]	encode	Phase encoding index in the sequence echo train in range `[0,encodes_per_shot-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 != NULL) && _phaseencoding_coord_pool.is_cleared_on_tgt;
 #else
   int oktoset = (phaseenc_plan_ptr != NULL) && phaseenc_plan_ptr->epoch == _phaseencoding_coord_pool.epoch;
 #endif
 
   if (!oktoset ||
       phaseenc_plan_ptr->encodes_per_shot == KS_NOTSET ||
       !(phaseenc_plan_ptr->entries_offset) ||
       shot >= phaseenc_plan_ptr->num_shots ||
       encode < 0 || encode >= phaseenc_plan_ptr->encodes_per_shot) {
     return;
   }
 
 
    const int shot_start_index = phaseenc_plan_ptr->entries_offset - 1 + phaseenc_plan_ptr->encodes_per_shot * shot;
 
    _phaseencoding_coord_pool.entries[shot_start_index + encode].ky = ky;
    _phaseencoding_coord_pool.entries[shot_start_index + encode].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, encode;
 #ifdef IPG
 #define PHASEENCODING_PLAN_FILENAME "ks_phaseencodingtable.tgt.txt"
 #else
 #define PHASEENCODING_PLAN_FILENAME "ks_phaseencodingtable.host.txt"
 #endif
 
 #ifdef PSD_HW
   FILE *fp = fopen("/usr/g/mrraw/" PHASEENCODING_PLAN_FILENAME, "w");
 #else
   FILE *fp = fopen("./" PHASEENCODING_PLAN_FILENAME, "w");
 #endif
 
   fprintf(fp, "numshots (vertical): %d, etl (horizontal): %d\n\n", phaseenc_plan_ptr->num_shots, phaseenc_plan_ptr->encodes_per_shot);
 
   if (phaseenc_plan_ptr->encodes_per_shot == KS_NOTSET) {
     fclose(fp);
     return; /* we haven't set it up yet */
   }
 
   for (shot = 0; shot < phaseenc_plan_ptr->num_shots; shot++) {
     for (encode = 0; encode < phaseenc_plan_ptr->encodes_per_shot; encode++) {
         coord = ks_phaseencoding_get(phaseenc_plan_ptr, encode, 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_alloc()

STATUS ks_phaseencoding_alloc	(	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

                                                                                                 {
   int i;
   if (_phaseencoding_coord_pool.size <= 0) {
     return KS_THROW("Phase encoding memory pool has not been allocated. Did you forget to call ks_phaseencoding_memorypool_init() ?");
   }
   if (!phaseenc_plan_ptr) {
     return ks_error("%s: phaseenc_plan_ptr is NULL", __FUNCTION__);
   }
 
   if (etl < 1 || num_shots < 1) {
     return KS_THROW("Both etl (%d) and num_shots (%d) needs to be positive", etl, num_shots);
   }
 
   const uint64_t size = etl * num_shots;
 
   if (_phaseencoding_coord_pool.used_size + size > _phaseencoding_coord_pool.size) {
     return KS_THROW("Memory pool full (size is %llu), adjust its size to be at least %llu entries"
                     " with ks_phaseencoding_memorypool_init()",
                     _phaseencoding_coord_pool.size,
                     _phaseencoding_coord_pool.used_size + size);
   }
 
   phaseenc_plan_ptr->entries_offset = _phaseencoding_coord_pool.used_size + 1;
   _phaseencoding_coord_pool.used_size += size;
 
   phaseenc_plan_ptr->encodes_per_shot = etl;
   phaseenc_plan_ptr->num_shots = num_shots;
   phaseenc_plan_ptr->epoch = _phaseencoding_coord_pool.epoch;
 
   for (i = 0; i < etl * num_shots; i++) {
     _phaseencoding_coord_pool.entries[phaseenc_plan_ptr->entries_offset - 1 + i].ky = KS_NOTSET;
     _phaseencoding_coord_pool.entries[phaseenc_plan_ptr->entries_offset - 1 + 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,
		int	encodes_per_shot
	)

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)
[in]	encodes_per_shot	How many readouts are acquired for each shot

Returns: void

                                                                                                                                                                         {
   int etl = encodes_per_shot;
   int num_shots;
   int shot, ky, kz;
   int encode;
   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_alloc(phaseenc_plan_ptr, etl, num_shots);
   KS_RAISE(status);
 
   shot = 0;
   if (zphaser != NULL) { /* 3D */
     for (kz = 0; kz < zphaser->numlinestoacq; kz++) {
       for (ky = 0; ky < phaser->numlinestoacq / encodes_per_shot; ky++) {
         for (encode = 0; encode < encodes_per_shot; encode++) {
           ks_phaseencoding_set(phaseenc_plan_ptr, encode, shot++, phaser->linetoacq[ky], zphaser->linetoacq[kz]);
         }
       }
     }
   } else { /* 2D */
     for (ky = 0; ky < phaser->numlinestoacq; ky++) {
       ks_phaseencoding_set(phaseenc_plan_ptr, 0, shot++, phaser->linetoacq[ky], KS_NOTSET);
     }
   }
 
   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, 1);
   }
 
 
   radius_ky = phaser->res/2.0;
   center_ky = phaser->res/2.0 - 0.5;
 
   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_alloc(phaseenc_plan_ptr, etl, inellipse);
       KS_RAISE(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_phaseencoding_generate_2d_singleshot_cal()

STATUS ks_phaseencoding_generate_2d_singleshot_cal	(	KS_PHASEENCODING_PLAN *	phaseenc_plan_ptr,
		int	yres
	)

ADDTITLEHERE

ADDDESCHERE

Parameters

[out]	phaseenc_plan_ptr	Pointer to KS_PHASEENCODING_PLAN
	yres	ADDTEXTHERE

Return values

STATUS SUCCESS or FAILURE

                                                                                                       {
   STATUS status;
   const int minimum_etl = 6;
 
   const int etl = phaseenc_plan_ptr->encodes_per_shot;
 
   if (etl < minimum_etl) {
     return ks_error("%s: etl must be >= %d", __FUNCTION__, minimum_etl);
   }
 
   /* allocate KS_PHASEENCODING_PLAN table (all entries will be initialized to KS_NOTSET) */
   status = ks_phaseencoding_alloc(phaseenc_plan_ptr, etl, 1);
   KS_RAISE(status);
 
   const int step = 1; /* Could be set to -1 too. We had logic to choose before. */
 
   const float ky_center_main = (yres-1)/2.0f;
   const float ky_center_cal = (etl-1)/2.0f;
   int i = 0;
   int ky = ky_center_main - step * ky_center_cal;
   if (ky < 0) {
     ky = 0;
   }
   for (; i < etl && i < yres; i++){
     ks_phaseencoding_set(phaseenc_plan_ptr, i, -1, ky, KS_NOTSET);
     ky += step;
   }
   /* In case yres < etl */
   for (i = yres; i < etl; i++){
     ks_phaseencoding_set(phaseenc_plan_ptr, i, -1, KS_NOTSET, KS_NOTSET);
   }
 
   return SUCCESS;
 }

◆ ks_comp_kcoord_r_t()

int ks_comp_kcoord_r_t	(	const void *	a,
		const void *	b
	)

ADDTITLEHERE

ADDDESCHERE

Parameters

a	ADDTEXTHERE
b	ADDTEXTHERE

Return values

int	ADDTEXTHERE

                                                      {
     KS_KCOORD* k_a =(KS_KCOORD*)a;
     KS_KCOORD* k_b =(KS_KCOORD*)b;
     if (k_a->r > k_b->r) {
       return 1;
     } else if (k_a->r < k_b->r) {
       return -1;
     }
 
     if (k_a->t > k_b->t) {
       return 1;
     } else if (k_a->t < k_b->t) {
       return -1;
     }
 
     return 0;
 }

◆ ks_comp_kcoord_z_y()

int ks_comp_kcoord_z_y	(	const void *	a,
		const void *	b
	)

ADDTITLEHERE

ADDDESCHERE

Parameters

a	ADDTEXTHERE
b	ADDTEXTHERE

Return values

int	ADDTEXTHERE

                                                      {
     KS_KCOORD* k_a =(KS_KCOORD*)a;
     KS_KCOORD* k_b =(KS_KCOORD*)b;
     if (k_a->z > k_b->z) {
       return 1;
     } else if (k_a->z < k_b->z) {
       return -1;
     }
 
     if (k_a->y > k_b->y) {
       return 1;
     } else if (k_a->y < k_b->y) {
       return -1;
     }
 
     return 0;
 }

◆ ks_comp_kcoord_y_z()

int ks_comp_kcoord_y_z	(	const void *	a,
		const void *	b
	)

ADDTITLEHERE

ADDDESCHERE

Parameters

a	ADDTEXTHERE
b	ADDTEXTHERE

Return values

int	ADDTEXTHERE

                                                      {
     KS_KCOORD* k_a =(KS_KCOORD*)a;
     KS_KCOORD* k_b =(KS_KCOORD*)b;
     if (k_a->y > k_b->y) {
       return 1;
     } else if (k_a->y < k_b->y) {
       return -1;
     }
 
     if (k_a->z > k_b->z) {
       return 1;
     } else if (k_a->z < k_b->z) {
       return -1;
     }
 
     return 0;
 }

◆ ks_comp_kview_r_t()

int ks_comp_kview_r_t	(	const void *	a,
		const void *	b
	)

ADDTITLEHERE

ADDDESCHERE

Parameters

a	ADDTEXTHERE
b	ADDTEXTHERE

Return values

int	ADDTEXTHERE

                                                     {
     KS_VIEW* k_a =(KS_VIEW*)a;
     KS_VIEW* k_b =(KS_VIEW*)b;
     if (k_a->coord->r > k_b->coord->r) {
       return 1;
     } else if (k_a->coord->r < k_b->coord->r) {
       return -1;
     }
 
     if (k_a->coord->t > k_b->coord->t) {
       return 1;
     } else if (k_a->coord->t < k_b->coord->t) {
       return -1;
     }
 
     return 0;
 }

◆ ks_comp_kview_y_z()

int ks_comp_kview_y_z	(	const void *	a,
		const void *	b
	)

ADDTITLEHERE

ADDDESCHERE

Parameters

a	ADDTEXTHERE
b	ADDTEXTHERE

Return values

int	ADDTEXTHERE

                                                     {
     KS_VIEW* k_a =(KS_VIEW*)a;
     KS_VIEW* k_b =(KS_VIEW*)b;
     if (k_a->coord->y > k_b->coord->y) {
       return 1;
     } else if (k_a->coord->y < k_b->coord->y) {
       return -1;
     }
 
     if (k_a->coord->z > k_b->coord->z) {
       return 1;
     } else if (k_a->coord->z < k_b->coord->z) {
       return -1;
     }
     return 0;
 }

◆ ks_comp_kview_e_t()

int ks_comp_kview_e_t	(	const void *	a,
		const void *	b
	)

ADDTITLEHERE

ADDDESCHERE

Parameters

a	ADDTEXTHERE
b	ADDTEXTHERE

Return values

int	ADDTEXTHERE

◆ ks_comp_kview_e_z()

int ks_comp_kview_e_z	(	const void *	a,
		const void *	b
	)

ADDTITLEHERE

ADDDESCHERE

Parameters

a	ADDTEXTHERE
b	ADDTEXTHERE

Return values

int	ADDTEXTHERE

◆ ks_cal_from_nacslines()

int ks_cal_from_nacslines	(	int	R,
		int	nacslines
	)

ADDTITLEHERE

ADDDESCHERE

Parameters

[in]	R	ADDTEXTHERE
[in]	nacslines	ADDTEXTHERE

Return values

int	ADDTEXTHERE

                                                 {
   if (R == 1) return nacslines;
   return nacslines + nacslines / (R - 1) + 1;
 }

◆ ks_get_ry_from_kcoords()

int ks_get_ry_from_kcoords	(	KS_KCOORD *	coord,
		const int	num_coords
	)

Checks all KCOORDS to find the largest gap in ky.

Parameters

[in]	coord	- Will be sorted
[in]	num_coords

Returns: int Largest gap (Ry)

◆ ks_get_rz_from_kcoords()

int ks_get_rz_from_kcoords	(	KS_KCOORD *	coord,
		const int	num_coords
	)

Checks all KCOORDS to find the largest gap in kz.

Parameters

[in]	coord	- Will be sorted
[in]	num_coords

Returns: int Largest gap (Rz)

◆ ks_get_matrix_from_kcoords()

void ks_get_matrix_from_kcoords	(	KS_KCOORD *	K,
		const int	num_coords,
		int *	y,
		int *	z
	)

Checks all KCOORDS to find the largest span in ky and/or kz.

Parameters

[in]	K	- Will be sorted
[in]	num_coords	- number of entries in K
[out]	y	- matrix size in y
[out]	z	- matrix size in z

                                                                                     {
   if (!K) {
     KS_THROW("K is NULL");
     return;
   }
 
   if (y == NULL && z == NULL) {
     KS_THROW("y and z cannot both be null");
     return;
   }
 
   if (y != NULL) {
     qsort(K, num_coords, sizeof(KS_KCOORD), &ks_comp_kcoord_dist_y_z);
     *y = K[num_coords - 1].y;
     if (*y > 0) {
       (*y)++;  /* Increment since coordinates are left-aligned */
     } else {
       *y = -(*y);
     }
     *y *= 2;
   }
 
   if (z != NULL) {
     qsort(K, num_coords, sizeof(KS_KCOORD), &ks_comp_kcoord_dist_z_y);
     *z = K[num_coords - 1].z;
     if (*z > 0) {
       (*z)++;
     } else {
       *z = -(*z);
     }
     *z *= 2;
   }
 
   ks_dbg("Matrix [Y, Z] = [%d, %d]", y == NULL ? 0 : *y, z == NULL ? 0 : *z);
   return;
 }

◆ ks_generate_3d_coords_caipi()

STATUS ks_generate_3d_coords_caipi	(	KS_KSPACE_ACQ *	kacq,
		int	Ny,
		int	Nz,
		int	nover_y,
		int	nover_z,
		int	Ry,
		int	Rz,
		int	cal_y,
		int	cal_z,
		KS_COVERAGE	cal_coverage,
		KS_COVERAGE	acq_coverage,
		int	dy,
		int	dz,
		int	step_y,
		int	step_z
	)

Generates Cartesian Coordinates with or without CAPIRINHA undersampling.

Parameters

[out]	kacq	KS_KSPACE_ACQ object to be populated with coords, num_coords, and matrix_size
[in]	Ny	Number of lines along ky (without acceleration)
[in]	Nz	Number of lines accross Nz (without acceleration).
[in]	nover_y	Number of lines beyond Ny/2 to acquire when using partial Fourier. If nover_y < 0 remove low ky. If nover_y > 0 remove high ky. If nover_y = 0 no Partial Fourier in y.
[in]	nover_z	Number of lines beyond Nz/2 to acquire when using partial Fourier. If nover_z < 0 remove low ky. If nover_z > 0 remove high ky. If nover_z = 0 no Partial Fourier in z.
[in]	Ry	Undersampling factor in y
[in]	Rz	Undersampling factor in z
[in]	cal_y	Width of calibration region in y
[in]	cal_z	Width of calibration region in z
[in]	cal_coverage	Calibration region coverage, (RECTANGULAR or ELLIPTICAL)
[in]	acq_coverage	Acquisition region coverage, (RECTANGULAR or ELLIPTICAL)
[in]	dy	(CAIPIRINHA) Amount of shifting of the y-coordinate between consecutive kz rows
[in]	dz	Not used
[in]	step_y	(CAIPIRINHA) Maximum y offset (N*dy) before it loops back to 0
[in]	step_z	Not used

Return values

STATUS SUCCESS or FAILURE

                                                            {
 (void)(dz);
 (void)(step_z);
 if (Nz == KS_NOTSET) {
   Nz = 1;
 }
 
 
 
 
 KS_PF_EARLYLATE pf_ymode = KS_PF_NO;
 KS_PF_EARLYLATE pf_zmode = KS_PF_NO;
 
 if (nover_y < 0) {
   pf_ymode = KS_PF_EARLY; /* Remove low ky */
 } else if (nover_y > 0) {
   pf_ymode = KS_PF_LATE; /* Remove high ky */
 }
 
 
 
 
 if (nover_z < 0) {
   pf_zmode = KS_PF_EARLY; /* Remove low kz */
 } else if (nover_z > 0) {
   pf_zmode = KS_PF_LATE; /* Remove high kz */
 }
 
 
 
 
 nover_y = abs(nover_y);
 nover_z = abs(nover_z);
 
 if (Nz == 1) {
   pf_zmode = KS_PF_NO;
   cal_coverage = RECTANGULAR;
   acq_coverage = RECTANGULAR;
   cal_z = 1;
   dy = 0;
   Rz = 1;
 }
 
 
 
 
 KS_KCOORD* K = (KS_KCOORD*)realloc(kacq->coords, (Nz*Ny/(Ry*Rz) + 2*cal_y*cal_z) * sizeof(KS_KCOORD));
 if (!K) {
   return KS_THROW("Failed reallocation");
 }
 
 
 
 
 kacq->coords = K;
 kacq->num_coords = 0;
 
 int y = 0;
 int z = 0;
 int row, col;
 int offset = 0;
 int entry = 0;
 
 float ky_center = (Ny - 1) / 2.0;
 float kz_center = (Nz - 1) / 2.0;
 
 /* Generate acq coordinates honoring acceleration. Cal region is excluded */
 cal_z = IMax(2, cal_z, 1);
 int y_cal_low = RDN_FACTOR((Ny - cal_y) / 2, Ry);
 int y_cal_hi = y_cal_low + cal_y;
 int z_cal_low = RDN_FACTOR((Nz - cal_z) / 2, Rz);
 int z_cal_hi = z_cal_low + cal_z;
 float y_max = (Ny-1)/2.0;
 float z_max = (Nz-1)/2.0;
 int skipped = 0;
 for (row = 0; row < Nz; row += Rz) { /* row/col maps to ky-kz plane */
     z = row;
 
     /* PF z */
     if ((pf_zmode == KS_PF_LATE  && z >= (Nz/2 + nover_z)) ||
         (pf_zmode == KS_PF_EARLY && z <  (Nz/2 - nover_z))) { continue; }
 
     for (col = 0; col < Ny; col += Ry) {
       y = col + offset;
       if ((pf_ymode == KS_PF_LATE  && y >= (Ny/2 + nover_y)) ||
           (pf_ymode == KS_PF_EARLY && y <  (Ny/2 - nover_y))) { continue; }
 
       if (y >= Ny) {
          continue;
       }
       float y1 = Ny > 1 ? (y - Ny/2 + .5) / y_max /* Normalized global coordinate [-1, 1] */
                         : 0;
       float z1 = Nz > 1 ? (z - Nz/2 + .5) / z_max /* Normalized global coordinate [-1, 1] */
                         : 0;
       KS_KCOORD c = {y - Ny/2,
                      z - Nz/2,
                      (float)sqrt(y1*y1 + z1*z1),
                      (float)atan2(z1, y1)
                      };
      if (acq_coverage == ELLIPTICAL && c.r > 1.0) {
        continue;
      }
      if (Ry > 1 || Rz > 1) {
        if (y >= y_cal_low &&
            y < y_cal_hi &&
            z >= z_cal_low &&
            z < z_cal_hi) {
           if (cal_coverage == RECTANGULAR) { 
             skipped++;
             continue;
           }
           /* Local coordinates (local as in cal region) */
           float l_y = ((float)y + .5 - ky_center ) / (cal_y / 2);
           float l_z = ((float)z + .5 - kz_center ) / (cal_z / 2);
           float l_r = l_y * l_y + l_z * l_z; /* Local, no need for sqrt here as it only checked against unity */
           if (l_r < 1.0) {
             skipped++;
             continue;
           }
         }
      }
     K[entry++] = c;
   }
     offset += dy;
     offset = offset % (step_y+1);
 
 }
 
 
 
 
 /* Fill cal region */
 if (Ry > 1 || Rz > 1) {
   for (y = y_cal_low; y < y_cal_hi; y++) {
     for (z = z_cal_low; z < z_cal_hi; z++) {
       if (z < 0 || z >= Nz || y < 0 || y >= Ny) {
         ks_error("%s: cal region is outside the accelerated region - (y,z) = (%d,%d)", __FUNCTION__, y, z);
         continue;
       }
       if (cal_coverage == ELLIPTICAL) { /* Local coordinates */
         float l_y = (float)(y + .5 - ky_center) / (cal_y / 2.0);
         float l_z = (float)(z + .5 - kz_center) / (cal_z / 2.0);
         float l_r = l_y * l_y + l_z * l_z; /* No need for sqrt here as it only checked against unity */
         if (l_r > 1.0) { /* Outside ellipse */
           continue;
         }
       }
       float y1 = Ny > 1 ? (y - Ny/2 + .5) / y_max /* Normalized global coordinate [-1, 1] */
                         : 0;
       float z1 = Nz > 1 ? (z - Nz/2 + .5) / z_max /* Normalized global coordinate [-1, 1] */
                         : 0;
       KS_KCOORD c = {y - Ny/2,
                      z - Nz/2,
                      (float)sqrt(y1*y1 + z1*z1),
                      (float)atan2(z1, y1)
                      };
 
       K[entry++] = c;
     }
   }
 }
 
 kacq->num_coords = entry;
 kacq->matrix_size[YGRAD] = Ny;
 kacq->matrix_size[ZGRAD] = Nz;
 return SUCCESS;
 }  /*ks_generate_3d_coords_caipi*/

◆ ks_generate_3d_coords_radial()

STATUS ks_generate_3d_coords_radial	(	KS_KSPACE_ACQ *	kacq,
		int	tiny_level,
		int	Ny,
		int	Nz,
		int	Ry,
		int	Rz,
		KS_RADIAL_SAMPLING_MODE	radial_mode,
		KS_RADIAL_SAMPLING_COVERAGE	radial_sampling_coverage
	)

Generates Radial Coordinates.

If radial_sampling_mode is CARTESIAN, this function will call ks_generate_3d_coords_simple(kacq, Ny, Nz, 0, 0, Ry, Rz, 0, 0, RECTANGULAR, RECTANGULAR);

For 2D radial, Nz<=1. For 3D Kooshball radial, radial_mode must be RADIAL_THROUGH_CENTER and Nz>1. For 3D Stack-of-stars radial, radial_mode must be RADIAL_SOS and Nz>1.

For golden angle sampling (tiny_level != 0), the angular increment between consecutive spokes are generated using the following formula for 2D and stack of stars (Wundrak et al. https://doi.org/10.1002/mrm.25831):

phi_step = 1.0 /(KS_GOLDEN_MEANS_1D+tiny_level-1)

...and for kooshball this formula is followed (Fyrdahl et al. https://doi.org/10.1007/s10334-020-00859-z):

phi_step = 1.0/(pow(KS_GOLDEN_MEANS_2D_2,-1) + tiny_level-1.0)

theta_step = phi_step/(1+KS_GOLDEN_MEANS_2D_1)

For SAMPLE_360 radial_sampling_coverage the spokes are generated on the half circle/sphere but every other spoke is inverted.

In kacq.coords the angles are stored as signed 16 bit integers that can be converted to floats in the range -180:180 degrees using KS_ANGLE_PER_INT_16_MAX_180

Parameters

[out]	kacq	KS_KSPACE_ACQ object to be populated with coords, num_coords, and matrix_size
[in]	tiny_level	Tiny level for golden angle radial sampling (0 means uniform sampling instead of golden angle).
[in]	Ny	Number of lines along ky (without acceleration)
[in]	Nz	Number of lines accross Nz (without acceleration).
[in]	Ry	Undersampling factor in coordinate 1 (phi)
[in]	Rz	Undersampling factor in coordinte 2 (kz or theta)
[in]	radial_mode	Sampling mode (Cartesian, radial through center, or stack-of-stars)
[in]	radial_sampling_coverage	Whether the spokes should originate from a half circle/sphere or full circel/sphere

Return values

STATUS SUCCESS or FAILURE

                                                                                            {
 
 int entry = 0;
 double phi = 0;
 double phi_step;
 double delta_phi;
 double theta = 0;
 double theta_step;
 double xx, yy, zz;
 int kz = 0;
 int spoke = 0;
 
 /* Cartesian */
 if(radial_mode == CARTESIAN){ 
   return ks_generate_3d_coords_simple(kacq, Ny, Nz, 0, 0, Ry, Rz, 0, 0,  RECTANGULAR, RECTANGULAR);
 }
 
 
 
 
 /* Through center (2d or kooshball) */
 else if(radial_mode == RADIAL_THROUGH_CENTER){ 
 
   kacq->num_coords = ceil(fabs(Ny * Nz * PI/2.0 / Ry / Rz)) ;
 
   KS_KCOORD* K = (KS_KCOORD*)realloc(kacq->coords, kacq->num_coords * sizeof(KS_KCOORD));
   if (!K) {
     return KS_THROW("Failed (re)allocation");
   }
   kacq->coords = K;
   for (entry = 0; entry < kacq->num_coords; entry++) {
 
     if(Nz<=1){ /* 2D radial */
       if(tiny_level==0){
         delta_phi = 180.0 / kacq->num_coords;
         phi = entry*delta_phi;
         theta = 0;
       }
       else{
         phi_step =  1.0 /(KS_GOLDEN_MEANS_1D+tiny_level-1);
         phi = 180.0 * (phi_step * entry - floor(phi_step * entry));
         theta = 0;
       }
       if (radial_sampling_coverage == SAMPLE_360 && entry%2){ /* cover full circle */
         phi = phi + 180;
       }
     }
     else{ /* Kooshball */
       if(tiny_level==0){
         zz = fabs((double)entry - (double) kacq->num_coords-1.0)/ (double) kacq->num_coords;
         xx = cos(pow( kacq->num_coords*PI,0.5)*asin(zz))*pow(1-pow(zz,2),0.5);
         yy = sin(pow( kacq->num_coords*PI,0.5)*asin(zz))*pow(1-pow(zz,2),0.5);
 
         theta = 90.0-(acos(zz) * 180.0 / PI);
         phi = ((yy > 0) - (yy < 0))*acos(xx/pow(pow(xx,2)+pow(yy,2),0.5))* 180.0 / PI;
 
       }
       else{
         phi_step = KS_GOLDEN_MEANS_2D_2;
         phi_step =  1.0/(pow(KS_GOLDEN_MEANS_2D_2,-1) + (double) tiny_level-1.0);
         phi = 360.0 * (phi_step * entry - floor(phi_step * entry));
         theta_step = phi_step/(1+KS_GOLDEN_MEANS_2D_1);
         theta = asin(theta_step * entry - floor(theta_step * entry)) * 180.0 / PI ;
       }
       if (radial_sampling_coverage == SAMPLE_360 && entry%2){ /* cover full sphere */
         theta = theta + 180;
       }
     }
 
     KS_KCOORD c = {(s16) (phi/KS_ANGLE_PER_INT_16_MAX_180),
                    (s16) (theta/KS_ANGLE_PER_INT_16_MAX_180),
                    (float) entry,
                    (float) entry};
     K[entry]= c;
   }
 }
 
 
 
 
 /* Stack of stars */
 else if(radial_mode == RADIAL_SOS){ 
 
   kacq->num_coords = ceil(Ny * PI/2.0 / Ry / Rz)* Nz ;
 
   KS_KCOORD* K = (KS_KCOORD*)realloc(kacq->coords, kacq->num_coords * sizeof(KS_KCOORD));
   if (!K) {
     return KS_THROW("Failed (re)allocation");
   }
   kacq->coords = K;
   for (entry = 0; entry < kacq->num_coords; entry++) {
     if(tiny_level==0){
       delta_phi = 180.0 / ceil(Ny * PI/2.0 / Ry / Rz);
       phi = spoke*delta_phi;
     }
     else{
       phi_step =  1.0 /(KS_GOLDEN_MEANS_1D+tiny_level-1);
       phi = 180.0 * (phi_step * spoke - floor(phi_step * spoke));
     }
 
     if (radial_sampling_coverage == SAMPLE_360 && spoke%2){ /* cover full circle */
       phi = phi + 180;
     }
 
     KS_KCOORD c = {(s16) (phi/KS_ANGLE_PER_INT_16_MAX_180),
                    (s16) (kz - Nz/2),
                    (float) spoke,
                    (float) spoke};
     K[entry]= c;
 
     if(kz < Nz - 1){
       kz++;
     }
     else{
       kz = 0;
       spoke++;
     }
   }
 
 }
 
 else{
   return KS_THROW("Requested radial mode (%d) does not exist.", radial_mode);
 }
 
 kacq->matrix_size[YGRAD] = Ny;
 kacq->matrix_size[ZGRAD] = Nz;
 
 return SUCCESS;
 } /* ks_generate_3d_coords_radial */

◆ ks_generate_3d_coords_simple()

STATUS ks_generate_3d_coords_simple	(	KS_KSPACE_ACQ *	kacq,
		int	Ny,
		int	Nz,
		int	nover_y,
		int	nover_z,
		int	Ry,
		int	Rz,
		int	cal_y,
		int	cal_z,
		KS_COVERAGE	cal_coverage,
		KS_COVERAGE	acq_coverage
	)

Generates Cartesian Coordinates.

Calls ks_generate_3d_coords_caipi with the CAIPIRINHA variables, dy, dz, step_y, and step_z set to 0.

Parameters

[out]	kacq	KS_KSPACE_ACQ object to be populated with coords, num_coords, and matrix_size
[in]	Ny	Number of lines along ky (without acceleration)
[in]	Nz	Number of lines accross Nz (without acceleration).
[in]	nover_y	Number of lines beyond Ny/2 to acquire when using partial Fourier. If nover_y < 0 remove low ky. If nover_y > 0 remove high ky. If nover_y = 0 no Partial Fourier in y.
[in]	nover_z	Number of lines beyond Nz/2 to acquire when using partial Fourier. If nover_z < 0 remove low ky. If nover_z > 0 remove high ky. If nover_z = 0 no Partial Fourier in z.
[in]	Ry	Undersampling factor in y
[in]	Rz	Undersampling factor in z
[in]	cal_y	Width of calibration region in y
[in]	cal_z	Width of calibration region in z
[in]	cal_coverage	Calibration region coverage, (RECTANGULAR or ELLIPTICAL)
[in]	acq_coverage	Acquisition region coverage, (RECTANGULAR or ELLIPTICAL)

Return values

STATUS SUCCESS or FAILURE

                                                               {
   return ks_generate_3d_coords_caipi(kacq, Ny, Nz, nover_y, nover_z, Ry, Rz, cal_y, cal_z, cal_coverage, acq_coverage, 0, 0, 0, 0);
 }/* ks_generate_3d_coords_simple */

◆ ks_generate_2d_coords_cal()

STATUS ks_generate_2d_coords_cal	(	KS_KSPACE_ACQ *	kacq,
		int	num_desired_coords,
		int	yres
	)

ADDTITLEHERE

ADDDESCHERE

Return values

STATUS SUCCESS or FAILURE

                                                                                         {
   int max_y = RUP_FACTOR(num_desired_coords, 2);
 
   STATUS status;
 
   status = ks_generate_3d_coords_simple(kacq, max_y, KS_NOTSET, 0, 0, 1, 1, 0, 0, RECTANGULAR, RECTANGULAR);
   KS_RAISE(status);
 
   kacq->matrix_size[YGRAD] = yres;
   if (kacq->num_coords < num_desired_coords) {
     return KS_THROW("Could not generate enough cal coords (%d < %d)", kacq->num_coords, num_desired_coords);
   }
 
   /* Make sure we get the most central coordinates */
   qsort(kacq->coords, kacq->num_coords, sizeof(KS_KCOORD), &ks_comp_kcoord_dist_y_z);
 
   if (kacq->num_coords > num_desired_coords) {
     KS_THROW("kacq->num_coords > num_desired_coords (%d > %d). Expected if num_desired_coords is odd", kacq->num_coords, num_desired_coords);
     kacq->num_coords = num_desired_coords;
     KS_KCOORD* tmp = (KS_KCOORD*)realloc(kacq->coords, kacq->num_coords);
     if (tmp) {
       kacq->coords = tmp;
     } else {
       return KS_THROW("Reallocation failed");
     }
   }
   qsort(kacq->coords, kacq->num_coords, sizeof(KS_KCOORD), &ks_comp_kcoord_y_z);
   return SUCCESS;
 }

◆ ks_generate_3d_coords_poisson_disc()

STATUS ks_generate_3d_coords_poisson_disc	(	KS_KSPACE_ACQ *	kacq,
		int	Ny,
		int	Nz,
		float	min_spacing,
		float	max_spacing,
		KS_COVERAGE	cal_coverage,
		int	cal_y,
		int	cal_z,
		RADIUS_PATTERN	pattern
	)

ADDTITLEHERE

ADDDESCHERE

Return values

STATUS SUCCESS or FAILURE

                                                                  {
   const int num_attempts = 50;
   const float ky_center = (Ny - 1) / 2.0;
   const float kz_center = (Nz - 1) / 2.0;
   const float ky_radius = Ny / 2.0;
   const float kz_radius = Nz / 2.0;
   const int max_queue = Ny*Nz;
   int queue_size = 0;
   int y, z;
 
   KS_KCOORD* queue = (KS_KCOORD*)malloc(max_queue * sizeof(KS_KCOORD));
 
 
   KS_KCOORD* K = (KS_KCOORD*)realloc(kacq->coords, Nz*Ny * sizeof(KS_KCOORD)); /* Output */
   if (!K) {
     return KS_THROW("Failed reallocation");
   }
   kacq->coords = K;
   int* grid = (int*) calloc (Ny*Nz,sizeof(int)); /* Initialized to zero */
   int idx = 0;
   int num_coords = 0;
 
 
   int y_corners[4] = {0,    0, Ny-1, Ny-1};
   int z_corners[4] = {0, Nz-1, Nz-1,    0};
 
   for (idx = 0; idx < 4; idx++) {
     y = y_corners[idx];
     z = z_corners[idx];
     float y2 = (y + .5 - ky_center) / ky_radius;  /* Global coordinate */
     float z2 = (z + .5 - kz_center) / kz_radius;  /* Global coordinate */
     KS_KCOORD coord = {y, z, (float)sqrt((y2 * y2) + (z2 * z2)), (float)atan2(z2, y2)};
     queue[queue_size++] = coord;
     K[num_coords++] = coord;
     set_grid(grid, Nz, coord.y, coord.z);
   }
 
 
   /* Fully sampled region */
   int y_cal_low = (Ny - cal_y) / 2;
   int y_cal_hi = y_cal_low + cal_y;
   int z_cal_low = (Nz - cal_z) / 2;
   int z_cal_hi = z_cal_low + cal_z;
   for (y = y_cal_low; y < y_cal_hi; y++) {
     for (z = z_cal_low; z < z_cal_hi; z++) {
       if (cal_coverage == ELLIPTICAL) {
         float l_y = (y + .5 - ky_center) / (cal_y / 2);
         float l_z = (z + .5 - kz_center) / (cal_z / 2);
         float l_r = sqrt(l_y * l_y + l_z * l_z);
         if (l_r > 1.0) {
           continue;
         }
       }
       float y2 = (y + .5 - ky_center) / ky_radius;
       float z2 = (z + .5 - kz_center) / kz_radius;
 
       KS_KCOORD coord = {y, z, (float)sqrt((y2 * y2) + (z2 * z2)), (float)atan2(z2, y2)};
       queue[queue_size++] = coord;
       K[num_coords++] = coord;
       set_grid(grid, Nz, coord.y, coord.z);
     }
   }
 
 
   while (queue_size > 0) {
     /* Pick a random element in active list */
     int active_idx = rand() % queue_size; 
     KS_KCOORD active_coord = queue[active_idx];
 
     float spacing = ks_poisson_disc_min_spacing(active_coord.y, active_coord.z, ky_center, kz_center, min_spacing, max_spacing, pattern);
 
     int success = 0;
     int attempt;
     for (attempt = 0; attempt < num_attempts; attempt++) {
       /* Spawn a candidate in the circular annulus around the active coordinate */
       float spawn_angle = rand_float_in_range(-3.14159265, 3.14159265);
       float spawn_distance = rand_float_in_range(spacing, 2*spacing);
 
       float cand_y = active_coord.y + 0.5 + spawn_distance * sin(spawn_angle);
       float cand_z = active_coord.z + 0.5 + spawn_distance * cos(spawn_angle);
 
       /* Snap the candidate to the grid */
       float y2 = ((int)cand_y + .5 - ky_center) / ky_radius;
       float z2 = ((int)cand_z + .5 - kz_center) / kz_radius;
       KS_KCOORD cand = {(int)(cand_y), (int)(cand_z), (float)sqrt((y2 * y2) + (z2 * z2)), (float)atan2(z2, y2) };
       if (cand.y < 0 || cand.y > (Ny-1) ||
           cand.z < 0 || cand.z > (Nz-1)  ) {
             continue;
       }
 
       /* Check if candidate is within active radius (it might have snapped closer than allowed) */
       if (sqrt(pow(active_coord.y - cand.y,2) + pow(active_coord.z - cand.z,2)) < spacing) {
         continue;
       }
       /* Retrieve the radius at the candidate position */
       float radius_candidate = ks_poisson_disc_min_spacing(cand.y, cand.z, ky_center, kz_center, min_spacing, max_spacing, pattern);
       int conflict = check_conflicts(grid, Ny, Nz, cand, radius_candidate);
       if (conflict != 1) {
         set_grid(grid, Nz, cand.y, cand.z);
         K[num_coords++] = cand;
         queue[queue_size++] = cand;
         success++;
         break;
       }
     }
 
     if (success == 0) {
       remove_element(queue, active_idx, queue_size--);
     }
 
   }
 
   free(queue);
   free(grid);
   K = (KS_KCOORD*)realloc(kacq->coords, num_coords* sizeof(KS_KCOORD)); /* Shrink */
   if (!K) {
     return KS_THROW("Failed reallocation");
   }
   kacq->coords = K;
   kacq->num_coords = num_coords;
 
   for (idx = 0; idx < kacq->num_coords; idx++) {
     kacq->coords[idx].y -= Ny/2;
     kacq->coords[idx].z -= Nz/2;
   }
 
   kacq->matrix_size[YGRAD] = Ny;
   kacq->matrix_size[ZGRAD] = Nz > 1 ? Nz : KS_NOTSET;
 
   return SUCCESS;
 }

◆ ks_generate_3d_coords_poisson_disc_R()

STATUS ks_generate_3d_coords_poisson_disc_R	(	KS_KSPACE_ACQ *	kacq,
		int	Ny,
		int	Nz,
		float	R,
		KS_COVERAGE	cal_coverage,
		int	cal_y,
		int	cal_z,
		RADIUS_PATTERN	pattern
	)

ADDTITLEHERE

ADDDESCHERE

Return values

STATUS SUCCESS or FAILURE

                                                                     {
 
   const float min_spacing = 1.4;
   float left_spacing = min_spacing;
   float right_spacing = IMax(2,Nz/4, Ny/4);
   STATUS status;
 
   status = ks_generate_3d_coords_poisson_disc(kacq, Ny, Nz, min_spacing, right_spacing, cal_coverage, cal_y, cal_z, pattern);
   KS_RAISE(status);
 
   const int max_iter = 10;
   float cur_R = Ny*Nz/(kacq->num_coords);
   int iter = 0;
   float cur_spacing;
   /* Binary search */
   while (fabs(cur_R - R) > 0.1 && iter < max_iter) {
     cur_spacing = (right_spacing + left_spacing) / 2.0;
 
     status = ks_generate_3d_coords_poisson_disc(kacq, Ny, Nz, min_spacing, cur_spacing, cal_coverage, cal_y, cal_z, pattern);
     KS_RAISE(status);
 
     cur_R = Ny*Nz/(float)(kacq->num_coords);
 
 
     if (cur_R > R) {
       right_spacing = cur_spacing;
     }
     if (cur_R < R) {
       left_spacing = cur_spacing;
     }
 
     iter++;
   }
 
   return SUCCESS;
 
 
 }

◆ ks_generate_3d_coords_epi()

STATUS ks_generate_3d_coords_epi	(	KS_KSPACE_ACQ *	kacq,
		const KS_EPI *	epitrain,
		const ks_enum_epiblipsign	blipsign,
		const int	Ry,
		const int	caipi_delta
	)

ADDTITLEHERE

ADDDESCHERE

Return values

STATUS SUCCESS or FAILURE

                                                         {
 
   /* Interleaves refers to the number of different shifts along ky */
   const int max_numileaves = epitrain->blipphaser.R;
   const int acc_numileaves = epitrain->blipphaser.R / Ry;
 
   if (epitrain->blipphaser.R < 1 || Ry < 1) {
     return KS_THROW("Acceleration factors must be positive");
   }
 
   if (acc_numileaves < 1) {
     return KS_THROW("The requested acceleration (%d) is greater than the maximum allowed (%d) by the EPI train", Ry, epitrain->blipphaser.R);
   }
 
   if (epitrain->blipphaser.R % Ry) {
     return KS_THROW("The maximum allowed acceleration by the EPI train must be divisible by the requested one");
   }
 
   /* Overallocate for now */
   const int Nz = epitrain->zphaser.res > 0 ? epitrain->zphaser.numlinestoacq : 1;
   KS_KCOORD* K = (KS_KCOORD*)realloc(kacq->coords, Nz*max_numileaves * sizeof(KS_KCOORD));
   if (!K) {
     return KS_THROW("Failed (re)allocation");
   }
   kacq->coords = K;
   kacq->num_coords = 0;
 
   const int base_kyview = blipsign == KS_EPI_NEGBLIPS ?
     epitrain->blipphaser.linetoacq[0] :
     epitrain->blipphaser.linetoacq[epitrain->blipphaser.numlinestoacq-1];
 
   const double ky_center = (epitrain->blipphaser.res-1)/2.0;
   const double kz_center = epitrain->zphaser.res > 0 ? (epitrain->zphaser.res-1)/2.0 : -1;
 
   int kzidx = 0, kyidx;
   int kzview = KS_NOTSET;
   int is_cal = 0;
   int shot = 0;
   do {
     if (epitrain->zphaser.res != KS_NOTSET) {
 
       kzview = epitrain->zphaser.linetoacq[kzidx];
 
       if (epitrain->zphaser.R > 1) {
         if (kzidx < epitrain->zphaser.numlinestoacq-1) {
           is_cal =
             epitrain->zphaser.nacslines > 0 &&
             abs(epitrain->zphaser.linetoacq[kzidx+1]- kzview) == 1;
         }
       } else {
         is_cal = abs(epitrain->zphaser.res/2.0 - kzview)*2.0 < epitrain->zphaser.nacslines;
       }
     }
 
     const int numileaves = is_cal ? max_numileaves : acc_numileaves;
     const int step = is_cal ? 1 : Ry;
 
     for (kyidx = 0; kyidx < numileaves; ++kyidx) {
       int shift = kyidx * step;
 
       if (epitrain->zphaser.res != KS_NOTSET) {
         /* CAIPIRINHA shift */
         shift = (shift + (kzview/epitrain->zphaser.R) * caipi_delta) % max_numileaves;
       }
 
       const int kyview = base_kyview + shift;
       /* Calculate the symmetric coordinates normalized to [-1,1].
          Note that, if kzview is -1, so is kz_center. This results in a z coordinate of zero. */
       const double y = (kyview - ky_center)/ky_center;
       const double z = (kzview - kz_center)/kz_center; 
       KS_KCOORD c = {kyview - epitrain->blipphaser.res/2,
                      kzview - epitrain->zphaser.res/2,
                      (float)sqrt((y * y) + (z * z)),
                      (float)atan2(z, y),
                      };
 
       K[shot] = c;
       ++shot;
     }
 
     ++kzidx;
 
   } while(epitrain->zphaser.res != KS_NOTSET && kzidx < epitrain->zphaser.numlinestoacq);
 
   /* Downsize if necessary */
   K = (KS_KCOORD*)realloc(K, shot * sizeof(KS_KCOORD));
   if (!K) {
     return KS_THROW("Failed (re)allocation");
   }
 
   kacq->coords = K;
   kacq->num_coords = shot;
   kacq->matrix_size[YGRAD] = epitrain->blipphaser.res;
   kacq->matrix_size[ZGRAD] = epitrain->zphaser.res > 0 ? epitrain->zphaser.numlinestoacq : KS_NOTSET;
 
   return SUCCESS;
 }

◆ ks_pe_linear()

void ks_pe_linear	(	int *	view_order,
		int	ETL
	)

ADDTITLEHERE

ADDDESCHERE

Parameters

[out]	view_order	ADDTEXTHERE
[in]	ETL	ADDTEXTHERE

Returns: void

                                             {
   int i;
   for (i = 0; i < ETL; i++) {
     view_order[i] = i;
   }
 }

◆ ks_pe_linear_roll()

void ks_pe_linear_roll	(	int *	view_order,
		int	ETL,
		int	c
	)

ADDTITLEHERE

ADDDESCHERE

Parameters

	view_order	ADDTEXTHERE
[in]	ETL	ADDTEXTHERE
[in]	c	ADDTEXTHERE

Returns: void

                                                         {
   int base[ETL];
   int idx;
   for (idx = 0; idx < ETL; idx++) {
     base[idx] = idx;
   }
   int s;
   if (c < (ETL/2)) {
     s = ETL/2 - c;
   } else {
     s = 3*ETL/2 - c;
   }
 
   memcpy(&(view_order[0]), &(base[ETL-s]), sizeof(int) * s);
   memcpy(&(view_order[s]), &(base[0]), sizeof(int) * (ETL-s));
 }

◆ ks_pe_pivot_roll()

void ks_pe_pivot_roll	(	int *	view_order,
		int	ETL,
		int	c
	)

ADDTITLEHERE

ADDDESCHERE

Parameters

	view_order	ADDTEXTHERE
[in]	ETL	ADDTEXTHERE
[in]	c	ADDTEXTHERE

Returns: void

                                                        {
   int base[ETL];
   ks_pivot_specific_center_symk(base, ETL, 0);
   int s;
   if (c == 0) {
     s = 0;
   } else {
     if (ETL % 2 ) {
       if (c % 2) {
         s = ETL - c/2 - 1;
       } else {
         s = c / 2;
       }
     } else {
       if (c % 2) {
         s = ETL - c/2;
       } else {
         s = c / 2;
       }
     }
   }
 
   memcpy(&(view_order[0]), &(base[ETL-s]), sizeof(int) * s);
   memcpy(&(view_order[s]), &(base[0]), sizeof(int) * (ETL-s));
 }

◆ ks_pivot_linear_center_symk()

void ks_pivot_linear_center_symk	(	int *	view_order,
		int	ETL,
		int	c
	)

ADDTITLEHERE

ADDDESCHERE

Parameters

	view_order	ADDTEXTHERE
[in]	ETL	ADDTEXTHERE
[in]	c	ADDTEXTHERE

Returns: void

                                                                   {
 
   typedef enum {
     UP,
     DOWN
   } UPDOWN;
 
   typedef enum {
     LEFT,
     RIGHT
   } LR;
   int odd_ETL = ETL % 2; 
   int idx = 0;
 
   if (c == ETL-1 && odd_ETL != 1) {
     return ks_pivot_linear_center_symk(view_order, ETL, c-1);
   }
   UPDOWN centertype =  c < (ETL/2) ? UP 
                                    : DOWN;
 
   /* Pivoting from center (replace later) */
   int pivot_index = (ETL-1)/2;
   if (odd_ETL != 1 && centertype == DOWN) {
     pivot_index++;
   }
 
   LR s_dir = RIGHT;
   if (centertype == DOWN && odd_ETL != 1) {
     s_dir = LEFT;
   } else if (centertype == UP && odd_ETL == 1) {
     s_dir = LEFT;
   }
   int val = centertype == DOWN ? ETL-1
                              : 0;
   for (idx = 0; idx < (ETL/2); idx++) {
     if (centertype == UP) {
       if (s_dir == LEFT) {
         view_order[pivot_index + idx] = val++;
         view_order[pivot_index - idx - 1] = val++;
       } else {
         view_order[pivot_index - idx] = val++;
         view_order[pivot_index + idx + 1] = val++;
       }
     } else {
       if (s_dir == LEFT) {
         view_order[pivot_index + idx] = val--;
         view_order[pivot_index - idx - 1] = val--;
       } else {
         view_order[pivot_index - idx] = val--;
         view_order[pivot_index + idx + 1] = val--;
       }
     }
   }
 
   if (odd_ETL == 1) {
     if (centertype == UP) {
       view_order[ETL-1] = ETL-1;
     } else {
       view_order[0] = 0;
     }
 
   }
 
 
   /* Linear sweep */
   const int linear_start = odd_ETL ? abs(ETL/2 - c)
                                    : abs(ETL/2 - 1 - c);
   const int num_linear = ETL - 2*linear_start;
   for (idx=0; idx < num_linear; idx++) {
     view_order[linear_start + idx] = centertype == UP ? idx
                                                      : linear_start*2 + idx;
   }
 }

◆ ks_pe_permute_pclo_rad()

STATUS ks_pe_permute_pclo_rad	(	int *	view_order,
		const int	etl,
		const int	center
	)

ADDTITLEHERE

ADDDESCHERE

Parameters

	view_order	ADDTEXTHERE
[in]	etl	ADDTEXTHERE
[in]	center	ADDTEXTHERE

Return values

STATUS SUCCESS or FAILURE

                                                                                 {
   if (view_order == NULL) {
     return KS_THROW("View order is NULL");
   }
   if (center < 0) {
     return KS_THROW("Center encode (%d) must be in [0, %d)", center, etl);
   }
   if (center > etl-1) {
     return KS_THROW("Center encode (%d) must be smaller than encodes per shot (%d)", center, etl);
   }
   int i;
   if (center >= (etl + 1)/2) {
 
     KS_RAISE(ks_pe_permute_pclo_rad(view_order, etl, etl-center-1));
     for (i=0; i < etl; i++) {
       view_order[i] = etl - 1 - view_order[i];
     }
     return SUCCESS;
   }
   const int num_inner = CEIL_DIV(center,2);
   const int num_outer = CEIL_DIV(center+1,2);
   const int num_linear = etl - num_inner - num_outer - 1;
   const int even_center_encode = center % 2 == 0;
 
   for (i = 0; i < num_inner; i++) {
     view_order[i] = center - 2*i;
   }
 
   view_order[i] = 0;
 
 
   for (i = 1; i <= num_outer; i++) {
     view_order[num_inner + i] = 2*i - even_center_encode;
   }
 
   for (i = 1; i <= num_linear; i++) {
     view_order[num_inner + num_outer + i] = num_inner + num_outer + i;
   }
 
 
   return SUCCESS;
 }

◆ ks_pivot_specific_center_symk()

void ks_pivot_specific_center_symk	(	int *	view_order,
		int	ETL,
		int	c
	)

ADDTITLEHERE

ADDDESCHERE

Parameters

	view_order	ADDTEXTHERE
[in]	ETL	ADDTEXTHERE
[in]	c	ADDTEXTHERE

Returns: void

                                                                     {
   /* Some enums for YOUR convenience */
   typedef enum {
     UP,
     DOWN
   } UPDOWN;
 
   typedef enum {
     LEFT,
     RIGHT
   } LR;
 
   /* Is center a peak or valley? */
   UPDOWN centertype =  c < (ETL/2) ? DOWN 
                                    : UP;
   int pivot = centertype == DOWN ? (int)(ceil((ETL - c)/ 2.0) - 1)
                                  : (int)(ceil((c   - 1)/ 2.0) + 1);
   if (centertype == UP) {
     pivot -= 1;
   }
   LR s_dir;
 
   if (ETL % 2) {
     s_dir = (c % 2) ? RIGHT : LEFT;
   } else {
     if (centertype == DOWN) {
       s_dir = (c % 2) ? LEFT : RIGHT;
     } else {
       s_dir = (c % 2) ? RIGHT : LEFT;
     }
   }
   int idx = 0;
   int val = centertype == DOWN ? 0 : (ETL-1);
   view_order[pivot] = (centertype == DOWN ? 0 : (ETL-1));
   for (; idx < pivot; idx++) {
     if (centertype == DOWN) {
       if (s_dir == LEFT) {
         view_order[pivot - idx - 1] = ++val;
         view_order[pivot + idx + 1] = ++val;
       } else {
         view_order[pivot + idx + 1] = ++val;
         view_order[pivot - idx - 1] = ++val;
       }
     } else {
       if (s_dir == LEFT) {
         view_order[pivot - idx - 1] = --val;
         view_order[pivot + idx + 1] = --val;
       } else {
         view_order[pivot + idx + 1] = --val;
         view_order[pivot - idx - 1] = --val;
       }
     }
   }
   for (idx = (pivot*2+1); idx < ETL; idx++) {
     view_order[idx] = (centertype == DOWN) ? idx
                                            : ((ETL-1-idx));
   }
 
   /* If center echo matches linear sweep */
   if (ETL/2 == c) {
     for (idx=0; idx < ETL; idx++) {
       view_order[idx] = idx;
     }
   }
 
 }

◆ ks_pivot_specific_center_radk()

void ks_pivot_specific_center_radk	(	int *	view_order,
		int	ETL,
		int	c
	)

ADDTITLEHERE

ADDDESCHERE

Parameters

	view_order	ADDTEXTHERE
[in]	ETL	ADDTEXTHERE
[in]	c	ADDTEXTHERE

Returns: void

                                                                     {
     /* Some enums for YOUR convenience */
   typedef enum {
     UP,
     DOWN
   } UPDOWN;
 
   typedef enum {
     LEFT,
     RIGHT
   } LR;
 
   /* Is center a peak or valley? */
   UPDOWN centertype =  c < (ETL/2) ? DOWN 
                                    : UP;
   int pivot = centertype == DOWN ? (int)floor((  1 + c) / 2.0)
                                  : (int)floor((ETL - c) / 2.0);
 
   LR s_dir;
   if (ETL % 2) { /* Odd ETL */
     s_dir = (c % 2) ? RIGHT : LEFT;
   } else { /* Even ETL */
     if (centertype == DOWN) {
       s_dir = (c % 2) ? LEFT : RIGHT;
     } else {
       s_dir = (c % 2) ? RIGHT : LEFT;
     }
   }
   int idx = 0;
   int val = centertype == DOWN ? 0 : (ETL-1);
   view_order[pivot] = (centertype == DOWN ? 0 : (ETL-1));
 
 
   for (; idx < pivot; idx++) {
     if (centertype == DOWN) {
       if (s_dir == LEFT) {
         view_order[pivot - idx - 1] = ++val;
         view_order[pivot + idx + 1] = ++val;
       } else {
         view_order[pivot + idx + 1] = ++val;
         view_order[pivot - idx - 1] = ++val;
       }
     } else {
       if (s_dir == LEFT) {
         view_order[pivot - idx - 1] = --val;
         view_order[pivot + idx + 1] = --val;
       } else {
         view_order[pivot + idx + 1] = --val;
         view_order[pivot - idx - 1] = --val;
       }
     }
   }
   for (idx = (pivot*2+1); idx < ETL; idx++) {
     view_order[idx] = (centertype == DOWN) ? idx
                                            : ((ETL-1-idx));
   }
 
 }

◆ ks_generate_peplan_from_kcoords()

STATUS ks_generate_peplan_from_kcoords	(	const KS_KSPACE_ACQ *	kacq,
		KS_PHASEENCODING_PLAN *	peplan,
		KS_MTF_DIRECTION	mtf_direction,
		KS_VIEW_SORT_ORDER	encode_shot_assignment_order,
		KS_VIEW_MTF_PROFILE	mtf_profile,
		const int	etl,
		int	center,
		const KS_COORDINATE_TYPE *const	coord_types
	)

Phase encoding plan generators

ADDDESCHERE

Parameters

[in]	kacq	ADDTEXTHERE
[out]	peplan	ADDTEXTHERE
[in]	mtf_direction	ADDTEXTHERE
[in]	encode_shot_assignment_order	ADDTEXTHERE
[in]	mtf_profile	ADDTEXTHERE
[in]	etl	ADDTEXTHERE
[in]	center	ADDTEXTHERE
[in]	coord_types	KS_COORDINATE_TYPE ADDTEXTHERE

Return values

STATUS SUCCESS or FAILURE

                                                                                 {
   if (center == KS_NOTSET) {
       mtf_profile = LINEAR_SWEEP;
       KS_PEPLAN_SHOT_DISTRIBUTION tmp_dist = ks_peplan_distribute_shots(etl, kacq->num_coords, center);
       const int center_lth_linsweep = ks_peplan_find_center_from_linear_sweep(kacq->coords, NULL, kacq->num_coords, mtf_direction, +1 /* lth */, tmp_dist.shots, 0 /* start_from */);
       const int center_htl_linsweep = ks_peplan_find_center_from_linear_sweep(kacq->coords, NULL, kacq->num_coords, mtf_direction, -1 /* htl */, tmp_dist.shots, 0 /* start_from */);
       if (center_lth_linsweep != center_htl_linsweep) {
         return KS_THROW("Ambigous center encode: center encode was not set and partial Fourier coords are supplied");
       }
       center = center_lth_linsweep;
   } else if (center < 0) {
     return KS_THROW("Center index cannot be negative (requested %d)", center);
   }
 
   if (center >= etl) {
     return KS_THROW("Center index must be in [0,etl-1] (center=%d, etl=%d)", center, etl);
   }
   if (kacq->num_coords <= 0) {
     return KS_THROW("num_coords is %d", kacq->num_coords);
   }
 
   if (kacq->coords == NULL) {
     return KS_THROW("No coordinates supplied");
   }
 
   if (center >= kacq->num_coords) {
     return KS_THROW("Center index must be in [0,num_coords-1] (center=%d, num_coords=%d)", center, kacq->num_coords);
   }
 
   if (mtf_profile == SPLIT_SHOTS_AMERICAN) {
     STATUS s = ks_generate_peplan_from_kcoords_american(kacq, peplan, mtf_direction, etl, center);
     return s;
   } else if (mtf_profile == SPLIT_SHOTS_DUTCH) {
     return ks_generate_peplan_from_kcoords_dutch(kacq, peplan, mtf_direction, etl, center);
   }
 
   KS_PEPLAN_SHOT_DISTRIBUTION shot_dist = ks_peplan_distribute_shots(etl, kacq->num_coords, center);
 
   int idx, readout, train;
   KS_KCOORD* K = kacq->coords;
   /* Check if K.z is the same for all KCOORDS. If it is then we don't set it later.*/
   int is3d = 0;
   for (idx = 0; idx < kacq->num_coords; idx++) {
     is3d |= (K[0].z != K[idx].z);
   }
 
   if ((is3d == 0) && ((mtf_direction == MTF_R) || (mtf_direction == MTF_R))) {
     return KS_THROW("Radial MTF is not supported for 2D acquisitions");
   }
 
   KS_COORDINATE_TYPE default_coord_types[] = {CARTESIAN_COORD, CARTESIAN_COORD};
   if (coord_types == NULL) {
     coord_types = default_coord_types;
   }
 
   /* Create views */
   KS_VIEW* views = (KS_VIEW*) malloc(kacq->num_coords * sizeof(KS_VIEW));
 
   for (idx = 0; idx < kacq->num_coords; idx++) {
     views[idx].coord = &(K[idx]);
     views[idx].encode = KS_NOTSET;
     views[idx].train = KS_NOTSET;
   }
 
   /*
    Calculate the view order (e.g. center out if center=0) using a pivot algorithm. 
    The view order describes the T2 modulation in k-space.
    If you want to implement linear sweep, view_order is simply [0, 1, ..., shot_dist.encodes_per_shot-1] 
   */
   int view_order[shot_dist.encodes_per_shot];
   memset(view_order, KS_NOTSET, sizeof(view_order));
   view_order[0] = KS_NOTSET;
   if ((mtf_direction == MTF_Y) || (mtf_direction == MTF_Z)) {
     switch (mtf_profile) {
     case PIVOT_CENTER_OUTER_LINEAR: {
       ks_pivot_specific_center_symk(view_order, shot_dist.encodes_per_shot, center);
       break;
     } case SPLIT_SHOTS_LCPO:
       case LCPO: {
         if (coord_types[0] == RADIAL_COORD || coord_types[1] == RADIAL_COORD) {
          ks_pivot_linear_center_symk(view_order, shot_dist.encodes_per_shot, center);
         } else {
           ks_lcpo_assign_encodes(views, kacq->num_coords, mtf_direction,
                                 mtf_profile == SPLIT_SHOTS_LCPO ? 1 : 0,
                                 etl, center);
         }
       break;
     } case LINEAR_ROLL: {
       ks_pe_linear_roll(view_order, shot_dist.encodes_per_shot, center);
       break;
     } case PIVOT_ROLL: {
       ks_pe_pivot_roll(view_order, shot_dist.encodes_per_shot, center);
       break;
     } case LINEAR_SWEEP: {
       ks_pe_linear(view_order, shot_dist.encodes_per_shot);
       break;
     }
     default:
       free(views);
       return KS_THROW("MTF profile %d not implemented", (int)mtf_profile);
       break;
     }
   } else if ((mtf_direction == MTF_R) || (mtf_direction == MTF_T)) {
 /*     ks_pivot_specific_center_radk(view_order, shot_dist.encodes_per_shot, center); */
     ks_pe_permute_pclo_rad(view_order, shot_dist.encodes_per_shot, center);
 
   }
 
   if (view_order[0] != KS_NOTSET) {
     /* Permute has been set - assign encodes */
     /* Sort KCOORDS according to their radius or ky coordinate */
     switch (mtf_direction) {
       case MTF_R: {
         qsort(views, kacq->num_coords, sizeof(KS_VIEW), &ks_comp_kview_r_t);
         break;
       }
       case MTF_T: {
         qsort(views, kacq->num_coords, sizeof(KS_VIEW), &ks_comp_kview_t_r);
         break;
       }
       case MTF_Y: {
         qsort(views, kacq->num_coords, sizeof(KS_VIEW), &ks_comp_kview_y_z);
         break;
       }
       case MTF_Z: {
         qsort(views, kacq->num_coords, sizeof(KS_VIEW), &ks_comp_kview_z_y);
         break;
       }
       default:
       {
         return ks_error("Unknown mtf_direction: %i", mtf_direction);
       }
     }
 
     /* Assign each point an encode ("echo" in an echo train) according to the desired view order (center out etc)
     The linear indexing (idx) is a consequence of the sort above */
     const int readout_end = shot_dist.readout_start + shot_dist.encodes_per_shot;
     for (idx = 0, readout = shot_dist.readout_start; readout < readout_end; readout++) {
       for (train = 0; train < shot_dist.shots; train++) {
         int block = train < shot_dist.first_blocks ? 0 : 1;
         if (block == 1 && readout == (readout_end -1)) {
           continue;
         }
         if (idx < kacq->num_coords) {
           views[idx].encode = view_order[readout];
         }
         idx++;
       }
     } 
   }
 
   /* Now each point has an encode (or TE if you prefer). It's time to sort the encodes (TE's) for the desired order. */
   switch (encode_shot_assignment_order) {
     case T_R:
     {
       /* Sort for encode->theta then r. This enforces a spoke in ky-kz when we later pick encodes in a train. 
        Note that radial is not at all related to elliptical k-space coverage. */
       qsort(views, kacq->num_coords, sizeof(KS_VIEW), &ks_comp_kview_e_tr);
       break;
     }
     case R_T:
     {
       /* Sort for encode->r then theta. This enforces a ring in ky-kz when we later pick encodes in a train. */
       qsort(views, kacq->num_coords, sizeof(KS_VIEW), &ks_comp_kview_e_rt);
       break;
     }
     case Y_Z:
     {
       /* Sort for encode->kz. This enforces a column in ky-kz when we later pick encodes in a train */
       qsort(views, kacq->num_coords, sizeof(KS_VIEW), &ks_comp_kview_e_yz);
       break;
     }
     case Z_Y:
     {
       /* Sort for encode->ky. This enforces a row in ky-kz when we later pick encodes in a train */
       qsort(views, kacq->num_coords, sizeof(KS_VIEW), &ks_comp_kview_e_zy);
       break;
     }
 
     case Y_R:
     {
       /* Sort for encode->kz. This enforces a column in ky-kz when we later pick encodes in a train */
       qsort(views, kacq->num_coords, sizeof(KS_VIEW), &ks_comp_kview_e_yr);
       break;
     }
     case Z_R:
     {
       /* Sort for encode->ky. This enforces a row in ky-kz when we later pick encodes in a train */ 
       qsort(views, kacq->num_coords, sizeof(KS_VIEW), &ks_comp_kview_e_zr);
       break;
     }
 
     case SEC_T:
     {
       qsort(views, kacq->num_coords, sizeof(KS_VIEW), &ks_comp_kview_e_sec_t);
       break;
     }
 
     default:
     {
       return ks_error("Unknown encode_shot_assignment_order: %i", encode_shot_assignment_order);
     }
   }
 
   /* Make the actual phase encoding plan */
   STATUS status = ks_phaseencoding_alloc(peplan, etl, shot_dist.shots);
   KS_RAISE(status);
 
   int yshift = coord_types[0] == CARTESIAN_COORD ? kacq->matrix_size[YGRAD]/2 : 0;
   int zshift = coord_types[1] == CARTESIAN_COORD ? kacq->matrix_size[ZGRAD]/2 : 0;
 
   status = ks_peplan_assign_shots(peplan, views, kacq->num_coords, &shot_dist, 0, yshift, zshift, is3d);
   free(views);
 
   KS_RAISE(status);
 
   return SUCCESS;
 }

◆ ks_generate_peplan_from_kcoords_american()

STATUS ks_generate_peplan_from_kcoords_american	(	const KS_KSPACE_ACQ *	kacq,
		KS_PHASEENCODING_PLAN *	peplan,
		const KS_MTF_DIRECTION	mtf_direction,
		const int	etl,
		const int	center
	)

<-— center
^ *
| *
ky *

                     Time ->

                                                                     {
 
   KS_PEPLAN_SHOT_DISTRIBUTION unsplit_shots = ks_peplan_distribute_shots(etl, kacq->num_coords, center);
 
   int midshots, idx;
   KS_VIEW* views =(KS_VIEW*) malloc(kacq->num_coords * sizeof(KS_VIEW));
 
   int midcoords = 0;
   int readout, train;
   int is3d = 0;
 
   KS_PEPLAN_SHOT_DISTRIBUTION mid_shots;
   KS_PEPLAN_SHOT_DISTRIBUTION outer_shots;
   /* Figure out center by sorting by radius */
   KS_KCOORD* K = kacq->coords;
   int center_line = mtf_direction == MTF_Z ? kacq->matrix_size[ZGRAD]
                                            : kacq->matrix_size[YGRAD];
 
   /* Create views and figure out if this is a 3D peplan */
   for (idx = 0; idx < kacq->num_coords; idx++) {
     is3d |= (K[0].z != K[idx].z);
     views[idx].coord = &(K[idx]);
     views[idx].train = KS_NOTSET;
   }
 
   if (is3d == 0 && mtf_direction == MTF_Z) {
     free(views);
     return KS_THROW("Requested MTF along Z ordering with 2D coordinates");
   }
 
   int found_solution = 0;
   for (midshots = 1; midshots < unsplit_shots.shots; ) {
     midcoords = midshots * unsplit_shots.encodes_per_shot;
     mid_shots = ks_peplan_distribute_shots(etl, midcoords, center);
     int mid_readout_end = mid_shots.readout_start + mid_shots.encodes_per_shot;
 
     /* Reset encodes */
     for (idx = 0; idx < kacq->num_coords; idx++) {
       views[idx].encode = -1000;
     }
 
     /* Sort views z->y or y->z */
     if (mtf_direction == MTF_Z) {
       qsort(views, kacq->num_coords, sizeof(KS_VIEW), &ks_comp_kview_z_y);
     } else {
       qsort(views, kacq->num_coords, sizeof(KS_VIEW), &ks_comp_kview_y_z);
     }
 
     /* Assign encodes to midcoord views (center -> out) */
     idx = 0;
     for (readout = mid_readout_end-1; readout >= mid_shots.readout_start; readout--) {
       for (train = 0; train < midshots; train++) {
         int block = train < mid_shots.first_blocks ? 0 : 1;
         if (block == 1 && readout == (mid_readout_end -1)) {
           continue;
         }
 
         /* Only assign midcoords */
         if (idx < midcoords) {
           views[idx].encode = readout;
         }
         idx++;
       }
     }
 
     if (idx != midcoords) {
       ks_error("Something is wrong with the midcoords");
     }
 
     /* Sort midcoords encode->z or encode->y */
     if (mtf_direction == MTF_Z) {
       qsort(views, midcoords, sizeof(KS_VIEW), &ks_comp_kview_e_zy);
     } else {
       qsort(views, midcoords, sizeof(KS_VIEW), &ks_comp_kview_e_yz);
     }
 
     /* Figure out the center encode */
     int current_center_encode, center_distance_late, center_distance_early, e;
     for (e = 0; e < mid_shots.encodes_per_shot; e++) {
       if (mtf_direction == MTF_Z) {
         center_distance_late = views[(e+1) * midshots - 1].coord->z - center_line;
         center_distance_early = views[e * midshots].coord->z - center_line;
       } else {
         center_distance_late = views[(e+1) * midshots - 1].coord->y - center_line;
         center_distance_early = views[e * midshots].coord->y - center_line;
       }
       if (center_distance_early <= 0 && center_distance_late >= 0) { /* distance 0 is inside the encode section */
         current_center_encode = e;
         found_solution = 1;
         break;
       }
     }
     if (current_center_encode == center) { /* Found it */
       break;
     } else {
       /* Incorrect center encode -> increase midshots and try again */
       midshots++;
       continue;
     }
   } /* for midshots */
 
   if (!found_solution) {
     free(views);
     return KS_THROW("Could not split shots to get center = %d", center);
   }
   /* Split encodes between remaining shots */
   const int rest_num_coords = kacq->num_coords - midcoords;
   outer_shots = ks_peplan_distribute_shots(etl, rest_num_coords, center);
 
   STATUS status = ks_phaseencoding_alloc(peplan, etl, outer_shots.shots + mid_shots.shots);
   KS_RAISE(status);
 
   const int outer_readout_end = outer_shots.readout_start + outer_shots.encodes_per_shot;
   /* Loop through the block (which is shifted to the desired encode) and assign the entries */
   for (readout = outer_shots.readout_start; readout < outer_readout_end; readout++) {
     for (train = 0; train < outer_shots.shots; train++) {
       int block = train < outer_shots.first_blocks ? 0 : 1;
       if (block == 1 && readout == (outer_readout_end -1)) {
         continue;
       }
       if (idx >= kacq->num_coords) {
         free(views);
         return KS_THROW("Trying to assign more coordinates than what is available");
       }
       views[idx++].encode = readout;
     }
   }
 
   /* Sort outer coordinates (either encode->z or encode->y) */
   if (mtf_direction == MTF_Z) {
     qsort(views + midcoords, rest_num_coords, sizeof(KS_VIEW), &ks_comp_kview_e_zy);
   } else {
     qsort(views + midcoords, rest_num_coords, sizeof(KS_VIEW), &ks_comp_kview_e_yz);
   }
 
   KS_RAISE(ks_peplan_assign_shots(peplan, views,                   midcoords,   &mid_shots,         0, kacq->matrix_size[YGRAD]/2, kacq->matrix_size[ZGRAD]/2, is3d)); 
   KS_RAISE(ks_peplan_assign_shots(peplan, views + midcoords, rest_num_coords, &outer_shots,  midshots, kacq->matrix_size[YGRAD]/2, kacq->matrix_size[ZGRAD]/2, is3d));
 
   free(views);
   return SUCCESS;
 }

◆ ks_fse_calcecho()

STATUS ks_fse_calcecho	(	double *	bestecho,
		double *	optecho,
		int *	nacqlines_to_kspacecenter,
		const KS_PHASER *const	pe,
		KS_PF_EARLYLATE	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` or `KS_PF_LATE` (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) {
     *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_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_PF_EARLYLATE	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` or `KS_PF_LATE` (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_alloc(phaseenc_plan_ptr, etl, totalnumshots);
   KS_RAISE(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) && (blipsign == KS_EPI_POSBLIPS)) || ((pf_direction == KS_PF_EARLY) && (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_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 = slperpass;
 
   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_band, passes_per_band;
   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 'band' 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_band = CEIL_DIV(nslices, multiband_factor);
 
   /* number of passes per TR for one slice stack */
   passes_per_band = CEIL_DIV(slices_per_band, slperpass);
 
   if (passes_per_band == 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_band);
   } else {
     /* need 2+ acqs to acquire the 'slices_per_band' slices. Do standard slice interleaving */
     ks_calc_sliceplan(slice_plan, slices_per_band, slperpass);
   }
 
   /* copy to stacks 2->multiband_factor */
   slice_plan->nslices = slices_per_band * multiband_factor;
   slice_plan->npasses = passes_per_band * multiband_factor;
 
   for (i = slices_per_band; i < slice_plan->nslices; i++) {
     int slice_in_stack = i % slices_per_band;
     int stack = i / slices_per_band;
     slice_plan->acq_order[i].slloc  = i;
     slice_plan->acq_order[i].slpass = slice_plan->acq_order[slice_in_stack].slpass + stack * passes_per_band;
     slice_plan->acq_order[i].sltime = slice_plan->acq_order[slice_in_stack].sltime;
   }
 
   return SUCCESS;
 }

◆ ks_sms_check_divisibility()

STATUS ks_sms_check_divisibility	(	int *	inpass_interleaves,
		const int	sms_factor,
		const int	nslices_per_pass,
		const int	nslices
	)

Checks that nslices_per_pass is an odd number when accelerating with SMS

If possible, the number of inpass_interleaves will be adjusted to fix the issue.

Parameters

[out]	inpass_interleaves	Interleave factor of slices in a pass
[in]	sms_factor	Number of SMS slices
[in]	nslices_per_pass	Number of slices per pass (i.e. per TR)
[in]	nslices	Total number of slices

Return values

STATUS SUCCESS or FAILURE

                                                                                                        {
 
   if ((sms_factor > 1) && (!(nslices_per_pass % 2))) {
     int npasses = CEIL_DIV(nslices, nslices_per_pass);
     int adjusted_ileaves = 0;
     if (areSame((float)nslices/nslices_per_pass,(float)npasses)) {
       /* Check if adjusting the number of interleaves can help */
       int i;
       for (i = 4; i > 1; i--) {
         int y = CEIL_DIV(nslices_per_pass, i);
         float x = (float)(nslices_per_pass) / (float)(y*(i-1) + (y-1));
         if (areSame(x,1.0)) {
           *inpass_interleaves = i;
           adjusted_ileaves = 1;
         }    
       }
     }
     if (!adjusted_ileaves) {
       int down = (nslices_per_pass - 1) * npasses * sms_factor; 
       int up = (nslices_per_pass + 1) * npasses * sms_factor; 
       return ks_error("#slices not compatible with SMS, try %d or %d.", down, up);
     } else {
       ks_dbg("%s: Adjusted inpass_interleaves to %d, for SMS divisibillity.", __FUNCTION__, *inpass_interleaves);
     }
   }
 
   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_integrate_coords()

float ks_calc_integrate_coords	(	float *	t,
		float *	G,
		int	num_coords
	)

Integrates between coords using a trapezoidal method.

Parameters

[in]	t	Time points (array with num_coords elements)
[in]	G	Amplitude (array with num_coords elements)
[in]	num_coords	Number of points in t and G

Return values

float Integral (in units of G*t)

                                                                    {
   int i;
   if (num_coords < 2) {
     return ks_error("%s: At least two coords must be provided", __FUNCTION__);
   }
 
   for (i = 1; i < num_coords; i++) {
     if (t[i] < t[i-1]) {
       return ks_error("%s: Coords must be in time order", __FUNCTION__);
     }
   }
   float sum = 0.0;
   for (i = 0; i < (num_coords -1); i++) {
     sum += (t[i+1] - t[i])/2 * (G[i] + G[i+1]);
   }
   return sum;
 }

◆ 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

TODO: just works for single acquisitions

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_acqwaves()

STATUS ks_print_acqwaves ( KS_SEQ_COLLECTION * seqcollection )

A generic function that searches for acquisition waves that require resampling

Parameters

[in] seqcollection The KS_SEQ_COLLECTION sequence collection

Returns: void This function writes out a file acq_waveforms.bin in /usr/g/mrraw/kstmp//embed/

                                                            {
   int seq;
   int resampler_index = 0;
   STATUS status = SUCCESS;
 
   char filename[512];
 #ifdef PSD_HW /* on MR-scanner (host) */
   char outputdir_uid[512];
   char cmd[512];
   sprintf(outputdir_uid, "/usr/g/mrraw/kstmp/%010d/embed/", rhkacq_uid);
   sprintf(filename, "%s/acq_waveforms.bin", outputdir_uid);
   sprintf(cmd, "mkdir -p %s > /dev/null", outputdir_uid);
   system(cmd);
 #else /* e.g. WTools */
   sprintf(filename, "./acq_waveforms.bin");
 #endif
 
   FILE* fp = fopen(filename, "wb");
 
   for(seq = 0; seq < seqcollection->numseq; seq++) {
     KS_GRADRFCTRL * gradrf = &seqcollection->seqctrlptr[seq]->gradrf;
     int acq;
     for(acq = 0; acq < gradrf->numacq; acq++) {
       KS_READ * read = gradrf->readptr[acq];
       KSCOMMON_RESAMPLER header = (KSCOMMON_RESAMPLER)KSCOMMON_INIT_RESAMPLER;
       switch (read->resampler.ndims) {
         case 3:
         {
           if (read->resampler.zwave) {
             header.zgrad.dwell = read->resampler.zwave->duration / read->resampler.zwave->res;
             header.zgrad.npts = read->duration / header.zgrad.dwell;
             header.zgrad.target_res = read->resampler.target_res;
           }
         }
         case 2:
         {
           if (read->resampler.ywave) {
             header.ygrad.dwell = read->resampler.ywave->duration / read->resampler.ywave->res;
             header.ygrad.npts = read->duration / header.ygrad.dwell;
             header.ygrad.target_res = read->resampler.target_res;
           }
         }
         case 1:
         {
           if (read->resampler.xwave) {
             header.xgrad.dwell = read->resampler.xwave->duration / read->resampler.xwave->res;
             header.xgrad.npts = read->duration / header.xgrad.dwell;
             header.xgrad.target_res = read->resampler.target_res;
           }
 
           header.acq_bw = read->filt.bw;
           header.acq_npts = read->filt.outputs;
           header.acq_tsp = read->filt.tsp;
 
           int state;
           for (state = 0; state < read->resampler.xwave->base.nstates; state++) {
             read->resampler.index[state] = resampler_index++;
             fwrite(&header, 1, sizeof(KSCOMMON_RESAMPLER), fp);
             if(header.xgrad.npts) {
               fwrite(&read->resampler.xwave->p_waveformstates[state][read->resampler.wave_st_idx], header.xgrad.npts, sizeof(float), fp);
             }
             if(header.ygrad.npts) {
               fwrite(&read->resampler.ywave->p_waveformstates[state][read->resampler.wave_st_idx], header.ygrad.npts, sizeof(float), fp);
             }
             if(header.zgrad.npts) {
               fwrite(&read->resampler.zwave->p_waveformstates[state][read->resampler.wave_st_idx], header.zgrad.npts, sizeof(float), fp);
             }
           }
           break;
         }
         case 0:
           break;
         default:
           return ks_error("%s - acq_resampling up to 3 dims supported (read.ndims = %d)", __FUNCTION__, read->resampler.ndims);
       }
 
     } /*gradrf*/
 
   } /*seqcollection*/
   fflush(fp);
   fclose(fp);
 
   return status;
 }

◆ ks_print_readwave()

void ks_print_readwave	(	const KS_READWAVE *const	readwave,
		const char *	filename
	)

Writes a KS_READWAVE to disk with the specified filename.

Only the waveform played out while acquiring data is saved. If the full waveform is desired, useks_print_wave on readwave.grads[].

Parameters

[in]	readwave	Pointer to KS_READWAVE to be printed
[in]	filename	String with the output file name

Returns: void

                                                                                 {
   FILE *fp;
   int i = 0;
   fp = fopen(filename, "w");
 
   if (fp == NULL) {
     return;
   }
 
   for (i = (readwave->acqdelay / GRAD_UPDATE_TIME);
        i < (readwave->acqdelay + readwave->acq.duration) / GRAD_UPDATE_TIME;
        i++) {
     fprintf(fp, "%f, ", readwave->grad.waveform[i]);
   }
   fflush(fp);
   fclose(fp); /* close ascii file */
 }

◆ ks_print_wave_part()

void ks_print_wave_part	(	const KS_WAVE *const	wave,
		const char *	filename,
		int	startidx,
		int	stopidx
	)

ADDTITLEHERE

                                                                                                   {
   FILE *fp = fopen(filename, "ab");
   if (fp == NULL) {
     return;
   }
   if (startidx < 0 || startidx >= wave->res) {
     ks_error("%s: startidx (%d) is not in [0, %d]", __FUNCTION__, startidx, wave->res-1);
     return;
   }
   int stopidx = startidx + numel;
   if (stopidx < startidx || stopidx >= wave->res) {
     ks_error("%s: stopidx (%d) is not in [%d, %d]", __FUNCTION__, stopidx, startidx, wave->res-1);
     return;
   }
   fwrite(&wave->waveform[startidx], sizeof(float), numel, fp);
   fflush(fp);
   fclose(fp);
 }

◆ ks_print_wave()

void ks_print_wave	(	const KS_WAVE *const	wave,
		const char *	filename
	)

ADDTITLEHERE

                                                                     {
   FILE *fp;
   int i = 0;
   fp = fopen(filename, "w");
 
   if (fp == NULL) {
     return;
   }
 
   for (i = 0; i < wave->res; i++) {
     fprintf(fp, "%f, ", wave->waveform[i]);
   }
   fflush(fp);
   fclose(fp); /* 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) {
     fprintf(fp, "omega: {");
     int i = 0;
     for (i = 0; i < r.omega.res; i++) {
       fprintf(fp, "%f, ", r.omega.waveform[i]);
     }
     fprintf(fp, "}");
     fflush(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, "crusher_dephasing: %g\n", r.crusher_dephasing);
   fprintf(fp, "bridge_crushers: %d\n", r.bridge_crushers);
   fprintf(fp, "pregrad_area_offset: %g\n", r.pregrad_area_offset);
   fprintf(fp, "postgrad_area_offset: %g\n", r.postgrad_area_offset);
   ks_print_trap(r.pregrad, fp);
   ks_print_trap(r.grad, fp);
   ks_print_trap(r.postgrad, fp);
   if (r.gradwave.res > 0) {
     fprintf(fp, "     gradwave: Waveform assigned\n");
   }
   fprintf(fp, "grad2rf_start: %d\n", r.grad2rf_start);
   fprintf(fp, "rf2grad_end: %d\n", r.rf2grad_end);
 
   ks_print_rf(r.rf, fp);
 
   fflush(fp);
 
 } /* ks_print_selrf */

◆ ks_print_readwaves()

void ks_print_readwaves	(	KS_ECHOTRAIN *const	echotrain,
		const char *	suffix,
		int	rhkacq_uid
	)

ADDTITLEHERE

ADDDESCHERE

Parameters

	echotrain	ADDTEXTHERE
	suffix	ADDTEXTHERE
[in]	rhkacq_uid	ADDTEXTHERE

Returns: void

                                                                                            {
   if (echotrain->numwaves == 0) {
     return;
   }
 
   char filename[512];
 #ifdef PSD_HW /* on MR-scanner (host) */
   char outputdir_uid[512];
   char cmd[512];
   sprintf(outputdir_uid, "/usr/g/mrraw/kstmp/%010d/embed/", rhkacq_uid);
   sprintf(filename, "%s/readout_waveforms%s.bin", outputdir_uid, suffix);
   sprintf(cmd, "mkdir -p %s > /dev/null", outputdir_uid);
   system(cmd);
 #else /* e.g. WTools */
   sprintf(filename, "./readout_waveforms%s.bin", suffix);
 #endif
 
   FILE* fp = fopen(filename, "wb");
   int8_t wave_index;
 
   for (wave_index = 0; wave_index < echotrain->numwaves; wave_index++) {
     /* int object_index = echotrain->controls[wave_index].pg.object_index; */
     KS_READWAVE* const rw = &echotrain->readwaves[wave_index];
     const int16_t numplaced =ks_numplaced(&rw->grad.base);
     if (numplaced == 0) {
       ks_error("%s: %s has not been pg'd. Not included in %s", __FUNCTION__, rw->grad.description, filename);
       continue;
     }
     const int8_t acq_dwell = rw->acq.filt.tsp;
     const int8_t grad_dwell = rw->grad.duration / rw->grad.res;
     const uint16_t grad_samples_during_acq = rw->acq.duration / grad_dwell;
     const int8_t nstates = rw->grad.base.nstates;
     fwrite(&wave_index, sizeof(wave_index), 1, fp);
     fwrite(&nstates, sizeof(nstates), 1, fp);
     fwrite(&numplaced, sizeof(numplaced), 1, fp);
     fwrite(&grad_samples_during_acq, sizeof(grad_samples_during_acq),   1, fp);
     fwrite(&acq_dwell, sizeof(acq_dwell), 1, fp);
     fwrite(&grad_dwell, sizeof(grad_dwell), 1, fp);
     if (rw->grad.base.nstates > 1) {
       int state = 0;
       for (; state < rw->grad.base.nstates; state++) {
         fwrite(&(rw->grad.p_waveformstates[state][rw->acqdelay / grad_dwell]), sizeof(float), grad_samples_during_acq, fp);
       }
     } else {
       fwrite(&rw->grad.waveform[rw->acqdelay / grad_dwell], sizeof(float), grad_samples_during_acq, fp);
     }
   }
   fflush(fp);
   fclose(fp);
 } /* ks_print_readwaves */

◆ 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 )

ADDTITLEHERE

ADDDESCHERE

Parameters

fname ADDTEXTHERE

Return values

STATUS ADDTEXTHERE

                                     {
     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

                                              {
   extern float ks_srfact, ks_qfact;
   if (ks_srfact / ks_qfact < 1/sqrt(3)){
     return(ks_syslimits_slewrate_phys());
   }
 #if EPIC_RELEASE >= 27
   return (ks_syslimits_ampmax(loggrd) / ((float)ks_syslimits_ramptimemax(loggrd) * loggrd.scale_3axis_risetime));
 #else
   return (ks_syslimits_ampmax(loggrd) / ks_syslimits_ramptimemax(loggrd));
 #endif
 }

◆ 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

                                               {
   extern float ks_srfact, ks_qfact;
   if (ks_srfact / ks_qfact < 1/sqrt(3)){
     return(ks_syslimits_slewrate_phys());
   }
 #if EPIC_RELEASE >= 27
   return (ks_syslimits_ampmax2(loggrd) / ((float)ks_syslimits_ramptimemax(loggrd) * loggrd.scale_2axis_risetime));
 #else
   return (ks_syslimits_ampmax2(loggrd) / ks_syslimits_ramptimemax(loggrd));
 #endif  
 }

◆ 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

                                               {
   extern float ks_srfact, ks_qfact;
   if (ks_srfact / ks_qfact < 1/sqrt(3)){
     return(ks_syslimits_slewrate_phys());
   }  
 #if EPIC_RELEASE >= 27
   return (ks_syslimits_ampmax1(loggrd) / ((float)ks_syslimits_ramptimemax(loggrd) * loggrd.scale_1axis_risetime));
 #else
   return (ks_syslimits_ampmax1(loggrd) / ks_syslimits_ramptimemax(loggrd));
 #endif  
 
 }

◆ 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;
   case OMEGA:
     return 5e6;
   default:
     return 1.0;
   }
 }

◆ ks_syslimits_ampmax_phys()

float ks_syslimits_ampmax_phys ( )

ADDTITLEHERE

                                  {
   return FMin(3, phygrd.xfs,    phygrd.yfs,    phygrd.zfs);
 }

◆ ks_syslimits_ramptimemax_phys()

int ks_syslimits_ramptimemax_phys ( )

ADDTITLEHERE

                                     {
   /* ramptime at full gradient scale */
   return IMax(3, phygrd.xrt, phygrd.yrt, phygrd.zrt);
 }

◆ ks_syslimits_slewrate_phys()

float ks_syslimits_slewrate_phys ( )

ADDTITLEHERE

                                    {
   return ks_syslimits_ampmax_phys()/((float) ks_syslimits_ramptimemax_phys());
 }

◆ ks_cycles_to_iphase()

unsigned short ks_cycles_to_iphase ( double cycles )

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] cycles periods

Return values

unsigned iphase to use on THETA board on hardwarewrapper of ks_cycles_to_iphase for degrees

                                                   {
     /* Actual period for u14 */
     static const unsigned short FS_2PI_u14 = (1<<14); 
     /* Want the fractional part */
     cycles -= (long)cycles; 
     /* Force positive */
     cycles++; 
     /* Scale to u14 domain then shift two bits to the 
        left for compatibility with FS_2PI [u16] period. */
     return (unsigned short)(cycles * (double)FS_2PI_u14 + 0.5) % FS_2PI_u14 << 2;
 } /* ks_cycles_to_iphase */

◆ ks_degrees_to_iphase()

unsigned short ks_degrees_to_iphase ( double degrees )

wrapper of ks_cycles_to_iphase for radians

                                                     {
   return ks_cycles_to_iphase(degrees / 360.0);
 } /* wrapper for ks_cycles_to_iphase */

◆ ks_radians_to_iphase()

unsigned short ks_radians_to_iphase ( double radians )

                                                     {
   return ks_cycles_to_iphase(radians / (2.0 * PI));
 } /* wrapper for ks_cycles_to_iphase */

◆ 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_compute_params()

void ks_wave_compute_params ( KS_WAVE *const wave )

Fills the members of the KS_WAVE sequence object

max_amp, min_amp, abs_max_amp, abs_max_slew, area

Parameters

[in] wave KS_WAVE object

Return values

void

                                                   {
   /* pre-compute fields: max_amp, min_amp, abs_max_amp, abs_max_slew, area */
   wave->abs_max_slew = 0.0;
   float val = wave->waveform[0];
   wave->area = val;
   wave->min_amp = val;
   wave->max_amp = val;
 
   int i;
   for(i = 1; i < wave->res; i++) {
     val = wave->waveform[i];
     wave->area += val;
     if (val < wave->min_amp) {
       wave->min_amp = val;
     } 
     if (val > wave->max_amp) {
       wave->max_amp = val;
     }
     float slew = fabs(val - wave->waveform[i-1]);
     if (slew > wave->abs_max_slew) {
       wave->abs_max_slew = slew;
     }
   }
   float dwell = (float)wave->duration / (float)wave->res;
   wave->abs_max_slew /= dwell;
   wave->area *= dwell;
   /* maximum amplitude in wave (in its own units, like e.g. [G/cm] or [degrees]) */
   wave->abs_max_amp = (fabs(wave->min_amp) > fabs(wave->max_amp)) ? fabs(wave->min_amp) : fabs(wave->max_amp);
 }

◆ 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,
		int *	index
	)

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
[out]	index	Index in waveform where max slewrate is. Can be NULL if you are not interested.

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;
       if (index != NULL) {
         *index = i;
       }
     }
   }
   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, NULL);
 }

◆ 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_wave_time2area()

int ks_wave_time2area	(	const KS_WAVE *	wave,
		float	area_in
	)

Calculates the time in [us] that it takes a wave to achieve a certain area

Parameters

[in]	wave	Pointer to KS_WAVE
[in]	area_in	float [(G/cm) * us]

Return values

time [us]

                                                           {
   float dwell = wave->duration / wave->res;
   int time_dwells = 0;
   float area = 0.0f;
   for (time_dwells = 0; time_dwells < wave->res; time_dwells++) {
     area += wave->waveform[time_dwells] * dwell;
     if (fabs(area) > area_in) { /* area_in should be positive */
       break;
     }
   }
   if (time_dwells == wave->res) {
     if (areSame(area_in, area)) {
       return wave->duration;
     }
     return KS_NOTSET;
   }
   /* Now step back and find the fractional part */
   area -= wave->waveform[time_dwells] * dwell;
   float f = fabs((area_in - fabs(area)) / (wave->waveform[time_dwells] * dwell));
   return (int)(((float)(time_dwells) + f) * dwell + 0.5f);
 }

◆ 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];
   }
   area *= 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_iwave_area()

long ks_iwave_area	(	const KS_IWAVE	iwave,
		int	start,
		int	end,
		int	dwelltime
	)

Returns the area of an interger waveform (not in use), used for exact areas

Parameters

[in]	iwave	KS_IWAVE (short 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_IWAVE over the specified interval in aribtrary units

                                                                                   {
   int i;
   long area = 0;
   int start_indx = CEIL_DIV(start, dwelltime);
   int end_indx = end / dwelltime;
 
   if (iwave == 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 += iwave[i];
   }
   area *= 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 += iwave[start_indx - 1] * ((start_indx * dwelltime) - 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 += iwave[end_indx + 1] * (end - (end_indx * dwelltime));
   }
 
   return 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_wave_full_area()

float ks_wave_full_area ( const KS_WAVE * wave )

Returns the area of a KS_WAVE object over its entire duration

Parameters

[in] wave KS_WAVE object

Return values

area	The area of the KS_WAVE object in [(G/cm) * us]

                                              {
   return ks_wave_area(wave, 0, wave->duration);
 }

◆ 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_wave_compute_params(wave_mod);
 
 }

◆ 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_eval_readwave_negatestate()

void ks_eval_readwave_negatestate	(	KS_READWAVE *	readwave,
		int	state
	)

#### Modify an existing state to its negative (flipped polarity readout)

Parameters

[in,out]	readwave	A pointer to KS_READWAVE you would like to negate
[in]	state	The wavestate to modify

                                                                     {
   if (state == 0) {
     KS_WAVE* wave = &readwave->grad;
     wave->max_amp *= -1;
     wave->min_amp *= -1;
     float min_amp = wave->max_amp;
     wave->max_amp = wave->min_amp;
     wave->min_amp = min_amp;
     wave->area *= -1;
   }
 
   ks_waveform_multiplyval(readwave->grad_states[state],  -1, readwave->grad.res);
   ks_waveform_multiplyval(readwave->omega_states[state], -1, readwave->omega.res);
 }

◆ 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_wave_compute_params(wave_mod);
 }

◆ 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);
   /* max_amp, min_amp, abs_max_amp, abs_max_slew, area */
   wave->max_amp *= val;
   wave->min_amp *= val;
   if (val < 0.0) { /* swap min/max for negative val */
     float min_amp = wave->max_amp;
     wave->max_amp = wave->min_amp;
     wave->min_amp = min_amp;
   }
   wave->abs_max_amp *= fabs(val);
   wave->abs_max_slew *= fabs(val);
   wave->area *= val;
 }

◆ 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);
   /* max_amp, min_amp, abs_max_amp, abs_max_slew, area */
   wave->max_amp += val;
   wave->min_amp += val;
   if(-wave->min_amp > wave->max_amp) {
     wave->abs_max_amp = -wave->min_amp;
   } else {
     wave->abs_max_amp = wave->max_amp;
   }
   wave->area += (val * wave->duration);
 }

◆ ks_waveform2iwave()

STATUS ks_waveform2iwave	(	KS_IWAVE	iwave,
		const KS_WAVEFORM	waveform,
		int	res,
		int	board,
		float	max,
		float	fs_factor
	)

(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_cycles_to_iphase(). 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
[in]	max	max value of the waveform
[in]	fs_factor	how much of the dynamic range to use 1 = FULL

Return values

STATUS SUCCESS or FAILURE

                                                                                                                      {
   int i;
   if (board != THETA) {
     /* 16383 - FS signed 15bit value (2^15) / 2 - 1 */
     const float FS = (float)(max_pg_wamp>>1) * fs_factor / max;
     for (i = 0; i < res; i++) {
       iwave[i] = ((short) (FS * waveform[i]) << 1);
     }
   } else {
     for (i = 0; i < res; i++) {
       /* Theta board used a 14-bit representation */
       iwave[i] = ((short) ks_degrees_to_iphase(waveform[i]));
     }
   }
 
   /* 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_cycles_to_iphase(). 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, wave->abs_max_amp, wave->fs_factor);
 }

◆ 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)) {
     return ks_error("ks_pg_trap(%s): All timing parameters must be divisible by 4", trap->description);
   }
 
   if ((trap->ramptime < 4) || (trap->plateautime < 4) || (trap->duration < 4)) {
     return ks_error("ks_pg_trap(%s): All timing parameters must be at least 4 us", trap->description);
   }
 
   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) {
     return ks_error("ks_pg_trap(%s): Invalid position %d, it must be between 4us and 4s", trap->description, loc.pos);
   }
 
   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) {
     return ks_error("ks_pg_trap(%s): Invalid ampscale %g, it must be between -1.0 and 1.0", trap->description, loc.ampscale);
   }
 
   if (loc.board != XGRAD && loc.board != YGRAD && loc.board != ZGRAD && loc.board != OMEGA) {
     return 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);
   }
 
   /* compute the minimum fs_factor */
   float min_fs_factor = fabs(trap->amp) / boardmax;
   /* change fs_factor to min if needed */
   if (trap->fs_factor < min_fs_factor) {
     ks_dbg("%s: (%s) trap->fs_factor too low, modified from %1.2f to: %1.2f", __FUNCTION__, trap->description, trap->fs_factor, min_fs_factor);
     trap->fs_factor = min_fs_factor;
   }
 
   if (trap->fs_factor > 1.0f) {
     ks_error("ks_pg_trap(%s): Corner case where an exact representation of the trap shape is not possible amp %g [g/cm] with a ramp period of %i us", trap->description, trap->amp, trap->ramptime);
   }
 
   if (fabs(trap->amp * loc.ampscale) > boardmax) {
     return 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]);
   }
 
   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) {
       return 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);
     }
 
     if (!ctrl->gradrf.is_cleared_on_tgt) /* Reset gradrfctrl on tgt to remove dead pointers copied from host. */
     {
       ks_tgt_reset_gradrfctrl(&ctrl->gradrf);
     }
 
     const int res = trap->ramptime / GRAD_UPDATE_TIME;
     short * attack = (short *) AllocNode(res * sizeof(short));
     short * decay = (short *) AllocNode(res * sizeof(short));
 
     if(ctrl->discrete_representation == KS_DISCRETE_REPRESENTATION_SYMMETRIC) {
 
       ks_pg_trap_make_symramps(trap, min_fs_factor, attack, decay);
 
     }
     /* now set the plateau once all adjustments of fs_factor are over */
     short plateau = (short)(trap->fs_factor * max_pg_wamp);
 
     /* 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);
 
           if(ctrl->discrete_representation == KS_DISCRETE_REPRESENTATION_SYMMETRIC) {
             createreserve(&trap->wfpulse[i][G_ATTACK], (WF_PROCESSOR) i, res);
             trap->wfpulse[i][G_ATTACK].type = TYPEXTERNAL;
             movewaveimm(attack, &trap->wfpulse[i][G_ATTACK], (int) 0, res, TOHARDWARE);
 
             createreserve(&trap->wfpulse[i][G_DECAY], (WF_PROCESSOR) i, res);
             trap->wfpulse[i][G_DECAY].type = TYPEXTERNAL;
             movewaveimm(decay, &trap->wfpulse[i][G_DECAY], (int) 0, res, TOHARDWARE);
           } else {
             createramp(&(trap->wfpulse[i][G_ATTACK]), (WF_PROCESSOR) i, trap->ramptime, 0, plateau,  res, 1.0);
             createramp(&(trap->wfpulse[i][G_DECAY]),  (WF_PROCESSOR) i, trap->ramptime, plateau, 0,  res, 1.0);
           }
           createconst(&(trap->wfpulse[i][G_PLATEAU]), (WF_PROCESSOR) i, trap->plateautime, plateau);
 
           linkpulses(3, &(trap->wfpulse[i][G_PLATEAU]), &(trap->wfpulse[i][G_ATTACK]), &(trap->wfpulse[i][G_DECAY]));
 
         } else {
 
           trap->wfpulse[i] = NULL;
 
         }
 
       } /* per board */
       FreeNode(attack);
       FreeNode(decay);
 
     } /* 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 / (trap->fs_factor * boardmax)));
       createinstr(&(trap->wfpulse[loc.board][G_PLATEAU]),
                   corrected_pos + trap->ramptime,
                   trap->plateautime,
                   (int)(trap->amp * loc.ampscale * MAX_PG_IAMP / (trap->fs_factor * boardmax)));
       createinstr(&(trap->wfpulse[loc.board][G_DECAY]),
                   corrected_pos + trap->ramptime + trap->plateautime,
                   trap->ramptime,
                   (int)(trap->amp * loc.ampscale * MAX_PG_IAMP / (trap->fs_factor * 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 */
     /* update instance counter on host only. This counter is used to allocate the right amount of WFINSTANCEs on IPG */
     trap->base.ninst++;
 
     KS_SEQLOC *locs = (KS_SEQLOC *) realloc(trap->locs, sizeof(KS_SEQLOC)*trap->base.ninst);
     if (!locs) {
       return KS_THROW("Realloc failed");
     }
     trap->locs = locs;
     trap->locs[trap->base.ninst-1] = loc;
 
 
     ks_sort_loc_by_timeboard(trap->locs, 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);
       KS_RAISE(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) {
       return 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);
     }
 
     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 */
 
     /* the ADC start time is the bin center so we need to shift by half a tsp */
     /* tsp is always a multiple of 2, so div by two is exact here for int representation */
     acqwin_start = pos + psd_grd_wait + (int)(read->filt.tsp / 2.0f);
     /* in symmetric mode the waveforms are shifted half a GRAD_UPDATE_TIME earlier */
     if(ctrl->discrete_representation == KS_DISCRETE_REPRESENTATION_SYMMETRIC) {
       acqwin_start -= GRAD_UPDATE_TIME / 2;
     }
 
     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->base.ninst++; /* update acq counter on host */
 
     int *locs = (int*) realloc(read->pos, sizeof(int)*read->base.ninst);
     if (!locs) {
       return KS_THROW("Realloc failed");
     }
     read->pos = locs;
     read->pos[read->base.ninst-1] = pos;
   }
 #endif /* IPG */
 
   status = ks_eval_addreadtogradrfctrl(&ctrl->gradrf, read);
   KS_RAISE(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

                                                                                   {
 
   STATUS status;
   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) && !areSame(loc.ampscale, 0.0)) {
     return ks_error("%s(%s): .ampscale %g must be exactly +1, 0 or -1 for readout gradients", __FUNCTION__, readtrap->grad.description, loc.ampscale);
   }
 
   /*** acq ***/
   status = ks_pg_read(&readtrap->acq, loc.pos + readtrap->acqdelay, ctrl);
   KS_RAISE(status);
 
   /*** trapezoid ***/
   status = ks_pg_trap(&readtrap->grad, loc, ctrl);
   KS_RAISE(status);
 
   /* 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 + readtrap->acqdelay;
     omegaloc.ampscale = 1.0; /* just unity value for conformance. It does not matter during scanning, since ks_scan_omegahz() ignores this value */
     status = ks_pg_wave(&readtrap->omega, omegaloc, ctrl);
     KS_RAISE(status);
 
 #ifdef IPG
     short * iwave = (short *) AllocNode(readtrap->omega.res * sizeof(short));
     movewaveimm(iwave, &readtrap->omega.wfpulse[OMEGA][0], 0, readtrap->omega.res, FROMHARDWARE);
 
     /* phase is accumulated at 10 MHz */
     int k;
     readtrap->omega_iwave_phase_at_echo = 0;
     for(k = 0; k < (readtrap->time2center - readtrap->acqdelay); k++) {
       readtrap->omega_iwave_phase_at_echo += 10 * iwave[k / GRAD_UPDATE_TIME];
     }
     FreeNode(iwave);
 #endif 
 
   }
 
   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

graphical description

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

This function adds an instruction and a waveform (state 0) in the sequencer memory. If you intend to use states this function must always be called first, before you try: ks_pg_addwaveformstate. For more infor see ks_pg_addwaveformstate

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

                                                                       {
 
   STATUS status;
   (void)status;
 
   float boardmax;
   char boardc[8] = "xyzrrto"; /* x,y,z,rho1,rho2,theta,omega */
 
   boardmax = ks_syslimits_gradtarget(loggrd, loc.board); /* returns 1.0 for non-gradients boards */
 
   float min_fs_factor = wave->abs_max_amp / boardmax;
   if (wave->fs_factor < min_fs_factor) {
     wave->fs_factor = min_fs_factor;
   }
 
   /* 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);
   }
 
 #ifndef IPG
   /* HOST: eval the wave to ensure its members have been computed correctly */
   int isGrad = (loc.board == XGRAD || loc.board == YGRAD || loc.board == ZGRAD);
   ks_wave_compute_params(wave);
   /* we use config variables because loggrd or physgrd may be derated for silent scanning purposes selrf waves are timing sensitive */
   extern float cfxfs, cfyfs, cfzfs;
   extern int cfrmp2xfs, cfrmp2yfs, cfrmp2zfs;
   float slew_limit = sqrt(3.0) * FMin(3, cfxfs, cfyfs, cfzfs)/IMax(3,cfrmp2xfs,cfrmp2yfs,cfrmp2zfs);
   /* multiply by 1.00001 to account for errors cause by floating point calcs */
   if ((isGrad) && (fabs(wave->abs_max_slew * loc.ampscale) > (1.00001 * slew_limit))) {
     int _i;
     ks_waveform_maxslew(wave->waveform, wave->res, wave->duration, &_i);
     KS_THROW("wave(%s) exceeds the least conservative gradient slew rate limit at index %d. This will not scan. %f > %f", wave->description, _i, fabs(wave->abs_max_slew * loc.ampscale), (1.00001 * slew_limit));
 #ifdef PSD_HW
      return FAILURE; /* TODO: why not return the error on the host? */
 #endif
   }
 #endif
 
 #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_THROW("%s: Refusing to place wave since seqctrl.duration = 0 (indicating `%s` not to be played in scan())", 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->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 %d times 'res' (%d) for gradient boards", wave->description, wave->duration, GRAD_UPDATE_TIME, wave->res);
     }
     if (wave->gradwave_units == KS_GRADWAVE_ABSOLUTE && !areSame(loc.ampscale,1.0)) {
       ks_error("ks_pg_wave(%s): ampscale must be +1.0 for gradwave with absolute units", wave->description); /* TODO: missing return */
     }
   } 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(wave->abs_max_amp * loc.ampscale) > boardmax && loc.board != THETA && loc.board != OMEGA) {
     return  ks_error("ks_pg_wave(%s): wave amplitude (%.2f) exceeds maximum (%g) for board %c", wave->description, wave->abs_max_amp * loc.ampscale, boardmax, boardc[loc.board]);
   }
 
   if (loc.board != OMEGA) {
     loc.pos = RUP_GRD(loc.pos);
   }
 
 #ifdef HOST_TGT
 
   /* HOST */
   /* update instance counter on host only. This counter is used to allocate the right amount of WFINSTANCEs on IPG */
   wave->base.ninst++;
 
   KS_SEQLOC *locs = (KS_SEQLOC*) realloc(wave->locs, sizeof(KS_SEQLOC)*wave->base.ninst);
   if (!locs) {
     return KS_THROW("Realloc failed");
   }
   wave->locs = locs;
   wave->locs[wave->base.ninst-1] = loc;
 
   ks_sort_loc_by_timeboard(wave->locs, wave->base.ninst);
 
   /* To check if pg has been called */
   wave->base.nstates = 1; /* this function will create state0 */
   wave->p_waveformstates[0] = wave->waveform;
   /* 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
 
   {
 
     short i;
     int isrf;
     char tmpstr[KS_DESCRIPTION_LENGTH + 14];
 
     if (wave->base.ngenerated >= wave->base.ninst) {
       return 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);
     }
 
 
     /* 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 */
     if (wave->wfpulse[loc.board] == NULL) {
       WF_PULSE wfInit = INITPULSE;
       wave->wfpulse[loc.board] = (WF_PULSE *) AllocNode(wave->base.nstates * sizeof(WF_PULSE)); /* allocate memory for nstates */
       wave->wave_ptrs = (LONG *) AllocNode(wave->base.nstates * sizeof(LONG));
       /* give the pulse for each state a unqiue name */
       for (i = 0; i < wave->base.nstates; i++) {
         wave->wfpulse[loc.board][i] = wfInit;
         sprintf(tmpstr, "%s.state%d.%c", wave->description, i, boardc[loc.board]);      
         pulsename(&(wave->wfpulse[loc.board][i]), tmpstr);
         wave->wfpulse[loc.board][i].type = TYPEXTERNAL;
       }
 
       /* wave -> short int wave for hardware use. All waveforms but THETA are autoscaled to +/- max_pg_wamp (32766)*/
       short * iwave = (short *) AllocNode(wave->res * sizeof(short));
       status = ks_wave2iwave(iwave, wave, loc.board);
       KS_RAISE(status);
 
       /* STATE 0 is the primary waveform; we reserve the memory for this pulse here*/
       createreserve(&wave->wfpulse[loc.board][0], (WF_PROCESSOR) loc.board, wave->res);
       movewaveimm(iwave, &wave->wfpulse[loc.board][0], (int) 0, wave->res, TOHARDWARE);
       getwave(&wave->wave_ptrs[0], &wave->wfpulse[loc.board][0]);
       FreeNode(iwave);
     } /* wfpulse[loc.board] == NULL */
 
     int iamp;
 
     /* create instruction at the current position */
     isrf = loc.board == RHO || loc.board == RHO2 || loc.board == THETA || loc.board == OMEGA;
 
     switch (loc.board) {
       case RHO:
       case RHO2:
       {
         wave->fs_factor = 1.0f;
         iamp = (int)((wave->abs_max_amp * loc.ampscale / boardmax) * MAX_PG_IAMP);
         break;
       }
       case XGRAD:
       case YGRAD:
       case ZGRAD:
       {
         iamp = (int)((wave->abs_max_amp * loc.ampscale / (wave->fs_factor * boardmax)) * MAX_PG_IAMP);
         break;
       }
       case OMEGA:
       {
         /* The TARDIS_FREQ_RES = 10e6 / (1 << 24) is the effect of one bit. This is the overflow period of the 24-bit register
            when incremented by 1 at 10 MHz = 0.586 Hz.
            The product of iwave and iamp is only 16 bit wide and is therefore shift left 8 bits before being added to the accumulator,
            this effectively mulitplies this value by 256 - so we need to shift 8 to the right here to be in the correct units [Hz] */
         iamp = (int)((wave->abs_max_amp * loc.ampscale / (wave->fs_factor * TARDIS_FREQ_RES))) >> 8;
         break;
       }
       case THETA:
       {
         iamp = (int)(loc.ampscale * MAX_PG_IAMP);
         break;  
       }
       default:
         KS_RAISE(ks_error("Wave scaling is currently not implemented for board: %i", loc.board));
     }
 
     createinstr(&wave->wfpulse[loc.board][0],
                 (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][0].ninsts - 1;
     wave->wfi[wave->base.ngenerated].wf = wave->wfpulse[loc.board];
     wave->wfi[wave->base.ngenerated].loc = loc;
 
     wave->base.ngenerated++;
 
     wave->p_waveformstates[0] = wave->waveform;
 
     /* 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);
     KS_RAISE(status);
   }
     wave->current_state = (int *) AllocNode(wave->base.ngenerated * sizeof(int*));
 
   return SUCCESS;
 
 } /* ks_pg_wave */

◆ ks_pg_addwaveformstate()

STATUS ks_pg_addwaveformstate	(	KS_WAVE *	wave,
		KS_WAVEFORM	waveform,
		int	state_index
	)

Allocates an additional waveformstate in sequencer memory

graphical description

This function reserves additional space on the sequencer waveform memory and assignes the state=state_index to the waveform. During the scan it is then possible to make any instance of theat KS_WAVE object point to an alternative state using the fuction ks_scan_setwavestate, effectively changing the waveform shape in real time. This approach is much more effecient and safer than ks_scan_wave2hardware because we can ensure the waveform states used pass gradient and SAR limits. A drawback is that sequencer memory is not unlimited, so we have limited the number of states to #define KS_WAVE_MAXNSTATES 16 (in future we will increase this). If you require more waveform shapes than that, then you would have to use the more complicated ks_scan_wave2hardware.

ks_pg_wave needs to be called on the KS_WAVE object before you can use this function. It is also important to note that ks_pg_wave reserves state0, so don't overwrite 0 if you intend to use it. This function can be used on any KS_WAVE object. eg. if you would like to add multiple RF envelopes to a KS_SELRF compound object you can add additional states to the KS_WAVE members (like &myselrf->rf.wave) once you have called the pg_selrf function.

Parameters

[in,out]	wave	Pointer to a KS_WAVE sequence object
[in]	waveform	A KS_WAVEFORM representing a new state/shape
[in]	state_index

                                                                                      {
 
   STATUS status;
   (void)status;
 
 #ifdef HOST_TGT
   const float waveform_abs_max = ks_waveform_absmax(waveform, wave->res);
   if(wave->base.nstates == 0) {
     return ks_error("%s [%s]: cannot add state before ks_wave_pg is called.", __FUNCTION__, wave->description);
   }
 
   if (state_index == wave->base.nstates) {
     wave->base.nstates = state_index + 1;
   }
 
   if(wave->max_amp < waveform_abs_max) {
     return ks_error("%s [%s]: can't add a waveform state with a larger amplitude.", __FUNCTION__, wave->description);
   }
 
   int idx_slew_max;
   float slew_max = ks_waveform_maxslew(waveform, wave->res, wave->duration, &idx_slew_max);
   /* times > 1 in case of float rounding */
   extern float cfxfs, cfyfs, cfzfs;
   extern int cfrmp2xfs, cfrmp2yfs, cfrmp2zfs;
   float slew_limit = sqrt(3.0) * FMin(3, cfxfs, cfyfs, cfzfs)/IMax(3,cfrmp2xfs,cfrmp2yfs,cfrmp2zfs)* 1.00001;
   int i = 0;
   for (; i < wave->base.ninst; i++) {
     KS_SEQLOC loc = wave->locs[i];
     int isGrad = (loc.board == XGRAD || loc.board == YGRAD || loc.board == ZGRAD);
     if ((isGrad) && (slew_max > slew_limit)) {
      /* TODO: no return? */
 #ifdef PSD_HW
      return KS_THROW("[%s]: state %i exceeds the least conservative gradient slew rate limit at index %d. %f > %f", 
                       wave->description, state_index, idx_slew_max, slew_max, slew_limit);
 #else
      KS_THROW("[%s]: state %i exceeds the least conservative gradient slew rate limit at index %d. This will not scan %f > %f", 
                       wave->description, state_index, idx_slew_max, slew_max, slew_limit);
 #endif
     }
     if (loc.board == RHO) {
       if (waveform_abs_max > 1.0f) {
         return KS_THROW("[%s]: RHO waves must be normalised (%1.3f > 1)", wave->description, waveform_abs_max);
       }
     }
   }
 #endif
 
   if (state_index < KS_WAVE_MAXNSTATES) {
     wave->p_waveformstates[state_index] = waveform;
   } else {
     return ks_error("%s [%s]: you have exceeded the maximum number of wavestates = %i", __FUNCTION__, wave->description, KS_WAVE_MAXNSTATES);
   }
 
   /*TODO: test slew rate for this board if(wave->abs_max_slew < ks_waveform_maxslew(waveform, wave->res, wave->duration)) {
     return ks_error("%s [%s]: can't add a waveform state with a higher max slew rate", __FUNCTION__, wave->description);
   }*/
 
 #ifndef HOST_TGT
   if(state_index > wave->base.nstates) 
     return ks_error("ks_pg_addwavestate: state_index too large");
   /* wave -> short int wave for hardware use. All waveforms but THETA are autoscaled to +/- max_pg_wamp (32766)*/
   WF_PULSE * wfpulse;
   int board;
   short * iwave = (short *) AllocNode(wave->res * sizeof(short));
   int skippedboards = 0;
   for(board = 0; board < 7; board++) {
     wfpulse = wave->wfpulse[board];
     if (!wfpulse) {
       skippedboards++;
       continue;
     }
 
     float max_amp;
     if (board == RHO) {
       /* RHO waves are scaled after predownload */
       max_amp = 1.0;
     } else {
       max_amp = wave->abs_max_amp;
     }
     /* Here we adjust the iwave amplitude to achieve the correct final amplitude iamp*iwave*/
     status = ks_waveform2iwave(iwave, 
                                waveform, 
                                wave->res, 
                                board, 
                                max_amp, 
                                wave->fs_factor);
     KS_RAISE(status);
 
     createreserve(&wfpulse[state_index], (WF_PROCESSOR) board, wave->res);
     movewaveimm(iwave, &wfpulse[state_index], (int) 0, wave->res, TOHARDWARE);
     getwave(&wave->wave_ptrs[state_index], &wave->wfpulse[board][state_index]);
   }
   FreeNode(iwave);
 
   if (skippedboards == 7) {
     return ks_error("%s [%s] -> state %d: no WF_PULSES have been allocated, something is very wrong!", __FUNCTION__, wave->description, state_index);
   }
 
 #endif 
 
   return SUCCESS;
 }

◆ 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, see ks_scan_setwavestate, ks_scan_wave2hardware if you want to modiy waveforms during the scan.

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_hwlimits() 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_hwlimits()

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

                                                                 {
 
   STATUS status;
 
   /* 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) {
       return ks_error("ks_pg_rf (%s): The duration of the omega waveform must be equal to the RF duration", rf->rfwave.description);
     }
   }
   if (rf->thetawave.res) {
     if (rf->thetawave.duration != rf->rfwave.duration) {
       return ks_error("ks_pg_rf (%s): The duration of the theta waveform must be equal to the RF duration", rf->rfwave.description);
     }
   }
 
   /* 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);
     KS_RAISE(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)) {
     return ks_error("ks_pg_rf @tgt(%s): pulsegen was never run on HOST (rf->rfpulse.num = 0)", rf->rfwave.description);
   }
 
   if (rf->rfpulse.activity == 0) {
     return ks_error("ks_pg_rf @tgt(%s): RF pulse with zero activity", rf->rfwave.description);
   }
 
   /* 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;
   status = ks_pg_wave(&rf->rfwave, loc, ctrl);
   KS_RAISE(status);
 
 #ifdef IPG
   /* add SSP RF bits that handles the frequency control and blanking/unblanking the receiver */
   addrfbits(&rf->rfwave.wfpulse[RHO][0], 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][0], rf->rfwave.base.ngenerated - 1);
 #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) {
     status = ks_pg_wave(&rf->omegawave, loc, ctrl);
     KS_RAISE(status);
 
 #ifdef IPG
     short * iwave = (short *) AllocNode(rf->omegawave.res * sizeof(short));
     movewaveimm(iwave, &rf->omegawave.wfpulse[OMEGA][0], 0, rf->omegawave.res, FROMHARDWARE);
 
     /* phase is accumulated at 10 MHz */
     int k;
     rf->omega_iwave_phase_at_iso = 0;
     for(k = 0; k < rf->start2iso; k++) {
       rf->omega_iwave_phase_at_iso += 10 * iwave[k / GRAD_UPDATE_TIME];
     }
     FreeNode(iwave);
 #endif 
   }
 
 #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][0], 0, loc.pos + psd_rf_wait, rf->omegawave.duration);
   }
 #endif
 
   /* place the THETA wave */
   loc.board = THETA;
   if (rf->thetawave.res) {
     status = ks_pg_wave(&rf->thetawave, loc, ctrl);
     KS_RAISE(status);
   }
 
 #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][0], 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, see ks_scan_setwavestate, ks_scan_wave2hardware if you want to modiy waveforms during the scan.

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

                                                                          {
 
   STATUS status;
   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) and ramp of slicesel (if present) */
   rfloc.pos += selrf->grad2rf_start;
 
   /************* generate the RF (incl. optional THETA & OMEGA) *************/
 
   status = ks_pg_rf(&selrf->rf, rfloc, ctrl);
   KS_RAISE(status);
 
   /************************ 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 */
   status = ks_pg_trap(&selrf->pregrad, gradloc, ctrl);
   KS_RAISE(status);
   gradloc.pos += selrf->pregrad.duration;
 
 
 
   /* slice select gradient */
   gradloc.ampscale = 1.0;
 
   if (selrf->gradwave.res) {
     /* use gradwave (not trapezoid) */
     status = ks_pg_wave(&selrf->gradwave, gradloc, ctrl);
     KS_RAISE(status);
 
     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 {
       status = ks_pg_trap(&selrf->grad, gradloc, ctrl);
       KS_RAISE(status);
 
       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;
   status = ks_pg_trap(&selrf->postgrad, gradloc, ctrl);
   KS_RAISE(status);
   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->max_duration == 0 || wait->pg_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->pg_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->pg_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
   {
     KS_SEQLOC *locs = (KS_SEQLOC*) realloc(wait->locs, sizeof(KS_SEQLOC)*(wait->base.ninst + last - first + 1));
     if (!locs) {
       return KS_THROW("Realloc failed");
     }
     wait->locs = locs;
 
     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++;
       ks_sort_loc_by_timeboard(wait->locs, wait->base.ninst);
       STATUS status = ks_eval_addwaittogradrfctrl(&ctrl->gradrf, wait);
       KS_RAISE(status);
     }
   }
 #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);
KS_RAISE(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);

KS_RAISE(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

                                                                                                              {
   STATUS status;
   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);
 
   status = ks_pg_wait(&isirot->waitfun, tmploc, ctrl);
   KS_RAISE(status);
 
   tmploc.pos += RUP_GRD(isirot->waitfun.max_duration);
 
   status = ks_pg_wait(&isirot->waitrot, tmploc, ctrl);
   KS_RAISE(status);
 
 
 #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

                                                                              {
 
   STATUS status;
   int readaxis, blipaxis, sliceaxis;
   KS_SEQLOC tmploc = KS_INIT_SEQLOC;
   int maxduration;
 
   if (!epi) { return ks_error("Ops"); }
 
   /* 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:
     return ks_error("ks_pg_epi_dephasers: loc.board is not valid: %d", loc.board);
   }
 
   /* 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;
     status = ks_pg_trap(&epi->readphaser, tmploc, ctrl);
     KS_RAISE(status);
   }
 
   /* 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;
     status = ks_pg_phaser(&epi->blipphaser, tmploc, ctrl);
     KS_RAISE(status);
   }
 
    /* balancing CAIPI-blip */
   if (epi->caipiblip.duration > 0) {
     tmploc.board = sliceaxis;
     tmploc.pos = loc.pos + maxduration - epi->caipiblip.duration;
     tmploc.ampscale = fabs(loc.ampscale);
     if (ks_pg_trap(&epi->caipiblip, 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;
     status = ks_pg_phaser(&epi->zphaser, tmploc, ctrl);
     KS_RAISE(status);
   }
 
   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

                                                                              {
 
   STATUS status;
   int readaxis, blipaxis, sliceaxis;
   KS_SEQLOC tmploc = KS_INIT_SEQLOC;
 
   if (!epi) { return ks_error("Ops"); }
 
   /* 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:
     return ks_error("ks_pg_epi_rephasers: loc.board is not valid: %d", loc.board);
   }
 
   /* 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 && !(epi->epi_readout_mode == KS_EPI_BIPOLAR)) || (epi->epi_readout_mode == KS_EPI_FLYBACK)) {
        /* same polarity of rephaser as dephaser if odd ETL and not epi->splitoddeven, or flyback */
       tmploc.ampscale = loc.ampscale;
     } else {
       tmploc.ampscale = -loc.ampscale;
     }
     status = ks_pg_trap(&epi->readphaser, tmploc, ctrl);
     KS_RAISE(status);
   }
 
   /* 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;
     status = ks_pg_phaser(&epi->blipphaser, tmploc, ctrl);
     KS_RAISE(status);
   }
 
   /* balancing CAIPI-blip */
   if (epi->caipiblip.duration > 0) {
     tmploc.board = sliceaxis;
     tmploc.pos = loc.pos;
     tmploc.ampscale = fabs(loc.ampscale);
     if (ks_pg_trap(&epi->caipiblip, 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;
     status = ks_pg_phaser(&epi->zphaser, tmploc, ctrl);
     KS_RAISE(status);
   }
 
   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

                                                                         {
 
   STATUS status;
   int readaxis, blipaxis, caipiaxis;
   KS_SEQLOC readloc = KS_INIT_SEQLOC;
   KS_SEQLOC bliploc = KS_INIT_SEQLOC;
   int i, s;
 
   if (!epi || !epi->read.grad.description) { return ks_error("Ops"); }
 
   /* 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; caipiaxis = ZGRAD; break;
   case KS_FREQY_PHASEX:
     readaxis = YGRAD; blipaxis = XGRAD; caipiaxis = ZGRAD; break;
   case KS_FREQX_PHASEZ:
     readaxis = XGRAD; blipaxis = ZGRAD; caipiaxis = YGRAD; break;
   case KS_FREQZ_PHASEX:
     readaxis = ZGRAD; blipaxis = XGRAD; caipiaxis = YGRAD; break;
   case KS_FREQY_PHASEZ:
     readaxis = YGRAD; blipaxis = ZGRAD; caipiaxis = XGRAD; break;
   case KS_FREQZ_PHASEY:
     readaxis = ZGRAD; blipaxis = YGRAD; caipiaxis = XGRAD; break;
   default:
     return ks_error("ks_pg_epi_echo: field 'board' in 2nd arg is not valid: %d", loc.board);
   }
 
   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)");
   }
 
   /* read trapezoid */
   readloc.board = readaxis;
   for (i = 0; i < epi->etl; i++) {
       if (epi->epi_readout_mode == KS_EPI_FLYBACK){
         status = ks_pg_readtrap(&epi->read, readloc, ctrl);
         KS_RAISE(status);
 
         readloc.pos += RUP_GRD(epi->read.grad.duration);
 
         /* No flyback needed for the last echo */
         if (i < epi->etl - 1){
           readloc.ampscale *= -1;
           status =  ks_pg_trap(&epi->read_flyback, readloc, ctrl);
           KS_RAISE(status);
 
           readloc.ampscale *= -1;
           readloc.pos += RUP_GRD(epi->read_flyback.duration + epi->read_spacing);
         }
 
     } else {
       int n_readouts_per_blip = (epi->epi_readout_mode == KS_EPI_SPLITODDEVEN ? 2 : 1);
       for (s = 0; s < n_readouts_per_blip; s++) { /* epi->splitoddeven can be 0 or 1 */
 
         if (epi->epi_readout_mode == KS_EPI_SPLITODDEVEN) {
           readloc.ampscale = (s % 2) ? -loc.ampscale : loc.ampscale; /* +1 or -1 */
         } else {
           readloc.ampscale = (i % 2) ? -loc.ampscale : loc.ampscale; /* +1 or -1 */
         }
         status = ks_pg_readtrap(&epi->read, readloc, ctrl);
         KS_RAISE(status);
 
         /* read_spacing is additional gap between lobes (normally 0) */
         readloc.pos += RUP_GRD(epi->read.grad.duration + epi->read_spacing);
 
       } /* for s */
     }
 
     /* 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->blip.duration / 2 - epi->read_spacing / 2);
       bliploc.ampscale = fabs(loc.ampscale);
       status = ks_pg_trap(&epi->blip, bliploc, ctrl);
       KS_RAISE(status);
 
       bliploc.board = caipiaxis;
       bliploc.pos = RUP_GRD(readloc.pos - epi->caipiblip.duration / 2 + epi->read_spacing / 2);
       status = ks_pg_trap(&epi->caipiblip, bliploc, ctrl);
       KS_RAISE(status);
     }
 
   } /* 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

                                                                    {
 
   STATUS status;
   KS_SEQLOC tmploc = loc;
   const int readfact = (epi->epi_readout_mode == KS_EPI_SPLITODDEVEN) ? 2 : 1;
 
   /* 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)");
   }
 
   status = ks_pg_epi_dephasers(epi, tmploc, ctrl);
   KS_RAISE(status);
 
   tmploc.pos += IMax(3, epi->readphaser.duration, epi->blipphaser.grad.duration, epi->zphaser.grad.duration);
 
   /* main epi train (w/o DE/REphasers) */
   status = ks_pg_epi_echo(epi, tmploc, ctrl);
   KS_RAISE(status);
 
   tmploc.pos += (epi->etl * readfact) * epi->read.grad.duration + ((epi->etl * readfact) - 1) * (epi->read_flyback.duration + epi->read_spacing);
 
   status = ks_pg_epi_rephasers(epi, tmploc, ctrl);
   KS_RAISE(status);
 
   return SUCCESS;
 } /* ks_pg_epi */

◆ ks_pg_get_trap_loc()

KS_SEQLOC ks_pg_get_trap_loc	(	KS_TRAP *	trap,
		int	instance
	)

Returns the location of a trap

This function should be called in the @pg section to find the SEQLOC of a PGed trap. If instance = -1 it returns the last SEQLOC of the last instance.

Parameters

[in]	trap
[in]	instance

Return values

KS_SEQLOC

                                                           {
 
   if (ks_numplaced(&trap->base) <= instance || instance < -1) {
     KS_THROW("%s: instance (%d) out of range [-1-%d)", __FUNCTION__, instance, trap->base.ngenerated);
     KS_SEQLOC tmploc = KS_INIT_SEQLOC;
     return tmploc; 
   }
 
   instance = (instance == -1) ? ks_numplaced(&trap->base) - 1 : instance;
 
 #ifdef HOST_TGT
   /* HOST */
   return trap->locs[instance];
 #else
   /* TARGET */
   return trap->wfi[instance].loc;
 #endif
 }

◆ ks_pg_get_wave_loc()

KS_SEQLOC ks_pg_get_wave_loc	(	KS_WAVE *	wave,
		int	instance
	)

Returns the location of a wave

This function should be called in the @pg section to find the SEQLOC of a PGed wave. If instance = -1 it returns the last SEQLOC of the last instance.

Parameters

[in]	wave
[in]	instance

Return values

KS_SEQLOC

                                                           {
 
   if (ks_numplaced(&wave->base) <= instance || instance < -1) {
     KS_THROW("%s: instance (%d) out of range [-1-%d)", __FUNCTION__, instance, wave->base.ngenerated);
     KS_SEQLOC tmploc = KS_INIT_SEQLOC;
     return tmploc; 
   }
 
   instance = (instance == -1) ? ks_numplaced(&wave->base) - 1 : instance;
 
 #ifdef HOST_TGT
   /* HOST */
   return wave->locs[instance];
 #else
   /* TARGET */
   return wave->wfi[instance].loc;
 #endif
 }

◆ 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_double_to_float()

void ks_mat4_double_to_float	(	KS_MAT4x4f	out,
		const KS_MAT4x4	in
	)

Conversion of a 4x4 matrix from double to float

Parameters

[out]	out	Float matrix (KS_MAT4x4f)
[in]	in	Double matrix (KS_MAT4x4)

Returns: void

                                                                  {
   int n = 0;
   for (; n < 16; n++) {
     out[n] = (float) in[n];
   }
 } /* ks_mat_double_to_float */

◆ ks_mat4_float_to_double()

void ks_mat4_float_to_double	(	KS_MAT4x4	out,
		const KS_MAT4x4f	in
	)

Conversion of a 4x4 matrix from float to double

Parameters

[out]	out	Double matrix (KS_MAT4x4)
[in]	in	Float matrix (KS_MAT4x4f)

Returns: void

                                                                  {
   int n = 0;
   for (; n < 16; n++) {
     out[n] = (double) in[n];
   }
 } /* ks_mat_float_to_double */

◆ 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_setgeometry */

◆ ks_mat4f_setgeometry()

void ks_mat4f_setgeometry	(	KS_MAT4x4f	lhs,
		float	x,
		float	y,
		float	z,
		float	xr,
		float	yr,
		float	zr
	)

                                                                                                    {
   KS_MAT4x4 tmp = KS_MAT4x4_IDENTITY;
   ks_mat4_setgeometry(tmp, x, y, z, xr, yr, zr);
   ks_mat4_double_to_float(lhs, tmp);
 } /* ks_mat4f_setgeometry */

◆ 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_mat3f_apply()

void ks_mat3f_apply	(	float *	w,
		const KS_MAT3x3f	R,
		const float *	v
	)

Rotate a vector with a 3x3 matrix

Parameters

[in]	w	column vector (3)
[in]	R	rotation matrix
	v	result of R.dot(v)

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] * (double)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_mat3f_invapply()

void ks_mat3f_invapply	(	float *	w,
		const KS_MAT3x3f	R,
		const float *	v
	)

Same as ks_mat3f_apply but use transpose of Rotation (R)

Parameters

[in]	w	column vector (3)
[in]	R	rotation matrix
	v	result of R.dot(v)

Returns: void

                                                                      {
   int i, j;
   for (i = 0; i < 3; ++i) {
     double acc = 0;
     for (j = 0; j < 3; ++j) {
       acc += v[j] * (double)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_update_slice_location_float()

void ks_scan_update_slice_location_float	(	SCAN_INFO *	new_loc,
		const SCAN_INFO	orig_loc,
		const KS_MAT4x4f	M_physical,
		const KS_MAT4x4f	M_logical
	)

                                                                                                                                                 {
   KS_MAT4x4 Mphysical = KS_MAT4x4_IDENTITY;
   KS_MAT4x4 Mlogical = KS_MAT4x4_IDENTITY;
   ks_mat4_float_to_double(Mphysical, M_physical);
   ks_mat4_float_to_double(Mlogical, M_logical);
   ks_scan_update_slice_location(new_loc, orig_loc, Mphysical, Mlogical);
 } /* ks_scan_update_slice_location_float */

◆ ks_scan_rotate()

void ks_scan_rotate ( SCAN_INFO slice_pos )

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_pos SCAN_INFO struct holding new slice information

Returns: void

                                          {
 #ifdef IPG
 
   /* scale to long int rotation matrix (accounting for gradient scaling) */
   scale(&slice_pos.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
	)

ADDTITLEHERE

                                                        {
 
   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
	)

ADDTITLEHERE

                                                   {
 
   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_wave(&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 ks_compare_loc_by_timeboard(&a->loc, &b->loc);
 }

◆ 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 on tgt

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_loc_by_timeboard()

void ks_sort_loc_by_timeboard	(	KS_SEQLOC *	a,
		int	nitems
	)

Sort KS_SEQLOCs in time, then board

This is the sorting method used in all ks_pg_***() on host

Parameters

[in,out]	a	Array of KS_SEQLOC elements
[in]	nitems	Number of elements in array

Returns: void

                                                         {
   qsort(a, nitems, sizeof(KS_SEQLOC),
         (int(*)(const void *, const void *))ks_compare_loc_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 ( )

ADDTITLEHERE

ADDDESCHERE

Returns: void

                                      {
   char fname[500];
   ks_plot_host_slicetime_fullfile(fname);
   remove(fname);
   ks_plot_enable = 0;
 }

◆ ks_plot_slicetime_begin()

void ks_plot_slicetime_begin ( )

ADDTITLEHERE

ADDDESCHERE

Returns: void

                                {
 #ifdef IPG
   return;
 #endif
   ks_plot_host_slicetime_begin();
 }

◆ ks_plot_slicetime()

void ks_plot_slicetime	(	const KS_SEQ_CONTROL *	ctrl,
		int	nslices,
		float *	slicepos_mm,
		float	slthick_mm,
		KS_PLOT_EXCITATION_MODE	exctype
	)

ADDTITLEHERE

ADDDESCHERE

Parameters

	ctrl	ADDTEXTHERE
[in]	nslices	ADDTEXTHERE
	slicepos_mm	ADDTEXTHERE
[in]	slthick_mm	ADDTEXTHERE
[in]	exctype	ADDTEXTHERE

Returns: void

                                                                                                                                        {
 #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 )

ADDTITLEHERE

ADDDESCHERE

Parameters

desc	ADDTEXTHERE

Returns: void

                                                          {
 #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
	)

ADDTITLEHERE

ADDDESCHERE

Parameters

	desc	ADDTEXTHERE
[in]	tag	ADDTEXTHERE

Returns: void

                                                                                                    {
 #ifdef IPG
   return;
 #endif
   ks_plot_host_slicetime_endofslicegroup(desc, tag);
 }

◆ ks_plot_slicetime_endofpass()

void ks_plot_slicetime_endofpass ( KS_PLOT_PASS_MODE pass_mode )

ADDTITLEHERE

ADDDESCHERE

Parameters

[in] pass_mode ADDTEXTHERE

Returns: void

                                                               {
 #ifdef IPG
   return;
 #endif
   ks_plot_host_slicetime_endofpass(pass_mode);
 }

◆ ks_plot_slicetime_end()

void ks_plot_slicetime_end ( )

ADDTITLEHERE

ADDDESCHERE

Returns: void

                              {
 #ifdef IPG
   return;
 #endif
   ks_plot_host_slicetime_end();
 }

◆ ks_plot_write_peplans()

void ks_plot_write_peplans	(	const KS_PHASEENCODING_PLAN const	plans,
		const int	num_plans,
		FILE *	fp
	)

ADDTITLEHERE

ADDDESCHERE

Parameters

	plans	ADDTEXTHERE
[in]	num_plans	ADDTEXTHERE
	fp	ADDTEXTHERE

Returns: void

                                                                                                       {
 
   if (plans == NULL || num_plans <= 0) {
         return;
   }
   int plan_idx = 0;
   fprintf(fp, "\"phaseencplans\": [\n");
   for (; plan_idx < num_plans; plan_idx++) {
     const KS_PHASEENCODING_PLAN* const 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\"coord_type\": [\"%s\", \"%s\"],\n",  plan->coord_type[0] == CARTESIAN_COORD ? "CARTESIAN_COORD" : "RADIAL_COORD",
                                                             plan->coord_type[1] == CARTESIAN_COORD ? "CARTESIAN_COORD" : "RADIAL_COORD");
       fprintf(fp, "\t\"encodes_per_shot\": %d,\n", plan->encodes_per_shot);
       fprintf(fp, "\t\"entries\": [\n");
       int shot;
       for (shot = 0; shot < plan->num_shots; shot++) {
         fprintf(fp, "\t\t[");
         int encode;
         for (encode = 0; encode < plan->encodes_per_shot; encode++) {
           const KS_PHASEENCODING_COORD coord = ks_phaseencoding_get(plan, encode, shot);
           fprintf(fp, "[%d, %d]", coord.ky, coord.kz);
           if (encode < (plan->encodes_per_shot - 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");
       }
     } else {
       /* KS_THROW("plans[%d] is NULL", plan_idx); */
     }
   }
   fputs("]", fp);
 
   return;
 }

◆ ks_plot_host_slicetime_begin()

void ks_plot_host_slicetime_begin ( )

ADDTITLEHERE

ADDDESCHERE

Returns: void

                                     {
   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\tP", /* P indicates a new pass has started */
    ks_psdname, optr, pitscan);
   fclose(fp);
 
   ks_plot_enable = 1;
 }

◆ ks_plot_host_slicetime()

void ks_plot_host_slicetime	(	const KS_SEQ_CONTROL *	ctrl,
		int	nslices,
		float *	slicepos_mm,
		float	slthick_mm,
		KS_PLOT_EXCITATION_MODE	exctype
	)

ADDTITLEHERE

ADDDESCHERE

Parameters

	ctrl	ADDTEXTHERE
[in]	nslices	ADDTEXTHERE
	slicepos_mm	ADDTEXTHERE
[in]	slthick_mm	ADDTEXTHERE
[in]	exctype	ADDTEXTHERE

Returns: void

                                                              {
   if (!ks_plot_enable || 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, -1, SEEK_END);
     int lastchar = fgetc(fp);
     if (!(lastchar == 'S' || lastchar == 'G' || lastchar == 'P')) {
       KS_THROW("%c not expected", lastchar);
     }
     fseek(fp, -1, SEEK_END);
 
     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},S", slicepos_mm == NULL ? 0.0 : slicepos_mm[nslices - 1]); /* S indicates a slice was added */
     fflush(fp);
     fclose(fp);
   }
 
 }

◆ ks_plot_host_slicetime_endofslicegroup()

void ks_plot_host_slicetime_endofslicegroup	(	const char *	desc,
		const KS_PLOT_SLICEGROUP_MODE	tag
	)

ADDTITLEHERE

ADDDESCHERE

Parameters

	desc	ADDTEXTHERE
[in]	tag	ADDTEXTHERE

Returns: void

                                                                                                   {
   if (!ks_plot_enable || 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, -1, SEEK_END);
   int lastchar = fgetc(fp);
   if (lastchar == 'S') {
     fseek(fp, -1, SEEK_END); /* Expected */
   } else if (lastchar == 'G' || lastchar == 'P') {
     KS_THROW("%s is an empty slice group (lastchar \"%c\")", desc, lastchar);
     fclose(fp);
     return;
   } else {
     KS_THROW("last character \"%c\" not expected", lastchar);
   }
 
 
   fseek(fp, -1, SEEK_END);
   fprintf(fp,
           "{\n\t"
           "\"groupdescription\": \"%s\",\n\t"
           "\"mode\": \"%s\"\n\t"
           "}", desc == NULL ? "N/A" : desc,
           modestr);
   fputs("],[\n\t{},\n\tG", fp); /* G indicates slicegroup was closed */
   fflush(fp);
   fclose(fp);
 }

◆ ks_plot_host_slicetime_endofpass()

void ks_plot_host_slicetime_endofpass ( KS_PLOT_PASS_MODE pass_mode )

ADDTITLEHERE

ADDDESCHERE

Parameters

[in] pass_mode ADDTEXTHERE

Returns: void

                                                                    {
   if (!ks_plot_enable || 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, -1, SEEK_END);
   int lastchar = fgetc(fp);
   if (lastchar == 'S') {
     KS_THROW("Slice group will be automatically closed");
     ks_plot_host_slicetime_endofslicegroup("Auto closed", KS_PLOT_SG_NOTSET);
   } else if (lastchar == 'G') {
     /* Expected - closed slice group */
   } else if (lastchar == 'P') {
     KS_THROW("Trying to close an empty pass");
     fclose(fp);
     return;
   } else {
     KS_THROW("last character \"%c\" not expected", lastchar);
   }
 
   fseek(fp, -10, SEEK_END);
   fputs("],\n", fp);
   fprintf(fp,
             "\t\"passmode\": \"%s\"\n"
             "\t},{\n"
             "\t\"slicegroups\": [\n\t[{},\n\tP", passmode_str); /* P indicates a new pass or end is expected */
   fflush(fp);
   fclose(fp);
 }

◆ ks_plot_host_slicetime_end()

void ks_plot_host_slicetime_end ( )

ADDTITLEHERE

ADDDESCHERE

Returns: void

                                   {
   if (!ks_plot_enable || ks_plot_filefmt == KS_PLOT_OFF) {
     ks_plot_enable = 0;
     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, -1, SEEK_END);
   int lastchar = fgetc(fp);
   if (lastchar == 'S') {
     KS_THROW("Slicegroup and pass will be closed automatically");
     ks_plot_host_slicetime_endofslicegroup("Auto closed", KS_PLOT_SG_NOTSET);
     ks_plot_host_slicetime_endofpass(KS_PLOT_PASS_WAS_STANDARD);
   } else if (lastchar == 'G') {
     /*KS_THROW("Pass will be closed automatically");*/
     ks_plot_host_slicetime_endofpass(KS_PLOT_PASS_WAS_STANDARD);
   } else if (lastchar == 'P') {
     /* Expected*/
   } else {
     KS_THROW("last character \"%c\" not expected", lastchar);
   }
 
   fseek(fp, -29, 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);
 
   ks_plot_enable = 0;
   return;
 }

◆ ks_plot_host()

void ks_plot_host	(	const KS_SEQ_COLLECTION *	seqcollection,
		const KS_PHASEENCODING_PLAN *	plan
	)

ADDTITLEHERE

ADDDESCHERE

Parameters

seqcollection	ADDTEXTHERE
plan	ADDTEXTHERE

Returns: void

                                                                                              {
   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	(	const KS_SEQ_CONTROL *	ctrl,
		const KS_PHASEENCODING_PLAN *	plan
	)

ADDTITLEHERE

ADDDESCHERE

Parameters

ctrl	ADDTEXTHERE
plan	ADDTEXTHERE

Returns: void

                                                                                          {
   ks_plot_host_seqctrl_manyplans(ctrl, &plan, 1);
 }

◆ ks_plot_host_seqctrl_manyplans()

void ks_plot_host_seqctrl_manyplans	(	const KS_SEQ_CONTROL *	ctrl,
		const KS_PHASEENCODING_PLAN **	plan,
		const int	num_plans
	)

ADDTITLEHERE

ADDDESCHERE

Parameters

	ctrl	ADDTEXTHERE
	plan	ADDTEXTHERE
[in]	num_plans	ADDTEXTHERE

Returns: void

                                                                                                                           {
 #if defined (PSD_HW) && defined (IPG)
   /* on IPG and on scanner, i.e. we are actually scanning so no plots for you */
   return;
 #endif
 
   if (ks_plot_filefmt == KS_PLOT_OFF || ctrl->duration == 0 || ctrl->nseqinstances ==  0) {
     return;
   }
 
   char boardc[9] = "xyzrRtos"; /* x,y,z,rho1, (unused rho2), theta, omega, ssp */
   char fname[1000]; /* Full filename of the json file */
   char path[250]; /* Directory of json file */
   char outputdir[250]; /* Where plots are saved */
   char outputdir_uid[250]; /* rhkacq_uid based output directory (for automatic transfers) */
 
   ks_plot_filename(fname, path, outputdir, outputdir_uid, ctrl->description);
 
   char cmd[250];
   FILE* fp;
   int i, j;
   KS_SEQLOC loc;
 
 #ifdef PSD_HW
   /* on MR-scanner */
   if (ks_plot_kstmp) {
     sprintf(cmd, "mkdir -p %s > /dev/null", outputdir_uid);
     system(cmd);
   }
   char pythonpath[] = "/usr/local/bin/apython";
   char psdplotpath[] = "/usr/local/bin/psdplot.py";
 #else
   /* in Simulation */
   char pythonpath[] = "apython";
   char psdplotpath[] = "../KSFoundation/psdplot/psdplot.py";
 #endif
   sprintf(cmd, "mkdir -p %s > /dev/null", path);
   system(cmd);
 
   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);
   fprintf(fp, "},\n");
 
   /* PHASE ENCODING PLANS */
   ks_plot_write_peplans( plans,  num_plans, fp);
 
   fputs(",\n", fp);
   /* 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\": [");
 
     for (j = 0; j < trap->base.ninst; j++) { /* each instance of the trap */
       fprintf(fp, "{\n");
       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);
       fputs("\t\t\t\"rtscale\": ", fp);
       ks_plot_host_rtscales_amps(&trap->rtscaling, fp, j);
       fputs("\t\t\t\"state\": ", fp);
       ks_plot_host_rtscales_states(&trap->rtscaling, fp, j);
       fprintf(fp,"\t\t\t\"ampscale\": %0.6f\n", loc.ampscale);
       if (j < (trap->base.ninst - 1)) {
         fprintf(fp, "\t\t},");
       } else {
         fprintf(fp, "\t\t}");    
       }
     }
     fprintf(fp, "]\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, ", ");
       }
     }
     fprintf(fp, "]\n");
     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);
         ks_plot_host_wavestates(&rfptr->omegawave, fp);
         fprintf(fp, "\t\t\t\"instances\": [");
         for (j = 0; j < rfptr->omegawave.base.ninst; j++) {
           fprintf(fp, "{\n");
           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]);
           fputs("\t\t\t\t\"rtscale\": ", fp);
           ks_plot_host_rtscales_amps(&rfptr->omegawave.rtscaling, fp, j);
           fputs("\t\t\t\"state\": ", fp);
           ks_plot_host_rtscales_states(&rfptr->omegawave.rtscaling, fp, 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},");
           } else {
             fprintf(fp, "\t\t\t}");
           }
         }
         fprintf(fp, "]\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);
 
         ks_plot_host_wavestates(&rfptr->thetawave, fp);
         fprintf(fp, "\t\t\t\"instances\": [");
         for (j = 0; j < rfptr->thetawave.base.ninst; j++) {
           fprintf(fp, "{\n");
           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]);
           fputs("\t\t\t\t\"rtscale\": ", fp);
           ks_plot_host_rtscales_amps(&rfptr->thetawave.rtscaling, fp, j);
           fputs("\t\t\t\t\"state\": ", fp);
           ks_plot_host_rtscales_states(&rfptr->thetawave.rtscaling, fp, 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},");
           } else {
             fprintf(fp, "\t\t\t}");
           }
         }
         fprintf(fp, "]\n");
       }
       fprintf(fp, "\t\t},\n");  /* Theta */
 
 
       fflush(fp);
       ks_plot_host_wavestates(&rfptr->rfwave, fp);
       fflush(fp);
       fprintf(fp, "\t\t\"instances\": [");
       for (j = 0; j < rfptr->rfwave.base.ninst; j++) { /* each instance of the wave (RHO1) */
         fprintf(fp, "{\n");
         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]);
         fputs("\t\t\t\"rtscale\": ", fp);
         ks_plot_host_rtscales_amps(&rfptr->rfwave.rtscaling, fp, j);
         fputs("\t\t\t\"state\": ", fp);
         ks_plot_host_rtscales_states(&rfptr->rfwave.rtscaling, fp, j);
         fprintf(fp, "\t\t\t\"ampscale\": %0.6f\n", loc.ampscale);
         if (j < (rfptr->rfwave.base.ninst - 1)) {
           fprintf(fp, "\t\t},");
         } else {
           fprintf(fp, "\t\t}");
         }
       }
       fprintf(fp, "]\n");
 
       if (i < (ctrl->gradrf.numrf - 1)) {
         fprintf(fp, "\t},\n");
       } else {
         fprintf(fp, "\t}\n");
       }
     } /* res > 0 */
   } /* rf */
   fprintf(fp, "},\n");
 
   /* Wait pulses */
   fputs("\"waits\": {\n",fp);
   for (i = 0; i < ctrl->gradrf.numwait; i++) {
     KS_WAIT* waitptr = ctrl->gradrf.waitptr[i];
     if (waitptr->max_duration > 0) {
       fprintf(fp, "\t\"%s\": {\n", waitptr->description);
       fprintf(fp, "\t\t\"description\": \"%s\",\n", waitptr->description);
       fprintf(fp, "\t\t\"max_duration\": %0.3f,\n", waitptr->max_duration / 1000.0);
       fprintf(fp, "\t\t\"pg_duration\": %0.3f,\n", waitptr->pg_duration / 1000.0);
       fprintf(fp, "\t\t\"instances\": [");
       for (j = 0; j < waitptr->base.ninst; j++) { /* each instance of the wave */
         fprintf(fp, "{\n");
         loc = waitptr->locs[j];
         fprintf(fp, "\t\t\t\"board\": \"%c\",\n", boardc[loc.board]);
         fputs("\t\t\t\"duration\": ", fp);
         if (waitptr->rtscaling.states && (waitptr->rtscaling.num_completed_playouts * waitptr->rtscaling.num_instances) > 0) {
           ks_plot_host_rtscales_states(&waitptr->rtscaling, fp, j);
         } else { /* Default to pg duration if not set in scan */
           fprintf(fp, "[%d],\n", waitptr->pg_duration);
         }
         fprintf(fp, "\t\t\t\"time\": %0.3f\n", loc.pos/1000.0);
         if (j < (waitptr->base.ninst - 1)) {
           fprintf(fp, "\t\t},");
         } else {
           fprintf(fp, "\t\t}");
         }
       }
       fprintf(fp, "]\n");
       if (i < (ctrl->gradrf.numwait - 1)) {
         fprintf(fp, "\t},\n");
       } else {
         fprintf(fp, "\t}\n");
       }
     }
   }
   fputs("},\n", fp); /* End waits */
 
   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);
       ks_plot_host_wavestates(waveptr, fp);
       fprintf(fp, "\t\t\"instances\": [");
       for (j = 0; j < waveptr->base.ninst; j++) { /* each instance of the wave */
         fprintf(fp, "{\n");
         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);
         fputs("\t\t\t\"rtscale\": ", fp);
         ks_plot_host_rtscales_amps(&waveptr->rtscaling, fp, j);
         fputs("\t\t\t\"state\": ", fp);
         ks_plot_host_rtscales_states(&waveptr->rtscaling, fp, j);
         fprintf(fp, "\t\t\t\"ampscale\": %0.6f\n", loc.ampscale);
         if (j < (waveptr->base.ninst - 1)) {
           fprintf(fp, "\t\t},");
         } else {
           fprintf(fp, "\t\t}");
         }
       }
       fprintf(fp, "]\n");
       if (i < (ctrl->gradrf.numwave - 1)) {
         fprintf(fp, "\t},\n");
       } else {
         fprintf(fp, "\t}\n");
       }
     } /* res > 0 */
   } 
   fputs("}\n}\n]\n}", fp); /* end waves, frame, frames, 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);
       system(cmd);
       sprintf(cmd, "cp %s %s > /dev/null", fname, outputdir_uid);
       system(cmd);
     }
 #endif
   }
   return;
 }

◆ ks_plot_tgt_reset()

void ks_plot_tgt_reset ( KS_SEQ_CONTROL * ctrl )

ADDTITLEHERE

ADDDESCHERE

Parameters

ctrl	ADDTEXTHERE

Returns: void

                                              {
   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_filename()

void ks_plot_filename	(	char *	fname,
		char *	path,
		char *	outputdir,
		char *	outputdir_uid,
		const char *const	seq_desc
	)

ADDTITLEHERE

ADDDESCHERE

Parameters

fname	ADDTEXTHERE
path	ADDTEXTHERE
outputdir	ADDTEXTHERE
outputdir_uid	ADDTEXTHERE
seq_desc	ADDTEXTHERE

Returns: void

                                                                                                                   {
 #if defined (PSD_HW) && defined (IPG)
   return;
 #endif
 
 
 #ifdef PSD_HW
   /* on MR-scanner */
   sprintf(path,  "/usr/g/mrraw/plot/%s/host/", ks_psdname);
   if (outputdir) {
    sprintf(outputdir, "/usr/g/mrraw/plot/%s/", ks_psdname); 
   }
 
   if (outputdir_uid && ks_plot_kstmp) {
     sprintf(outputdir_uid, "/usr/g/mrraw/kstmp/%010d/plot/", rhkacq_uid);
   }
 #else
   /* in Simulation */
   sprintf(path, "./plot/host/");
   if (outputdir) {
    sprintf(outputdir, "./plot/"); 
   }
 #endif
 
   sprintf(fname, "%spsdplot_%s_%s.json", path, ks_psdname, seq_desc);
 
 return;
 }

◆ ks_plot_saveconfig()

void ks_plot_saveconfig ( KS_SEQ_CONTROL * ctrl )

ADDTITLEHERE

ADDDESCHERE

Parameters

ctrl	ADDTEXTHERE

Returns: void

                                                {
 #ifdef IPG
   return;
 #endif
   char fname[1000]; /* Full filename of the json file */
   char path[250]; /* Directory of json file */
   ks_plot_filename(fname, path, NULL, NULL, ctrl->description);
   int i, j;
   FILE* fp;
   if ((fp = fopen(fname, "r+"))) {
     ks_dbg("The file %s exists", fname);
   } else {
     ks_dbg("The file %s is not there", fname);
     return;
   }
   fseek(fp, -4, SEEK_END);
   fputs(",\n"
         "\t{\n", fp);
   for (i = 0; i < ctrl->gradrf.numtrap; i++) {
     KS_TRAP* trap = ctrl->gradrf.trapptr[i];
     fprintf(fp, "\t\t\"%s\": [", trap->description);
 
     for (j = 0; j < ks_numplaced(&trap->base); j++) { /* each instance of the trap */
       fprintf(fp, "%0.6f", ks_rt_scale_log_get(&trap->rtscaling, j, ctrl->current_playout));
       if (j < (ks_numplaced(&trap->base) - 1)) {
         fputs(", ", fp);
       }
     }
     fputs("]", fp);
      if (i == (ctrl->gradrf.numtrap - 1)) {
       fputs("\n", fp);
     } else {
       fputs(",\n", fp);
     } 
   }
 
   fputs("\t}", fp);
 
 
   fputs("\n"
         "]\n"
         "}",fp);
   fflush(fp);
   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][0]);
           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][0]);
           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][0]);
         /* 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][0]);
         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_get_center_encode()

int ks_get_center_encode	(	const KS_PHASEENCODING_PLAN *const	peplan,
		int	shot,
		int	yres,
		int	zres
	)

Finds the center encode in a phase encoding plan

TODO: Support searching more than one shot

                                              {
 
   int best_encode = -1;
   KS_PHASEENCODING_COORD closest_coord;
   float closest_distance = 1.0f/0.0f; /* +Inf */
 
   const float y_center = (yres - 1) / 2.0;
   const float z_center = (zres - 1) / 2.0;
 
   int encode = 0;
   for (; encode < peplan->encodes_per_shot; encode++) {
     KS_PHASEENCODING_COORD coord = ks_phaseencoding_get(peplan, encode, shot);
 
     const float distance = (zres == KS_NOTSET || coord.kz == KS_NOTSET)  ?
       fabs(coord.ky - y_center) :
       (coord.ky - y_center)*(coord.ky - y_center) + (coord.kz - z_center)*(coord.kz - z_center);
 
     if (distance < closest_distance) {
         best_encode = encode;
         closest_coord = coord;
         closest_distance = distance;
     }
   }
 
   return best_encode;
 
 } /* ks_get_center_encode() */

◆ ks_peplan_find_center_from_linear_sweep()

int ks_peplan_find_center_from_linear_sweep	(	KS_KCOORD *const	K,
		KS_VIEW *	view,
		const int	num_coords,
		const KS_MTF_DIRECTION	mtf_direction,
		const int	sweep_sign,
		const int	segment_size,
		const int	start_encode
	)

ADDTITLEHERE

                                                                     {
   int idx;
   if (sweep_sign != 1 && sweep_sign != -1) {
     KS_THROW("Sweep sign must be +-1, not%d", sweep_sign);
     return KS_NOTSET;
   }
   KS_VIEW* views = (KS_VIEW*) malloc(num_coords * sizeof(KS_VIEW));
   if (views_in == NULL) {
     if (K == NULL) {
       KS_THROW("K and views cannot both be null");
       return KS_NOTSET;
     }
 
     for (idx = 0; idx < num_coords; idx++) {
       views[idx].coord = &(K[idx]);
     }
   } else if (K != NULL) {
       KS_THROW("Both K and views != NULL");
       return KS_NOTSET;
   } else {
     memcpy(views, views_in, num_coords * sizeof(KS_VIEW));
   }
 
   if (mtf_direction == MTF_Z) {
     qsort(views, num_coords, sizeof(KS_VIEW), ks_get_comp_kview_z_y(sweep_sign));
   } else if (mtf_direction == MTF_Y) {
     qsort(views, num_coords, sizeof(KS_VIEW), ks_get_comp_kview_y_z(sweep_sign));
   } else if (mtf_direction == MTF_R) {
     qsort(views, num_coords, sizeof(KS_VIEW), &ks_comp_kview_r_t);
   }
 
   for (idx = 0; idx < num_coords; idx++) {
     views[idx].encode = idx / segment_size + start_encode;
   }
 
   if (mtf_direction == MTF_Y) {
     qsort(views, num_coords, sizeof(KS_VIEW), &ks_comp_kview_dist_y_z);
     /* qsort(views, num_coords, sizeof(KS_VIEW), &ks_comp_kview_r_t); */
 
   } else if (mtf_direction == MTF_Z) {
     qsort(views, num_coords, sizeof(KS_VIEW), &ks_comp_kview_dist_z_y);
     /* qsort(views, num_coords, sizeof(KS_VIEW), &ks_comp_kview_r_t); */
 
   } else if (mtf_direction == MTF_R) {
     qsort(views, num_coords, sizeof(KS_VIEW), &ks_comp_kview_r_t);
   }
   int center = views[0].encode;
   /* ks_dbg("Center %d at [%d,%d]", views[0].encode, views[0].coord->y, views[0].coord->z); */
 
 
   free(views);
 
 
   return center;
 }

◆ ks_get_center_encode_linearsweep()

int ks_get_center_encode_linearsweep	(	const KS_KSPACE_ACQ *	kacq,
		const int	etl,
		const KS_PF_EARLYLATE	pf_earlylate_te
	)

ADDTITLEHERE

                                                                             {
 
   const KS_PEPLAN_SHOT_DISTRIBUTION shot_dist = ks_peplan_distribute_shots(etl, kacq->num_coords, KS_NOTSET /* center not known */);
   const int searched_encode_low_to_high = ks_peplan_find_center_from_linear_sweep(kacq->coords, NULL, kacq->num_coords, MTF_Y, 1, shot_dist.shots, 0 /* start from zero */);
   const int searched_encode_high_to_low = ks_peplan_find_center_from_linear_sweep(kacq->coords, NULL, kacq->num_coords, MTF_Y, -1, shot_dist.shots, 0 /* start from zero */);
 /*   ks_dbg("searched_encode_low_to_high = %d, searched_encode_high_to_low = %d", searched_encode_low_to_high, searched_encode_high_to_low); */
   int out = searched_encode_low_to_high;
   if (pf_earlylate_te == KS_PF_EARLY) {
     out = IMin(2, searched_encode_low_to_high, searched_encode_high_to_low);
   } else if (pf_earlylate_te == KS_PF_LATE) {
     out = IMax(2, searched_encode_low_to_high, searched_encode_high_to_low);
   }
   return out;
 
 } /* ks_get_center_encode_linearsweep() */

◆ ks_calc_caipi_scale()

float ks_calc_caipi_scale	(	const int	ky,
		const int	R,
		const int	caipi_factor
	)

ADDTITLEHERE

                                                                              {
   float caipi_scale = 0;
 
   /* Get target caipi-phase with pattern linspace(-1.0, 1.0, sms_caipi_factor) */
   if (ky != KS_NOTSET && caipi_factor > 1) {
     caipi_scale = ( (double) ((ky / R) % caipi_factor) / (caipi_factor - 1.0) ) * 2.0 - 1.0;
   }
 
   return caipi_scale;
 }

◆ ks_calc_caipi_phase()

float ks_calc_caipi_phase	(	const float	sms_slice_gap,
		const int	sms_multiband_factor,
		const SCAN_INFO *	slice_info,
		const float	caipi_blip_area,
		const int	slice_encode_dir
	)

ADDTITLEHERE

                                                                                                                                                                            {
 
   int sign = slice_encode_dir == 0 ? -1 : 1;                                           
   float offset = (sms_slice_gap / 2) * (sms_multiband_factor - 1) * sign; /* bottom slice's distance from RF-scan_info slice position (optloc) [mm] */
   float A_blip = (caipi_blip_area / 10.0) * 1e-6 ; /* [(G/cm) * us] -> [(G/mm) * s] */ 
   float gamma = (2.0*PI*GAM); /* [Hz/G] */
 
   float caipi_phase = (slice_info->optloc + offset) * A_blip * gamma; /* radians */
 
   return caipi_phase * (180.0/PI); /* convert to degrees and return */                      
 }

◆ ks_calc_caipi_offset_phase()

float ks_calc_caipi_offset_phase	(	const float	sms_slice_gap,
		const int	sms_multiband_factor,
		const SCAN_INFO *	slice_info,
		const int	caipi_factor,
		const float	caipi_blip_area,
		const int	ky,
		const int	R,
		const int	slice_encode_dir
	)

ADDTITLEHERE

                                                                                                    {
 
   float caipi_phase = ks_calc_caipi_phase(sms_slice_gap, sms_multiband_factor, slice_info, caipi_blip_area, slice_encode_dir);
 
   float caipi_scale = ks_calc_caipi_scale(ky, R, caipi_factor);
 
   return caipi_phase *= caipi_scale;
 
 }

◆ ks_eval_caipiblip()

STATUS ks_eval_caipiblip	(	KS_TRAP *	caipiblip,
		const int	caipi_factor,
		const float	sms_slice_gap,
		const KS_DESCRIPTION	seq_desc
	)

ADDTITLEHERE

                                                                                                                                {
   KS_DESCRIPTION tmpdesc;
 
   ks_create_suffixed_description(tmpdesc, seq_desc, "_caipiblip");
   caipiblip->area = ks_eval_sms_calc_caipi_area(caipi_factor, sms_slice_gap);
   caipiblip->fs_factor = 0; /* since the amplitude of a caipi-blip is so low, the fs_factor=0 minimizes potential round of errors while scaling */
   return ks_eval_trap(caipiblip, tmpdesc);
 }

◆ ks_eval_sms_rf_scan_info()

int ks_eval_sms_rf_scan_info	(	SCAN_INFO *	sms_slice_positions,
		const SCAN_INFO *	org_slice_positions,
		int	sms_multiband_factor,
		int	nslices
	)

Returns a new SCAN_INFO struct with a shifted slice postions

The slice positions used for SMS needs to be shifted, since the SMS pulses are created symetrically around the center freq.

Parameters

[in,out]	sms_slice_positions
[in]	org_slice_positions
[in]	sms_multiband_factor
[in]	nslices

Return values

sms_nslices

                                                                                                                                 {
 
     if (sms_factor == 1) {
       ks_error("%s: sms_factor = %d. Only works with sms_factor > 1.", __FUNCTION__, sms_factor);
       return KS_NOTSET;
     }
 
     int sms_nslices = CEIL_DIV(nslices, sms_factor);
 
     /* Index offset between the org. slice postion and the new one */
     int idx_offset = (sms_nslices) * ((int)ceil((float)sms_factor/2.0) - 1);
     idx_offset += sms_factor % 2 ? 0 : (int)floor((float)nslices / ((float)sms_factor * 2.0));
 
     /* Allocate new struct and fill with shifted postions */
     memcpy(sms_slice_positions, org_slice_positions, sms_nslices * sizeof(SCAN_INFO));
     int idx;
     for (idx = 0; idx < sms_nslices; idx++) {
       if ((sms_nslices) % 2 && !(sms_factor % 2)) { 
         /* if sms_nslices is odd and sms_factor is even, calc pos between indexes */
         float a = org_slice_positions[idx+idx_offset].optloc;
         float b = org_slice_positions[idx+idx_offset+1].optloc; 
         sms_slice_positions[idx].optloc = a - (a-b)/2.0;
       } else {
         sms_slice_positions[idx].optloc = org_slice_positions[idx+idx_offset].optloc;
       }
     }
 
     return sms_nslices;
 }

◆ 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:

The designed flip angle
The per-instance .ampscale in the KS_SEQLOC struct passed to ks_pg_rf()
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;
   }
 
   rf->rfwave.rtscaling.num_instances = numplaced;
 
 #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++) {
     ks_rt_scale_log_set(&rf->rfwave.rtscaling, 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] */
     unsigned short iphase_omega = 0;
     /* optloc-dependent freq offset */
     if (selrf->rf.omegawave.res > 0) {
       iphase_omega = -ks_scan_omegawave_hz(&selrf->rf.omegawave, i, hertzPerMm * tloc /* [Hz] */, selrf->rf.omega_iwave_phase_at_iso);
     } 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 */
       unsigned short 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 start of RF pulse */
       time_delay = rfstartpos - syncpos - 9 /* frq2sync_dly */;
 
       /*** Modified from GE's setupphases() ***/
       ftime_delay = ((double)(time_delay + selrf->rf.start2iso)) / ((double) 1.0e6);
       temp_freq = (double) freqoffHz;
       tmpphase = ks_degrees_to_iphase(rfphase) /* deg->iphase */ + ks_cycles_to_iphase( - temp_freq * ftime_delay ) + iphase_omega; /* iphase */
       setiphase((long)tmpphase,  selrf->rf.rfwave.wfi[i].wf, selrf->rf.rfwave.wfi[i].boardinstance);
     }
 #else
     (void)iphase_omega;
 #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, (selrf->rf.thetawave.current_state[i])+1 % selrf->rf.thetawave.base.nstates);
   }
 
 #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 */
       unsigned short 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 ); /* iphase */
       setiphase((long)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	newwaveform,
		int	state
	)

Writes over an existing waveform state in sequencer memory

graphical description

This function copies a waveform to the iwave buffer on the sequencer associated with the specified wave state. In order to use this function multiple wave states are required, these are added using ks_pg_addwavestate. During run time, it is the responsibility of the programmer to not copy a waveform into the currently active wave state. This is because the sequencer and your psd-code are asynchronous and this function writes into the sequence immediately. If the KS_WAVE is currently playing this could trip you scanner! Note: This function affects all instructions (instances) pointing to this state.

Example

@ipgexport (HOST)
KS_WAVE mywave = KS_INIT_WAVE;
KS_SEQ_CONTROL seqctrl;
@host
cveval() {
  ks_eval_wave(&mywave, "mywavedesc", res, duration, some_floatarray);
}
@pg
  KS_SEQLOC tmploc = KS_INIT_SEQLOC;
  tmploc.pos = 10ms;
  tmploc.board = XGRAD;
  ks_pg_wave(&mywave, tmploc, &seqctrl); // Same wave object *can* be placed on multiple boards (but not recommended as the units differ between gradient and RF/OMEGA boards)
  ks_pg_addwaveformstate(mywave, some_other_waveform, 1); // We add state 1, we will use this as our buffer later
@rsp (TGT)
scan() {
  float * your_waveform = (float *) AllocNode(1024 * sizeof(float)); // allocate some memory
  make_your_waveform(your_waveform, some_inputs); // create a float array
  const int new_state = (mywave.current_state+1) % mywave.base.nstates; // safely fetch the inactive state (for nstate=2 -> 1010101010.. etc)
  ks_scan_wave2hardware(&mywave, your_waveform, new_state); // replace the waveform at the address of <new_state> (this affects all instances pointing to this state)
  ks_scan_setwavestate(&mywave, new_state, INSTRALL); // change all instances of the instruction addresses to point to the <new_state> (so it plays out on the next time the seqctrl executes)
  FreeNode(your_waveform); // free the memory on the heap
}

Parameters

[in,out]	wave	Pointer to KS_WAVE
[in]	newwaveform	KS_WAVEFORM to copy to hardware (if `NULL`, the `.waveform` field in KS_WAVE will be used instead)
[in]	state	The wave state to write the waveform into; this can't be equal to the currently active wavestate

                                                                                     {
 #ifndef IPG  
   if(wave->max_amp < ks_waveform_absmax(newwaveform, wave->res)) {
     ks_error("%s [%s]: can't add a newwaveform state with a larger amplitude than state0.", __FUNCTION__, wave->description);
     return;
   }
 
   float slew_max = ks_waveform_maxslew(newwaveform, wave->res, wave->duration, NULL);
   /* times > 1 in case of float rounding */
   extern float cfxfs, cfyfs, cfzfs;
   extern int cfrmp2xfs, cfrmp2yfs, cfrmp2zfs;
   int i;
   float slew_limit = FMin(3, cfxfs, cfyfs, cfzfs)/IMax(3,cfrmp2xfs,cfrmp2yfs,cfrmp2zfs)* 1.00001;
   /* float slew_limit = ks_syslimits_slewrate1(loggrd) * 1.00001; */
   for (i = 0; i < ks_numplaced(&wave->base); i++) {
     KS_SEQLOC loc = wave->locs[i];
     int isGrad = (loc.board == XGRAD || loc.board == YGRAD || loc.board == ZGRAD);
     if ((isGrad) && (slew_max > slew_limit)) {
       KS_THROW("[%s]: state %i exceeds the least conservative gradient slew rate limit. %f > %f", 
                wave->description, state, slew_max, slew_limit);
       return;
     }
   }
   if(state > wave->base.nstates) {
     KS_THROW("This state (%d) was not pulsegen'd", state);
     return;
   }
 
 #endif
 
 #ifdef IPG
   /* wave -> short int wave for hardware use. All waveforms but THETA are autoscaled to +/- max_pg_wamp (32766)*/
   WF_PULSE * wfpulse;
   int board;
   short * iwave = (short *) AllocNode(wave->res * sizeof(short));
   int skippedboards = 0;
   int i;
   for (i = 0; i < ks_numplaced(&wave->base); i++) {
     if(state == wave->current_state[i]) {
       ks_error("Can't move a waveform to the currently active state, instance = %i!", i);
       return;
     }
   }
 
   const int board_instance  = 0;
   for(board = 0; board < 7; board++) {
     wfpulse = wave->wfpulse[board];
     if (!wfpulse) {
       skippedboards++;
       continue;
     }
     float max_amp = 0.0;
     if (board == RHO) {
       max_amp = 1.0;
     } else {
       max_amp = wave->abs_max_amp;
     }
 
     /* Here we adjust the iwave amplitude to achieve the correct final amplitude iamp*iwave*/
     if (ks_waveform2iwave(iwave, 
                           newwaveform, 
                           wave->res, 
                           board, 
                           max_amp, 
                           wave->fs_factor) == FAILURE)
     return;
     LONG wave_ptr = 0;
     getwave(&wave_ptr, &wfpulse[0]); /* Get current ptr */
     setwave(wave->wave_ptrs[state], &wfpulse[0], board_instance); /* Load state ptr */
     movewaveimm(iwave, &wfpulse[0], (int) board_instance, wave->res, TOHARDWARE); /* Write to wave to state ptr */
     setwave(wave_ptr, &wfpulse[0], board_instance); /* Restore current ptr */
   }
   FreeNode(iwave);
 
   if (skippedboards == 7) {
     ks_error("%s [%s] -> state %d: no WF_PULSES have been allocated, something is very wrong!", __FUNCTION__, wave->description, state);
     return;
   }
 
 #endif
 
 } /* ks_scan_wave2hardware */

◆ ks_scan_setwavestate()

void ks_scan_setwavestate	(	KS_WAVE *	wave,
		int	state,
		int	instance
	)

Change the address of an instruction instance to point to a different state

graphical description

During the ks_pg_addwaveform state calls we keep track of the address of each new waveform that was added. This function then allows you to switch to a new waveform by simply changing the address in the intstruction. Be aware that each instance of the KS_WAVE has a unique instruction. This allows you change wave_state on an instance granularity level.

Parameters

[in]	wave	Pointer to a KS_WAVE sequence object
[in]	state	The new state to switch to (previously added by ks_pg_addwaveformstate)
[in]	instance	Which instance you would like to change state (INSTRALL affects all)

                                                                   {
 
 
   if (ks_numplaced(&wave->base) == 0) {
     return;
   }
 
 #ifdef IPG
   setwave(wave->wave_ptrs[state], wave->wfi[instance].wf, wave->wfi[instance].boardinstance);
 #else
   if (state < 0) {
     KS_THROW("%s: tried to set to negative state: %i", wave->description, state);
   } else if (state >= KS_WAVE_MAXNSTATES) {
     KS_THROW("%s: invalid state: %d > %d ", wave->description, state, KS_WAVE_MAXNSTATES-1);
   } else if (wave->p_waveformstates[state] == NULL || state >= wave->base.nstates) {
     KS_THROW("%s: invalid state %d. Did you forget to call ks_pg_addwaveformstate() ?", wave->description, state);
   }
 
   if (instance < 0) {
     KS_THROW("%s: tried to modify negative instance: %i [this function is not compatible with INSTRALL(=%d)]", wave->description, instance, INSTRALL);
   } else if (instance > ks_numplaced(&wave->base)) {
     KS_THROW("%s: Invalid instance: %d > %d", wave->description, instance, ks_numplaced(&wave->base)-1);
   }
 
   wave->rtscaling.num_instances = ks_numplaced(&wave->base);
   ks_rt_scale_log_set_state(&wave->rtscaling, instance, state);
 #endif
   wave->current_state[instance] = state;
 
 } /* ks_scan_setwavestate */

◆ 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 float ampscale = readtrap->grad.wfi[i].loc.ampscale;
     float rloc = sliceinfo.oprloc;
 #else
     const float ampscale = readtrap->grad.locs[i].ampscale;
     float rloc = 1;
 #endif
 
     const double hertz_per_mm = (readtrap->grad.amp * ampscale) * GAM / 10.0; /* [Hz/mm] = amp [G/cm] * GAM [Hz/G] / 10.0 [cm->mm] */
 
     /* iphase_omega for rampsampled cases includes the entire ramp up (+acqdelay) */
     unsigned short iphase_omega = 0;
     if (readtrap->omega.duration > 0 && !areSame(ampscale, 0.0)) {
       iphase_omega = -ks_scan_omegawave_hz(&readtrap->omega, i,  hertz_per_mm * rloc /* [Hz] */, readtrap->omega_iwave_phase_at_echo);
     }
 
 #ifdef IPG
     const int gradsign = (hertz_per_mm >= 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
        - hertz_per_mm * 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) * (hertz_per_mm * 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) {
 
        /* The period of time between when the oscillator starts accumulating phase and 
          the centre of the first ADC sample is XTRSETLNG (132 us) + XTR_TAIL (5 us). XTRSETLNG is 
          used in the placement of the XTR, DAB and RBA messages in acqq_longdab/acqq.
          If the pulse placement in the acqq functions are modified from the GE defaults,
          this timing is no longer valid! */
       int freqstart2readstart = XTRSETLNG + XTR_TAIL + 2 - (int)(readtrap->acq.filt.tsp / 2.0f);
       int readstart2echo = readtrap->time2center - readtrap->acqdelay;
 
       const unsigned short iphase_due_to_freqoffset = ks_cycles_to_iphase(- freqoffHz * (freqstart2readstart + readstart2echo) * 1e-6);
       const unsigned short iphase_ky = ks_cycles_to_iphase(- ky * sliceinfo.opphasoff / readtrap->fov);
       const unsigned short iphase_kz = ks_cycles_to_iphase(- kz * sliceinfo.optloc / readtrap->fov);
       const unsigned short ircvphase = ks_degrees_to_iphase(rcvphase);
       unsigned short iphase = (iphase_ky + iphase_kz + ircvphase + iphase_due_to_freqoffset + iphase_omega);
       setiphase((long)iphase,  &readtrap->acq.echo[i], 0);
 
     }
 #else
     (void)iphase_omega;
 #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_offsetfov3D_readwave()

void ks_scan_offsetfov3D_readwave	(	KS_READWAVE *	readwave,
		int	instanceno,
		SCAN_INFO	sliceinfo,
		float	ky,
		float	phasefovratio,
		float	kz,
		float	zphasefovratio,
		float	rcvphase
	)

ADDTITLEHERE

                                                                                                                                                                                {
   const double koffset = (double)(ky) / phasefovratio;
   const double kzoffset = (double)(kz) / zphasefovratio;
   ks_scan_offsetfov_iso_readwave(readwave, instanceno, sliceinfo, koffset, kzoffset, rcvphase);
 }

◆ ks_scan_offsetfov_iso_readwave()

void ks_scan_offsetfov_iso_readwave	(	KS_READWAVE *	readwave,
		int	instanceno,
		SCAN_INFO	sliceinfo,
		double	ky,
		double	kz,
		double	rcvphase
	)

ADDTITLEHERE

                                                                                                                                        {
   KS_READ * read = &readwave->acq;
   const int numplaced = ks_numplaced(&read->base);
 
   if (numplaced == 0) {
     return;
   }
 
   int firstgrad, lastgrad;
   if (instanceno == INSTRALL) {
     firstgrad = 0;
     lastgrad = numplaced - 1;
   } else {
     firstgrad = instanceno;
     lastgrad = instanceno;
   }
 
   if (firstgrad < 0 || lastgrad >= numplaced) {
     ks_error("%s: readwave gradinstance (%d) out of range [0,%d]", __FUNCTION__, instanceno, numplaced - 1);
     return;
   }
 
   int i;
   for (i = firstgrad; i <= lastgrad; i++) {
 #ifdef IPG
     /* gradient amplitude for this instance -> Hz */
     const float ampscale = readwave->grad.wfi[i].loc.ampscale;
     const float rloc = sliceinfo.oprloc;
 #else
     const float ampscale = readwave->grad.locs[i].ampscale;
     const float rloc = 1;
 #endif
 
     const double hertz_per_mm = readwave->omega.abs_max_amp * ampscale; /* [Hz/mm] * ampscale (to match polarity of read gradient) */
     unsigned short iphase_omega = 0;
     iphase_omega = -ks_scan_omegawave_hz(&readwave->omega, i, hertz_per_mm * rloc /* [Hz] */, readwave->omega_iwave_phase_at_echo);
 
 #ifdef IPG
     const int gradsign = (ampscale >= 0) ? 1 : -1;
 
     /* Frequency offsets [Hz]:
        - cfreceiveroffsetfreq: GE's standard frequency offset
        - readwave->freqoffHz: Additional frequency offset for current KS_WAVE. This value is multiplied with the gradient polarity sign        */
     const double freqoffHz = cfreceiveroffsetfreq 
                             + readwave->freqoffHz * gradsign;
 
     /* set readout frequency offset */
     if (i < read->base.ngenerated && read->echo[i].tag == SSPDAB) {/* make sure it has been set up properly */
       setfrequency((int)(freqoffHz / TARDIS_FREQ_RES), &read->echo[i], 0);
     }
 
     /* set phase offset */
     if (i < numplaced && read->echo[i].tag == SSPDAB) {
 
       /* The period of time between when the oscillator starts accumulating phase and 
          the centre of the first ADC sample is XTRSETLNG (132 us) + XTR_TAIL (5 us). XTRSETLNG is 
          used in the placement of the XTR, DAB and RBA messages in acqq_longdab/acqq.
          If the pulse placement in the acqq functions are modified from the GE defaults,
          this timing is no longer valid! */
       int freqstart2readstart = XTRSETLNG + XTR_TAIL + 2 - (int)(readwave->acq.filt.tsp / 2.0f);
       int readstart2echo = readwave->time2center - readwave->acqdelay;
 
       const unsigned short iphase_due_to_freqoffset = ks_cycles_to_iphase(- freqoffHz * (freqstart2readstart + readstart2echo) * 1e-6);
       const unsigned short iphase_ky = ks_cycles_to_iphase(- ky * sliceinfo.opphasoff / readwave->fov);
       const unsigned short iphase_kz = ks_cycles_to_iphase(- kz * sliceinfo.optloc / readwave->fov);
       const unsigned short ircvphase = ks_degrees_to_iphase(rcvphase);
       unsigned short iphase = (iphase_ky + iphase_kz + ircvphase + iphase_due_to_freqoffset + iphase_omega);
       setiphase(iphase,  &read->echo[i], 0);
     }
 #else
     (void)iphase_omega;
 #endif
 
   } /* for */
 } /* ks_scan_offsetfov_iso_readwave */

◆ ks_scan_offsetfov_iso_readwave_oneread()

void ks_scan_offsetfov_iso_readwave_oneread	(	KS_READWAVE *	readwave,
		KS_READ *	read,
		int	gradinstanceno,
		int	readinstanceno,
		SCAN_INFO	sliceinfo,
		double	ky,
		double	kz,
		double	rcvphase
	)

ADDTITLEHERE

◆ ks_scan_offsetfov_readwave()

void ks_scan_offsetfov_readwave	(	KS_READWAVE *	readwave,
		int	instanceno,
		SCAN_INFO	sliceinfo,
		float	ky,
		float	phasefovratio,
		float	rcvphase
	)

ADDTITLEHERE

                                                                                                                                            {
   const double koffset = (double)(ky) / phasefovratio;
   ks_scan_offsetfov_iso_readwave(readwave, instanceno, sliceinfo, koffset, 0, rcvphase);
 }

◆ ks_eval_append_blip()

int ks_eval_append_blip	(	KS_WAVE *	wave,
		const float	s,
		const int	max_points,
		const float	area
	)

ADDTITLEHERE

                                                                                                     {
   float* prev = &wave->waveform[wave->res -1];
   float start_amp = *prev;
 
   /* Calculate tb slightly less than specified slewrate */
   const int tb = RUP_GRD(ceil(start_amp / max_s));
   const float sb = start_amp/tb;
   const float Mb = tb * start_amp / 2.0f;
   const float Ma = area - Mb;
   const int ta = RUP_GRD(ceil(( -start_amp + sqrt(start_amp*start_amp + max_s*Ma)) / max_s));
   if (ta < 0) {
     return ks_error("Ops");
   }
   const float sa = Ma/(ta*ta) - 2*start_amp/ta;
 
   const int num_a = ta / GRAD_UPDATE_TIME;
   const int num_b = tb / GRAD_UPDATE_TIME;
   if ((2*num_a + num_b) > max_points) {
     return ks_error("%s: num_a (%d) + num_b (%d) exceeds max points (%d)", __FUNCTION__, num_a, num_b, max_points);
   }
   int idx;
   float c_area = 0;
   for (idx = 0; idx < num_a; idx++) {
     float* cur = prev + 1;
     *cur = *prev + sa*GRAD_UPDATE_TIME;
     c_area += GRAD_UPDATE_TIME * (*prev + *cur) / 2.0f;
     prev++;
   }
 
   for (idx = 0; idx < num_a; idx++) {
     float* cur = prev + 1;
     *cur = *prev - sa*GRAD_UPDATE_TIME;
     c_area += GRAD_UPDATE_TIME * (*prev + *cur) / 2.0f;
     prev++;
   }
   for (idx = 0; idx < num_b; idx++) {
     float* cur = prev + 1;
     *cur = *prev - sb*GRAD_UPDATE_TIME;
     c_area += GRAD_UPDATE_TIME * (*prev + *cur) / 2.0f;
     prev++;
   }
 
   wave->res += 2*num_a + num_b;
   wave->duration = wave->res * GRAD_UPDATE_TIME;
 
   return SUCCESS;
 }

◆ ks_scan_omegatrap_hz()

unsigned short ks_scan_omegatrap_hz	(	KS_TRAP *	trap,
		int	instanceno,
		float	Hz,
		int	omega_iwave_phase_at_null
	)

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
[in]	omega_iwave_phase_at_null	the area of the integer waveform at the null point

Return values

iphase correction to be applied with XTR packet

                                                                                                            {
   int iamp;
   float omega_scale = 256.0;
   short iphase_omega = 0;
 
   iamp = (int) (Hz / (TARDIS_FREQ_RES * omega_scale * trp->fs_factor));
   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 0;
   }
 
 #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 0;
   }
 
   /* 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 0;
   }
 
   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 0;
   }
 
 
   int phase_accum = 0;
   phase_accum = (omega_iwave_phase_at_null * iamp) >> 7;
   /* Convert integer phase with 24-bit period to integer phase 
      with 16-bit period compatible with setiphase function */
   iphase_omega = phase_accum >> 8;
 
 #else
   int numplaced = trp->base.ninst;
   if (!numplaced) {
     return 0;
   }
 
   trp->rtscaling.num_instances = numplaced;
   ks_rt_scale_log_set(&trp->rtscaling, instanceno, Hz < 0 ? -1 : 1);
 
 #endif
 
   return iphase_omega;
 
 } /* ks_scan_omegatrap_hz */

◆ ks_scan_omegawave_hz()

unsigned short ks_scan_omegawave_hz	(	KS_WAVE *	wave,
		int	instanceno,
		float	Hz,
		int	omega_iwave_phase_at_null
	)

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

while an RF pulse is played out. One example is Spectral-Spatial RF pulses
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
[in]	omega_iwave_phase_at_null	the area of the integer waveform at the null point

Return values

iphase correction to be applied with XTR packet

                                                                                                             {
   int iamp;
   float omega_scale = 256.0;
   unsigned short iphase_omega = 0;
 
   iamp = (int) (Hz / (TARDIS_FREQ_RES * omega_scale * wave->fs_factor));
 
   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 0;
   }
 
 #ifdef IPG
 
   if (wave->wfi[instanceno].loc.board != OMEGA) {
     ks_error("ks_scan_omegawave_hz(%s): Only omega board is supported", wave->description);
     return 0;
   }
 
   /* 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 0;
   }
 
   if (setiamp((short) iamp, wave->wfi[instanceno].wf, wave->wfi[instanceno].boardinstance) != SUCCESS) {
     ks_error("ks_scan_omegawave_hz(%s): An error occurred calling 'setiamp()'", wave->description);
     return 0;
   }
 
   int phase_accum = 0;
   phase_accum = (omega_iwave_phase_at_null * iamp) >> 7;
   /* Convert integer phase with 24-bit period to integer phase with 16-bit period compatible with setiphase function */
   iphase_omega = phase_accum >> 8;
 
 #else
   int numplaced = wave->base.ninst;
   if (!numplaced) {
     return 0;
   }
 
   wave->rtscaling.num_instances = numplaced;
   ks_rt_scale_log_set(&wave->rtscaling, instanceno, Hz < 0 ? -1 : 1);
 
 #endif
 
   return iphase_omega;
 
 } /* 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

                                                  {
   int numplaced = ks_numplaced(&wait->base);
   if (numplaced == 0) {
     return;
   }
 
   int i;
 
   /* 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;
     }
   }
 # else
   wait->rtscaling.num_instances = numplaced;
   for (i = 0; i < numplaced; i++) {
     /* We use state to indicate the duration in µs instead of ampscaling since the former is an int */
     ks_rt_scale_log_set_state(&wait->rtscaling, i, waitperiod);
   }
 
 #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:

The designed amplitude [G/cm]
The per-instance .ampscale in the KS_SEQLOC struct passed to ks_pg_trap()
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;
   } 
 
   trp->rtscaling.num_instances = numplaced;
 
 #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 * trp->fs_factor)) * MAX_PG_IAMP);
 
     if (abs(iamp) > 32768) {
       ks_error("ks_scan_trap_ampscale(%s): the integer amplitude is too large (%d) (ampscale %1.5f, amplitude %1.5f G/cm, boardmax %1.5f, fs_factor %1.5f), for instance %d", trp->description, iamp, ampscale, trp->wfi[i].loc.ampscale * trp->amp, gradmax, trp->fs_factor, 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++) {
     ks_rt_scale_log_set(&trp->rtscaling, i, ampscale);
   }
 #endif
 } /* ks_scan_trap_ampscale */

◆ ks_scan_wave_ampscale()

void ks_scan_wave_ampscale	(	KS_WAVE *	wave,
		int	instanceno,
		float	ampscale
	)

Updates the amplitude of one or all instances of a KS_WAVE sequence object

This function multiplies one instance of a KS_WAVE 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_WAVE object is the multiplication of the three factors:

The designed amplitude [G/cm] in the KS_WAVEFORM array
The per-instance .ampscale in the KS_SEQLOC struct passed to ks_pg_trap()
The ampscale value passed in as 3rd argument to this function.

Parameters

[in,out]	wave	Pointer to KS_WAVE
[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 = wave->base.ngenerated;
 #else
   int numplaced = wave->base.ninst;
   if (!numplaced) {
     return;
   }
 
   wave->rtscaling.num_instances = numplaced;
 
 #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_wave_ampscale(%s): instanceno (%d) out of range [0,%d]", wave->description, instanceno, numplaced - 1);
     return;
   }
 
   if (fabs(ampscale) > 1.0) {
     ks_error("ks_scan_wave_ampscale(%s): ampscale too large (%f)", wave->description, ampscale);
     return;
   }
 
 #ifdef IPG
 
   if (wave->wfi == NULL) {
     ks_error("ks_scan_wave_ampscale(%s): WF_INSTANCE of trap is NULL", wave->description);
     return;
   }
 
   /* set amplitude(s) */
   for (i = firstinstance; i <= lastinstance; i++) {
     const int board = wave->wfi[i].loc.board;
     gradmax = ks_syslimits_gradtarget(loggrd, board);
     switch (board) {
       case XGRAD:
       case YGRAD:
       case ZGRAD:
       {
         iamp = (int)((wave->abs_max_amp * ampscale * wave->wfi[i].loc.ampscale / (wave->fs_factor * gradmax)) * MAX_PG_IAMP);
         break;
       }
       case OMEGA:
       {
         /* The TARDIS_FREQ_RES = 10e6 / (1 << 24) is the effect of one bit. This is the overflow period of the 24-bit register
            when incremented by 1 at 10 MHz = 0.586 Hz.
            The product of iwave and iamp is 32 bit wide [the most significant 8-bits appear to be discarded as it is truncated to 24-bits],
            this effectively mulitplies this value by 256 - so we need to shift 8-bits to the right here to be in the correct units [Hz] */
         iamp = (int)((wave->abs_max_amp * ampscale * wave->wfi[i].loc.ampscale / (wave->fs_factor * TARDIS_FREQ_RES))) >> 8;
         break;
       }
       case THETA:
       {
         iamp = (int)(wave->wfi[i].loc.ampscale * MAX_PG_IAMP);
         break;  
       }
       default:
         ks_error("Wave scaling is currently not implemented for board: %i", board);
         return;
     }
 
     if (abs(iamp) > MAX_PG_IAMP) {
       ks_error("ks_scan_wave_ampscale(%s): the integer amplitude is too large (%d) for instance %d", wave->description, iamp, i);
       return;
     }
     if (setiamp((short) iamp, wave->wfi[i].wf, wave->wfi[i].boardinstance) != SUCCESS) {
       ks_error("ks_scan_wave_ampscale(%s): An error occurred calling 'setiamp()'", wave->description);
       return;
     }
 
   }
 
 #else
   for (i = firstinstance; i <= lastinstance; i++) {
     ks_rt_scale_log_set(&wave->rtscaling, i, ampscale);
   }
 #endif
 } /* ks_scan_wave_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

                                                                         {
 
   if (phaser == NULL)
     return;
 
   const double kmove =  ks_scan_phaser_compute_kmove(phaser, view);
 
   ks_scan_phaser_kmove(phaser, instanceno, kmove);
 
 } /* 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_phaser_average()

void ks_scan_phaser_average	(	KS_PHASER *	phaser,
		int	instanceno
	)

ADDTITLEHERE

                                                                {
   ks_scan_trap_ampscale(&phaser->grad, instanceno, 0.58);
 }

◆ ks_scan_phaser_max()

void ks_scan_phaser_max	(	KS_PHASER *	phaser,
		int	instanceno
	)

ADDTITLEHERE

                                                            {
   ks_scan_trap_ampscale(&phaser->grad, instanceno, 1.0);
 }

◆ 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
	)

ADDTITLEHERE

                                                                                                                   {
   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_THROW("%s: KS_EPI does not support varying ky step size", 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_sms()

void ks_scan_epi_shotcontrol_sms	(	KS_EPI *	epi,
		int	echo,
		SCAN_INFO	sliceinfo,
		KS_PHASEENCODING_COORD	starting_coord,
		ks_enum_epiblipsign	blipsign,
		float	rcvphase,
		int	sms_factor,
		float	sms_slice_gap,
		int	caipi_factor,
		int	sms_slice_encoding_direction
	)

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]	starting_coord	coordinate in k-space from where the EPI train starts
[in]	blipsign	KS_EPI_POSBLIPS or KS_EPI_NEGBLIPS
[in]	rcvphase	Receiver phase in degrees, for RF spoiling.
[in]	sms_factor	ADDTEXTHERE
[in]	sms_slice_gap	ADDTEXTHERE
[in]	caipi_factor	ADDTEXTHERE
[in]	sms_slice_encoding_direction	ADDTEXTHERE

Returns: void

                                                                                                                                                                                                                                                            {
   float blipampscale = 1.0;
   float yfovratio, zfovratio;
   int i, s;
   int numblips = (epi->etl - 1);
   int readindx, blipindx, kyview, kzview;
   float caipi_rcvphase = 0.0;
 
   if (blipsign == KS_EPI_NOBLIPS) {
     starting_coord.ky = KS_NOTSET;
     starting_coord.kz = KS_NOTSET;
   }
 
   const int readfact = (epi->epi_readout_mode == KS_EPI_SPLITODDEVEN) ? 2 : 1;
 
   /* Blips-off triggers: If at least one of KS_EPI_NOBLIPS or ky = KS_NOTSET, make sure
      both blipdephasers and blips are off */
   if (blipsign == KS_EPI_NOBLIPS || starting_coord.ky == KS_NOTSET) {
     blipsign = KS_EPI_NOBLIPS; /* blip amp off */
     starting_coord.ky = KS_NOTSET; /* blipdephaser off */
   }
 
   /* EPI dephaser. From k-space center to this line */
   ks_scan_phaser_toline(&epi->blipphaser, 0 + 2 * echo, starting_coord.ky); /* 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, starting_coord.kz);
   }
 
   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, starting_coord.kz);
   }
 
   /* EPI read & blips for current 'echo' = EPI train. */
   float caipi_phase = ks_calc_caipi_phase(sms_slice_gap, sms_factor, &sliceinfo, epi->caipiblip.area, sms_slice_encoding_direction);
   float caipi_previous = 0.0;
   for (i = 0; i < epi->etl; i++) {
     kyview = starting_coord.ky - blipsign * epi->blipphaser.R * i;
     kzview = starting_coord.kz;
 
     readindx = readfact * (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);
     }
 
     /* CAIPI-blip */
     float caipi_target = ks_calc_caipi_scale(kyview, epi->R_ky, caipi_factor) * abs(blipsign) * 0.5; /* Get target caipi-phase with pattern linspace(-0.5, 0.5, sms_caipi_factor) */
     float caipi_scale = caipi_target - caipi_previous;
     ks_scan_trap_ampscale(&epi->caipiblip, blipindx, caipi_scale);
     caipi_previous = caipi_target;
 
     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 */
       /* CAIPI rephaser */
       ks_scan_trap_ampscale(&epi->caipiblip, blipindx+1, -caipi_previous);
     }
 
     /* FOV offsets (by changing freq/phase of epi.read) */
     float ky_centred, kz_centred;
     if (kyview < 0 || blipsign == KS_EPI_NOBLIPS) {
       ky_centred = 0.0f;
     } else {
       ky_centred = (float)kyview - ((epi->blipphaser.res - 1) / 2.0f);
     }
     yfovratio = epi->blipphaser.fov / epi->read.fov;
 
     int n_readouts_per_blip = (epi->epi_readout_mode == KS_EPI_SPLITODDEVEN ? 2 : 1);
     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;
       for (s = 0; s < n_readouts_per_blip; s++) {
         ks_scan_offsetfov3D(&epi->read, readindx + s, sliceinfo, ky_centred, yfovratio, kz_centred, zfovratio, rcvphase);
       }
     } else {
 
       if (caipi_factor > 1) {
         caipi_rcvphase = caipi_phase * caipi_target; 
       } else {
         caipi_rcvphase = 0.0;
       }
 
       for (s = 0; s < n_readouts_per_blip; s++) {
         ks_scan_offsetfov(&epi->read, readindx + s, sliceinfo, ky_centred, yfovratio, rcvphase + caipi_rcvphase);
       }
     }
 
   } /* for etl */
 
 } /* ks_scan_epi_shotcontrol_sms */

◆ ks_scan_epi_shotcontrol()

void ks_scan_epi_shotcontrol	(	KS_EPI *	epi,
		int	echo,
		SCAN_INFO	sliceinfo,
		KS_PHASEENCODING_COORD	starting_coord,
		ks_enum_epiblipsign	blipsign,
		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]	starting_coord	coordinate in k-space from where the EPI train starts
[in]	blipsign	KS_EPI_POSBLIPS or KS_EPI_NEGBLIPS
[in]	rcvphase	Receiver phase in degrees, for RF spoiling.

                                                                                                                                                               {
 
   int sms_factor = 1; 
   float sms_slice_gap = 0.0;
   int caipi_factor = 1; 
   int sms_slice_encoding_direction = 1; 
 
   ks_scan_epi_shotcontrol_sms(epi, echo, sliceinfo, starting_coord, blipsign, rcvphase, sms_factor, sms_slice_gap, caipi_factor, sms_slice_encoding_direction);
 
 }

◆ ks_scan_epi_loadecho()

void ks_scan_epi_loadecho	(	KS_EPI *	epi,
		int	echo,
		int	storeecho,
		int	slice,
		KS_PHASEENCODING_COORD	starting_coord,
		ks_enum_epiblipsign	blipsign,
		KS_DYNAMIC_STATE *	dynamic
	)

Loads the data storage information to hardware for the acquisition windows in a KS_EPI sequence object

ADDTEXTHERE

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]	starting_coord	coordinate in k-space from where the EPI train starts
[in]	blipsign	KS_EPI_POSBLIPS or KS_EPI_NEGBLIPS
	dynamic	Pointer to KS_DYNAMIC_STATE struct, which has elements being automatically updated by the scan looping functions

Returns: void

                                                                    {
 
   int i, readindx;
   const int n_readouts_per_blip = (epi->epi_readout_mode == KS_EPI_SPLITODDEVEN) ? 2 : 1;
   const int numplaced = ks_numplaced(&epi->read.acq.base);
   if (numplaced == 0) {
     return;
   }
 
 
   /* Data routing control */
   TYPDAB_PACKETS dabacqctrl = dynamic->slloc >= 0 ? DABON : DABOFF;
   if ((dynamic->prescan || !dynamic->force_acq) && (dynamic->shot < 0 || dynamic->average < 0)) {
     dabacqctrl = DABOFF;
   }
   (void)dabacqctrl;
 
 
   if (echo < 0 || (echo + 1) * (n_readouts_per_blip * epi->etl) > numplaced) {
     KS_THROW("echo (%d) must be in range [0:%d]", echo, numplaced/(n_readouts_per_blip * epi->etl) - 1);
     return;
   }
 
   const int view_factor = epi->compressed_bam ? epi->R_ky : 1;
   (void) view_factor;
   
   for (i = 0; i < epi->etl; i++) {
 
     readindx = n_readouts_per_blip * (i + echo * epi->etl); /* N.B.: 'echo' is # of EPI trains, not EPI readout lobes (up to 16 possible, set by opnecho) */
 
     if ((readindx + (epi->epi_readout_mode == KS_EPI_SPLITODDEVEN)) >= numplaced) {
       KS_THROW("%s: Readout lobe index %d has not been placed in PG", epi->read.grad.description, readindx);
       return;
     }
 
 #ifdef IPG
     int kyview = starting_coord.ky - blipsign * epi->blipphaser.R * i;
     int s;
     int centerread = epi->time2center / epi->read.grad.duration; /* etl index corresponding to k-space center */
       /* '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;
 
     kyview = kyview < 0 ? kyview : kyview / view_factor;
 
     for (s = 0; s < n_readouts_per_blip; s++) {
 
       WF_PULSE_ADDR current_wf_pulse = &epi->read.acq.echo[readindx + s];
 
       if (dynamic->prescan) {
         /* Prescan (R1 & R2), turn on acquisition for center echo of 1st EPI train */
         TYPDAB_PACKETS psc_dabacqctrl = ((readindx + s) == centerread && echo == 0) ? dabacqctrl : DABOFF;
         loaddab(current_wf_pulse, slice, 0, DABSTORE, 0, psc_dabacqctrl, PSD_LOAD_DAB_ALL); 
       } else {
         loaddab_hub_r1(current_wf_pulse, slice, n_readouts_per_blip * storeecho + s, DABSTORE, kyview + 1 /* GE's views are 1-based */, 0, currentR1, dabacqctrl, PSD_LOAD_DAB_ALL_WITH_HUB_R1);
       }
 
     } /* for s */
 #endif
 
   } /* per acq window (readout lobe) */
 
 } /* ks_scan_epi_loadecho() */

◆ ks_loaddab_reserved()

void ks_loaddab_reserved	(	WF_PULSE_ADDR	echo,
		short	state,
		short	resampler_index
	)

ADDTITLEHERE

Parameters

[in]	echo	ADDTEXTHERE
[in]	state	ADDTEXTHERE
[in]	resampler_index	ADDTEXTHERE

Returns: void

                                                                                  {
   #ifdef IPG
     sspload(&state,  echo, 28, 1, (HW_DIRECTION)TOHARDWARE, (SSP_S_ATTRIB)SSPS1);
     sspload(&resampler_index, echo, 29, 1, (HW_DIRECTION)TOHARDWARE, (SSP_S_ATTRIB)SSPS1);
 #endif
 }

◆ ks_loaddab()

void ks_loaddab	(	WF_PULSE_ADDR	echo,
		const char *	dab_array
	)

ADDTITLEHERE

Parameters

[in]	echo	ADDTEXTHERE
[in]	dab_array	ADDTEXTHERE

Returns: void

                                                                   {
   int i;
   static const int dab_indices[KS_DABARRAY_AVAILABLE_BYTES] = {2,3,4,5,6,7,14,15,16,17,18,19,20,21,22,23,24,25,26,27}; /* 20 */
 
   if (!custom_dab_array) {
     return;
   }
   short dabbyte;
   for (i = 0; i < KS_DABARRAY_AVAILABLE_BYTES; i++) { /* KS_DABARRAY_AVAILABLE_BYTES = 20 */
     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() */

◆ ks_loaddab_full()

void ks_loaddab_full	(	WF_PULSE_ADDR	echo,
		const char *	custom_dab_array
	)

ADDTITLEHERE

Parameters

[in]	echo	ADDTEXTHERE
[in]	custom_dab_array	ADDTEXTHERE

Returns: void

                                                                        {
   int i;
 
   if (!custom_dab_array) {
     return;
   }
   static const int dab_indices_full[KS_DABARRAY_FULL_LENGTH] = {2,3,4,5,6,7,8,9,10,11,12,13,14,15,16,17,18,19,20,21,22,23,24,25,26,27,28,29};
 
   for (i=0; i<KS_DABARRAY_FULL_LENGTH; i++){
     short dabbyte = custom_dab_array[i];
 #ifdef IPG
     sspload(&dabbyte, echo, dab_indices_full[i], 1, (HW_DIRECTION)TOHARDWARE, (SSP_S_ATTRIB)SSPS1);
 #else
     (void) dabbyte;
     (void) dab_indices_full;
 #endif
   }
 }

◆ ks_get_read_in_echotrain()

const KS_READ* ks_get_read_in_echotrain	(	const KS_ECHOTRAIN *	echotrain,
		const int	readout_index
	)

ADDTITLEHERE

Parameters

[in]	echotrain	ADDTEXTHERE
[in]	readout_index	ADDTEXTHERE

Returns: void

                                                                                                 {
   int object_index = echotrain->controls[readout_index].pg.object_index;
   KS_READ_TYPE type = echotrain->controls[readout_index].pg.read_type;
   if (type == KS_READ_TRAP) {
     return &echotrain->readtraps[object_index].acq;
   } else {
     return &echotrain->readwaves[object_index].acq;
   }
 }

◆ ks_get_wf_pulse()

WF_PULSE_ADDR ks_get_wf_pulse	(	KS_ECHOTRAIN *	echotrain,
		const int	readout_index
	)

ADDTITLEHERE

Parameters

[in]	echotrain	ADDTEXTHERE
[in]	readout_index	ADDTEXTHERE

Return values

WF_PULSE_ADDR

                                                                                 {
   int object_index = echotrain->controls[readout_index].pg.object_index;
   int instance_index = echotrain->controls[readout_index].pg.instance_index;
   KS_READ_TYPE type = echotrain->controls[readout_index].pg.read_type;
   if (type == KS_READ_TRAP) {
     return &echotrain->readtraps[object_index].acq.echo[instance_index];
   } else {
     return &echotrain->readwaves[object_index].acq.echo[instance_index];
   } 
 }

◆ ks_get_override_R1()

LONG ks_get_override_R1	(	KS_ECHOTRAIN *	echotrain,
		const int	readout_index
	)

ADDTITLEHERE

Parameters

[in]	echotrain	ADDTEXTHERE
[in]	readout_index	ADDTEXTHERE

Return values

LONG

                                                                           {
   int object_index = echotrain->controls[readout_index].pg.object_index;
   KS_READ_TYPE type = echotrain->controls[readout_index].pg.read_type;
   const int override_R1 = (type == KS_READ_TRAP) ?
     echotrain->readtraps[object_index].acq.override_R1 :
     echotrain->readwaves[object_index].acq.override_R1;
   return override_R1;
 }

◆ 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) {
     if (ctrl->handle.offset == NULL) {
       ks_error("%s: ctrl->handle.offset is NULL. Missing calls to pg and KS_SEQLENGTH in pulsegen?", __FUNCTION__);
     } else {
       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++;
 
     /* Register the playout to the seq. collection */
     if (ctrl->collection->numplayouts < KS_MAX_SEQUENCE_PLAYOUTS) {
       ctrl->collection->seqplayouts[ctrl->collection->numplayouts++] = ctrl;
     }
 
     /* Advance scaling logs for all objects */
     int i;
     for (i = 0; i < ctrl->gradrf.numrf; ++i) {
       ks_rt_scale_log_next(&ctrl->gradrf.rfptr[i]->rfwave.rtscaling);
       if (ks_numplaced(&ctrl->gradrf.rfptr[i]->omegawave.base)) {
         ks_rt_scale_log_next(&ctrl->gradrf.rfptr[i]->omegawave.rtscaling);
       }
       if (ks_numplaced(&ctrl->gradrf.rfptr[i]->thetawave.base)) {
         ks_rt_scale_log_next(&ctrl->gradrf.rfptr[i]->thetawave.rtscaling);
       }
     }
     for (i = 0; i < ctrl->gradrf.numtrap; ++i) {
       ks_rt_scale_log_next(&ctrl->gradrf.trapptr[i]->rtscaling);
     }
     for (i = 0; i < ctrl->gradrf.numwave; ++i) {
       ks_rt_scale_log_next(&ctrl->gradrf.waveptr[i]->rtscaling);
     }
     for (i = 0; i < ctrl->gradrf.numwait; ++i) {
       ks_rt_scale_log_next(&ctrl->gradrf.waitptr[i]->rtscaling);
     }
 #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]

                                              {
   unsigned int phase = 117 * ( counter * (counter + 1) + 2) / 2;
 
   /* fmod() does not seem to work on TGT on hardware (MR scanner) */
 
   return ((float) (phase%360));
 }

◆ ks_scan_gettherightshot()

int ks_scan_gettherightshot ( const KS_DYNAMIC_STATE * dynamic )

shot vs inner shot logic for ksepi.cc

Parameters

dynamic

Returns: int

                                                              {
   int shot = 0;
 
   if (dynamic) {
     shot = (dynamic->shot == 0) ? dynamic->inner_shot : dynamic->shot;
   }
 
   return shot;
 
 }

◆ ks_get_trapamp_instance()

float ks_get_trapamp_instance	(	const KS_TRAP *	trap,
		int	instance
	)

Get the amplitude in G/cm for an instance of a KS_TRAP (excluding realtime changes)

Parameters

[in]	trap	Pointer to KS_TRAP
[in]	instance	0-based instance (up to .base.ninst-1)

Returns: float Gradient amplitude in G/cm

                                                                  {
   float trapamp = -999.0;
 
 #ifdef IPG
     /* getiamp(&readiamp, trap->wfi[i].wf, trap->wfi[i].boardinstance); */
     trapamp = trap->wfi[instance].loc.ampscale * trap->amp;
 #else
     trapamp = trap->locs[instance].ampscale * trap->amp;
 #endif
 
   return trapamp;
 }

◆ 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;
   }
   for (i = 0; i < gradrfctrl->numwait; ++i) {
     gradrfctrl->waitptr[i] = NULL;
   }
   gradrfctrl->numrf = 0;
   gradrfctrl->numtrap = 0;
   gradrfctrl->numwave = 0;
   gradrfctrl->numacq = 0;
   gradrfctrl->numwait = 0;
   gradrfctrl->is_cleared_on_tgt = TRUE;
 }

◆ ks_eval_clear_readwave()

int ks_eval_clear_readwave ( KS_READWAVE * readwave )

ADDTITLEHERE

                                                   {
   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_polyder()

void ks_polyder	(	const double *	coeffs,
		const int	order,
		double *	der_coeffs
	)

get derivative coeffs of polynomial of order

                                                                            {
   int ido;
   for (ido = 0; ido < order; ido++) {
     der_coeffs[ido] = coeffs[ido] * (order - ido);
   }
 }

◆ ks_polyval()

void ks_polyval	(	const double *	coeffs,
		const int	order,
		const double *	x,
		const int	numx,
		double *	values
	)

eval polynomial

                                                                                                         {
   int idx, ido;
   for (idx = 0; idx < numx; idx++) {
     values[idx] = 0.0;
     for (ido = 0; ido <= order; ido++) {
       values[idx] = values[idx] * x[idx] + coeffs[ido];
     }
   }
 }

◆ ks_polyval_f()

void ks_polyval_f	(	const double *	coeffs,
		const int	order,
		const float *	x,
		const int	numx,
		float *	values
	)

eval polynomial with float values

                                                                                                         {
   double xd[numx];
   double vald[numx];
   int i;
 
   for (i = 0; i < numx; i++) {
     xd[i] = (double) x[i];
   }
 
   ks_polyval(coeffs, order, xd, numx, vald);
 
   for (i = 0; i < numx; i++) {
     values[i] = (float) vald[i];
   }
 }

◆ ks_Newtons_method()

double ks_Newtons_method	(	const double *	coeffs,
		const int	order,
		const double	x0,
		const int	num_iter
	)

find real polynomial root near x0 using Newton's method

                                                                                                      {
   double x = x0;
   double der_coeffs[order];
   ks_polyder(coeffs, order, der_coeffs); /* get derivative */
 
   int iter;
   for (iter = 0; iter < num_iter; iter++) {
     double f, fp; /* polynomial and its derivative at x */
     ks_polyval(coeffs, order, &x, 1, &f);
     ks_polyval(der_coeffs, order-1, &x, 1, &fp);
     x -= f / fp;
   }
   return x;
 }

◆ ks_pg_readwave()

int ks_pg_readwave	(	KS_READWAVE *	readwave,
		KS_SEQLOC	loc,
		KS_SEQ_CONTROL *	ctrl
	)

ADDTITLEHERE

                                                                                   {
   STATUS status;
 
   int startpos = loc.pos;
   KS_SEQLOC omegaloc = KS_INIT_SEQLOC;
   omegaloc.board = OMEGA;
   omegaloc.pos = startpos + readwave->acqdelay;
   omegaloc.ampscale = 1.0f;
 
   /* Readout waveforms */
   /* readwave->delay should be 0 */
   loc.pos = startpos + readwave->delay;
 
 
 
   status = ks_pg_wave(&readwave->grad, loc, ctrl);
   KS_RAISE(status);
 
   /* Omega */
   status = ks_pg_wave(&readwave->omega, omegaloc, ctrl);
   KS_RAISE(status);
 
   int state;
   for (state = 0; state < KS_READCONTROL_MAXSTATE; state++) {
     if (readwave->grad.p_waveformstates[state] != NULL ) {
       ks_pg_addwaveformstate(&readwave->grad, readwave->grad_states[state], state);
     }
     if (readwave->omega.p_waveformstates[state] != NULL ) {
       ks_pg_addwaveformstate(&readwave->omega, readwave->omega_states[state], state);
     }
   }
 
   /* Acquisition */
   status = ks_pg_read(&readwave->acq, omegaloc.pos, ctrl);
   KS_RAISE(status);
 
 #ifdef IPG
   short * iwave = (short *) AllocNode(readwave->omega.res * sizeof(short));
   movewaveimm(iwave, &readwave->omega.wfpulse[OMEGA][0], 0, readwave->omega.res, FROMHARDWARE);
 
   /* phase is accumulated at 10 MHz */
   int k;
   readwave->omega_iwave_phase_at_echo = 0;
   for(k = 0; k < (readwave->time2center - readwave->acqdelay); k++) {
     readwave->omega_iwave_phase_at_echo += 10 * iwave[k / GRAD_UPDATE_TIME];
   }
   FreeNode(iwave);
 #endif 
 
   return SUCCESS;
 }

◆ ks_pg_echotrain_readout()

STATUS ks_pg_echotrain_readout	(	KS_ECHOTRAIN *	echotrain,
		int	readout_index,
		int	echo_time,
		KS_ECHOTRAIN_READOUT_TIMING *	timing,
		KS_SEQ_CONTROL *	ctrl
	)

ADDTITLEHERE

                                                      {
 
   STATUS status;
 
   KS_READCONTROL *control = &echotrain->controls[readout_index];
   const int object_index = control->pg.object_index;
 
   KS_SEQLOC loc;
   loc.ampscale = control->pg.ampscale;
   loc.board = XGRAD;
 
   switch (control->pg.read_type) {
   case KS_READ_TRAP: {
     KS_READTRAP* trap = &echotrain->readtraps[object_index];
     control->pg.instance_index = ks_numplaced(&trap->acq.base);
     /* center acq over echo */
     loc.pos = RDN_GRD(echo_time - trap->acq.duration / 2 - trap->acqdelay + control->pg.shift);
     status = ks_pg_readtrap(trap, loc, ctrl);
     KS_RAISE(status);
     timing->start = loc.pos;
     timing->start_acq = loc.pos + trap->acqdelay;
     timing->end_acq = timing->start_acq + trap->acq.duration;
     timing->end = loc.pos + trap->grad.duration;
     break;
   }
   case KS_READ_WAVE: {
     KS_READWAVE* wave = &echotrain->readwaves[object_index];
     control->pg.instance_index = ks_numplaced(&wave->acq.base);
     /* center acq over echo */
     loc.pos = RDN_GRD(echo_time - wave->acq.duration / 2 - wave->acqdelay + control->pg.shift);
     status = ks_pg_readwave(wave, loc, ctrl);
     KS_RAISE(status);
     timing->start = loc.pos;
     timing->start_acq = loc.pos + wave->acqdelay;
     timing->end_acq = timing->start_acq + wave->acq.duration;
     timing->end = loc.pos + wave->grad.duration;
     break;
   }
   default: {
     return KS_THROW("echo train cannot place undefined read type");
   }
   }
 
   return SUCCESS;
 }

◆ ks_numplaced()

int ks_numplaced ( KS_BASE * base )

ADDTITLEHERE

                                 {
 #ifdef IPG
   return base->ngenerated;
 #else
   return base->ninst;
 #endif
 }

◆ ks_set_opcode()

void ks_set_opcode	(	WF_PULSE_ADDR	echo,
		short	opcode
	)

ADDTITLEHERE

                                                      {
   sspload(&opcode, echo, 1, 1, (HW_DIRECTION)TOHARDWARE, (SSP_S_ATTRIB)SSPS1);
 }

◆ ks_write_vector_bf()

int ks_write_vector_bf	(	float *	vec,
		uint32_t	numel,
		const char *	fname
	)

ADDTITLEHERE

                                                                          {
   char embedfile_uid[512];
   #ifdef PSD_HW /* on MR-scanner */
     char outputdir_uid[512];
     char cmd[512];
     sprintf(outputdir_uid, "/usr/g/mrraw/kstmp/%010d/embed/", rhkacq_uid);
     sprintf(embedfile_uid, "%s/%s", outputdir_uid, fname);
     sprintf(cmd, "mkdir -p %s > /dev/null", outputdir_uid);
     system(cmd);
   #else
     sprintf(embedfile_uid, "./%s", fname);
   #endif
   FILE* fp = fopen(embedfile_uid, "wb");
   const uint32_t rank = 1;
   fwrite(&rank, sizeof(rank), 1, fp);
   fwrite(&numel, sizeof(numel), 1, fp);
   fwrite(vec, sizeof(float), numel, fp);
   fflush(fp);
   fclose(fp);
   return SUCCESS;
 }

◆ ks_open_file_in_embed()

FILE* ks_open_file_in_embed	(	const char *	fname,
		const char *	write_mode
	)

ADDTITLEHERE

                                                                        {
   char embedfile_uid[512];
   #ifdef PSD_HW /* on MR-scanner */
     char outputdir_uid[512];
     char cmd[512];
     sprintf(outputdir_uid, "/usr/g/mrraw/kstmp/%010d/embed/", rhkacq_uid);
     sprintf(embedfile_uid, "%s/%s", outputdir_uid, fname);
     sprintf(cmd, "mkdir -p %s > /dev/null", outputdir_uid);
     system(cmd);
   #else
     sprintf(embedfile_uid, "./%s", fname);
   #endif
 
   return fopen(embedfile_uid, write_mode);
   /* to do add error handling */
 }

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

Data Structures

Macros

Typedefs

Enumerations

Functions

Variables

Detailed Description

This file contains the most documentation, and contains all definitions, sequence objects

Macro Definition Documentation

◆ WARN_UNUSED_RESULT

◆ KS_GOLDEN_MEANS_1D

◆ KS_GOLDEN_MEANS_2D_1

◆ KS_GOLDEN_MEANS_2D_2

◆ KS_ANGLE_PER_INT_16_MAX_180

◆ KS_ANGLE_PER_UINT_16_MAX_180

◆ KS_SIGN

◆ DEFAULT_SCAN_INFO_HEAD

◆ INT_MAX

◆ DEFAULT_SCAN_INFO_TAIL

◆ DEFAULT_AXIAL_SCAN_INFO

◆ DEFAULT_AX_SCAN_INFO_FREQ_LR

◆ DEFAULT_AX_SCAN_INFO_FREQ_AP

◆ DEFAULT_SAG_SCAN_INFO_FREQ_SI

◆ DEFAULT_SAG_SCAN_INFO_FREQ_AP

◆ DEFAULT_COR_SCAN_INFO_FREQ_SI

◆ DEFAULT_COR_SCAN_INFO_FREQ_LR

◆ KS_NOTSET

◆ KS_INFINITY

◆ _cvdesc

◆ KS_EXPAND_OPUSER

◆ KS_EXPAND_CVFLOAT

◆ KS_OPUSER_FROM_NUM

◆ KS_OPUSER_VALUE_FROM_NUM

◆ areSame

◆ areWithinTol

◆ areSameRelative

◆ isNotSet

◆ isSet

◆ ks_abs

◆ ks_round

◆ KS_RUP_GRD_FLOAT

◆ KS_SRC_FILE

◆ KS_THROW

◆ KS_RAISE_TRACE_FN

◆ KS_RAISE

◆ KS_ISI_predelay

◆ KS_ISI_time

◆ KS_ISI_rotupdatetime

◆ KS_ISI_postdelay

◆ KS_MINPLATEAUTIME

◆ KS_DEFAULT_SSI_TIME

◆ KS_DEFAULT_SSI_TIME_MR750w

◆ KS_DEFAULT_SSI_TIME_MR750

◆ KS_DEFAULT_SSI_TIME_MR450W

◆ KS_DEFAULT_SSI_TIME_MR450

◆ KS_DEFAULT_SSI_TIME_PREMIER

◆ KS_DEFAULT_SSI_TIME_ICE

◆ KS_DEFAULT_SSI_TIME_OTHERWISE

◆ KS_RFSSP_PRETIME

◆ KS_RFSSP_POSTTIME

◆ KS_EPI_MIN_INTERTRAIN_SSPGAP

◆ L_REF

◆ KS_SSP_PRE_READ_TIME

◆ PSD_HRMW_COIL

◆ HAVE_PREMIER_GRADIENTS

◆ HALF_KHZ_USEC

◆ KS_SAVEPFILES

◆ KS_GERECON

◆ KS_3D_SELECTED

◆ KS_3D_SINGLESLAB_SELECTED

◆ KS_3D_MULTISLAB_SELECTED

◆ KS_PLANE_AX

◆ KS_PLANE_COR

◆ KS_PLANE_SAG

◆ KS_DESCRIPTION_LENGTH

◆ KS_MAXWAVELEN

◆ KS_MAXUNIQUE_RF

◆ KS_MAXUNIQUE_TRAP

◆ KS_MAXUNIQUE_WAVE

◆ KS_MAXUNIQUE_WAIT