KSFoundation_common.c File Reference

Data Structures
struct	_phaseencoding_coord_pool_s

Macros
#define	ABORT_ON_KSERROR   0
#define	_INIT_PHASEENCODING_COORD_POOL   {0, 0, NULL, 0, 0};
#define	PHASEENCODING_PLAN_FILENAME   "ks_phaseencodingtable.host.txt"

Functions
STATUS	acqq_longdab (WF_PULSE_ADDR pulse, LONG pos_ref, LONG dab_ref, LONG xtr_ref, LONG fslot_value)
int	isNaN (float a)
STATUS	ks_error (const char *format,...)
void	ks_dbg_reset ()
STATUS	ks_dbg (const char *format,...)
STATUS	existfile (const char *fname)
int	ks_syslimits_hasICEhardware ()
float	ks_syslimits_ampmax_phys ()
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)
float	ks_syslimits_gradtarget (LOG_GRAD loggrd, int board)
int	ks_syslimits_ramptimemax (LOG_GRAD loggrd)
int	ks_syslimits_ramptimemax_phys ()
float	ks_syslimits_slewrate_phys ()
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)
unsigned short	ks_cycles_to_iphase (double cycles)
unsigned short	ks_degrees_to_iphase (double degrees)
unsigned short	ks_radians_to_iphase (double radians)
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)
float	ks_calc_selgradamp (float rfbw, float slthick)
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)
void	ks_init_dynamic (KS_DYNAMIC_STATE *dynamic)
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_phaseencoding_memorypool_init (KS_PHASEENCODING_COORD *entries, uint64_t size)
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)
void	ks_phaseencoding_set (KS_PHASEENCODING_PLAN *phaseenc_plan_ptr, int encode, int shot, int ky, int kz)
void	ks_create_suffixed_description (char *const out, const char *const prefix, const char *const suffix,...)
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)
int	ks_phaseencoding_isvalid (const KS_PHASEENCODING_PLAN *phaseenc_plan_ptr)
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_simple (KS_PHASEENCODING_PLAN *phaseenc_plan_ptr, const char *const desc, KS_PHASER *phaser, KS_PHASER *zphaser, int encodes_per_shot)
STATUS	ks_phaseencoding_generate_simple_ellipse (KS_PHASEENCODING_PLAN *phaseenc_plan_ptr, const char *const desc, KS_PHASER *phaser, KS_PHASER *zphaser)
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)
void	ks_wave_compute_params (KS_WAVE *const wave)
int	ks_wave_res (const KS_WAVE *wave)
int	ks_echotrain_get_max_kspace_index (KS_ECHOTRAIN *echotrain)
STATUS	ks_pg_echotrain_readout (KS_ECHOTRAIN *echotrain, int readout_index, int echo_time, KS_ECHOTRAIN_READOUT_TIMING *timing, KS_SEQ_CONTROL *ctrl)
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)
short	ks_iwave_absmax (const KS_IWAVE waveform, int res)
float	ks_waveform_absmax (const KS_WAVEFORM waveform, int res)
float	ks_wave_absmax (const KS_WAVE *wave)
float	ks_waveform_maxslew (const KS_WAVEFORM waveform, int res, int duration, int *index)
float	ks_wave_maxslew (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_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)
STATUS	ks_wave2iwave (KS_IWAVE iwave, const KS_WAVE *wave, int board)
WF_PULSE *	ks_pg_echossp (WF_PULSE *echo, const char *suffix)
void	ks_pg_trap_make_symramps (KS_TRAP *trap, float min_fs_factor, KS_IWAVE attack, KS_IWAVE decay)
STATUS	ks_pg_trap (KS_TRAP *trap, KS_SEQLOC loc, KS_SEQ_CONTROL *ctrl)
STATUS	ks_pg_phaser (KS_PHASER *phaser, KS_SEQLOC loc, KS_SEQ_CONTROL *ctrl)
STATUS	ks_pg_read (KS_READ *read, int pos, KS_SEQ_CONTROL *ctrl)
STATUS	ks_pg_readtrap (KS_READTRAP *readtrap, KS_SEQLOC loc, KS_SEQ_CONTROL *ctrl)
STATUS	ks_pg_readwave (KS_READWAVE *readwave, KS_SEQLOC loc, KS_SEQ_CONTROL *ctrl)
STATUS	ks_pg_wave (KS_WAVE *wave, KS_SEQLOC loc, KS_SEQ_CONTROL *ctrl)
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)
STATUS	ks_pg_selrf (KS_SELRF *selrf, KS_SEQLOC loc, KS_SEQ_CONTROL *ctrl)
STATUS	ks_pg_wait (KS_WAIT *wait, KS_SEQLOC loc, KS_SEQ_CONTROL *ctrl)
STATUS	ks_pg_isirot (KS_ISIROT *isirot, SCAN_INFO scan_info, int pos, void(*rotfun)(), KS_SEQ_CONTROL *ctrl)
STATUS	ks_pg_epi_dephasers (KS_EPI *epi, KS_SEQLOC loc, KS_SEQ_CONTROL *ctrl)
STATUS	ks_pg_epi_rephasers (KS_EPI *epi, KS_SEQLOC loc, KS_SEQ_CONTROL *ctrl)
STATUS	ks_pg_epi_echo (KS_EPI *epi, KS_SEQLOC loc, KS_SEQ_CONTROL *ctrl)
STATUS	ks_pg_epi (KS_EPI *epi, KS_SEQLOC loc, KS_SEQ_CONTROL *ctrl)
void	ks_pg_mod_fse_rfpulse_structs (KS_SELRF *rf1, KS_SELRF *rf2, KS_SELRF *rf3, const double *flip_angles, const int etl)
STATUS	ks_pg_fse_flip_angle_taperoff (double *flip_angles, int etl, double flip1, double flip2, double flip3, double target_flip, int start_middle)
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_init_rtscalelog (KS_RT_SCALE_LOG *const rtscale)
void	ks_instancereset_trap (KS_TRAP *trap)
void	ks_instancereset_wave (KS_WAVE *wave)
void	ks_instancereset_wait (KS_WAIT *wait)
void	ks_instancereset_phaser (KS_PHASER *phaser)
void	ks_instancereset_readtrap (KS_READTRAP *read)
void	ks_instancereset_rf (KS_RF *rf)
void	ks_instancereset_selrf (KS_SELRF *selrf)
void	ks_instancereset_epi (KS_EPI *epi)
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_mat3_invapply (double *w, const KS_MAT3x3 R, const double *v)
void	ks_mat3f_apply (float *w, const KS_MAT3x3f R, const float *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)
int	ks_compare_loc_by_timeboard (const KS_SEQLOC *a, const KS_SEQLOC *b)
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)
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_compare_pshort (const void *v1, const void *v2)
int	ks_compare_pint (const void *v1, const void *v2)
int	ks_compare_pfloat (const void *v1, const void *v2)
int	ks_compare_short (const void *v1, const void *v2)
int	ks_compare_int (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_plot_slicetime_begin ()
void	ks_plot_slicetime (const KS_SEQ_CONTROL *ctrl, int nslices, float *slicepos_mm, float slthick_mm, KS_PLOT_EXCITATION_MODE excmode)
void	ks_plot_slicetime_endofpass (KS_PLOT_PASS_MODE pass_mode)
void	ks_plot_slicetime_endofslicegroup_tagged (const char *desc, const KS_PLOT_SLICEGROUP_MODE tag)
void	ks_plot_slicetime_endofslicegroup (const char *desc)
void	ks_plot_slicetime_end ()
void	ks_plot_tgt_reset (KS_SEQ_CONTROL *ctrl)
void	ks_plot_tgt_addframe (KS_SEQ_CONTROL *ctrl)
STATUS	ks_eval_addtraptogradrfctrl (KS_GRADRFCTRL *gradrfctrl, KS_TRAP *trap)
STATUS	ks_eval_addwaittogradrfctrl (KS_GRADRFCTRL *gradrfctrl, KS_WAIT *wait)
FILE *	ks_open_file_in_embed (const char *fname, const char *write_mode)
STATUS	ks_eval_addwavetogradrfctrl (KS_GRADRFCTRL *gradrfctrl, KS_WAVE *wave)
STATUS	ks_eval_addrftogradrfctrl (KS_GRADRFCTRL *gradrfctrl, KS_RF *rf)
STATUS	ks_eval_addreadtogradrfctrl (KS_GRADRFCTRL *gradrfctrl, KS_READ *read)
float	ks_scan_rf_phase_spoiling (int counter)
int	ks_numplaced (KS_BASE *base)
int	ks_scan_gettherightshot (const KS_DYNAMIC_STATE *dynamic)
float	ks_get_trapamp_instance (const KS_TRAP *trap, int instance)
const KS_READ *	ks_get_read_in_echotrain (const KS_ECHOTRAIN *echotrain, const int readout_index)
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)
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)

Variables
int	maxGradRes
int	psd_rf_wait
int	psd_grd_wait
int	cfssctype
float	opfov
int	opxres
int	opyres
float	opslthick
int	rhkacq_uid
int	ks_plot_filefmt
char	ks_psdname [256]
int	abort_on_kserror = ABORT_ON_KSERROR
int	ks_rhoboard = TYPRHO1
struct _phaseencoding_coord_pool_s	_phaseencoding_coord_pool = _INIT_PHASEENCODING_COORD_POOL

Detailed Description

This file contains functions accessible on both HOST and TGT

Macro Definition Documentation

ABORT_ON_KSERROR

#define ABORT_ON_KSERROR   0

_INIT_PHASEENCODING_COORD_POOL

#define _INIT_PHASEENCODING_COORD_POOL   {0, 0, NULL, 0, 0};

PHASEENCODING_PLAN_FILENAME

#define PHASEENCODING_PLAN_FILENAME   "ks_phaseencodingtable.host.txt"

Function Documentation

acqq_longdab()

STATUS acqq_longdab	(	WF_PULSE_ADDR	pulse,
		LONG	pos_ref,
		LONG	dab_ref,
		LONG	xtr_ref,
		LONG	fslot_value
	)

{
    static const CHAR *routine = "acqq_longdab";
    CHAR *basename = NULL;
    INT start;                   /* Start of the pulse */
    WF_PULSE_ADDR newpulse;      /* Pointer to new pulse */
    INT pack_ix = 0;           /* CERD change */
    INT LONG_DAB_length = 31; /* Maximum is 31, hardware limitation */
    SHORT LONG_DAB_bits[31]; /* Maximum is 31, hardware limitation */
#ifdef PGEN_TIMING
    extern INT time_pgen;
    if (time_pgen == 1) {
        start_timer(&_PGEN_start_time);
    }
#endif

    pack_ix = PSD_XCVR2;

#ifdef SIM_IO
    if (psdtrace3)
    {
        CHAR tmpname[50];
        if (pulse->pulsename == NULL)
            strcpy(tmpname,"");
        else
            strcpy(tmpname,pulse->pulsename);

        fprintf(stderr,"%s  pulse: %s  posref %d xtrref %d dabref %d fslot %d\n",
                routine,
                tmpname,
                pos_ref,
                xtr_ref,
                dab_ref,
                fslot_value);
        fflush(stderr);
    }
#endif
    LONG_DAB_bits[0] = SSPDS + DABDC;        /* CAPM , CERD change: new opcode */
    LONG_DAB_bits[1] = SSPOC + DXCT;         /* Excitation , CERD change: ew opcode */
    LONG_DAB_bits[2] = SSPD;
    LONG_DAB_bits[3] = SSPD;
    LONG_DAB_bits[4] = SSPD;
    LONG_DAB_bits[5] = SSPD;
    LONG_DAB_bits[6] = SSPD;
    LONG_DAB_bits[7] = SSPD + DABIS; /* if DABIS is really needed is unclear, we leave it for the moment */
    LONG_DAB_bits[8] = SSPD;
    LONG_DAB_bits[9] = SSPD;
    LONG_DAB_bits[10] = SSPD;
    LONG_DAB_bits[11] = SSPD;
    LONG_DAB_bits[12] = SSPD;
    LONG_DAB_bits[13] = SSPD;
    LONG_DAB_bits[14] = SSPD;
    LONG_DAB_bits[15] = SSPD;
    LONG_DAB_bits[16] = SSPD;
    LONG_DAB_bits[17] = SSPD;
    LONG_DAB_bits[18] = SSPD;
    LONG_DAB_bits[19] = SSPD;
    LONG_DAB_bits[20] = SSPD;
    LONG_DAB_bits[21] = SSPD;
    LONG_DAB_bits[22] = SSPD;
    LONG_DAB_bits[23] = SSPD;
    LONG_DAB_bits[24] = SSPD;
    LONG_DAB_bits[25] = SSPD;
    LONG_DAB_bits[26] = SSPD;
    LONG_DAB_bits[27] = SSPD;
    LONG_DAB_bits[28] = SSPD;
    LONG_DAB_bits[29] = SSPD;
    LONG_DAB_bits[30] = SSPDS; /* Last field must be SSPDS, max number of fields = 31 */

    /* Make sure packets are ordered properly (dab->xtr->rba) and that
       the dab packet doesn't collide with xtr packet. */
    if ((dab_ref != DEFAULTPOS) && (xtr_ref != DEFAULTPOS) &&
        (dab_ref + LONG_DAB_length > xtr_ref))
        MsgHndlr(routine, 
                 MSG_PULSE, pulse,
                 MSG_FORMAT,
                 CODING_PBM, 
                 EMT_INVLD_INSTR_START, 
                 dab_ref);

    /* Make sure there is enough room for xtr packet */
    if ((xtr_ref != DEFAULTPOS) &&
        (pos_ref - xtr_ref < (XTR_length[pack_ix] + RBA_length[pack_ix])))
        MsgHndlr(routine, 
                 MSG_PULSE, pulse,
                 MSG_FORMAT,
                 CODING_PBM, 
                 EMT_INVLD_INSTR_START, 
                 xtr_ref);

    if ((xtr_ref == DEFAULTPOS) && (RBA_length[pack_ix] > XTRSETLNG))
        MsgHndlr(routine, 
                 MSG_PULSE, pulse,
                 MSG_FORMAT,
                 CODING_PBM, 
                 EMT_INVLD_INSTR_START, 
                 pos_ref);

    /* This routine assumes that the user has created the
     *  the pulse passed into this routine with the pre-processor
     */

    /***** The bits will be created first ****/
    /* The first thing this routine will do will be to verify if
     *  any bits have been created or no.
     */

    if (pulse-> ninsts == 0)
    {

        /***************************************/
        /**** Create DAB 'bits' Pulse **********/
        /***************************************/

        if (!(basename = (CHAR *)AllocNode(strlen(pulse->  pulsename)+1)))
        {
            MsgHndlr(routine,  MSG_FORMAT, HARDWARE_PBM,
                     EMT_ALLOC, pulse->  pulsename);
        }
        strcpy(basename, pulse-> pulsename);

        char* dabname = (char *)AllocNode(strlen(basename)+4);
        /* Create Name For Pulse */
        if (!dabname)
        {
            MsgHndlr(routine, MSG_PULSE, pulse, 
                     MSG_FORMAT, HARDWARE_PBM,
                     EMT_ALLOC, "DAB Bits Pulse Name");
        }

        /* Append "dab" suffix for loaddab... routines */
        sprintf(dabname,"%sdab",basename);
        pulse-> pulsename = dabname;

        createbits(pulse, (WF_PROCESSOR)TYPSSP,
                   LONG_DAB_length,
                   LONG_DAB_bits);

        /***************************************/
        /**** Create XTR 'bits' Pulse **********/
        /***************************************/

        if (!(newpulse = (WF_PULSE *)AllocNode(sizeof(WF_PULSE))))
        {

            MsgHndlr(routine, MSG_FORMAT,
                     HARDWARE_PBM, EMT_ALLOC, "Receive Bits");

        }

        char* xtrname = (char *)AllocNode(strlen(basename)+4);
        /* Create Name For Pulse */
        if (!xtrname)
        {
            MsgHndlr(routine, MSG_PULSE, pulse,
                     MSG_FORMAT, 
                     HARDWARE_PBM,
                     EMT_ALLOC, 
                     "Xtr Bits Pulse Name"); 
        }

        /* Attach to dab pulse */
        pulse-> assoc_pulse = newpulse;

        /* Append xtr for use by other routines */
        sprintf(xtrname,"%sxtr",basename);
        newpulse-> pulsename = xtrname;

        /* Verify the parameters for the pulse */

        /* Begin LxMGD - RJF 12/6/00 */

        /* For MGD, there is a maximum of 8 filters with slot numbers 0 thru 7. 
           The filter block is terminated with a slot number of -1.
           So the valid filter slots are from 0 to 7 - RJF */

        if ((fslot_value < MIN_FILTER_SLOT) || (fslot_value > MAX_FILTER_SLOT) )
        {
            MsgHndlr(routine,
                     MSG_PULSE, newpulse,
                     MSG_FORMAT,
                     CODING_PBM,
                     EMT_DAB_SLOT_NO,
                     fslot_value);
        }

        /* Begin LxMGD - RJF, 12/6/00 */
        /*   The way XTR bits was set up for CERD was wrong 
             (see sspinit.c, which initializes the 
             packet.) The receiver values should have been at offset 10
             and the filter slot value should be at offset 11. */

        XTR_bits[pack_ix][10] = SSPOC + RFLTRS;
        XTR_bits[pack_ix][11] = SSPD + fslot_value;

        /* End CERD change */

        /* Insert EOS */
        XTR_bits[pack_ix][XTR_length[pack_ix]-1] = SSPDS;

        createbits(newpulse, 
                   (WF_PROCESSOR)TYPSSP,  
                   XTR_length[pack_ix], 
                   XTR_bits[pack_ix]);


        /*************************************/
        /**** Create Receive 'bits' Pulse ****/
        /*************************************/

        if (!(newpulse = (WF_PULSE *)AllocNode(sizeof(WF_PULSE))))
        {

            MsgHndlr(routine, MSG_FORMAT,
                     HARDWARE_PBM, EMT_ALLOC, "Receive Bits");

        }

        char* rbaname = (char *)AllocNode(strlen(basename)+4);
        /* Create Name For Pulse */
        if (!rbaname)
        {
            MsgHndlr(routine, MSG_PULSE, pulse,
                     MSG_FORMAT, 
                     HARDWARE_PBM,
                     EMT_ALLOC, 
                     "Receive Bits Pulse Name");
        }
        sprintf(rbaname,"%srba",basename);
        newpulse-> pulsename = rbaname;

        /* Attach to exciter pulse */
        pulse-> assoc_pulse -> assoc_pulse = newpulse;


        createbits(newpulse, 
                   (WF_PROCESSOR)TYPSSP,  
                   RBA_length[pack_ix], 
                   RBA_bits[pack_ix]);
        /* End CERD change */

    }

    /********** End of creating bits *******************/

    /***************************************/
    /**** Create XTR Instruction ***********/
    /***************************************/

    /* Back off for settling time of exciter */
    if (xtr_ref == DEFAULTPOS) {
        start = pos_ref - (XTRSETLNG + XTR_length[pack_ix]); 
    } else {
        start = xtr_ref;
    }
    createinstr(pulse -> assoc_pulse,
                start,
                XTR_length[pack_ix],
                0);

    pulse->assoc_pulse-> tag = SSPXTR;

    /***************************************/
    /**** Create DAB Instruction ***********/
    /***************************************/
    /* The DAB needs at least DABSETUP set-up time. */
    if (dab_ref == DEFAULTPOS) {
        if (xtr_ref == DEFAULTPOS) {
            start = pos_ref - IMax(2, DABSETUP, 
                                   XTRSETLNG + XTR_length[pack_ix] + LONG_DAB_length);
        } else {
            start = IMin(2, pos_ref-DABSETUP,xtr_ref-LONG_DAB_length);
        }

    } else {
        start = dab_ref;
    }

    /* For DAB packet */
    createinstr(pulse, start, LONG_DAB_length, 0);

    pulse->tag = SSPDAB;

    /***************************************/
    /**** Create RBA Instruction ***********/
    /***************************************/
    /* Back off by length of RBA packet */

    start = pos_ref - RBA_length[pack_ix];

    createinstr(pulse -> assoc_pulse -> assoc_pulse, 
                start + RBA_start, 
                RBA_length[pack_ix], 
                0);

    pulse-> assoc_pulse-> assoc_pulse-> tag = SSPRBA;
    /* End of CERD change */  
    FreeNode(basename);   /* Arg must be a LONG  : pradeep */
#ifdef PGEN_TIMING
    if (time_pgen == 1) {

        end_timer(_PGEN_start_time,acqq_ix,"acqq");

    }
#endif

    return SUCCESS;
}

isNaN()

int isNaN

(

float

a

)

                   {
  return a != a;
}

ks_error()

STATUS ks_error	(	const char *	format,
			...
	)

                                         {
  char errstring[1000];
  FILE *fp;
  time_t mytime;
  char mydatestr[100];

  va_list args;
  va_start(args, format);
  vsprintf(errstring, format, args);
  va_end(args);
  mytime = time(NULL);
  sprintf(mydatestr, "%s", ctime(&mytime));
  mydatestr[strcspn(mydatestr, "\n")] = 0; /* remove newline character */

#ifdef PSD_HW
  /* Report the error in the debug file also so that "stack traces" 
     from KS_RAISE are completed. */
  ks_dbg("HOST ERROR - %s", errstring);

  /* if on MR scanner (HOST and TGT/IPG, HW=hardware=MRscanner) */
  fp = fopen("/usr/g/mrraw/ks_errors.txt", "a+");
#else
  /* in WTools (simulation)  (HOST and TGT/IPG) */
  fp = stdout;
#endif

#ifdef IPG
  char side[] = "TGT";
#else
  char side[] = "HOST";
#endif

#ifdef REV
  fprintf(fp, "%s ERROR %s@%s [%s] - %s\n", side, ks_psdname, REV, mydatestr, errstring);
#else
  fprintf(fp, "%s ERROR %s [%s] - %s\n", side, ks_psdname, mydatestr, errstring);
#endif

  fflush(fp);

#ifdef PSD_HW
  /* if on MR scanner */
  fclose(fp);
#endif

#if defined(HOST_TGT)
  /* HOST_TGT: HOST for either WTools or MR scanner */

  char *err_tail = strrchr(errstring, ':');
  epic_error( 0, err_tail ? err_tail + 1 : errstring, 0, EE_ARGS(0));
#endif

  if (abort_on_kserror) {
    abort();
  }

  return ADVISORY_FAILURE;
}

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

STATUS ks_dbg	(	const char *	format,
			...
	)

                                       {
  char fname[1000];
  char string[1000];
  FILE *fp;
  time_t mytime;
  char mydatestr[100];

  va_list args;
  va_start(args, format);
  vsprintf(string, format, args);
  va_end(args);


#ifdef PSD_HW
#ifdef IPG
  return SUCCESS; /* Don't run ks_dbg() on MR scanner TGT to avoid potential real-time issues writing to disk */
#endif
  /* MR scanner */
  sprintf(fname, "/usr/g/mrraw/ks_debug.txt");
#else
  /* Simulation (WTools) */
  sprintf(fname, "./ks_debug.txt");
#endif

  mytime = time(NULL);
  sprintf(mydatestr, "%s", ctime(&mytime));
  mydatestr[strcspn(mydatestr, "\n")] = 0; /* remove newline character */

  fp = fopen(fname, "a+");

#ifdef REV
  fprintf(fp, "%s@%s [%s] - %s\n", ks_psdname, REV, mydatestr, string);
#else
  fprintf(fp, "%s [%s] - %s\n", ks_psdname, mydatestr, string);
#endif

  fflush(fp);
  fclose(fp);

  return SUCCESS;

}

existfile()

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

float ks_syslimits_ampmax_phys

(

)

ADDTITLEHERE

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

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

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

                                                                                                              {
  char suffix_complete[1000];
  va_list args;
  va_start(args, suffix);
  vsprintf(suffix_complete, suffix, args);
  va_end(args);
  if ((strlen(prefix) + strlen(suffix_complete)) > KS_DESCRIPTION_LENGTH) {
    KS_THROW("Description string (prefix \"%s\", suffix \"%s\") does not fit into a KS_DESCRIPTION (%d%+d > %d)", prefix, suffix_complete, strlen(prefix), strlen(suffix_complete), KS_DESCRIPTION_LENGTH);
  }
#if EPIC_RELEASE > 29 || (EPIC_RELEASE == 29 && EPIC_SUBRELEASE == 1)
  snprintf(out, KS_DESCRIPTION_LENGTH, "%s%s", prefix, suffix_complete);
#else
  int num_to_print = KS_DESCRIPTION_LENGTH - strlen(prefix);
  num_to_print = IMin(2, num_to_print, strlen(suffix_complete));
  sprintf(out, "%s%.*s", prefix, num_to_print, suffix_complete);
#endif
}

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

float ks_wave_absmax

(

const KS_WAVE *

wave

)

Returns the maximum absolute value in a KS_WAVE sequence object

Parameters

[in]

wave

KS_WAVE object

Return values

absmaxval

Maximum absolute value

                                          {
  return ks_waveform_absmax(wave->waveform, wave->res);
}

ks_waveform_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_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_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_make_symramps()

void ks_pg_trap_make_symramps	(	KS_TRAP *	trap,
		float	min_fs_factor,
		KS_IWAVE	attack,
		KS_IWAVE	decay
	)

                                                                                                    {
  const int res = trap->ramptime / GRAD_UPDATE_TIME;
  /* for exact shape in iwave for half steps */
  int step_size = 2 * res;

  /* compute the nearest lowest fs_factor that allows exact ramp representation */
  float fs = trap->fs_factor * (float)(max_pg_wamp>>1);
  if (fs > 0.0f) {
    trap->fs_factor *= ((int)(fs / step_size) * step_size) / fs;
  }

  /* compute the minimum fs_factor for exact ramp */
  float min_fs = min_fs_factor * (float)(max_pg_wamp>>1);
  min_fs_factor *= ((int)(min_fs / step_size + 1.0f) * step_size) / min_fs;

  /* change fs_factor to min if needed */
  if (trap->fs_factor < min_fs_factor) {
    trap->fs_factor = min_fs_factor;
  }

  /* fullscale in iwave memory */
  short fs_exact = (short)(trap->fs_factor * (float)(max_pg_wamp>>1));

  /* use float in case an exact slope is not possible */
  float half_ramp_slope = (float)fs_exact / (float)step_size;

  if (trap->fs_factor > 1.0f) {
    /* an exact representation of the ramp is not possible */
    trap->fs_factor = 1.0f;
    fs_exact = (max_pg_wamp>>1);
    half_ramp_slope = (float)fs_exact / (float)step_size;
  }

  /* form ramps and exploit symmetry */
  int i = 0;
  for(i = 0; i < res; i++) {
    attack[i] = (int)(half_ramp_slope + 2 * half_ramp_slope * i) << 1;
    decay[res - 1 - i] = attack[i];
  }
  /* set end-of-waveform flag */
  attack[res - 1] |= WEOS_BIT;
  decay[res - 1] |= WEOS_BIT;
}

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

STATUS 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_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_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_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_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_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_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_wave()

void ks_instancereset_wave

(

KS_WAVE *

wave

)

                                          {
  if (!wave) { return; }

  wave->base.ngenerated = 0;
  wave->wfpulse = NULL;
  wave->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_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_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_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_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_compare_loc_by_timeboard()

int ks_compare_loc_by_timeboard	(	const KS_SEQLOC *	a,
		const KS_SEQLOC *	b
	)

                                                                        {

return (a->pos > b->pos) - (a->pos < b->pos) +
       (a->pos == b->pos) * ((a->board > b->board) - (a->board < b->board));
}

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

void ks_plot_slicetime_end

(

)

ADDTITLEHERE

ADDDESCHERE

Returns

void

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

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_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_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_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_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 */
}

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

int ks_numplaced

(

KS_BASE *

base

)

ADDTITLEHERE

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

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_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_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_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];
}

Variable Documentation

maxGradRes

int maxGradRes

psd_rf_wait

int psd_rf_wait

psd_grd_wait

int psd_grd_wait

cfssctype

int cfssctype

opfov

float opfov

opxres

int opxres

opyres

int opyres

opslthick

float opslthick

rhkacq_uid

int rhkacq_uid

ks_plot_filefmt

int ks_plot_filefmt

ks_psdname

char ks_psdname[256]

abort_on_kserror

int abort_on_kserror = ABORT_ON_KSERROR

ks_rhoboard

int ks_rhoboard = TYPRHO1

_phaseencoding_coord_pool

struct _phaseencoding_coord_pool_s _phaseencoding_coord_pool = _INIT_PHASEENCODING_COORD_POOL