KSFoundation_common.c File Reference

Macros
#define	ABORT_ON_KSERROR   0

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)
short	ks_phase_radians2hw (float phase)
short	ks_phase_degrees2hw (float phase)
void	ks_polyval (const double *coeffs, const int order, const float x[], const int numx, float values[])
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_phaseencoding_init_tgt (KS_PHASEENCODING_PLAN *phaseenc_plan_ptr)
KS_PHASEENCODING_COORD	ks_phaseencoding_get (const KS_PHASEENCODING_PLAN *phaseenc_plan_ptr, int echo, int shot)
void	ks_phaseencoding_set (KS_PHASEENCODING_PLAN *phaseenc_plan_ptr, int echo, int shot, int ky, int kz)
void	ks_phaseencoding_print (const KS_PHASEENCODING_PLAN *phaseenc_plan_ptr)
STATUS	ks_phaseencoding_resize (KS_PHASEENCODING_PLAN *phaseenc_plan_ptr, int etl, int num_shots)
STATUS	ks_phaseencoding_generate_simple (KS_PHASEENCODING_PLAN *phaseenc_plan_ptr, const char *const desc, KS_PHASER *phaser, KS_PHASER *zphaser)
STATUS	ks_phaseencoding_generate_simple_ellipse (KS_PHASEENCODING_PLAN *phaseenc_plan_ptr, const char *const desc, KS_PHASER *phaser, KS_PHASER *zphaser)
STATUS	ks_fse_calcecho (double *bestecho, double *optecho, int *nacqlines_to_kspacecenter, KS_PHASER *pe, ks_enum_pf_earlylate_te pf_direction, int TE, int etl, int esp)
STATUS	ks_phaseencoding_generate_2Dfse (KS_PHASEENCODING_PLAN *phaseenc_plan_ptr, const char *const desc, KS_PHASER *phaser, KS_PHASER *zphaser, ks_enum_pf_earlylate_te pf_direction, int TE, int etl, int esp)
STATUS	ks_phaseencoding_generate_epi (KS_PHASEENCODING_PLAN *phaseenc_plan_ptr, const char *const desc, const KS_EPI *epitrain, const ks_enum_epiblipsign blipsign, const ks_enum_pf_earlylate_te pf_direction, const int numileavestoacq, ks_enum_sweep_order sweep_order, int numsegments, const int caipi_delta)
STATUS	ks_phaseencoding_generate_allepiplans (KS_PHASEENCODING_ALLEPIPLANS phaseenc_plans, const char *const desc, const KS_EPI *epitrain, const int caipi_delta)
STATUS	ks_phaseencoding_allepiplans_setechoes (KS_PHASEENCODING_PLAN_16PTRS peplan_echoes, KS_PHASEENCODING_ALLEPIPLANS allepiplans, int nechoes, int multishot_flag, int min1stTE, int mirrorTE, ks_enum_epiblipsign blipsign)
int	ks_wave_res (const KS_WAVE *wave)
float	ks_waveform_max (const KS_WAVEFORM waveform, int res)
float	ks_wave_max (const KS_WAVE *wave)
float	ks_waveform_min (const KS_WAVEFORM waveform, int res)
float	ks_wave_min (const KS_WAVE *wave)
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)
float	ks_wave_maxslew (const KS_WAVE *wave)
float	ks_waveform_area (const KS_WAVEFORM waveform, int start, int end, int dwelltime)
float	ks_wave_area (const KS_WAVE *wave, int start, int end)
float	ks_waveform_sum (const KS_WAVEFORM waveform, int res)
float	ks_wave_sum (const KS_WAVE *wave)
float	ks_waveform_norm (const KS_WAVEFORM waveform, int res)
float	ks_wave_norm (const KS_WAVE *wave)
void	ks_waveform_cumsum (KS_WAVEFORM cumsumwaveform, const KS_WAVEFORM waveform, int res)
void	ks_wave_cumsum (KS_WAVE *cumsumwave, const KS_WAVE *wave)
void	ks_waveform_multiply (KS_WAVEFORM waveform_mod, const KS_WAVEFORM waveform, int res)
void	ks_wave_multiply (KS_WAVE *wave_mod, const KS_WAVE *wave)
void	ks_waveform_add (KS_WAVEFORM waveform_mod, const KS_WAVEFORM waveform, int res)
void	ks_wave_add (KS_WAVE *wave_mod, const KS_WAVE *wave)
void	ks_waveform_multiplyval (KS_WAVEFORM waveform, float val, int res)
void	ks_wave_multiplyval (KS_WAVE *wave, float val)
void	ks_waveform_addval (KS_WAVEFORM waveform, float val, int res)
void	ks_wave_addval (KS_WAVE *wave, float val)
STATUS	ks_waveform2iwave (KS_IWAVE iwave, const KS_WAVEFORM waveform, int res, int board)
STATUS	ks_wave2iwave (KS_IWAVE iwave, const KS_WAVE *wave, int board)
WF_PULSE *	ks_pg_echossp (WF_PULSE *echo, const char *suffix)
STATUS	ks_pg_trap (KS_TRAP *trap, KS_SEQLOC loc, KS_SEQ_CONTROL *ctrl)
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_wave (KS_WAVE *wave, KS_SEQLOC loc, KS_SEQ_CONTROL *ctrl)
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)
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_setgeometry (KS_MAT4x4 lhs, float x, float y, float z, float xr, float yr, float zr)
void	ks_mat4_setrotation1axis (KS_MAT4x4 rhs, float rot, char axis)
void	ks_mat4_extractrotation (KS_MAT3x3 R, const KS_MAT4x4 M)
void	ks_mat4_extracttranslation (double *T, const KS_MAT4x4 M)
void	ks_mat3_identity (KS_MAT3x3 m)
void	ks_mat3_multiply (KS_MAT3x3 lhs, const KS_MAT3x3 rhs_left, const KS_MAT3x3 rhs_right)
void	ks_mat3_print (const KS_MAT3x3 m)
void	ks_mat3_apply (double *w, const KS_MAT3x3 R, const double *v)
void	ks_mat3_invapply (double *w, const KS_MAT3x3 R, const double *v)
void	ks_scan_update_slice_location (SCAN_INFO *new_loc, const SCAN_INFO orig_loc, const KS_MAT4x4 M_physical, const KS_MAT4x4 M_logical)
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_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 (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_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)

Variables
int	maxGradRes
int	cfswgut
int	cfswrfut
int	psd_rf_wait
int	psd_grd_wait
float	GAM
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

Detailed Description

This file contains functions accessible on both HOST and TGT.

Macro Definition Documentation

ABORT_ON_KSERROR

#define ABORT_ON_KSERROR   0

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
  /* 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
  /* tgt.c: TGT/IPG side */
  fprintf(fp, "TGT ERROR %s [%s]: %s\n", ks_psdname, mydatestr, errstring);
#else
  /* host.c: HOST side */
  fprintf(fp, "HOST ERROR %s [%s]: %s\n", 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 */
  epic_error( 0, errstring, 0, EE_ARGS(0));
#endif

  if (abort_on_kserror) {
    abort();
  }

  return 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+");

  fprintf(fp, "%s [%s]: %s\n", ks_psdname, mydatestr, string);

  fflush(fp);
  fclose(fp);

  return SUCCESS;

}

existfile()

STATUS existfile

(

const char *

fname

)

                                    {
    FILE *file;
    if ((file = fopen(fname, "r"))) {
        fclose(file);
        return SUCCESS;
    }
    return FAILURE;
}

ks_syslimits_hasICEhardware()

int ks_syslimits_hasICEhardware

(

)

Check for ICE Hardware (e.g. RX27+ on SIGNA Premier)

Return values

int	1: ICE 0: MGD

                                  {
  int isice = FALSE;
#if EPIC_RELEASE >= 27
  isice = cfssctype;
#endif

  return isice;

}

ks_syslimits_ampmax_phys()

float ks_syslimits_ampmax_phys

(

)

Returns the integer phase (not in use)

All phase values in KSFoundation are in [degrees], including flip angles, RF/receive phases and THETA waveforms. This function is therefore currently not used. See instead ks_phase_degrees2hw()

Parameters

[in]

radphase

Phase in radians

Return values

intphase

Integer phase to use on THETA board on hardware

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

ks_syslimits_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;
  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

(

)

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

ks_syslimits_slewrate_phys()

float ks_syslimits_slewrate_phys

(

)

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

ks_syslimits_slewrate()

float ks_syslimits_slewrate

(

LOG_GRAD

loggrd

)

Returns the maximum slewrate that can be used on all gradient boards simultaneously

The return value from this function is the ratio of ks_syslimits_ampmax() and ks_syslimits_ramptimemax() and can be passed in as slewrate to all ks_eval***_constrained() functions

Parameters

[in]

loggrd

GE's LOG_GRAD struct, dependent on the gradient system and current slice angulation

Return values

slewrate

Maximum slewrate ([(G/cm) / us]) that can be used on all boards simultaneously

                                             {
  return (ks_syslimits_ampmax(loggrd) / ks_syslimits_ramptimemax(loggrd));
}

ks_syslimits_slewrate2()

float ks_syslimits_slewrate2

(

LOG_GRAD

loggrd

)

Returns the maximum slewrate that can be used on two gradient boards simultaneously

The return value from this function is the ratio of ks_syslimits_ampmax2() and ks_syslimits_ramptimemax() and can be passed in as slewrate to all ks_eval***_constrained() functions

Parameters

[in]

loggrd

GE's LOG_GRAD struct, dependent on the gradient system and current slice angulation

Return values

slewrate

Maximum slewrate ([(G/cm) / us]) that can be used on all boards simultaneously

                                              {
  return (ks_syslimits_ampmax2(loggrd) / ks_syslimits_ramptimemax(loggrd));
}

ks_syslimits_slewrate1()

float ks_syslimits_slewrate1

(

LOG_GRAD

loggrd

)

Returns the maximum slewrate that can be used on one gradient board at a time

The return value from this function is the ratio of ks_syslimits_ampmax1() and ks_syslimits_ramptimemax() and can be passed in as slewrate to all ks_eval***_constrained() functions

Parameters

[in]

loggrd

GE's LOG_GRAD struct, dependent on the gradient system and current slice angulation

Return values

slewrate

Maximum slewrate ([(G/cm) / us]) that can be used on one board at at time

                                              {
  return (ks_syslimits_ampmax1(loggrd) / ks_syslimits_ramptimemax(loggrd));
}

ks_syslimits_slewrate1p()

float ks_syslimits_slewrate1p

(

LOG_GRAD

loggrd

)

Returns the maximum gradient amplitude on the physical gradient axes

Parameters

[in]

loggrd

GE's LOG_GRAD struct, dependent on the gradient system and current slice angulation

Return values

gradmax

Maximum slewrate ([(G/cm) / us]) that can be used on one board at at time as defined by the physical gradients (lowest of physical X, Y, Z)

                                               {
  return (ks_syslimits_ampmax1p(loggrd) / ks_syslimits_ramptimemax(loggrd));
}

ks_phase_radians2hw()

short ks_phase_radians2hw

(

float

phase

)

                                       {
  short iphase;
  UINT uiphase;
  double dphase = (double) phase;
  double twopi = (double) 2.0 * PI;

  /* Resolve angle to lie within range ( -2*pi <= dphase < 2*pi ) */
  dphase = fmod(dphase, twopi);

  /* Find the equivalent positive angle */
  if (dphase < 0.0)
    dphase = twopi + dphase;

  /* Convert the angle to exciter DDS phase representation where only the
     upper 14 bits of 16 are used */
  uiphase = (UINT) (dphase * 16384.0 / twopi + 0.5);
  if (uiphase == 16384)
    uiphase = 0;

  /* left shift the result by 2 bits */
  iphase = (short) (uiphase << 2);

  return iphase;
}

ks_phase_degrees2hw()

short ks_phase_degrees2hw

(

float

degphase

)

Returns the integer phase (internal use)

All phase values in KSFoundation are in [degrees], including flip angles, RF/receive phases and THETA waveforms. This function is used internally by another internal function ks_wave2iwave(), which is in turn called by ks_pg_wave()

Parameters

[in]

degphase

Phase in degrees

Return values

intphase

Integer phase to use on THETA board on hardware

                                       {

  return ks_phase_radians2hw(phase * PI / 180.0);
}

ks_polyval()

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

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

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

void ks_phaseencoding_init_tgt

(

KS_PHASEENCODING_PLAN *

phaseenc_plan_ptr

)

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

Parameters

[in]

phaseenc_plan_ptr

Pointer to KS_PHASEENCODING_PLAN

Returns

void

                                                                         {
#ifdef IPG
  if (phaseenc_plan_ptr->is_cleared_on_tgt == FALSE) {
    phaseenc_plan_ptr->entries = NULL; /* clear memory pointer from HOST (which is garbage to the TGT) */
    phaseenc_plan_ptr->phaser = NULL; /* clear memory pointer from HOST (which is garbage to the TGT) */
    phaseenc_plan_ptr->zphaser = NULL; /* clear memory pointer from HOST (which is garbage to the TGT) */
    phaseenc_plan_ptr->is_cleared_on_tgt = TRUE;
  }
#else
  (void) (phaseenc_plan_ptr);
#endif
}

ks_phaseencoding_get()

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

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

If the .ky and .kz values returned by this function is = KS_NOTSET (-1), it indicates that this echo/shot combination should have zero phase encoding and should be ignored. For 2D, .kz will always be KS_NOTSET

Parameters

[in]	phaseenc_plan_ptr	Pointer to KS_PHASEENCODING_PLAN
[in]	echo	Echo index in the sequence ETL in range [0,ETL-1]
[in]	shot	Shot index (i.e. how many times the sequence is played out per slice). For 3D, this is the combined number of shots over ky and kz

Return values

<tt>KS_PHASEENCODING_COORD</tt>

                                                                                                                {
#ifdef IPG
  int oktoset = ((phaseenc_plan_ptr != NULL) && phaseenc_plan_ptr->etl != KS_NOTSET) && (phaseenc_plan_ptr->is_cleared_on_tgt);
#else
  int oktoset = (phaseenc_plan_ptr != NULL) && phaseenc_plan_ptr->etl != KS_NOTSET;
#endif

  if (!oktoset || !(phaseenc_plan_ptr->entries) ||
      shot < 0 || shot >= phaseenc_plan_ptr->num_shots ||
      echo < 0 || echo >= phaseenc_plan_ptr->etl) {

    KS_PHASEENCODING_COORD fake_coords = KS_INIT_PHASEENCODING_COORD;
    return fake_coords;
  }

  return phaseenc_plan_ptr->entries[echo + phaseenc_plan_ptr->etl * shot];
}

ks_phaseencoding_set()

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

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

If the .ky and .kz values passed to this function is = KS_NOTSET (-1), it indicates that this echo/shot combination should have zero phase encoding and should be ignored. However, ignored echo/shot combinations are not necessary since the etl*num_shots entries in .entries of KS_PHASEENCODING_PLAN are always initialized to KS_NOTSET by ks_phaseencoding_resize(). Hence, it is only necessary to explicitly set the echo/shot combination for ky/kz coordinates being acquired.

For 2D, kz (5th arg) should always be KS_NOTSET.

Parameters

[in]	phaseenc_plan_ptr	Pointer to KS_PHASEENCODING_PLAN
[in]	echo	Echo index in the sequence ETL in range [0,ETL-1]
[in]	shot	Shot index (in range [0,how many times the sequence is played out per slice - 1]). For 3D, this is the combined number of shots over ky and kz
[in]	ky	K-space coordinate along the first (only for 2D) phase encoding direction (integer) in range [0, phaser.numlinestoacq-1]
[in]	kz	K-space coordinate along the second (use KS_NOTSET for 2D) phase encoding direction (integer) in range [0, zphaser.numlinestoacq-1]

Returns

void

                                                                                                        {
#ifdef IPG
  int oktoset = (phaseenc_plan_ptr->etl != KS_NOTSET) && (phaseenc_plan_ptr->is_cleared_on_tgt);
#else
  int oktoset = phaseenc_plan_ptr->etl != KS_NOTSET;
#endif

  if (!oktoset || !phaseenc_plan_ptr || !(phaseenc_plan_ptr->entries) ||
      shot < 0 || shot >= phaseenc_plan_ptr->num_shots ||
      echo < 0 || echo >= phaseenc_plan_ptr->etl) {

    return;
  }

  ky = (ky < 0) ? KS_NOTSET : ky; /* KS_NOTSET = shut off phase encoding */
  kz = (kz < 0) ? KS_NOTSET : kz;

  phaseenc_plan_ptr->entries[echo + phaseenc_plan_ptr->etl * shot].ky = ky;
  phaseenc_plan_ptr->entries[echo + phaseenc_plan_ptr->etl * shot].kz = kz;

}

ks_phaseencoding_print()

void ks_phaseencoding_print

(

const KS_PHASEENCODING_PLAN *

phaseenc_plan_ptr

)

Print out KS_PHASEENCODING_PLAN to a text file

In SIM (WTools), a file ks_phaseencodingtable.txt will be generated in the current directory On HW (MR scanner), the same file will be located in /usr/g/mrraw

Parameters

[in]

phaseenc_plan_ptr

Pointer to KS_PHASEENCODING_PLAN

Returns

void

                                                                            {
  KS_PHASEENCODING_COORD coord = KS_INIT_PHASEENCODING_COORD;
  int shot, echo;
#ifdef PSD_HW
  FILE *fp = fopen("/usr/g/mrraw/ks_phaseencodingtable.txt", "w");
#else
  FILE *fp = fopen("./ks_phaseencodingtable.txt", "w");
#endif

  if (phaseenc_plan_ptr->etl == KS_NOTSET) {
    return; /* we haven't set it up yet */
  }

  fprintf(fp, "numshots (vertical): %d, etl (horizontal): %d\n\n", phaseenc_plan_ptr->num_shots, phaseenc_plan_ptr->etl);

  for (shot = 0; shot < phaseenc_plan_ptr->num_shots; shot++) {
    for (echo = 0; echo < phaseenc_plan_ptr->etl; echo++) {
        coord = ks_phaseencoding_get(phaseenc_plan_ptr, echo, shot);
        if (coord.ky != KS_NOTSET) {
          fprintf(fp, "[%03d", coord.ky);
        } else {
          fprintf(fp, "[***");
        }
        if (coord.kz != KS_NOTSET) {
          fprintf(fp, ",%03d] ", coord.kz);
        } else {
          fprintf(fp, ",***] ");
        }
      }
    fprintf(fp,"\n");
  }

  fclose(fp);

}

ks_phaseencoding_resize()

STATUS ks_phaseencoding_resize	(	KS_PHASEENCODING_PLAN *	phaseenc_plan_ptr,
		int	etl,
		int	num_shots
	)

Reallocate memory for KS_PHASEENCODING_PLAN entries

For every (and custom) ks_phaseencoding_generate_** functions, this function must be called before ks_phaseencoding_set() so that there is memory allocataed for the array of KS_PHASEENCODING_COORD

Parameters

[in]	phaseenc_plan_ptr	Pointer to KS_PHASEENCODING_PLAN
[in]	etl	The number of acquisition window in the pulse sequence, or echo train length (ETL)
[in]	num_shots	Number of shots (i.e. how many times the sequence is played out per slice). For 3D, shot is over both ky and kz

Returns

void

                                                                                                 {
  void *ptr = NULL;
  int i;

  ks_phaseencoding_init_tgt(phaseenc_plan_ptr);

  ptr = realloc(phaseenc_plan_ptr->entries, etl * num_shots * sizeof(KS_PHASEENCODING_COORD));
  if (!ptr) {
    return ks_error("%s: failed reallocation", __FUNCTION__);
  }

  phaseenc_plan_ptr->etl = etl;
  phaseenc_plan_ptr->num_shots = num_shots;
  phaseenc_plan_ptr->entries = (KS_PHASEENCODING_COORD *) ptr;

  for (i = 0; i < etl * num_shots; i++) {
    phaseenc_plan_ptr->entries[i].ky = KS_NOTSET;
    phaseenc_plan_ptr->entries[i].kz = KS_NOTSET;
  }

  return SUCCESS;
}

ks_phaseencoding_generate_simple()

STATUS ks_phaseencoding_generate_simple	(	KS_PHASEENCODING_PLAN *	phaseenc_plan_ptr,
		const char *const	desc,
		KS_PHASER *	phaser,
		KS_PHASER *	zphaser
	)

Generation of a KS_PHASEENCODING_PLAN for any sequence having only one echo (or same phasenc step for all echoes)

For sequences having only one echo (ETL=1) or having more echoes but where all echoes have the same ky/kz coordinate, there is no special logic necessary regarding which order to traverse the ky-kz plane over shots.

Parallel imaging in ky (and kz for 3D), with acs lines, is set up as usual using ks_eval_phaser() first before calling this function. For 2D, the phase encoding object (KS_PHASER) is then passed in as the 2nd arg to this function, with the 3rd arg being NULL. For 3D, both KS_PHASERs are passed in as 2nd and 3rd args, each with their own acceleration and resolution. For both 2D and 3D, the KS_PHASEENCODING_PLAN will be set up based on the KS_PHASER(s), but for 2D all entries.kz in the KS_PHASEENCODING_PLAN will be KS_NOTSET (-1)

Parameters

[out]	phaseenc_plan_ptr	Pointer to KS_PHASEENCODING_PLAN
[in]	desc	A description (text string) of the KS_PHASEENCODING_PLAN object. This description is used in the psd plot.
[in]	phaser	Pointer to the KS_PHASER object for the first (3D) / only (2D) phase encoding direction
[in]	zphaser	Pointer to the KS_PHASER object for the second phase encoding direction (NULL for 2D)

Returns

void

                                                                                                                                                  {
  int etl = 1;
  int num_shots;
  int shot, ky, kz;
  STATUS status;

  strncpy(phaseenc_plan_ptr->description, desc, KS_DESCRIPTION_LENGTH - 1);
  phaseenc_plan_ptr->description[KS_DESCRIPTION_LENGTH - 1] = 0;

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

  num_shots = (zphaser != NULL) ? (phaser->numlinestoacq * zphaser->numlinestoacq) : phaser->numlinestoacq;

  status = ks_phaseencoding_resize(phaseenc_plan_ptr, etl, num_shots);
  if (status != SUCCESS) return status;

  shot = 0;
  if (zphaser != NULL) { /* 3D */
    for (kz = 0; kz < zphaser->numlinestoacq; kz++) {
      for (ky = 0; ky < phaser->numlinestoacq; ky++) {
        ks_phaseencoding_set(phaseenc_plan_ptr, 0, shot++, phaser->linetoacq[ky], zphaser->linetoacq[kz]);
      }
    }
    phaseenc_plan_ptr->zphaser = zphaser;
  } else { /* 2D */
    for (ky = 0; ky < phaser->numlinestoacq; ky++) {
      ks_phaseencoding_set(phaseenc_plan_ptr, 0, shot++, phaser->linetoacq[ky], KS_NOTSET);
    }
    phaseenc_plan_ptr->zphaser = NULL;
  }

  phaseenc_plan_ptr->phaser = phaser;

  return SUCCESS;
}

ks_phaseencoding_generate_simple_ellipse()

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

Generation of a KS_PHASEENCODING_PLAN for any sequence having only one echo (or same phasenc step for all echoes) - ellipse version

For sequences having only one echo (ETL=1) or having more echoes but where all echoes have the same ky/kz coordinate, there is no special logic necessary regarding which order to traverse the ky-kz plane over shots.

Parallel imaging in ky (and kz for 3D), with acs lines, is set up as usual using ks_eval_phaser() first before calling this function. For 2D, the phase encoding object (KS_PHASER) is then passed in as the 2nd arg to this function, with the 3rd arg being NULL. For 3D, both KS_PHASERs are passed in as 2nd and 3rd args, each with their own acceleration and resolution. For both 2D and 3D, the KS_PHASEENCODING_PLAN will be set up based on the KS_PHASER(s), but for 2D all entries.kz in the KS_PHASEENCODING_PLAN will be KS_NOTSET (-1). This function will create an elliptical k-space in ky/kz. For rectangular k-space, use ks_phaseencoding_generate_simple.

Parameters

[out]	phaseenc_plan_ptr	Pointer to KS_PHASEENCODING_PLAN
[in]	desc	A description (text string) of the KS_PHASEENCODING_PLAN object. This description is used in the psd plot.
[in]	phaser	Pointer to the KS_PHASER object for the first (3D) / only (2D) phase encoding direction
[in]	zphaser	Pointer to the KS_PHASER object for the second phase encoding direction (NULL for 2D)

Returns

void

                                                                                                                                                          {
  int etl = 1;
  int ky, kz, i;
  float radius_ky, radius_kz, center_ky, center_kz;
  float x1, x2;
  STATUS status;
  int inellipse; /* Number of ky,kz points in the ellipse */

  strncpy(phaseenc_plan_ptr->description, desc, KS_DESCRIPTION_LENGTH - 1);
  phaseenc_plan_ptr->description[KS_DESCRIPTION_LENGTH - 1] = 0;

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

  if (zphaser == NULL) { /* We can't do ellipse k-space coverage (ky,kz) in 2D */
    return ks_phaseencoding_generate_simple(phaseenc_plan_ptr, desc, phaser, NULL);
  }


  phaseenc_plan_ptr->phaser = phaser;
  radius_ky = phaser->res/2.0;
  center_ky = phaser->res/2.0 - 0.5;

  phaseenc_plan_ptr->zphaser = zphaser;
  radius_kz = zphaser->res/2.0;
  center_kz = zphaser->res/2.0 - 0.5;

  for (i = 0; i < 2; i++) { /* i = 0: check how many. i = 1: set up coords */

    if (i == 1) {
      status = ks_phaseencoding_resize(phaseenc_plan_ptr, etl, inellipse);
      if (status != SUCCESS) return status;
    }
    inellipse = 0;

    for (kz = 0; kz < zphaser->numlinestoacq; kz++) {
      for (ky = 0; ky < phaser->numlinestoacq; ky++) {
          x1 = (phaser->linetoacq[ky]  - center_ky) / (float) radius_ky;
          x2 = (zphaser->linetoacq[kz] - center_kz) / (float) radius_kz;
          if ((x1 * x1 + x2 * x2) <= 1.0) {
            if (i == 1) {
              ks_phaseencoding_set(phaseenc_plan_ptr, 0, inellipse, phaser->linetoacq[ky], zphaser->linetoacq[kz]);
            }
            inellipse++;
          }
      } /* ky */
    } /* kz */

  } /* i */

  return SUCCESS;
}

ks_fse_calcecho()

STATUS ks_fse_calcecho	(	double *	bestecho,
		double *	optecho,
		int *	nacqlines_to_kspacecenter,
		KS_PHASER *	pe,
		ks_enum_pf_earlylate_te	pf_direction,
		int	TE,
		int	etl,
		int	esp
	)

Calculates the ETL index corresponding the desired TE given a KS_PHASER object and echo spacing

Given the KS_PHASER object used in the FSE train (containing res and partial ky Fourier info), the desired effective echo time (TE [us]), the echo train length (etl) and the echo spacing between consecutive echoes (esp [us]), this function calculates two echo indices:

• bestecho: is the 0-based index corresponding to the echo in the FSE train that should be placed in the center of k-space, i.e. the echo that most closely matches the desired TE. If bestecho is an integer value (although it is in double format), the data acquired for this echo should straddle the k-space center. bestecho can also be an interger + 0.5, indicating that there are two echo indices that should be placed around the k-space center. For example, floor(bestecho) corresponds to the echo index that should be placed just below the k-space center and ceil(bestecho) corresponds to the echo index that should be placed just above the k-space center. I.e. when bestecho = *.5, no single echo index will straddle the k-space center, and the k-space line located at ky position +0.5 will come from data acquired from echo #[floor(bestecho)] and ky position -0.5 correspondingly from echo #[ceil(bestecho)].
• optecho: is the 0-based index corresponding to an ideal TE choice that would allow the data from the echoes in the FSE train to be placed out linearly each time. Doing so will reduce ghosting and T2 blurring. Hence, optecho ignores the input TE value here, but the calling function can use this information to determine k-space acquisition order, but also to suggest a TE (optecho * esp) that would result in optimal image quality for the chosen ETL.

Parameters

[out]	bestecho	Pointer to the echo number in the train that should be placed at the center of k-space given the current ETL and ESP
[out]	optecho	Pointer to the optimal echo number in the train that would allow k-space to be sampled linearly (to reduce T2-blurring and ghosting)
[out]	nacqlines_to_kspacecenter	Pointer to a an integer with the number of k-space lines until center
[in]	pe	Pointer to a KS_PHASER
[in]	pf_direction	Should be either KS_PF_EARLY_TE or KS_PF_LATE_TE (applies to partial Fourier in ky to set if k-space center should be acquired early or late in the EPI train. Has no effect for full ky Fourier)
[in]	TE	(Echo Time in [us])
[in]	etl	(EchoTrain Length)
[in]	esp	(Echo Spacing in [us])

Return values

STATUS

SUCCESS or FAILURE

                                                                                                                                                                             {
  int numshots, i;
  int nacqlines_fullside, nacqlines_pfside;
  double numshots_double;

  if (etl < 1) {
    return ks_error("%s: ETL (arg 5) must be at least 1", __FUNCTION__);
  }
  if (pe->numlinestoacq < 1) {
    return ks_error("%s: field '.numlinestoacq' in 3rd arg must be at least 1", __FUNCTION__);
  }
  if (etl > pe->numlinestoacq) {
    return ks_error("%s: ETL (arg 5) cannot exceed number of lines to acquire", __FUNCTION__);
  }
  if (esp <= 0) {
    return ks_error("%s: ESP (arg 6) must be larger than 1", __FUNCTION__);
  }
  if (pe->nover < 0) {
    return ks_error("%s: Only top half of k-space supported for pFourier", __FUNCTION__);
  }

  /* Number of shots */
  numshots = CEIL_DIV(pe->numlinestoacq, etl);
  numshots_double = (double) pe->numlinestoacq / (double) etl;

  /* index 'i' will stop incrementing as we pass the center of k-space (i=0 is top row of k-space). 
     Note that 'i' will be much less that res/2 (after break) even for full Fourier when
     we have R > 1 and acslines */
  for (i = 0; i < pe->numlinestoacq - 1; i++) {
    if (((pe->res - 1) / 2.0 - pe->linetoacq[i]) < 0)
      break;
  }
  
  nacqlines_fullside = i;
  nacqlines_pfside = pe->numlinestoacq - i; /* which is equal or almost equal to nacqlines_fullside for full Fourier */

  if (pf_direction == KS_PF_EARLY_TE) {
    *nacqlines_to_kspacecenter = nacqlines_pfside;
  } else {
    *nacqlines_to_kspacecenter = nacqlines_fullside;
  }


  if (etl % 2) {
    /* etl is odd. The optimal echo will straddle around the center of k-space */

    if (optecho != NULL)
      *optecho = ceil((((double) *nacqlines_to_kspacecenter + numshots_double / 2.0) / numshots_double) - 1e-5); /* integer value since ETL is odd */

    if (bestecho != NULL) {
      *bestecho = floor((double) TE / (double) esp + 0.5); /* integer */
      if (*bestecho < 1)
        *bestecho = 1;
      if (*bestecho > etl)
        *bestecho = etl;
    }

  } else {
    /* etl is even. The optimal two echoes will be placed above and below k-space center, respectively */

    if (optecho != NULL)
      *optecho = ceil((double) *nacqlines_to_kspacecenter / numshots_double) + 0.5; /* half-integer value since ETL is even */

    if (bestecho != NULL) {
      if (etl == 2) {
        /* special case for ETL = 2 */
        if (TE < 1.25 * esp)
          *bestecho = 1; /* 1st echo straddling around k-space center */
        else if (TE < 1.75 * esp)
          *bestecho = 1.5; /* 1st/end echo below/above k-space center */
        else
          *bestecho = 2; /* 2nd echo straddling around k-space center */
      } else {
        *bestecho = floor((double) TE / (double) esp) + 0.5; /* half-integer */
        if (*bestecho <= 1.5)
          *bestecho = 1; /* minTE, back to integer 'bestecho' for center-out encoding */
        if (*bestecho >= (etl - 0.5))
          *bestecho = etl; /* max TE, back to integer 'bestecho' for out-center encoding */
      }
    }

  }

  if (optecho != NULL) {
    /* Partial Fourier MinTE case, regardless if ETL is even or odd */
    if ((pe->nover > 0) && (*nacqlines_to_kspacecenter <= numshots / 2))
      *optecho = 1;

    /* Partial Fourier MaxTE case, regardless if ETL is even or odd */
    if ((pe->nover < 0) && (*nacqlines_to_kspacecenter >= (pe->linetoacq[i] - numshots / 2)))
      *optecho = etl;
  }

  return SUCCESS;

} /* ks_fse_calcecho() */

ks_phaseencoding_generate_2Dfse()

STATUS ks_phaseencoding_generate_2Dfse	(	KS_PHASEENCODING_PLAN *	phaseenc_plan_ptr,
		const char *const	desc,
		KS_PHASER *	phaser,
		KS_PHASER *	zphaser,
		ks_enum_pf_earlylate_te	pf_direction,
		int	TE,
		int	etl,
		int	esp
	)

2DFSE: Makes a KS_PHASEENCODING_PLAN depending on etl, desired TE, and echo spacing (esp)

This function is only executed on TGT and will return early when called on HOST.

The phase encoding sorting is depending on many factors. First, the desired TE will dictate which one (or two) of the echoes in the FSE train (of length etl) that should be placed in the center. This is determined based on the properties of the KS_PHASER object (phase encoding gradients in the FSE train), TE and esp by calling ksfse_calc_echo().

Second, the sorting of the echoes will first of all depend on whether bestecho is equal to optecho. If it is, then the etl echoes can be placed out linearly in k-space (from the bottom->top of k-space, or vice versa). This will produce the best image quality with minimal T2-blurring and FSE ghosting.

As partial ky Fourier is allowed, this function first checks on which side (top or bottom half) of k-space that has more room for the echo indices that are either before or after the bestecho index corresponding to the desired TE. The goal with this is to try to sweep k-space as linearly as possible in as much of the center portion of k-space as possible when bestecho != optecho.

When bestecho != optecho, there will be data from either the first or last echo indices that won't fit in k-space if placed next to a neighboring index. If this data would be placed on the other size of k-space (that still needs lines to be filled in), where e.g. echo index #0 would be placed next to echo index #(etl-1), strong ghosting will occur due to the much strong signal from echo #0 compared to #(etl-1). With an echo train length of etl, k-space is filled in numshots = ceil(numlinestoacq / etl. Using half of the numshots lines for each echo index a linear sweep of the center half of k-space can is layed out. To avoid FSE ghosting, the numshots/2 remaining lines for each early or late echo index are placed such as neighboring ky lines will never have a change in echo index by more than one. For example if etl = 8, esp = 10 ms and TE = 25, then bestecho = 1.5 and optecho = 4.5. We avoid to sort the echoes in the following k-space order for ghosting reasons: 7-6-0-1*2-3-4-5 (* = k-space center) since there will be a strong discontinuity between 6 and 0. Instead we use groups of numshots/2 per echo index (and get two groups per echo index in k-space): 5-4-3-2-1-0-0-1*2-3-4-5-6-7-6-5

Parameters

[out]	phaseenc_plan_ptr	Pointer to KS_PHASEENCODING_PLAN
[in]	desc	A description (text string) of the KS_PHASEENCODING_PLAN object. This description is used in the psd plot.
[in]	phaser	Pointer to a KS_PHASER
[in]	zphaser	Pointer to a KS_PHASER (3D) or NULL (2D)
[in]	pf_direction	Should be either KS_PF_EARLY_TE or KS_PF_LATE_TE (applies to partial Fourier in ky to set if k-space center should be acquired early or late in the EPI train. Has no effect for full ky Fourier)
[in]	TE	(Echo Time in [us])
[in]	etl	(EchoTrain Length)
[in]	esp	(Echo Spacing in [us])

Return values

STATUS

SUCCESS or FAILURE

Grouping shots for each of the ETL echoes in k-space: We don't place all shots for each echo together in k-space since we need to make a z-shaped pattern to avoid ghosting. Instead we let half of the shots be one group (of size 'cgroupsize') that we place in the central ~50% of k-space, which allows us to get a linear sweep in this central half of k-space using all 'etl' echoes, regardless of the chosen effective TE. The actual center-ness depends on TE, and the remaining of k-space is filled using the echoes belonging to the latter 'numshots-cgroupsize' number of shots. At the edges of k-space, numshots*etl seldom match up to the chosen opyres, but numshots*etl is always >= opyres thanks to the CEIL_DIV at the beginning of this function. The surplus echoes we don't need are numshots*etl - opyres (for full Fourier and no ARC), and as they are already tagged as -1 = KS_NOTSET in the beginning of this function, they will be placed in baseline view (0) in the ksfse_scan_acqloop()

                                                                                                                                                                                                                 {
  int i, j, ky, kz;
  int numshots, numkz;
  double bestecho, optecho;
  int nacqlines_to_kspacecenter;
  int cgroupsize, halfgroupsize;
  int cstart, cshift;
  STATUS status;

  strncpy(phaseenc_plan_ptr->description, desc, KS_DESCRIPTION_LENGTH - 1);
  phaseenc_plan_ptr->description[KS_DESCRIPTION_LENGTH - 1] = 0;

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

  if (etl < 1) {
    return SUCCESS; /* we haven't set it up yet */
  }
  if (phaser->numlinestoacq < 2) {
    return ks_error("%s: field '.numlinestoacq' in 2nd arg must be at least 2", __FUNCTION__);
  }
  if (etl > phaser->numlinestoacq) {
    return ks_error("%s: ETL cannot exceed number of lines to acquire", __FUNCTION__);
  }
  if (phaser->nover < 0) {
    return ks_error("%s: Only top half of k-space supported for pFourier", __FUNCTION__);
  }

  phaseenc_plan_ptr->phaser = phaser;
  phaseenc_plan_ptr->zphaser = zphaser;

  /* Number of shots (2D) */
  numshots = CEIL_DIV(phaser->numlinestoacq, etl);

  /* Number of kz */
  numkz = (zphaser != NULL) ? zphaser->numlinestoacq : 1;

  /* allocate KS_PHASEENCODING_PLAN table (all entries will be initialized to KS_NOTSET) */
  status = ks_phaseencoding_resize(phaseenc_plan_ptr, etl, numshots * numkz);
  if (status != SUCCESS) return status;


  for (kz = 0; kz < numkz; kz++) {

    if (etl == 1) {

      /* Special case for ETL = 1. Just acquire the data in order */
      for (ky = 0; ky < phaser->numlinestoacq; ky++) {
        ks_phaseencoding_set(phaseenc_plan_ptr,
                             0, ky + kz * phaser->numlinestoacq,
                             phaser->linetoacq[ky], (zphaser != NULL) ? zphaser->linetoacq[kz] : KS_NOTSET);
      }

    } else {

      /* ETL > 1 (this is a long else-statement) */

      /* get the best echo number for the given TE/ETL/ESP, and also the optimal echo number that would allow for a linear k-space sweep */
      status = ks_fse_calcecho(&bestecho, &optecho, &nacqlines_to_kspacecenter, phaser, pf_direction, TE, etl, esp);
      if (status != SUCCESS) return status;


      if (areSame(bestecho, optecho)) {
        /* we can place the echoes linearly in k-space in groups of 'numshots' per echo given the current combination of TE, ETL and ESP */
        cgroupsize = numshots;
        halfgroupsize = (int) floor((float) phaser->numlinestoacq / (etl * 2.0) + 0.5);
      } else {
        cgroupsize = (int) ceil((float) phaser->numlinestoacq / (etl * 2.0)); /* ~numshots/2 lines per etl in the central 50% of k-space */
        halfgroupsize = (int) floor((float) phaser->numlinestoacq / (etl * 4.0) + 0.5);
      }

      /* if bestecho == optecho: Place out all echoes
         if bestecho != optecho: Place out the center half of lines */
      if (areSame(bestecho,1)) /* minTE */
        cshift = cgroupsize;
      else if (areSame(bestecho, etl)) /* maxTE */
        cshift = 0;
      else
        cshift = halfgroupsize; /* non-extreme TE */
      cstart = (int)((nacqlines_to_kspacecenter + cshift) - cgroupsize * bestecho);
      if (pf_direction == KS_PF_EARLY_TE)
        cstart = (phaser->numlinestoacq - 1) - cstart;
      ky = cstart;
      for (i = 0; i < etl; i++) {
        for (j = 0; j < cgroupsize; j++) {
          if (ky >= 0 && ky < phaser->numlinestoacq) {
            ks_phaseencoding_set(phaseenc_plan_ptr, i, j + kz * numshots, phaser->linetoacq[ky], (zphaser != NULL) ? zphaser->linetoacq[kz] : KS_NOTSET);
          }
          if (pf_direction == KS_PF_EARLY_TE)
            ky--;
          else
            ky++;
        }
      }

      if (!areSame(bestecho, optecho)) {
        /* remaining 'numshots-cgroupsize' number of shots for late echoes */
        i = etl - 1;
        while (i >= 0) {
          for (j = cgroupsize; j < numshots; j++) {
            if (ky >= 0 && ky < phaser->numlinestoacq) {
              ks_phaseencoding_set(phaseenc_plan_ptr, i, j + kz * numshots, phaser->linetoacq[ky], (zphaser != NULL) ? zphaser->linetoacq[kz] : KS_NOTSET);
            }
            if (pf_direction == KS_PF_EARLY_TE)
              ky--;
            else
              ky++;
          } /* for j */
          i--;
        }

        /* remaining 'numshots-cgroupsize' number of shots for early echoes */
        if (pf_direction == KS_PF_EARLY_TE)
          ky = cstart + 1;
        else
          ky = cstart - 1;
        i = 0;
        while (i < etl) {
          for (j = cgroupsize; j < numshots; j++) {
            if (ky >= 0 && ky < phaser->numlinestoacq) {
              ks_phaseencoding_set(phaseenc_plan_ptr, i, j + kz * numshots, phaser->linetoacq[ky], (zphaser != NULL) ? zphaser->linetoacq[kz] : KS_NOTSET);
            }
            if (pf_direction == KS_PF_EARLY_TE)
              ky++;
            else
              ky--;
          } /* for j */
          i++;
        }
      } /* bestecho != optecho */

    } /* etl > 1 */

  } /* numkz */


  return SUCCESS;


} /* ks_phaseencoding_generate_2Dfse() */

ks_phaseencoding_generate_epi()

STATUS ks_phaseencoding_generate_epi	(	KS_PHASEENCODING_PLAN *	phaseenc_plan_ptr,
		const char *const	desc,
		const KS_EPI *	epitrain,
		const ks_enum_epiblipsign	blipsign,
		const ks_enum_pf_earlylate_te	pf_direction,
		const int	numileavestoacq,
		ks_enum_sweep_order	sweep_order,
		int	numsegments,
		const int	caipi_delta
	)

EPI: Makes a KS_PHASEENCODING_PLAN suitable for 2D or 3D epi

The etl is the number of readouts in the EPI train, derived from the phaser. The number of ky shots is also given by the phaser, while the number of kz shots is given by zphaser. Any partial fourier is handled by the phasers, and acceleration and acs lines in the z direction is handled by zphaser. For 3D EPI, the number of shots in the phase encoding plan will be the product of the number of shots in the ky direction and the number of kz lines to acquire.

Each shot will be played out in a single kz plane. The shot order will be linear in ky and kz. The ky shots will be in the inner loop, unless kzshotsfirst is TRUE.

Parameters

[out]	phaseenc_plan_ptr	Pointer to the phase encoding plan
[in]	desc	A description (text string) of the KS_PHASEENCODING_PLAN object. This description is used in the psd plot.
[in]	epitrain	Pointer to a KS_EPI
[in]	blipsign	Should be either KS_EPI_POSBLIPS or KS_EPI_NEGBLIPS. Determines distortion direction.
[in]	pf_direction	Should be either KS_PF_EARLY_TE or KS_PF_LATE_TE (applies to partial Fourier in ky to set if k-space center should be acquired early or late in the EPI train. Has no effect for full ky Fourier)
[in]	numileavestoacq	Number of ky interleaves to play. Must be within 1-numInterleaves and an integer factor of numInterleaves. Set =1 for single-shot EPI. Set to phaser.R for full multi-shot EPI.
[in]	sweep_order	Sweep order for shots as defined in KSFoundation.h (ks_enum_sweep_order). Has no effect on distortions.
[in]	numsegments	Number of kz encodes to play
[in]	caipi_delta	Use CAIPIRINHA sampling pattern (affects 3D epi only)

Return values

STATUS

SUCCESS or FAILURE

                                                                                                                                                                                                                                                                                                                      {

  int numileaves = epitrain->blipphaser.R;

  if (epitrain->blipphaser.numlinestoacq < 2 && (numileaves != epitrain->blipphaser.res)) {
    return ks_error("%s: field '.numlinestoacq' of epitrain->blipphaser must be at least 2, not %d", __FUNCTION__, epitrain->blipphaser.numlinestoacq);
  }

  strncpy(phaseenc_plan_ptr->description, desc, KS_DESCRIPTION_LENGTH - 1);
  phaseenc_plan_ptr->description[KS_DESCRIPTION_LENGTH - 1] = 0;

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

  int readout, shot, interleaf, kyview, kzview, kzind;
  int etl, numfullsegments, numshotsforsegment, totalnumshots, i;
  int shift;
  STATUS status;

  /* Number of shots (2D) */
  if (numileavestoacq < 1 || numileavestoacq > numileaves || (numileaves % numileavestoacq != 0)) {
    return ks_error("%s: numileavestoacq (=%d) must be in range 1-blipphaser.R and an integer factor of blipphaser.R (=%d)", __FUNCTION__, numileavestoacq, numileaves);
  }

  /* Number of segments (3D) */
  if (epitrain->zphaser.res != KS_NOTSET && (numsegments < 1 || numsegments > epitrain->zphaser.numlinestoacq)) {
    return ks_error("%s: numsegments (=%d) must be in range 1-zphaser.numlinestoacq (=%d)", __FUNCTION__, numsegments, epitrain->zphaser.numlinestoacq);
  }

  /* Number of readouts per EPI train (etl) */
  etl = epitrain->blipphaser.numlinestoacq;

  /* Check number of kz segments and how many should be fully sampled (controlled by zphaser.nacslines) */
  if (epitrain->zphaser.res == KS_NOTSET) { /* 2D epi */
    numsegments = 1;
    numfullsegments = (numileavestoacq == numileaves);
  } else { /* 3D epi */
    if (epitrain->zphaser.R == 1) {
      numfullsegments = epitrain->zphaser.nacslines; /* special interpretation for zR=1 */
    } else { /* zR > 1 */
      if (epitrain->zphaser.nacslines > 0) {
        numfullsegments = 1; /* initialize */
        for (kzind = 1; kzind < numsegments; kzind++) {
          if (abs(epitrain->zphaser.linetoacq[kzind]-epitrain->zphaser.linetoacq[kzind-1])==1) {
            numfullsegments++;
          }
        }
      } else { /* no kz "acs lines" */
        numfullsegments = 0;
      }
    }
  }

  /* allocate KS_PHASEENCODING_PLAN table (all entries will be initialized to KS_NOTSET) */
  totalnumshots = numfullsegments * numileaves + (numsegments-numfullsegments) * numileavestoacq;
  status = ks_phaseencoding_resize(phaseenc_plan_ptr, etl, totalnumshots);

  phaseenc_plan_ptr->phaser = &epitrain->blipphaser;
  phaseenc_plan_ptr->zphaser = &epitrain->zphaser;

  if (status != SUCCESS) return status;

  shot = 0; /* initialize */
  int ileaves[numileaves]; /* interleaf indices */

  for (kzind = 0; kzind < numsegments; kzind++) {
    kzview = (epitrain->zphaser.numlinestoacq > 0) ? epitrain->zphaser.linetoacq[kzind] : KS_NOTSET;
    
    if (kzview != KS_NOTSET && abs(kzview*2 - (epitrain->zphaser.res-1)) <= numfullsegments) {
      numshotsforsegment = numileaves;
    } else {
      numshotsforsegment = numileavestoacq;
    }
    
    if (sweep_order == KS_SWEEP_ORDER_TOP_DOWN) {
      for (i = 0; i < numshotsforsegment; i++) {
        ileaves[i] = i;
      }
    } else if (sweep_order == KS_SWEEP_ORDER_BOTTOM_UP) {
      for (i = 0; i < numshotsforsegment; i++) {
        ileaves[numshotsforsegment - i - 1] = i;
      }
    } else if (sweep_order == KS_SWEEP_ORDER_OUTSIDE_IN) {
      for (i = 0; i < numshotsforsegment; i++) {
        ileaves[i] = (i % 2) ? numshotsforsegment - 1 - i/2 : i/2;
      }
    } else if (sweep_order == KS_SWEEP_ORDER_CENTER_OUT) {
      for (i = 0; i < numshotsforsegment; i++) {
        ileaves[numshotsforsegment - i - 1] = (i % 2) ? numshotsforsegment - 1 - i/2 : i/2;
      }
    }
    for (i = 0; i < numshotsforsegment; i++) {
      interleaf = ileaves[i];
      for (readout = 0; readout < etl; readout++) {
        shift = interleaf * (numileaves / numshotsforsegment); /* interleaf shift */
        shift = (shift + (kzview/epitrain->zphaser.R) * caipi_delta) % numileaves; /* CAIPIRINHA shift */
        if ((epitrain->blipphaser.nover != 0) && (((pf_direction == KS_PF_LATE_TE) && (blipsign == KS_EPI_POSBLIPS)) || ((pf_direction == KS_PF_EARLY_TE) && (blipsign == KS_EPI_NEGBLIPS))) ) {
          /* shift kspace area to lower half */
          shift += epitrain->blipphaser.res - (epitrain->blipphaser.res/2 + epitrain->blipphaser.nover);
        }
        if (blipsign == KS_EPI_NEGBLIPS) {
          kyview = epitrain->blipphaser.linetoacq[readout] + shift; /* admittedly, .linetoacq[] has lost its role a bit for EPI with all shifting we do */
        } else if (blipsign == KS_EPI_POSBLIPS) {
          kyview = epitrain->blipphaser.linetoacq[(etl - 1) - readout] + shift; /* admittedly, .linetoacq[] has lost its role a bit for EPI with all shifting we do */
        } else if (blipsign == KS_EPI_NOBLIPS) {
          kyview = KS_NOTSET;
          kzview = KS_NOTSET;
        } else {
          return ks_error("%s: blipsign must be KS_EPI_POSBLIPS or KS_EPI_NEGBLIPS, not %d", __FUNCTION__, blipsign);
        }
        ks_phaseencoding_set(phaseenc_plan_ptr, readout, shot, kyview, kzview);
      } /* readout */
      shot++;
    } /* interleaf */
  } /* kzind */

  return SUCCESS;

} /* ks_phaseencoding_generate_epi() */

ks_phaseencoding_generate_allepiplans()

STATUS ks_phaseencoding_generate_allepiplans	(	KS_PHASEENCODING_ALLEPIPLANS	phaseenc_plans,
		const char *const	desc,
		const KS_EPI *	epitrain,
		const int	caipi_delta
	)

EPI: Makes all 8 KS_PHASEENCODING_PLANs possible for 2D or 3D epi

Parameters

[out]	phaseenc_plans	Pointer to the phase encoding plan array (KS_PHASEENCODING_ALLEPIPLANS containing KS_EPI_PEPLAN_NUMPLANS elements)
[in]	desc	A description (text string) of the KS_PHASEENCODING_PLAN object. This description is used in the psd plot.
[in]	epitrain	Pointer to a KS_EPI
[in]	caipi_delta	Use CAIPIRINHA sampling pattern (affects 3D epi only)

Return values

STATUS

SUCCESS or FAILURE

                                                                                                                                                                  {
  ks_enum_epiblipsign kspace_direction;
  ks_enum_pf_earlylate_te pf_direction;
  int numileavestoacq, p;
  KS_DESCRIPTION tmpdesc;
  STATUS status;
  int is3Dscan = epitrain->zphaser.res > 1;
  int numileaves = epitrain->blipphaser.R;

  for (p = 0; p < KS_EPI_PEPLAN_NUMPLANS; p++) {

    switch (p) {
    case KS_EPI_PEPLAN_EARLYTE_BOTTOMUP_MULTISHOT:
      pf_direction = KS_PF_EARLY_TE;
      kspace_direction = KS_EPI_POSBLIPS;
      numileavestoacq = (is3Dscan) ? (numileaves / epitrain->R_3d) : numileaves;
      sprintf(tmpdesc, "%s:mShot/EarlyTE/blip+", desc);
      break;
    case KS_EPI_PEPLAN_EARLYTE_BOTTOMUP_UNDERSAMPLED:
      pf_direction = KS_PF_EARLY_TE;
      kspace_direction = KS_EPI_POSBLIPS;
      numileavestoacq = 1;
      sprintf(tmpdesc, "%s:Undersampled/EarlyTE/blip+", desc);
      break;
    case KS_EPI_PEPLAN_EARLYTE_TOPDOWN_MULTISHOT:
      pf_direction = KS_PF_EARLY_TE;
      kspace_direction = KS_EPI_NEGBLIPS;
      numileavestoacq = (is3Dscan) ? (numileaves / epitrain->R_3d) : numileaves;
      sprintf(tmpdesc, "%s:mShot/EarlyTE/blip-", desc);
      break;
    case KS_EPI_PEPLAN_EARLYTE_TOPDOWN_UNDERSAMPLED:
      pf_direction = KS_PF_EARLY_TE;
      kspace_direction = KS_EPI_NEGBLIPS;
      numileavestoacq = 1;
      sprintf(tmpdesc, "%s:Undersampled/EarlyTE/blip-", desc);
      break;
    case KS_EPI_PEPLAN_LATETE_BOTTOMUP_MULTISHOT:
      pf_direction = KS_PF_LATE_TE;
      kspace_direction = KS_EPI_POSBLIPS;
      numileavestoacq = (is3Dscan) ? (numileaves / epitrain->R_3d) : numileaves;
      sprintf(tmpdesc, "%s:mShot/LateTE/blip+", desc);
      break;
    case KS_EPI_PEPLAN_LATETE_BOTTOMUP_UNDERSAMPLED:
      pf_direction = KS_PF_LATE_TE;
      kspace_direction = KS_EPI_POSBLIPS;
      numileavestoacq = 1;
      sprintf(tmpdesc, "%s:Undersampled/LateTE/blip+", desc);
      break;
    case KS_EPI_PEPLAN_LATETE_TOPDOWN_MULTISHOT:
      pf_direction = KS_PF_LATE_TE;
      kspace_direction = KS_EPI_NEGBLIPS;
      numileavestoacq = (is3Dscan) ? (numileaves / epitrain->R_3d) : numileaves;
      sprintf(tmpdesc, "%s:mShot/LateTE/blip-", desc);
      break;
    case KS_EPI_PEPLAN_LATETE_TOPDOWN_UNDERSAMPLED:
      pf_direction = KS_PF_LATE_TE;
      kspace_direction = KS_EPI_NEGBLIPS;
      numileavestoacq = 1;
      sprintf(tmpdesc, "%s:Undersampled/LateTE/blip-", desc);
      break;   
    default:
      return ks_error("%s:Error, we should not have arrived here", __FUNCTION__);
      break;
    }

    status = ks_phaseencoding_generate_epi(&phaseenc_plans[p], tmpdesc,
                                    epitrain, 
                                    kspace_direction, 
                                    pf_direction,
                                    numileavestoacq,
                                    KS_SWEEP_ORDER_TOP_DOWN,
                                    epitrain->zphaser.numlinestoacq, 
                                    caipi_delta);
    if (status != SUCCESS) return status;

  }

  return SUCCESS;

} /* ks_phaseencoding_generate_allepiplans() */

ks_phaseencoding_allepiplans_setechoes()

STATUS ks_phaseencoding_allepiplans_setechoes	(	KS_PHASEENCODING_PLAN_16PTRS	peplan_echoes,
		KS_PHASEENCODING_ALLEPIPLANS	allepiplans,
		int	nechoes,
		int	multishot_flag,
		int	min1stTE,
		int	mirrorTE,
		ks_enum_epiblipsign	blipsign
	)

EPI: Makes a pointer to an entry in KS_PHASEENCODING_ALLEPIPLANS for each echo and store it in an array for scan loop usage

Parameters

[out]	peplan_echoes	Pointers to the phase encoding plan array to use for each EPI train in the sequence (max 16 EPI trains per sequence playout)
[in]	allepiplans	All possible EPI plans for current EPI train (with given read.res and blipphaser.res/.nover)
[in]	nechoes	Number of EPI train (echoes) in sequence (max 16)
[in]	multishot_flag	Multishot EPI or underampled EPI (both controlled by epitrain.blipphaser.R)
[in]	min1stTE	For partial ky Fourier (.blipphaser.nover > 0), should 1st EPI train pass k-space center early or late. Has no effect for full ky Fourier
[in]	mirrorTE	Should lateTE/earlyTE alternate between EPI trains (as when an RF refocusing pulse is placed in-between trains)
[in]	blipsign	Positive (KS_EPI_POSBLIPS) or negative (KS_EPI_NEGBLIPS) to control k-space direction and hence the geometric distortion direction

Return values

STATUS

SUCCESS or FAILURE

                                                                                                                                                                                                                               {
/*
  Assumes KSFoundation.h has the ks_enum_epiplans enum in the following ORDER:
  KS_EPI_PEPLAN_EARLYTE_BOTTOMUP_UNDERSAMPLED, // 0
  KS_EPI_PEPLAN_EARLYTE_BOTTOMUP_MULTISHOT, // 1
  KS_EPI_PEPLAN_EARLYTE_TOPDOWN_UNDERSAMPLED, // 2
  KS_EPI_PEPLAN_EARLYTE_TOPDOWN_MULTISHOT, // 3
  KS_EPI_PEPLAN_LATETE_BOTTOMUP_UNDERSAMPLED, // 4
  KS_EPI_PEPLAN_LATETE_BOTTOMUP_MULTISHOT, // 5
  KS_EPI_PEPLAN_LATETE_TOPDOWN_UNDERSAMPLED, // 6
  KS_EPI_PEPLAN_LATETE_TOPDOWN_MULTISHOT, // 7
  KS_EPI_PEPLAN_NUMPLANS // 8
*/

  int echo, whichplan;

  if (peplan_echoes == NULL) {
    return ks_error("%s: arg 1 (output) is NULL", __FUNCTION__);
  }
  if (allepiplans == NULL) {
    return ks_error("%s: arg 2 (input) is NULL", __FUNCTION__);
  }
  if (nechoes < 1 || nechoes > 16) {
    return ks_error("%s: nechoes (%d, arg 3) must be in range [1,16]", __FUNCTION__, nechoes);
  }
  if ( !(multishot_flag == 0 || multishot_flag == 1) ) {
    return ks_error("%s: multishot_flag (%d, arg 4) must be 0 or 1", __FUNCTION__, multishot_flag);
  }
  if ( !(min1stTE == 0 || min1stTE == 1) ) {
    return ks_error("%s: min1stTE (%d, arg 5) must be 0 or 1", __FUNCTION__, min1stTE);
  }
  if ( !(mirrorTE == 0 || mirrorTE == 1) ) {
    return ks_error("%s: mirrorTE (%d, arg 6) must be 0 or 1", __FUNCTION__, mirrorTE);
  }
  if ( !(blipsign == KS_EPI_POSBLIPS || blipsign == KS_EPI_NEGBLIPS || blipsign == KS_EPI_NOBLIPS) ) {
    return ks_error("%s: blipsign (%d, arg 7) must be -1, 0 or 1", __FUNCTION__, blipsign);
  }

  for (echo = 0; echo < 16; echo++) {
    peplan_echoes[echo] = NULL; /* reset all pointers in case #EPI trains has been reduced */
  }

  for (echo = 0; echo < nechoes; echo ++) {
    if (mirrorTE) { /* with 'mirrorTE', lateTE and earlyTE are alternating across echoes */
      whichplan = (min1stTE) ? ((echo % 2) * 4) : (((echo % 2) == 0) * 4); /* 0 or 4 */
    } else {
      whichplan = (min1stTE) ? 0 : 4;
    }
    whichplan += (blipsign == KS_EPI_NEGBLIPS) ? 2 : 0;
    whichplan += multishot_flag > 0;

    peplan_echoes[echo] = &allepiplans[whichplan];
  }

  return SUCCESS;

} /* ks_phaseencoding_allepiplans_setechoes() */

ks_wave_res()

int ks_wave_res

(

const KS_WAVE *

wave

)

Returns the number of samples in a KS_WAVE sequence object

Parameters

[in]

wave

KS_WAVE object

Return values

res	Resolution (i.e. number of samples) in the KS_WAVE object

                                     {

  if (wave == NULL) {
    ks_error("ks_wave_res: wave is NULL");
    return KS_NOTSET;
  }
  if (wave->description == NULL || wave->description[0] == ' ') {
    ks_error("ks_wave_res: wave description not initialized or has leading space");
    return KS_NOTSET;
  }
  if (wave->res < 2 || wave->res > KS_MAXWAVELEN) {
    ks_error("ks_wave_res(%s): 'res' (%d) is out of valid range [2, %d]", wave->description, wave->res, KS_MAXWAVELEN);
    return KS_NOTSET;
  }
  if (wave->res % 2) {
    ks_error("ks_wave_res(%s): 'res' (%d) must be even", wave->description, wave->res);
    return KS_NOTSET;
  }

  return wave->res;
}

ks_waveform_max()

float ks_waveform_max	(	const KS_WAVEFORM	waveform,
		int	res
	)

Returns the maximum value in a KS_WAVEFORM

Parameters

[in]	waveform	KS_WAVEFORM (float array)
[in]	res	Resolution (i.e. number of samples) in the KS_WAVEFORM

Return values

maxval

Maximum value

                                                           {
  float maxv = -1.0e38;
  int i;

  if (waveform == NULL) {
    ks_error("ks_waveform_max: wave is NULL");
    return maxv;
  }
  if (res <= 0) {
    return maxv;
  }

  for (i = 0; i < res; i++) {
    if (waveform[i] > maxv)
      maxv = waveform[i];
  }

  return maxv;
}

ks_wave_max()

float ks_wave_max

(

const KS_WAVE *

wave

)

Returns the maximum value in a KS_WAVE sequence object

Parameters

[in]

wave

KS_WAVE object

Return values

maxval

Maximum value

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

ks_waveform_min()

float ks_waveform_min	(	const KS_WAVEFORM	waveform,
		int	res
	)

Returns the minimum value in a KS_WAVEFORM

Parameters

[in]	waveform	KS_WAVEFORM (float array)
[in]	res	Resolution (i.e. number of samples) in the KS_WAVEFORM

Return values

minval

Minimum value

                                                           {
  float minv = 1.0e38;
  int i;

  if (waveform == NULL) {
    ks_error("ks_waveform_min: wave is NULL");
    return minv;
  }
  if (res <= 0) {
    return minv;
  }

  for (i = 0; i < res; i++) {
    if (waveform[i] < minv)
      minv = waveform[i];
  }

  return minv;
}

ks_wave_min()

float ks_wave_min

(

const KS_WAVE *

wave

)

Returns the minimum value in a KS_WAVE sequence object

Parameters

[in]

wave

KS_WAVE object

Return values

minval

Minimum value

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

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

Returns the maximum absolute value in a KS_WAVEFORM

Parameters

[in]	waveform	KS_WAVEFORM
[in]	res	Resolution (i.e. number of samples) in the KS_WAVEFORM
[in]	duration	Duration of the waveform in us

Return values

absmaxval

Maximum absolute value

                                                                             {
  float maxslew = -1.0e38;
  int i;

  if (waveform == NULL) {
    ks_error("ks_waveform_absmax: wave is NULL");
    return maxslew;
  }
  if (res <= 0) {
    return maxslew;
  }
  float tmp = 0;
  for (i = 0; i < res-1; i++) {
    tmp = fabs(waveform[i] - waveform[i+1]);
    if (tmp > maxslew)
      maxslew = tmp;
  }
  maxslew = maxslew*res/duration;
  return maxslew;
}

ks_wave_maxslew()

float ks_wave_maxslew

(

const KS_WAVE *

wave

)

Returns the maximum absolute value in a KS_WAVE

Parameters

[in]

wave

KS_WAVE

Return values

absmaxval

Maximum absolute value

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

ks_waveform_area()

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

Returns the area of a KS_WAVEFORM over a specified interval given in [us]

Parameters

[in]	waveform	KS_WAVEFORM (float array)
[in]	start	[us] Start position of area calculation in [us] (0 = start of waveform)
[in]	end	[us] End position of area calculation in [us] (res * dwelltime = end of waveform)
[in]	dwelltime	[us] of each waveform point (duration/res)

Return values

area	The area of the KS_WAVEFORM over the specified interval in [(G/cm) * us]

                                                                                            {
  int i;
  double area = 0;
  int start_indx = CEIL_DIV(start, dwelltime);
  int end_indx = end / dwelltime;

  if (waveform == NULL) {
    ks_error("%s: wave is NULL", __FUNCTION__);
  }
  if (start_indx < 0) {
    ks_error("%s: start must be >= 0", __FUNCTION__);
  }
  if (end_indx > KS_MAXWAVELEN) {
    ks_error("%s: end cannot exceed %d", __FUNCTION__, KS_MAXWAVELEN);
  }

  for (i = start_indx; i < end_indx; i++) {
    area += waveform[i] * dwelltime;
  }

  /* add potential partial dwell time due to CEIL_DIV, when start [us] is not divisible by dwelltime */
  if ((start_indx * dwelltime) > start && start_indx > 0) {
    area += waveform[start_indx - 1] * (((double) start_indx * dwelltime) - (double) start);
  }

  /* add potential partial dwell time due to (floor) integer division, when end [us] is not divisible by dwelltime */
  if ((end_indx * dwelltime) < end && (end_indx < (KS_MAXWAVELEN - 1))) {
    area += waveform[end_indx + 1] * ((double) end - ((double) end_indx * dwelltime));
  }

  return ((float) area);
}

ks_wave_area()

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

Returns the area of a KS_WAVE object over a specified interval given in [us]

Parameters

[in]	wave	KS_WAVE object
[in]	start	[us] Start position of area calculation in [us] (0 = start of waveform)
[in]	end	[us] End position of area calculation in us

Return values

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

                                                                {
  int dwelltime = wave->duration / wave->res;
  return ks_waveform_area(wave->waveform, start, end, dwelltime);
}

ks_waveform_sum()

float ks_waveform_sum	(	const KS_WAVEFORM	waveform,
		int	res
	)

Returns the sum of a KS_WAVEFORM

Parameters

[in]	waveform	KS_WAVEFORM (float array)
[in]	res	Resolution (i.e. number of samples) in the KS_WAVEFORM

Return values

sum	The sum of the KS_WAVEFORM

                                                           {
  int i;
  double sum = 0;

  if (waveform == NULL) {
    ks_error("ks_waveform_sum: wave is NULL");
  }
  if (res <= 0) {
    ks_error("ks_waveform_sum: res must be positive");
  }

  for (i = 0; i < res; i++) {
    sum += waveform[i];
  }

  return (float)sum;
}

ks_wave_sum()

float ks_wave_sum

(

const KS_WAVE *

wave

)

Returns the sum of a KS_WAVE sequence object

Parameters

[in]

wave

KS_WAVE object

Return values

sum	The sum of the KS_WAVEFORM

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

ks_waveform_norm()

float ks_waveform_norm	(	const KS_WAVEFORM	waveform,
		int	res
	)

Returns the 2-norm of a KS_WAVEFORM

Parameters

[in]	waveform	KS_WAVEFORM (float array)
[in]	res	Resolution (i.e. number of samples) in the KS_WAVEFORM

Return values

norm2

The 2-norm of a KS_WAVEFORM

                                                            {
  int i;
  double sum = 0;

  if (waveform == NULL) {
    ks_error("ks_waveform_norm: wave is NULL");
  }
  if (res <= 0) {
    ks_error("ks_waveform_norm: res must be positive");
  }

  for (i = 0; i < res; i++) {
    sum += pow(fabs(waveform[i]), 2.0);
  }

  return (float)sqrt(sum);
}

ks_wave_norm()

float ks_wave_norm

(

const KS_WAVE *

wave

)

Returns the 2-norm of a KS_WAVE

Parameters

[in]

wave

KS_WAVE object

Return values

norm2

The 2-norm of a KS_WAVE

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

ks_waveform_cumsum()

void ks_waveform_cumsum	(	KS_WAVEFORM	cumsumwaveform,
		const KS_WAVEFORM	waveform,
		int	res
	)

Calculates a KS_WAVEFORM with the cumulative sum (i.e. integral) of a KS_WAVEFORM

Parameters

[out]	cumsumwaveform	KS_WAVEFORM (float array)
[in]	waveform	KS_WAVEFORM (float array)
[in]	res	Resolution (i.e. number of samples) in the KS_WAVEFORM

                                                                                         {
  int i, j;

  for (j = 0; j < res; j++) {

    double sum = 0;
    for (i = 0; i < j; i++) {
      sum += waveform[i];
    }

    cumsumwaveform[j] = (float)sum;
  }
}

ks_wave_cumsum()

void ks_wave_cumsum	(	KS_WAVE *	cumsumwave,
		const KS_WAVE *	wave
	)

Calculates a KS_WAVE with the cumulative sum (i.e. integral) of a KS_WAVE

Parameters

[out]	cumsumwave	KS_WAVE object
[in]	wave	KS_WAVE

                                                              {
  int res;
  res = (cumsumwave->res > wave->res) ? wave->res : cumsumwave->res; /* smallest of the two */
  ks_waveform_cumsum(cumsumwave->waveform, wave->waveform, res);
}

ks_waveform_multiply()

void ks_waveform_multiply	(	KS_WAVEFORM	waveform_mod,
		const KS_WAVEFORM	waveform,
		int	res
	)

In-place multiplication of one KS_WAVEFORM with another KS_WAVEFORM

Multiplication of waveform a (arg 1) with waveform b (arg 2) as: a *= b

Parameters

[in,out]	waveform_mod	KS_WAVE object
[in]	waveform	KS_WAVEFORM (float array)
[in]	res	Resolution (i.e. number of samples) in the KS_WAVEFORM

                                                                                         {
  int i;

  for (i = 0; i < res; i++) {
    waveform_mod[i] *= waveform[i];
  }
}

ks_wave_multiply()

void ks_wave_multiply	(	KS_WAVE *	wave_mod,
		const KS_WAVE *	wave
	)

In-place multiplication of one KS_WAVE with another KS_WAVE

Multiplication of waveform a (arg 1) with waveform b (arg 2) as: a *= b

If the duration of the two KS_WAVE objects have different resolution, the shorter KS_WAVE will be multiplied with the first part of the longer KS_WAVE

Parameters

[in,out]	wave_mod	KS_WAVE object
[in]	wave	KS_WAVE object

                                                              {
  int res;
  res = (wave_mod->res > wave->res) ? wave->res : wave_mod->res; /* smallest of the two */
  ks_waveform_multiply(wave_mod->waveform, wave->waveform, res);
}

ks_waveform_add()

void ks_waveform_add	(	KS_WAVEFORM	waveform_mod,
		const KS_WAVEFORM	waveform,
		int	res
	)

In-place addition of one KS_WAVEFORM with another KS_WAVEFORM

Addition of waveform a (arg 1) with waveform b (arg 2) as: a += b

Parameters

[in,out]	waveform_mod	KS_WAVEFORM (float array)
[in]	waveform	KS_WAVEFORM (float array)
[in]	res	Resolution (i.e. number of samples) in the KS_WAVEFORM

                                                                                    {
  int i;

  for (i = 0; i < res; i++) {
    waveform_mod[i] += waveform[i];
  }
}

ks_wave_add()

void ks_wave_add	(	KS_WAVE *	wave_mod,
		const KS_WAVE *	wave
	)

In-place addition of one KS_WAVE with another KS_WAVE

Addition of waveform a (arg 1) with waveform b (arg 2) as: a *= b

If the duration of the two KS_WAVE objects have different resolution, the shorter KS_WAVE will be added to the first part of the longer KS_WAVE

Parameters

[in,out]	wave_mod	KS_WAVE object
[in]	wave	KS_WAVE object

                                                         {
  int res;
  res = (wave_mod->res > wave->res) ? wave->res : wave_mod->res; /* smallest of the two */
  ks_waveform_add(wave_mod->waveform, wave->waveform, res);
}

ks_waveform_multiplyval()

void ks_waveform_multiplyval	(	KS_WAVEFORM	waveform,
		float	val,
		int	res
	)

In-place scalar multiplication of a KS_WAVEFORM

The values in a KS_WAVEFORM are multiplied with a scalar value val

Parameters

[in,out]	waveform	KS_WAVEFORM (float array)
[in]	val	Floating point value to multiply with
[in]	res	Resolution (i.e. number of samples) in the KS_WAVEFORM

                                                                       {
  int i;

  for (i = 0; i < res; i++) {
    waveform[i] *= val;
  }
}

ks_wave_multiplyval()

void ks_wave_multiplyval	(	KS_WAVE *	wave,
		float	val
	)

In-place scalar multiplication of a KS_WAVE

The waveform values in a KS_WAVE sequence object (.waveform[]) are multiplied with a scalar value val

Parameters

[in,out]	wave	KS_WAVE object
[in]	val	Floating point value to multiply with

                                                   {
  ks_waveform_multiplyval(wave->waveform, val, wave->res);
}

ks_waveform_addval()

void ks_waveform_addval	(	KS_WAVEFORM	waveform,
		float	val,
		int	res
	)

In-place scalar addition of a KS_WAVEFORM

The values in a KS_WAVEFORM are added with a scalar value val

Parameters

[in,out]	waveform	KS_WAVEFORM (float array)
[in]	val	Floating point value to add
[in]	res	Resolution (i.e. number of samples) in the KS_WAVEFORM

                                                                  {
  int i;

  for (i = 0; i < res; i++) {
    waveform[i] += val;
  }
}

ks_wave_addval()

void ks_wave_addval	(	KS_WAVE *	wave,
		float	val
	)

In-place scalar addition of a KS_WAVE

The waveform values in a KS_WAVE sequence object (.waveform[]) are added with a scalar value val

Parameters

[in,out]	wave	KS_WAVE object
[in]	val	Floating point value to add

                                              {
  ks_waveform_addval(wave->waveform, val, wave->res);
}

ks_waveform2iwave()

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

(Internal use) Conversion of a KS_WAVEFORM to a short int array for use on hardware

This function is used internally by ks_pg_wave() and there should be no need to call this function directly.

For all boards except THETA, this function auto-scales the (float) values in KS_WAVEFORM so that the maximum absolute value becomes +/- 32766. The output short int (KS_IWAVE) array is to be copied to hardware. For a KS_WAVEFORM on the THETA board, the necessary phase wraps and scaling to short int format is performed using ks_phase_degrees2hw(). GE's requirement of only having even numbers in the waveform except for a final odd value (end-of-waveform) is also taken care of here

Note that the preservation of the physical units are done in ks_pg_wave() by setting the correct instruction amplitude to multiply this auto-scaled waveform with in the sequence's hardware memory

Parameters

[out]	iwave	KS_IWAVE (short int array)
[in]	waveform	KS_WAVEFORM
[in]	res	Resolution (i.e. number of samples) in the KS_WAVEFORM
[in]	board	One of XGRAD, YGRAD, ZGRAD, RHO, THETA, OMEGA

Return values

STATUS

SUCCESS or FAILURE

                                                                                         {
  int i;

  if (board != THETA) {
    float absmax = ks_waveform_absmax(waveform, res);
    for (i = 0; i < res; i++) {
      iwave[i] = ((short) (max_pg_wamp * waveform[i] / absmax)) & ~WEOS_BIT;
    }
  } else {
    for (i = 0; i < res; i++) {
      iwave[i] = ((short) ks_phase_degrees2hw(waveform[i])) & ~WEOS_BIT;
    }
  }

  /* set end-of-waveform flag */
  iwave[res - 1] |= WEOS_BIT;

  return SUCCESS;

} /* ks_wave2iwave() */

ks_wave2iwave()

STATUS ks_wave2iwave	(	KS_IWAVE	iwave,
		const KS_WAVE *	wave,
		int	board
	)

(Internal use) Conversion of waveform content in a KS_WAVE sequence object to a short int array for use on hardware

This function is used internally by ks_pg_wave() and there should be no need to call this function directly.

For all boards except THETA, this function auto-scales the (float) values in the .waveform[] field so that the maximum absolute value becomes +/- 32766. The output short int (KS_IWAVE) array is to be copied to hardware. For a KS_WAVE on the THETA board, the necessary phase wraps and scaling to short int format is performed using ks_phase_degrees2hw(). GE's requirement of only having even numbers in the waveform except for a final odd value (end-of-waveform) is also taken care of here

Note that the preservation of the physical units are done in ks_pg_wave() by setting the correct instruction amplitude to multiply this auto-scaled waveform with in the sequence's hardware memory

Parameters

[out]	iwave	KS_IWAVE (short int array)
[in]	wave	KS_WAVE
[in]	board	One of XGRAD, YGRAD, ZGRAD, RHO, THETA, OMEGA

Return values

STATUS

SUCCESS or FAILURE

                                                                     {
  return ks_waveform2iwave(iwave, wave->waveform, wave->res, board);
}

ks_pg_echossp()

WF_PULSE* ks_pg_echossp	(	WF_PULSE *	echo,
		const char *	suffix
	)

Returns the pointer to XTR or RBA for an echo WF_PULSE (internal use)

This function is used internally by ks_pg_read() to get pointers to the XTR and RBA SSP packets for an acquisition window

Parameters

[in]	echo	Pointer to an echo (WF_PULSE)
[in]	suffix	String being "xtr", "rba", or empty

Return values

wfptr

Pointer to a WF_PULSE

                                                             {

  if (!strcmp(suffix, "xtr")) {
    return echo->assoc_pulse;
  } else if (!strcmp(suffix, "rba")) {
    return echo->assoc_pulse->assoc_pulse;
  } else {
    return echo;
  }

}

ks_pg_trap()

STATUS ks_pg_trap	(	KS_TRAP *	trap,
		KS_SEQLOC	loc,
		KS_SEQ_CONTROL *	ctrl
	)

Places a KS_TRAP sequence object on a board at some position in the pulse sequence

This function should be called in the @pg section to place out a KS_TRAP sequence object that creates a static trapezoid in the pulse sequence. The same KS_TRAP object can be freely placed on XGRAD, YGRAD and ZGRAD as many times as desired, by only changing the second argument each time (to avoid waveform overlaps). The second argument is a KS_SEQLOC struct with three fields:

• .board: Choose between XGRAD, YGRAD, ZGRAD (or OMEGA)
• .pos: Absolute time in [us] of the start of the attack ramp of the trapezoid
• .ampscale: A factor that must be in range [-1.0,1.0] that is multiplied with .amp to yield a per-instance (i.e. per-placement) amplitude ([G/cm]). The simplest is to use 1.0, which makes the KS_TRAP object to be placed out on the board as initially designed using ks_eval_trap(). For the OMEGA board, this factor must be 1.0.

Regardless of the order placed out in the @pg section, and on which boards (XGRAD, YGRAD, ZGRAD) the KS_TRAP object is placed, the instance number of the KS_TRAP is automatically sorted in time. If two instances of one KS_TRAP occur at the same time (.pos) on different boards, XGRAD comes before YGRAD, which comes before ZGRAD. These abstract, sorted, instance numbers are used by ks_scan_***() functions in scan() to refer to a specific instance of a KS_TRAP object in the sequence

If the .duration field in the KS_TRAP object is 0, ks_pg_trap() will return SUCCESS and quietly ignore placing it out. This is a part of the mechanism that setting the .duration field to 0 in cveval() should eliminate its existance in both timing calulations and in the pulse sequence generation in @pg

When a trapezoid is placed on OMEGA, neither the designed amplitude (the .amp field in KS_TRAP) nor the .ampscale (in KS_SEQLOC) has an effect on the final frequency modulation. Instead the run-time amplitude of a KS_TRAP object on the OMEGA board is controlled in scan() via a function called ks_scan_omegatrap_hz()

GENERAL NOTE: It is a requirement that the function in the @pg section containing all ks_pg_***() calls is also called exactly once in cveval() after the calls to the corresponding ks_eval_***() functions that design the KS_*** sequence objects. Each ks_pg_***() will throw an error if this has not been done.

Parameters

[in,out]	trap	Pointer to a KS_TRAP sequence object
[in]	loc	KS_SEQLOC struct to specify when and where to place the KS_TRAP
[in,out]	ctrl	Pointer to the KS_SEQ_CONTROL struct corresponding to the sequence module for this KS_TRAP

Return values

STATUS

SUCCESS or FAILURE

                                                                      {
  float boardmax;
  char boardc[8] = "xyz---o";

  boardmax = ks_syslimits_gradtarget(loggrd, loc.board); /* returns 1.0 for OMEGA board */

  /* checking for NULL pointers */
  if (trap == NULL) {
    return ks_error("ks_pg_trap: First argument is NULL");
  }
  /* duration of 0 should not throw an error as this is a sign of that it has not been set up
     or has manually been disabled this way */
  if (trap->duration == 0) {
    return SUCCESS;
  }

  if (trap->description == NULL || trap->description[0] == 0 || trap->description[0] == ' ') {
    return ks_error("ks_pg_trap: Invalid description ('%s')", trap->description);
  }

#ifdef IPG
  /* TGT: Don't place anything on hardware if ctrl->duration = 0.
     This is in concert with:
     - not performing createseq() in KS_SEQLENGTH if seqctrl.duration = 0
     - not playing sequence modules in scan() using ks_scan_playsequence() if seqctrl.duration = 0
     */
  if (ctrl->duration == 0) {
    return ks_error("%s(%s): Refusing to place trap since seqctrl.duration = 0 (indicating `%s` not to be played in scan())", __FUNCTION__, trap->description, ctrl->description);
  }
#endif

  /* input validation */
  if ((trap->ramptime % 4) || (trap->plateautime % 4) || (trap->duration % 4)) {
    ks_error("ks_pg_trap(%s): All timing parameters must be divisible by 4", trap->description);
    return FAILURE;
  }

  if ((trap->ramptime < 4) || (trap->plateautime < 4) || (trap->duration < 4)) {
    ks_error("ks_pg_trap(%s): All timing parameters must be at least 4 us", trap->description);
    return FAILURE;
  }

  if (isNaN(loc.ampscale)) {
    return ks_error("ks_pg_trap(%s): loc.ampscale NaN", trap->description);
  }

  if (loc.pos < GRAD_UPDATE_TIME || loc.pos > 4e6) {
    ks_error("ks_pg_trap(%s): Invalid position %d, it must be between 4us and 4s", trap->description, loc.pos);
    return FAILURE;
  }

  if (loc.board == OMEGA && !areSame(loc.ampscale,1.0)) {
    return ks_error("ks_pg_trap(%s): ampscale must be +1.0 for OMEGA", trap->description);
  }

  if (loc.ampscale < -1.0 || loc.ampscale > 1.0) {
    ks_error("ks_pg_trap(%s): Invalid ampscale %g, it must be between -1.0 and 1.0", trap->description, loc.ampscale);
    return FAILURE;
  }

  if (loc.board != XGRAD && loc.board != YGRAD && loc.board != ZGRAD && loc.board != OMEGA) {
    ks_error("ks_pg_trap(%s): Invalid board code %d, it must be %d (XGRAD), %d (YGRAD), %d (ZGRAD) or %d (OMEGA)", trap->description, loc.board, XGRAD, YGRAD, ZGRAD, OMEGA);
    return FAILURE;
  }

  if (fabs(trap->amp * loc.ampscale) > boardmax) {
    ks_error("ks_pg_trap(%s): trapezoid amplitude %g exceeds maximum (%g) for board %c", trap->description, trap->amp * loc.ampscale, boardmax, boardc[loc.board]);
    return FAILURE;
  }

  loc.pos = RUP_GRD(loc.pos);

#ifdef IPG
  {

    int i;

    char tmpstr[KS_DESCRIPTION_LENGTH + 7];
    tmpstr[KS_DESCRIPTION_LENGTH + 7 - 1] = 0;

    if (trap->base.ngenerated >= trap->base.ninst) {
      ks_error("ks_pg_trap @tgt(%s): the number of instances generated on the target exceeds the number of ones generated on the host", trap->description);
      return FAILURE;
    }

    if (!ctrl->gradrf.is_cleared_on_tgt) /* Reset gradrfctrl on tgt to remove dead pointers copied from host. */
    {
      ks_tgt_reset_gradrfctrl(&ctrl->gradrf);
    }

    /* TODO: consider freeing memory if ngenerated is zero -- EA */

    if (trap->wfpulse == NULL) {
      WF_PULSE wfInit = INITPULSE;

      trap->wfpulse = (WF_PULSE **) AllocNode(8 * sizeof(WF_PULSE *)); /* X, Y, Z, (OMEGA = 6). Not applicable to other boards */

      for (i = XGRAD; i <= OMEGA; i++) {

        if (i == XGRAD || i == YGRAD || i == ZGRAD || i == OMEGA) {

          trap->wfpulse[i] = (WF_PULSE *) AllocNode(3 * sizeof(WF_PULSE)); /* attack, plateau, decay */

          /* init pulse structure */
          trap->wfpulse[i][G_ATTACK] = wfInit;
          trap->wfpulse[i][G_PLATEAU] = wfInit;
          trap->wfpulse[i][G_DECAY] = wfInit;

          /* Name for WF_PULSEs */
          sprintf(tmpstr, "%s.%ca", trap->description, boardc[i]); pulsename(&(trap->wfpulse[i][G_ATTACK]), tmpstr);
          sprintf(tmpstr, "%s.%c", trap->description,  boardc[i]); pulsename(&(trap->wfpulse[i][G_PLATEAU]), tmpstr);
          sprintf(tmpstr, "%s.%cd", trap->description, boardc[i]); pulsename(&(trap->wfpulse[i][G_DECAY]), tmpstr);

          createramp(&(trap->wfpulse[i][G_ATTACK]), (WF_PROCESSOR) i, trap->ramptime, 0, max_pg_wamp,
                     maxGradRes * (trap->ramptime / GRAD_UPDATE_TIME), 1.0);
          createconst(&(trap->wfpulse[i][G_PLATEAU]), (WF_PROCESSOR) i, trap->plateautime, max_pg_wamp);
          createramp(&(trap->wfpulse[i][G_DECAY]), (WF_PROCESSOR) i, trap->ramptime, max_pg_wamp, 0,
                     maxGradRes * (trap->ramptime / GRAD_UPDATE_TIME), 1.0);

          linkpulses(3, &(trap->wfpulse[i][G_PLATEAU]), &(trap->wfpulse[i][G_ATTACK]), &(trap->wfpulse[i][G_DECAY]));

        } else {

          trap->wfpulse[i] = NULL;

        }

      } /* per board */

    } /* wfpulse == NULL */


    /* allocate the array of WFINSTANCE's if needed */
    if (!trap->wfi) {
      trap->wfi = (KS_WFINSTANCE *) AllocNode(trap->base.ninst * sizeof(KS_WFINSTANCE));
    }

    /* Set instruction amplitudes at the proper position and board */
    {
      const int corrected_pos = loc.pos + (loc.board == OMEGA)*psd_rf_wait;
      /* creating new instructions */
      createinstr(&(trap->wfpulse[loc.board][G_ATTACK]),
                  corrected_pos,
                  trap->ramptime,
                  (int)(trap->amp * loc.ampscale * MAX_PG_IAMP / boardmax));
      createinstr(&(trap->wfpulse[loc.board][G_PLATEAU]),
                  corrected_pos + trap->ramptime,
                  trap->plateautime,
                  (int)(trap->amp * loc.ampscale * MAX_PG_IAMP / boardmax));
      createinstr(&(trap->wfpulse[loc.board][G_DECAY]),
                  corrected_pos + trap->ramptime + trap->plateautime,
                  trap->ramptime,
                  (int)(trap->amp * loc.ampscale * MAX_PG_IAMP / boardmax));
    }

    /* initializing the corresponding KS_WFINSTANCE */
    trap->wfi[trap->base.ngenerated].boardinstance = trap->wfpulse[loc.board][G_PLATEAU].ninsts - 1; /* zero based */
    trap->wfi[trap->base.ngenerated].wf = &(trap->wfpulse[loc.board][G_PLATEAU]);
    trap->wfi[trap->base.ngenerated].loc = loc;

    trap->base.ngenerated++;

    /* sort after the last instance is generated */
    if (trap->base.ngenerated == trap->base.ninst) {
      ks_sort_wfi_by_timeboard(trap->wfi, trap->base.ninst);
    }
  }
#else /* TGT(IPG) or HOST */
  {
    /* HOST */

    trap->locs[trap->base.ninst] = loc;

    /* update instance counter on host only. This counter is used to allocate the right amount of WFINSTANCEs on IPG */
    trap->base.ninst++;

    /* for trap, we also need to keep track of #instances per X, Y, Z for gradient heating calculations.
       As this needs to be done in HOST before the IPG (target), we can't use the wfi[...].boardinstance or .loc information above for this */
    if (loc.board == XGRAD || loc.board == YGRAD || loc.board == ZGRAD)
      trap->gradnum[loc.board]++;
  }

#endif /* IPG */
    /* register this KS_TRAP for later heating calculations */
    {
      STATUS status = ks_eval_addtraptogradrfctrl(&ctrl->gradrf, trap);
      if (status != SUCCESS) return status;
    }
  return SUCCESS;

} /* ks_pg_trap */

ks_pg_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) {
      ks_error("ks_pg_read @tgt(%s): the number of instances generated on the target exceeds the number of ones generated on the host", read->description);
      return FAILURE;
    }

    if (!ctrl->gradrf.is_cleared_on_tgt) { /* Reset gradrfctrl on tgt to remove dead pointers copied from host. */
      ks_tgt_reset_gradrfctrl(&ctrl->gradrf);
    }

    if (read->echo == NULL) {
      /* this relies on that we have run the sequence in cveval() (i.e. on host) before to get proper grad.ninst */
      read->echo = (WF_PULSE *) AllocNode(read->base.ninst * sizeof(WF_PULSE));
    }

    placementindx = read->base.ngenerated; /* not sorted in time, but in placement order */

    acqwin_start = pos + psd_grd_wait;

    if (placementindx == 0 || read->filt.tdaq > 200) {
      dab_pos = DEFAULTPOS; /* results in 200 us before RBA (DEFAULTPOS is defined as 0. See: /ESE_.../psd/include/private/pulsegen.h) */
    } else {
      /* For small matrix sizes, the acq window is so short that the DAB packet
         for current lobe may collide with the RBA belonging to the previous lobe.
         We are not allowed to decrease the DAB-RBA distance below 200us. Instead,
         let's put it right after the end of the previous XTR pulse.
         With the default XTR-RBA offset of 143us, and since the RBA-RBA distance
         is equal to read->grad.duration, we will get a DAB-RBA offset of
      acqwin_duration + 143us - 17us (XTR duration)
      */
      dab_pos = pbegallssp(ks_pg_echossp(&read->echo[placementindx - 1], "xtr"), 0) + 32 /* LONG_DAB_length = 31 */;
      if (dab_pos + 200 > acqwin_start)
        dab_pos = DEFAULTPOS; /* fallback to default pos. Perhaps the readouts were not placed out in time order in the PSD ? */
    }

    /* name the ACQ pulse */
    sprintf(tmpstr, "%s%03d", read->description, placementindx); pulsename(&(read->echo[placementindx]), tmpstr);

    if (read->filt.fslot == KS_NOTSET) {
      /* add 'return' before ks_error once we've got an answer from GE regarding acqq and setrfltrs() */
      ks_error("ks_pg_read @tgt(%s): WARNING no filter slot assigned. First run setfilter(&read.filt)", read->description);
    }

    /* place the ACQ pulse */
    acqq_longdab(&(read->echo[placementindx]),
         (long) acqwin_start,
         (long) dab_pos, /* DAB */
         (long) DEFAULTPOS, /* XTR */
         read->filt.fslot /* filter slot */);

    read->base.ngenerated++;

    /* sort after the last instance is generated */
    if (read->base.ngenerated == read->base.ninst) {
      ks_sort_wfp_by_time(read->echo, read->base.ninst);
    }

    /* Associate this echo with a global filter slot number
       This number is generated by the GE function setfilter() in e.g. predownload(), before this function is called.
       For main sequences, there is also the wrapper function GEReq_predownload_setfilter() */
    if (read->filt.fslot >= 0 && read->filt.fslot <= MAX_FILTER_SLOT) {
      setrfltrs((int) read->filt.fslot, &(read->echo[placementindx]));
    }

  }
#else /* IPG */
  {
    read->pos[read->base.ninst] = pos;
    read->base.ninst++; /* update acq counter on host */
  }
#endif /* IPG */

  status = ks_eval_addreadtogradrfctrl(&ctrl->gradrf, read);
  if (status != SUCCESS) return status;
  return SUCCESS;
}

ks_pg_readtrap()

STATUS ks_pg_readtrap	(	KS_READTRAP *	readtrap,
		KS_SEQLOC	loc,
		KS_SEQ_CONTROL *	ctrl
	)

Places a KS_READTRAP sequence object on a board at some position in the pulse sequence

This function should be called in the @pg section to place out a KS_READTRAP sequence object consisting of a trapezoid (KS_TRAP) and an acquisition window (KS_READ). The same KS_READTRAP object can be freely placed on XGRAD, YGRAD and ZGRAD as many times as desired, by only changing the second argument each time (to avoid waveform overlaps). For Cartesian applications, readouts such as KS_READTRAP are typically placed on XGRAD (frequency encoding axis). The second argument is a KS_SEQLOC struct with three fields:

• .board: Choose between XGRAD, YGRAD, ZGRAD
• .pos: Absolute time in [us] of the start of the attack ramp of the readout trapezoid
• .ampscale: For KS_READTRAP objects, this must be either +1.0 or -1.0 so that the FOV is not altered. Negative amplitudes will automatically be taken into account in ks_scan_offsetfov() to create the necessary frequency offset

Regardless of the order placed out in the @pg section, and on which boards (XGRAD, YGRAD, ZGRAD) the KS_READTRAP object is placed, the instance number of the KS_READTRAP is automatically sorted in time. If two instances of one KS_READTRAP occur at the same time (.pos) on different boards, XGRAD comes before YGRAD, which comes before ZGRAD. These abstract, sorted, instance numbers are used by ks_scan_***() functions in scan() to refer to a specific instance of a KS_READTRAP object in the sequence.

If the .duration field in the KS_READTRAP object is 0, ks_pg_readtrap() will return SUCCESS and quietly ignore placing it out. This is a part of the mechanism that setting the .duration field to 0 in cveval() should eliminate its existance in both timing calulations and in the pulse sequence generation in @pg

GENERAL NOTE: It is a requirement that the function in the @pg section containing all ks_pg_***() calls is also called exactly once in cveval() after the calls to the corresponding ks_eval_***() functions that design the KS_*** sequence objects. Each ks_pg_***() will throw an error if this has not been done.

Parameters

[in,out]	readtrap	Pointer to a KS_READTRAP sequence object
[in]	loc	KS_SEQLOC struct to specify when and where to place the KS_READTRAP
[in,out]	ctrl	Pointer to the KS_SEQ_CONTROL struct corresponding to the sequence module for this KS_READTRAP

Return values

STATUS

SUCCESS or FAILURE

                                                                                  {
  KS_SEQLOC omegaloc;

  /* checking for NULL pointers */
  if (readtrap == NULL) {
    return ks_error("%s: First argument is NULL", __FUNCTION__);
  }
  /* duration of 0 should not throw an error as this is a sign of that it has not been set up
     or has manually been disabled this way */
  if (readtrap->grad.duration == 0) {
    return SUCCESS;
  }
  if (readtrap->grad.description == NULL || readtrap->grad.description[0] == 0 || readtrap->grad.description[0] == ' ') {
    return ks_error("%s: Invalid description ('%s')", __FUNCTION__, readtrap->grad.description);
  }

#ifdef IPG
  /* TGT (IPG): Don't place anything on hardware if ctrl->duration = 0.
      This is in concert with:
      - not performing createseq() in KS_SEQLENGTH if seqctrl.duration = 0
     - not playing sequence modules in scan() using ks_scan_playsequence() if seqctrl.duration = 0
     */
  if (ctrl->duration == 0) {
    return ks_error("%s(%s): Refusing to place readtrap since seqctrl.duration = 0 (indicating `%s` not to be played in scan())", __FUNCTION__, readtrap->grad.description, ctrl->description);
  }
#endif

  if (!areSame(loc.ampscale, 1.0) && !areSame(loc.ampscale, -1.0)) {
    ks_error("%s(%s): .ampscale %g must be exactly +1 or -1 for readout gradients", __FUNCTION__, readtrap->grad.description, loc.ampscale);
    return FAILURE;
  }

  /*** acq ***/
  if (ks_pg_read(&readtrap->acq, loc.pos + readtrap->acqdelay, ctrl) == FAILURE)
    return FAILURE;


  /*** trapezoid ***/
  if (ks_pg_trap(&readtrap->grad, loc, ctrl) == FAILURE)
    return FAILURE;

  /* also place the omega wave form for rampsampled cases */
  if (readtrap->omega.duration > 0) {
    /* omega trapezoid matching the readout lobe to allow for FOV offsets in freq dir. with ramp sampling */
    omegaloc.board = OMEGA;
    omegaloc.pos = loc.pos;
    omegaloc.ampscale = 1.0; /* just unity value for conformance. It does not matter during scanning, since ks_scan_omegahz() ignores this value */
    if (ks_pg_trap(&readtrap->omega, omegaloc, ctrl) == FAILURE)
      return FAILURE;
  }


  return SUCCESS;


} /* ks_pg_readtrap */

ks_pg_wave()

STATUS ks_pg_wave	(	KS_WAVE *	wave,
		KS_SEQLOC	loc,
		KS_SEQ_CONTROL *	ctrl
	)

Places a KS_WAVE sequence object on a board at some position in the pulse sequence

This function should be called in the @pg section to place out a KS_WAVE sequence object that creates an arbitrary waveform in the pulse sequence. The same KS_WAVE object can be placed on any board as many times as desired, by only changing the second argument each time (to avoid waveform overlaps). However, the RHO (RF) board should be avoided as this bypasses RF scaling and SAR calculations, providing no control over the flip angle. For RF waveforms, always use KS_RF (or KS_SELRF). The second argument is a KS_SEQLOC struct with three fields:

• .board: Choose between XGRAD, YGRAD, ZGRAD, OMEGA, THETA
• .pos: Absolute time in [us] of the start of the waveform. For RF, OMEGA and THETA, pos_rf_wait will be added to this time to take system delays into account
• .ampscale: For gradient boards, this factor must be in range [-1.0,1.0] that is multiplied with the waveform to yield a per-instance (i.e. per-placement) amplitude ([G/cm]). For THETA, only values of +1.0 and -1.0 is allowed, and for OMEGA only 1.0 is allowed

The KS_WAVE sequence object contains a KS_WAVEFORM (float[KS_MAXWAVELEN]) to hold the waveform. The physical unit of the waveform in the KS_WAVE object depends the board on which it is placed using ks_pg_wave(). For the

• gradient boards (XGRAD, YGRAD, ZGRAD), the unit is [G/cm]
• THETA board, the unit is [degrees]
• RF (RHO) and OMEGA boards, the units are arbitrary (c.f. ks_eval_rf() and ks_eval_wave()). Don't call ks_pg_wave() directly to place a KS_WAVE on the RF board

When a waveform is placed on OMEGA, neither the waveform amplitude nor the .ampscale (in KS_SEQLOC) affects the final frequency modulation. Instead the run-time amplitude of a KS_WAVE object on the OMEGA board is controlled in scan() via a function called ks_scan_omegawave_hz(), where the largest value in the field .waveform[] in the KS_WAVE will correspond to the value in [Hz] provided.

If the .duration field in the KS_WAVE object is 0, ks_pg_wave() will return SUCCESS and quietly ignore placing it out. This is a part of the mechanism that setting the .duration field to 0 in cveval() should eliminate its existance in both timing calulations and in the pulse sequence generation in @pg

All KS_WAVE objects are double buffered in ks_pg_wave() so that waveforms can be replaced in run-time (scan()) using ks_scan_wave2hardware()

Regardless of the order placed out in the @pg section, and on which boards (XGRAD, YGRAD, ZGRAD) the KS_WAVE object is placed, the instance number of the KS_WAVE is automatically sorted in time. If two instances of one KS_WAVE occur at the same time (.pos) on different boards, XGRAD comes before YGRAD, which comes before ZGRAD. These abstract, sorted, instance numbers are used by ks_scan_***() functions in scan() to refer to a specific instance of a KS_WAVE object in the sequence.

GENERAL NOTE: It is a requirement that the function in the @pg section containing all ks_pg_***() calls is also called exactly once in cveval() after the calls to the corresponding ks_eval_***() functions that design the KS_*** sequence objects. Each ks_pg_***() will throw an error if this has not been done.

Parameters

[in,out]	wave	Pointer to a KS_WAVE sequence object
[in]	loc	KS_SEQLOC struct to specify when and where to place the KS_WAVE
[in,out]	ctrl	Pointer to the KS_SEQ_CONTROL struct corresponding to the sequence module for this KS_WAVE

Return values

STATUS

SUCCESS or FAILURE

                                                                      {
  float boardmax;
  char boardc[8] = "xyzrrto"; /* x,y,z,rho1,rho2,theta,omega */
  float waveamp = ks_wave_absmax(wave); /* maximum amplitude in wave (in its own units, like e.g. [G/cm] or [degrees]) */

  boardmax = ks_syslimits_gradtarget(loggrd, loc.board); /* returns 1.0 for non-gradients boards */

  /* checking for NULL pointers */
  if (wave == NULL) {
    return ks_error("ks_pg_wave: First argument is NULL");
  }
  /* duration of 0 should not throw an error as this is a sign of that it has not been set up
     or has manually been disabled this way */
  if (wave->duration == 0) {
    return SUCCESS;
  }
  if (wave->description == NULL || wave->description[0] == 0 || wave->description[0] == ' ') {
    return ks_error("ks_pg_wave: Invalid description ('%s')", wave->description);
  }

#ifdef IPG
  /* TGT: Don't place anything on hardware if ctrl->duration = 0.
     This is in concert with:
     - not performing createseq() in KS_SEQLENGTH if seqctrl.duration = 0
     - not playing sequence modules in scan() using ks_scan_playsequence() if seqctrl.duration = 0
     */
  if (ctrl->duration == 0) {
    return ks_error("%s(%s): Refusing to place wave since seqctrl.duration = 0 (indicating `%s` not to be played in scan())", __FUNCTION__, wave->description, ctrl->description);
  }

  if (!ctrl->gradrf.is_cleared_on_tgt) /* Reset gradrfctrl on tgt to remove dead pointers copied from host. */
  {
    ks_tgt_reset_gradrfctrl(&ctrl->gradrf);
  }

#endif

  /* input validation */
  if (wave->duration % 4) {
    return ks_error("ks_pg_wave(%s): field 'duration' (%d) must be divisible by 4", wave->description, wave->duration);
  }
  if (wave->res == 0) {
    return ks_error("ks_pg_wave(%s): field 'res' cannot be 0", wave->description);
  }
  if (wave->res % 2) {
    return ks_error("ks_pg_wave(%s): field 'res' (%d) must be even ", wave->description, wave->res);
  }
  if (wave->duration % wave->res) {
    return ks_error("ks_pg_wave(%s): field 'duration' (%d) must be divisible by 'res' %d", wave->description, wave->duration, wave->res);
  }
  if (loc.board == XGRAD || loc.board == YGRAD || loc.board == ZGRAD) {
    if ((wave->duration / wave->res) % GRAD_UPDATE_TIME) {
      return ks_error("ks_pg_wave(%s): field 'duration' (%d) must a multiple of 4 times 'res' (%d) for gradient boards", wave->description, wave->duration, wave->res);
    }
    if (wave->gradwave_units == KS_GRADWAVE_ABSOLUTE && !areSame(loc.ampscale,1.0)) {
      return ks_error("ks_pg_wave(%s): ampscale must be +1.0 for gradwave with absolute units", wave->description);
    }
  } else {
    if ((wave->duration / wave->res) % RF_UPDATE_TIME) {
      return ks_error("ks_pg_wave(%s): field 'duration' (%d) must a multiple of 2 times 'res' (%d) for non-gradient boards", wave->description, wave->duration, wave->res);
    }
  }

  if (isNaN(loc.ampscale)) {
    return ks_error("ks_pg_wave(%s): loc.ampscale NaN", wave->description);
  }
  if (loc.pos < GRAD_UPDATE_TIME || loc.pos > 4e6) {
    return ks_error("ks_pg_wave(%s): Invalid position %d, it must be between 4us and 4s", wave->description, loc.pos);
  }
  if (loc.board == OMEGA && !areSame(loc.ampscale,1.0)) {
    return ks_error("ks_pg_wave(%s): ampscale must be +1.0 for OMEGA", wave->description);
  }
  if (loc.board == THETA && !areSame(loc.ampscale,1.0) && !areSame(loc.ampscale,-1.0)) {
    return ks_error("ks_pg_wave(%s): ampscale must be +1.0 or -1.0 for THETA", wave->description);
  }
  if (loc.ampscale < -1.0 || loc.ampscale > 1.0) {
    return ks_error("ks_pg_wave(%s): Invalid ampscale %g, it must be between -1.0 and 1.0", wave->description, loc.ampscale);
  }
  if (fabs(waveamp * loc.ampscale) > boardmax && loc.board != THETA) {
    return  ks_error("ks_pg_wave(%s): wave amplitude (%.2f) exceeds maximum (%g) for board %c", wave->description, waveamp * loc.ampscale, boardmax, boardc[loc.board]);
  }

  loc.pos = RUP_GRD(loc.pos);


#ifdef HOST_TGT

  /* HOST */

  wave->locs[wave->base.ninst] = loc;

  /* update instance counter on host only. This counter is used to allocate the right amount of WFINSTANCEs on IPG */
  wave->base.ninst++;

  /* for wave, we also need to keep track of #instances per X, Y, Z for gradient heating calculations.
     As this needs to be done in HOST before the IPG (target), we can't use the wfi[...].boardinstance or .loc information above for this */
  if (loc.board == XGRAD || loc.board == YGRAD || loc.board == ZGRAD) {
    wave->gradnum[loc.board]++;
  }

#else

  {

    int i;
    int wave_ptr, isrf, iamp;
    char tmpstr[KS_DESCRIPTION_LENGTH + 7];

    if (wave->base.ngenerated >= wave->base.ninst) {
      ks_error("ks_pg_wave @tgt(%s): the number of instances generated on the target (%d) exceeds the number of ones generated on the host (%d)", wave->description, wave->base.ngenerated + 1, wave->base.ninst);
      return FAILURE;
    }

    /* first call on TGT, allocate WF_PULSE * array where each element corresponds to one board */
    if (wave->wfpulse == NULL) {
      wave->wfpulse = (WF_PULSE **) AllocNode(7 * sizeof(WF_PULSE *)); /* WF pointers for all boards (XGRAD->OMEGA) */
    } /* wfpulse == NULL */


    /* first call on TGT using this loc.board, make waveform memory (double buffered) */
    if (wave->wfpulse[loc.board] == NULL) {
      WF_PULSE wfInit = INITPULSE;
      KS_IWAVE iwave;

      wave->wfpulse[loc.board] = (WF_PULSE *) AllocNode(KS_WF_SIZE * sizeof(WF_PULSE)); /* KS_WF_SIZE (3) to allow for double buffering */

      for (i = KS_WF_MAIN; i < KS_WF_SIZE; i++)
        wave->wfpulse[loc.board][i] = wfInit;

      sprintf(tmpstr, "%s.%c", wave->description, boardc[loc.board]);      pulsename(&(wave->wfpulse[loc.board][KS_WF_MAIN]), tmpstr);
      sprintf(tmpstr, "%s_buf1.%c", wave->description, boardc[loc.board]); pulsename(&(wave->wfpulse[loc.board][KS_WF_BUF1]), tmpstr);
      sprintf(tmpstr, "%s_buf2.%c", wave->description, boardc[loc.board]); pulsename(&(wave->wfpulse[loc.board][KS_WF_BUF2]), tmpstr);

      /* wave -> short int wave for hardware use. All waveforms but THETA are autoscaled to +/- max_pg_wamp (32766)*/
      if (ks_wave2iwave(iwave, wave, loc.board) == FAILURE)
        return FAILURE;

      /* reserve hardware memory to allow for double buffering */
      for (i = KS_WF_MAIN; i <= KS_WF_BUF2; i++) {
        createreserve(&wave->wfpulse[loc.board][i], (WF_PROCESSOR) loc.board, wave->res);
        wave->wfpulse[loc.board][i].type = TYPEXTERNAL;
        movewaveimm(iwave, &wave->wfpulse[loc.board][i], (int) 0, wave->res, TOHARDWARE);
      }

    } /* wfpulse[loc.board] == NULL */


    /* create instruction at the current position */
    isrf = loc.board == RHO || loc.board == RHO2 || loc.board == THETA || loc.board == OMEGA;

    if (loc.board == THETA)
      iamp = (int)(loc.ampscale * MAX_PG_IAMP);
    else
      iamp = (int)((waveamp * loc.ampscale / boardmax) * MAX_PG_IAMP);

    createinstr(&wave->wfpulse[loc.board][KS_WF_MAIN],
                (long) (loc.pos + (psd_rf_wait * isrf)),
                (long) wave->duration,
                (long) iamp);

    /* WF instance bookkeeping */
    if (wave->wfi == NULL) {
      wave->wfi = (KS_WFINSTANCE *) AllocNode(wave->base.ninst * sizeof(KS_WFINSTANCE));
    }
    wave->wfi[wave->base.ngenerated].boardinstance = wave->wfpulse[loc.board][KS_WF_MAIN].ninsts - 1;
    wave->wfi[wave->base.ngenerated].wf = wave->wfpulse[loc.board];
    wave->wfi[wave->base.ngenerated].loc = loc;

    /* After instructions have been set, set the wfpulse[KS_WF_MAIN] to the first waveform buffer (_BUF1) */
    getwave(&wave_ptr, &(wave->wfpulse[loc.board][KS_WF_BUF1]));
    setwave(wave_ptr,  &(wave->wfpulse[loc.board][KS_WF_MAIN]), wave->wfi[wave->base.ngenerated].boardinstance);

    wave->base.ngenerated++;

    /* sort after the last instance is generated */
    if (wave->base.ngenerated == wave->base.ninst) {
      ks_sort_wfi_by_timeboard(wave->wfi, wave->base.ninst);
    }

  }

#endif /* IPG or HOST */

  /* register this KS_WAVE for later heating calculations */
  {
    STATUS status = ks_eval_addwavetogradrfctrl(&ctrl->gradrf, wave);
    if (status != SUCCESS) return status;
  }

  return SUCCESS;

} /* ks_pg_wave */

ks_pg_rf()

STATUS ks_pg_rf	(	KS_RF *	rf,
		KS_SEQLOC	loc,
		KS_SEQ_CONTROL *	ctrl
	)

Places a KS_RF sequence object on a board at some position in the pulse sequence

This function should be called in the @pg section to place out a KS_RF sequence object that creates an RF pulse in the pulse sequence. The same KS_RF object can be placed out as many times as desired, by only changing the second argument each time (to avoid waveform overlaps). The second argument is a KS_SEQLOC struct with three fields:

• .board: Ignored. .rfwave will always be placed on RHO. If the resolution of .omegawave is non-zero it will be placed on OMEGA, and correspondingly for .thetawave on THETA
• .pos: Absolute time in [us] of the start of the waveform
• .ampscale: A factor that must be in range [-1.0,1.0] that is multiplied with .amp to yield a per-instance (i.e. per-placement) amplitude. For KS_RF objects this will cause the flip angle to be reduced on a per-instance basis. This can be used to generate a variable flip-angle train of RF pulses using a single KS_RF object. An .ampscale of -1.0 is equivalent to adding a 180 degree RF phase shift to the RF pulse

If the rfwave.duration field in the KS_RF object is 0, ks_pg_rf() will return SUCCESS and quietly ignore placing it out. This is a part of the mechanism that setting the .duration field to 0 in cveval() should eliminate its existance in both timing calulations and in the pulse sequence generation in @pg

As ks_pg_rf() internally calls ks_pg_wave() for its KS_WAVEs, double buffering will be used for all hardware waveforms, allowing waveforms to be replaced in run-time (scan()) using ks_scan_wave2hardware()

Regardless of the order placed out in the @pg section the KS_RF object is placed, the instance number of the KS_RF is automatically sorted in time. These abstract, sorted, instance numbers are used by ks_scan_***() functions in scan() to refer to a specific instance of a KS_RF object in the sequence.

GENERAL NOTE: It is a requirement that the function in the @pg section containing all ks_pg_***() calls is also called exactly once in cveval() after the calls to the corresponding ks_eval_***() functions that design the KS_*** sequence objects. Each ks_pg_***() will throw an error if this has not been done.

When ks_pg_rf() is run in cveval() (on HOST), the field .rfpulse.activity that was first set to 0 by ks_eval_rf() is now set to PSD_APS2_ON + PSD_MPS2_ON + PSD_SCAN_ON by ks_pg_rf(). This triggers the RF functions used in ks_eval_gradrflimits() to include this KS_RF object in RF scaling and SAR calculations. Each time ks_pg_rf() is called, the field .rfpulse.num is incremented after being first set to 0 by ks_eval_rf(). Hence, it is crucial that the sequence generating function (c.f. KS_SEQ_CONTROL) containing all ks_pg_***() calls is executed between the ks_eval_rf() setup call and the call to ks_eval_gradrflimits()

Parameters

[in,out]	rf	Pointer to a KS_RF sequence object
[in]	loc	KS_SEQLOC struct to specify when to place the KS_RF
[in,out]	ctrl	Pointer to the KS_SEQ_CONTROL struct corresponding to the sequence module for this KS_RF

Return values

STATUS

SUCCESS or FAILURE

                                                                {

  /* input validation */
  if (rf == NULL) {
    return ks_error("%s: First argument is NULL", __FUNCTION__);
  }

  /* duration of 0 should not throw an error as this is a sign of that it has not been set up
     or has manually been disabled this way */
  if (rf->rfwave.duration == 0) {
    return SUCCESS;
  }
  if (rf->rfwave.description == NULL || rf->rfwave.description[0] == 0 || rf->rfwave.description[0] == ' ') {
    return ks_error("ks_pg_rf: Invalid description ('%s')", rf->rfwave.description);
  }

#ifdef IPG
  /* TGT: Don't place anything on hardware if ctrl->duration = 0.
     This is in concert with:
     - not performing createseq() in KS_SEQLENGTH if seqctrl.duration = 0
     - not playing sequence modules in scan() using ks_scan_playsequence() if seqctrl.duration = 0
     */
  if (ctrl->duration == 0) {
    return ks_error("%s(%s): Refusing to place RF since seqctrl.duration = 0 (indicating `%s` not to be played in scan())", __FUNCTION__, rf->rfwave.description, ctrl->description);
  }
  /* TGT: make sure (the RF pulses in) the sequence module were a part of the seqcollection when GEReq_eval_rfscaling() was called */
  if (ctrl->rfscalingdone == FALSE && ctrl->duration > 0) {
    return ks_error("%s(%s): Missing RF scaling for sequence module with non-zero duration. Add `%s` to seqcollection *before* calling GEReq_eval_rfscaling(seqcollection)", __FUNCTION__, rf->rfwave.description, ctrl->description);
  }

  if (!ctrl->gradrf.is_cleared_on_tgt) /* Reset gradrfctrl on tgt to remove dead pointers copied from host. */
  {
    ks_tgt_reset_gradrfctrl(&ctrl->gradrf);
  }

#endif

  loc.pos = RUP_RF(loc.pos);

  RFEnvelopeWaveformGeneratorCheck(rf->rfwave.description, (WF_PROCESSOR) ks_rhoboard);

  if (rf->omegawave.res) {
    if (rf->omegawave.duration != rf->rfwave.duration) {
      ks_error("ks_pg_rf (%s): The duration of the omega waveform must be equal to the RF duration", rf->rfwave.description);
      return FAILURE;
    }
  }
  if (rf->thetawave.res) {
    if (rf->thetawave.duration != rf->rfwave.duration) {
      ks_error("ks_pg_rf (%s): The duration of the theta waveform must be equal to the RF duration", rf->rfwave.description);
      return FAILURE;
    }
  }

  /* Set ctrl->momentstart if this is an excitation pulse */
  if (rf->role == KS_RF_ROLE_EXC) {
    ctrl->momentstart = RUP_GRD(loc.pos + rf->start2iso); /* RUP_GRD: make sure it is on a 4us raster too for gradient timing calcs */
  }

  /* register this KS_RF for later heating calculations - and do this *before* calls to ks_pg_wave() below (in this function) to avoid double registrations (c.f. ks_eval_addwavetogradrfctrl()).
     N.B.: While RF/sar calcs (ks_eval_rfscaling()) are not affected by this, registering the rf->rfwave both as a part of the RF object and as a separate wave in ctrl->gradrf would otherwise lead to problems for
     ks_gnuplot_seqmodule(). This would cause the RF pulse to show up twice in the plot / pdf / image.
     ks_eval_addwavetogradrfctrl() is called in ks_pg_wave() and checks if this wave also belongs to a parent registered RF pulse in which case the wave will not be registered again */
  {
    STATUS status = ks_eval_addrftogradrfctrl(&ctrl->gradrf, rf);
    if (status != SUCCESS) return status;
  }

#ifdef HOST_TGT

  /* update rfpulse.num counter on host only. We can use this ninst variable as info
     for RF heating calculations */
  rf->rfpulse.num++;

  /* now that we have shown that we are really going to use this pulse, set its
     activity flag to SCAN, APS2, MPS2 */
  rf->rfpulse.activity = PSD_APS2_ON + PSD_MPS2_ON + PSD_SCAN_ON;

#else

  if (areSame(rf->rfpulse.num, 0)) {
    ks_error("ks_pg_rf @tgt(%s): pulsegen was never run on HOST (rf->rfpulse.num = 0)", rf->rfwave.description);
    return FAILURE;
  }

  if (rf->rfpulse.activity == 0) {
    ks_error("ks_pg_rf @tgt(%s): RF pulse with zero activity", rf->rfwave.description);
    return FAILURE;
  }

  /* The values in rf->rfwave.waveform[] are relative (unit-less). The actual amplitude of the RF wave
     is only controlled by rf->amp (which in turn is set by GE's setScale() and indirectly by peakB1()).
     Prepare RF waveform with correct amplitude on TGT side that can be used with ks_pg_wave() to give the right
     RF amplitude, after we have done RF scaling on HOST and hence have a final value for rf->amp.
     The units of this RF waveform, before and after calling ks_wave_multiplywal(), are relative (not [G])
     due to GE's RF scaling process involving e.g. xmtaddScan.
     Look in GERequired.e:GEReq_eval_gradrflimits() for more info on how peakB1() and setScale() are used. */

  ks_wave_multiplyval(&rf->rfwave, rf->amp / ks_wave_absmax(&rf->rfwave));

#endif



  /* place the RF wave */
  loc.board = RHO;
  if (ks_pg_wave(&rf->rfwave, loc, ctrl) == FAILURE)
    return FAILURE;

#ifdef IPG
  /* add SSP RF bits that handles the frequency control and blanking/unblanking the receiver */
  addrfbits(&rf->rfwave.wfpulse[RHO][KS_WF_MAIN], 0, loc.pos + psd_rf_wait, rf->rfwave.duration);
  /* set RF frequency offset */
  setfrequency((int)(rf->cf_offset / TARDIS_FREQ_RES), &rf->rfwave.wfpulse[RHO][KS_WF_MAIN], INSTRALL);
#endif

  /* set ampscale to 1. If you want to scale the omega or theata board, do it seperatly */
  loc.ampscale = 1;

  /* place the OMEGA wave */
  loc.board = OMEGA;
  if (rf->omegawave.res) {
    if (ks_pg_wave(&rf->omegawave, loc, ctrl) == FAILURE)
      return FAILURE;
  }

#ifdef IPG
  if (rf->omegawave.res) {
    /* add SSP RF bits that handles the frequency control and blanking/unblanking the receiver */
    addrfbits(&rf->omegawave.wfpulse[OMEGA][KS_WF_MAIN], 0, loc.pos + psd_rf_wait, rf->omegawave.duration);
  }
#endif

  /* place the THETA wave */
  loc.board = THETA;
  if (rf->thetawave.res) {
    if (ks_pg_wave(&rf->thetawave, loc, ctrl) == FAILURE)
      return FAILURE;
  }

#ifdef IPG
  if (rf->thetawave.res) {
    /* add SSP RF bits that handles the frequency control and blanking/unblanking the receiver */
    addrfbits(&rf->thetawave.wfpulse[THETA][KS_WF_MAIN], 0, loc.pos + psd_rf_wait, rf->thetawave.duration);
  }
#endif

  return SUCCESS;

} /* ks_pg_rf */

ks_pg_selrf()

STATUS ks_pg_selrf	(	KS_SELRF *	selrf,
		KS_SEQLOC	loc,
		KS_SEQ_CONTROL *	ctrl
	)

Places a KS_SELRF sequence object on a gradient (and RF) board at some position in the pulse sequence

This function should be called in the @pg section to place out a KS_SELRF sequence object that creates an RF pulse with associated trapezoids in the pulse sequence. The same KS_SELRF object can be placed out as many times as desired, by only changing the second argument each time (to avoid waveform overlaps). The second argument is a KS_SEQLOC struct with three fields:

• .board: Choose between XGRAD, YGRAD, ZGRAD for the board on which .pregrad, .grad (or .gradwave) and .postgrad should be placed
• .pos: Absolute time in [us] of the start of the .pregrad attack ramp. If .pregrad has zero duration, .pos will in effect refer to the start of the .grad attack ramp
• .ampscale: A factor that must be in range [-1.0,1.0] that is multiplied with rf.rfwave.amp to yield a per-instance (i.e. per-placement) amplitude. For KS_SELRF objects the .ampscale value will be passed on its internal call to ks_pg_rf(), but not to its internal ks_pg_trap() calls. Hence .ampscale will have the same effect for ks_pg_selrf() as for ks_pg_rf(), with no per-instance control of the amplitude of the gradients involved. A reduced .ampscale will cause the flip angle to be reduced on a per-instance basis. This can be used to generate a variable flip-angle train of selective RF pulses using a single KS_SELRF object. An .ampscale of -1.0 is equivalent to adding a 180 degree RF phase shift to the RF pulse

If the .gradwave field has a non-zero resolution, ks_pg_selrf() will place out the .gradwave (KS_WAVE) instead of the .grad (KS_TRAP) during the time the RF pulse is played out. An error is thrown if .gradwave.duration (if .gradwave.res > 0) is not equal to the .rf.rfwave.duration. If .pregrad or .postgrad has zero duration, they will not be placed out. The existance of non-zero .pregrad and .postgrad is determined by ks_eval_selrf() based on .rf.role

As ks_pg_selrf() internally calls ks_pg_wave() for its KS_WAVEs, hardware double buffering will be used for all waveforms, allowing waveforms to be replaced in run-time (scan()) using ks_scan_wave2hardware()

Regardless of the order placed out in the @pg section the KS_SELRF object is placed, the instance number of the KS_SELRF is automatically sorted in time. These abstract, sorted, instance numbers are used by ks_scan_***() functions in scan() to refer to a specific instance of a KS_SELRF object in the sequence.

GENERAL NOTE: It is a requirement that the function in the @pg section containing all ks_pg_***() calls is also called exactly once in cveval() after the calls to the corresponding ks_eval_***() functions that design the KS_*** sequence objects. Each ks_pg_***() will throw an error if this has not been done.

Parameters

[in,out]	selrf	Pointer to a KS_SELRF sequence object
[in]	loc	KS_SEQLOC struct to specify when and where to place the KS_SELRF
[in,out]	ctrl	Pointer to the KS_SEQ_CONTROL struct corresponding to the sequence module for this KS_SELRF

Return values

STATUS

SUCCESS or FAILURE

                                                                         {
  KS_SEQLOC rfloc;
  KS_SEQLOC gradloc;

  if (loc.board != XGRAD && loc.board != YGRAD && loc.board != ZGRAD) {
    return ks_error("%s(%s): loc.board (2nd arg) must be a gradient board", __FUNCTION__, selrf->rf.rfwave.description);
  }

  gradloc = loc; gradloc.ampscale = 1.0;
  rfloc = loc; rfloc.board = RHO;

  /* RF starts after the preselgrad (if present) */
  rfloc.pos += selrf->pregrad.duration;

  /* delay the RF pulse start by the ramptime of the slice sel gradient
     when .gradwave is used, .grad.ramptime will be correctly zero  */
  rfloc.pos += selrf->grad.ramptime;


  /************* generate the RF (incl. optional THETA & OMEGA) *************/

  if (ks_pg_rf(&selrf->rf, rfloc, ctrl) == FAILURE)
    return FAILURE;

  /************************ place gradients *********************************/

  gradloc.ampscale = (selrf->rf.role != KS_RF_ROLE_EXC) ? loc.ampscale2 : 1.0;
  /* Pre-slice sel gradient. Roles: e.g. left crusher or dephasing gradient in bSSFP */
  if (ks_pg_trap(&selrf->pregrad, gradloc, ctrl) == FAILURE)
    return FAILURE;
  gradloc.pos += selrf->pregrad.duration;



  /* slice select gradient */
  gradloc.ampscale = 1.0;
  
  if (selrf->gradwave.res) {
    /* use gradwave (not trapezoid) */

    if (selrf->rf.rfwave.duration != (selrf->gradwave.duration) || (selrf->gradwave.res * GRAD_UPDATE_TIME != selrf->gradwave.duration)) {
      return ks_error("%s(%s): The duration of 'gradwave' (%d [us]) must equal the RF duration (%d [us])", __FUNCTION__,
                      selrf->rf.rfwave.description, selrf->gradwave.duration, selrf->rf.rfwave.duration);
    }

    if (ks_pg_wave(&selrf->gradwave, gradloc, ctrl) == FAILURE)
      return FAILURE;

    gradloc.pos += selrf->gradwave.duration;

  } else {
    /* use trapezoid (not gradwave) */

    if (selrf->grad.plateautime != selrf->rf.rfwave.duration) {
      return ks_error("%s(%s): Plateau time of slice select (%d) != RF duration (%d)", __FUNCTION__, selrf->rf.rfwave.description, selrf->grad.plateautime, selrf->rf.rfwave.duration);
    } else {
      if (ks_pg_trap(&selrf->grad, gradloc, ctrl) == FAILURE)
        return FAILURE;

      gradloc.pos += selrf->grad.duration;
    }

  } /* slice select */


  /* post-slice sel gradient. Roles: e.g. right crusher or refocusing gradient */
  gradloc.ampscale = (selrf->rf.role != KS_RF_ROLE_EXC) ? loc.ampscale2 : 1.0;
  if (ks_pg_trap(&selrf->postgrad, gradloc, ctrl) == FAILURE)
    return FAILURE;
  gradloc.pos += selrf->postgrad.duration;


  return SUCCESS;

} /* ks_pg_selrf */

ks_pg_wait()

STATUS ks_pg_wait	(	KS_WAIT *	wait,
		KS_SEQLOC	loc,
		KS_SEQ_CONTROL *	ctrl
	)

Places a KS_WAIT sequence object on all boards at some position in the pulse sequence

This function should be called in the @pg section to place out a KS_WAIT sequence object that creates a wait pulse. The same KS_WAIT object can be placed out as many times as desired, by only changing the second argument each time (to avoid waveform overlaps). The second argument is a KS_SEQLOC struct with three fields:

• .board: Ignored
• .pos: Absolute time in [us] of the start of the wait pulse
• .ampscale: Ignored

This function will insert a deadtime of duration equal to the .duration field in the KS_WAIT object at position .pos. This delay can be changed in run-time by calling ks_scan_wait().

GENERAL NOTE: It is a requirement that the function in the @pg section containing all ks_pg_***() calls is also called exactly once in cveval() after the calls to the corresponding ks_eval_***() functions that design the KS_*** sequence objects. Each ks_pg_***() will throw an error if this has not been done.

Parameters

[in,out]	wait	Pointer to a KS_WAIT sequence object
[in]	loc	KS_SEQLOC struct to specify when and where to place the KS_WAIT
[in,out]	ctrl	Pointer to the KS_SEQ_CONTROL struct corresponding to the sequence module for this KS_WAIT

Return values

STATUS

SUCCESS or FAILURE

                                                                      {
  int i;
  const int first = loc.board == KS_ALL ? XGRAD : loc.board;
  const int last = loc.board == KS_ALL ? SSP : loc.board;

  /* checking for NULL pointers */
  if (wait == NULL) {
    return ks_error("ks_pg_wait: First argument is NULL");
  }

  /* duration of 0 should not throw an error as this is a sign of that it has not been set up
     or has manually been disabled this way */
  if (wait->duration == 0) {
    return SUCCESS;
  }

  if (wait->description == NULL || wait->description[0] == 0 || wait->description[0] == ' ') {
    return ks_error("ks_pg_wait: Invalid description ('%s')", wait->description);
  }

  /* disallow EPI dual boards */
  if (loc.board >= KS_FREQX_PHASEY && loc.board <= KS_XYZ) {
    return ks_error("ks_pg_wait(%s): Invalid board selection: %d", wait->description, loc.board);
  }

  loc.pos = RUP_GRD(loc.pos);


#ifdef IPG
  {

    /* TGT: Don't place anything on hardware if ctrl->duration = 0.
       This is in concert with:
       - not performing createseq() in KS_SEQLENGTH if seqctrl.duration = 0
       - not playing sequence modules in scan() using ks_scan_playsequence() if seqctrl.duration = 0
       */
    if (ctrl->duration == 0) {
      ks_dbg("%s(%s): Refusing to place wait pulse since seqctrl.duration = 0 (indicating `%s` not to be played in scan())", __FUNCTION__, wait->description, ctrl->description);
      return SUCCESS;
    }

    if (wait->base.ngenerated >= wait->base.ninst) {
      return ks_error("ks_pg_wait @tgt(%s): the number of instances generated on the target exceed the number of ones generated on the host", wait->description);
    }

    if (wait->wfpulse == NULL) {
      WF_PULSE wfInit = INITPULSE;

      const char boardc[9] = "xyzrrtos";
      char tmpstr[KS_DESCRIPTION_LENGTH + 4];
      tmpstr[KS_DESCRIPTION_LENGTH + 4 - 1] = 0;

      wait->wfpulse = (WF_PULSE *) AllocNode(8 * sizeof(WF_PULSE));
      for (i = XGRAD; i <= SSP; i++) {
        if (i != RHO2){
          /* init pulse structure */
          wait->wfpulse[i] = wfInit;

          /* Name for WF_PULSEs */
          sprintf(tmpstr, "%s.w%c", wait->description, boardc[i]); pulsename(&(wait->wfpulse[i]), tmpstr);
          createconst(&(wait->wfpulse[i]), (WF_PROCESSOR) i, wait->duration, 0);

        } /* per board */
      }

    } /* wfpulse == NULL */

    if (!wait->wfi) {
      wait->wfi = (KS_WFINSTANCE *) AllocNode(wait->base.ninst * sizeof(KS_WAIT));
    }

    for (i = first; i <= last; ++i) {
      if (i == KS_RHO2) continue; /* skip RHO2 */
      
      loc.board = i;
      int isrf = loc.board == RHO || loc.board == RHO2 || loc.board == THETA || loc.board == OMEGA;
      int isssp = loc.board == SSP;

      createinstr(&(wait->wfpulse[i]), loc.pos + (isrf * psd_rf_wait) + (isssp * psd_grd_wait), wait->duration, 0);
      wait->wfi[wait->base.ngenerated].boardinstance = wait->wfpulse[i].ninsts - 1; /* zero based */
      wait->wfi[wait->base.ngenerated].wf = &(wait->wfpulse[i]);
      wait->wfi[wait->base.ngenerated].loc = loc;
      wait->base.ngenerated++;
    }

    /* sort after the last instance is generated */
    if (wait->base.ngenerated == wait->base.ninst) {
      ks_sort_wfi_by_timeboard(wait->wfi, wait->base.ninst);
    }
  }
#else
  {
    for (i = first; i <= last; ++i) {
      if (i == KS_RHO2) continue; /* skip RHO2 */
      loc.board = i;
      wait->locs[wait->base.ninst] = loc;
      wait->base.ninst++;
    }
  }
#endif

  return SUCCESS;

} /* ks_pg_wait */

ks_pg_isirot()

STATUS ks_pg_isirot	(	KS_ISIROT *	isirot,
		SCAN_INFO	scan_info,
		int	pos,
		void(*)()	rotfun,
		KS_SEQ_CONTROL *	ctrl
	)

Places out an intersequence interrupt at a specific time in the sequence module

This function connects the execution of a psd-specific rotation function in realtime when time passes this point in the sequence. This is done by two KS_WAIT pulses (being part of KS_ISIROT) on the SSP board.

Example of use in a myseqmodule_pg() function of the sequence module (in pulsegen()):

// add some padding time before the SSP pulses (not well tested how much of KS_ISI_predelay that is necessary)
mypos += RUP_GRD(KS_ISI_predelay);

status = ks_pg_isirot(&myisirot, myscaninfo, mypos, myisirotatefun, myseqctrl);
if (status != SUCCESS) return status;

// add some padding time after the SSP pulses (not well tested how much of KS_ISI_postdelay that is necessary)
mypos += RUP_GRD(myisirot.duration + KS_ISI_postdelay);

where the psd-specific rotation function is declared as:

// Intra sequence interrupts placed as WAIT pulses on the SSP board may be used to call for an immediate
// rotation of the logical coordinate system in real time as these WAIT pulses are played out, as
// opposed to during the SSI time for the sequence module.
// The WAIT pulse is assigned a control number (isi number) that is then connected to this void function
// using `isivector()` in ks_pg_isirot(). No input arguments can be passed to this function. Instead the
// rotation information specific to the sequence module is provided in `myscaninfo.oprot`. The acutal
// rotation work, incl. keeping track of number of isi pulses played out is done by ks_scan_isirotate().
void myisirotatefun() {

#ifdef IPG
  ks_scan_isirotate(&myisirot);
#endif

}

Note that the only difference between the psd-specific myisirotatefun() and the general ks_scan_isirotate() is that myisirotatefun() has no input arguments. Input arguments cannot be used as it is called from an interrupt routine, not from some other parent function.

Care must be taken when mixing the use of ks_scan_rotate() (executing during the SSI time) and these ISI interrupts, so that they are executed in the correct order. One way is to consistently avoid the use of ks_scan_rotate() and instead return to the prescribed slice rotation by calling ks_pg_isirot() again, last in the same myseqmodule_pg() function, this time using the prescribed scan_info struct:

status = ks_pg_isirot(&myisirot, ks_scan_info[0], mypos, myisirotatefun, myseqctrl);
if (status != SUCCESS) return status;

Parameters

[in,out]	isirot	Pointer to a KS_ISIROT sequence object
[in]	scan_info	SCAN_INFO struct holding an .oprot matrix to be used for real-time rotation
[in]	pos	Absolute position in [us] in the pulse sequence when this rotation should occur
[in]	rotfun	Function pointer to the psd-specific rotation function
[in,out]	ctrl	Pointer to the KS_SEQ_CONTROL struct corresponding to the sequence module

Return values

STATUS

SUCCESS or FAILURE

                                                                                                             {
  KS_SEQLOC tmploc = KS_INIT_SEQLOC;

  if (! isirot->duration) {
    /* must have called ks_eval_isirot() first */
    return SUCCESS;
  }

  if (rotfun == NULL)
    return ks_error("%s: 4th arg (rotfun) cannot be NULL", __FUNCTION__);


  /* Set the ctrl_word to binary match the isi vector interupt number */
  /* /--------------------------------------------------------------\ */
  /* | interupt number | ctrl_word                                  | */
  /* |--------------------------------------------------------------| */
  /* | 4               | PSD_ISI2_BIT                               | */
  /* | 5               | PSD_ISI0_BIT + PSD_ISI2_BIT                | */
  /* | 6               | PSD_ISI1_BIT + PSD_ISI2_BIT                | */
  /* | 7               | PSD_ISI0_BIT + PSD_ISI1_BIT + PSD_ISI2_BIT | */
  /* \--------------------------------------------------------------/ */

  tmploc.board = SSP;
  tmploc.pos = RUP_GRD(pos);

  if (ks_pg_wait(&isirot->waitfun, tmploc, ctrl) == FAILURE)
    return FAILURE;

  tmploc.pos += RUP_GRD(isirot->waitfun.duration);

  if (ks_pg_wait(&isirot->waitrot, tmploc, ctrl) == FAILURE)
    return FAILURE;


#ifdef IPG
  {
    long ctrl_word = 0;
    int placementindx = isirot->waitfun.base.ngenerated - 1;

    /* SSP ISI number */
    getctrl(&ctrl_word, &isirot->waitfun.wfpulse[SSP], isirot->waitfun.wfpulse[SSP].ninsts - 1);

    if (isirot->isinumber == 4)
      ctrl_word  = ctrl_word | PSD_ISI2_BIT;
    else if (isirot->isinumber == 5)
      ctrl_word  = ctrl_word | PSD_ISI0_BIT | PSD_ISI2_BIT;
    else if (isirot->isinumber == 6)
      ctrl_word  = ctrl_word | PSD_ISI1_BIT | PSD_ISI2_BIT;
    else if (isirot->isinumber == 7)
      ctrl_word  = ctrl_word | PSD_ISI0_BIT | PSD_ISI1_BIT | PSD_ISI2_BIT;

    setctrl(ctrl_word, &isirot->waitfun.wfpulse[SSP], isirot->waitfun.wfpulse[SSP].ninsts - 1);

    /* SSP Rotation */
    getctrl(&ctrl_word, &isirot->waitrot.wfpulse[SSP], isirot->waitrot.wfpulse[SSP].ninsts - 1);
    ctrl_word |= PSD_MTX_UPDT;
    setctrl(ctrl_word, &isirot->waitrot.wfpulse[SSP], isirot->waitrot.wfpulse[SSP].ninsts - 1);

    /* Allocate memory for scan info array */
    if (isirot->scan_info == NULL) {
      isirot->scan_info = (SCAN_INFO *) AllocNode(isirot->numinstances * sizeof(SCAN_INFO));
    }

    /* Store the scan info for current ISI, where scan_info.oprot contains the rotation matrix */
    isirot->scan_info[placementindx] = scan_info;

    /* Reset num ISI and counter */
    isirot->counter = 0; /* make sure it is zero before scan starts */

    /* Connect ths isi number with the function pointer */
    isivector((short) isirot->isinumber, rotfun, (short) FALSE);

  }
#else

  if (0) { /* make sure the WAIT pulses have been placed out in temporal order */
    int i;
    int lastpos = -1;
    WF_INSTR_HDR *instr = isirot->waitfun.wfpulse[SSP].inst_hdr_tail;
    for (i = 0; i < (isirot->waitfun.base.ninst - 1); i++) {
      if (lastpos > instr->start) {
        return ks_error("%s: Must place the ISI pulses in temporal order", __FUNCTION__);
      } else {
        lastpos = instr->start;
        instr = instr->next;
      }
    }
  }

  /* copy for convenience */
  isirot->numinstances = isirot->waitfun.base.ninst;

#endif

    return SUCCESS;

} /* ks_pg_isirot() */

ks_pg_epi_dephasers()

STATUS ks_pg_epi_dephasers	(	KS_EPI *	epi,
		KS_SEQLOC	loc,
		KS_SEQ_CONTROL *	ctrl
	)

Places out the dephasing gradients of a KS_EPI object (used by ks_pg_epi())

This function is called internally by ks_pg_epi() to place out the dephasing gradients of a KS_EPI object. See ks_pg_epi() for more details

For advanced usage of KS_EPI, it is possible to call ks_pg_epi_dephaser(), ks_pg_epi_echo() and ks_pg_epi_rephasers() separately instead of the single call to ks_pg_epi(). This allows the dephasing and rephasing gradients to be detached from the core EPI readout part

Parameters

[in,out]	epi	Pointer to a KS_EPI sequence object
[in]	loc	KS_SEQLOC struct to specify when and where to place the dephasers of the KS_EPI object
[in]	ctrl	Pointer to the KS_SEQ_CONTROL struct corresponding to the sequence module for this KS_EPI

Return values

STATUS

SUCCESS or FAILURE

                                                                             {
  int readaxis, blipaxis, sliceaxis;
  KS_SEQLOC tmploc = KS_INIT_SEQLOC;
  int maxduration;

  if (!epi) { return FAILURE; }

  /* loc.ampscale may only be +1 or -1 and will control the read polarity.
   The blip polarity is controlled in run time with ks_scan_epi_shotcontrol() */
  if (!areSame(loc.ampscale, 1.0) && !areSame(loc.ampscale, -1.0)) {
    return ks_error("ks_pg_epi_dephasers: loc.ampscale must be +1 or -1 (controls read polarity)");
  }

  loc.pos = RDN_GRD(loc.pos);

  switch (loc.board) {
  case KS_FREQX_PHASEY:
    readaxis = XGRAD; blipaxis = YGRAD; sliceaxis = ZGRAD; break;
  case KS_FREQY_PHASEX:
    readaxis = YGRAD; blipaxis = XGRAD; sliceaxis = ZGRAD; break;
  case KS_FREQX_PHASEZ:
    readaxis = XGRAD; blipaxis = ZGRAD; sliceaxis = YGRAD; break;
  case KS_FREQZ_PHASEX:
    readaxis = ZGRAD; blipaxis = XGRAD; sliceaxis = YGRAD; break;
  case KS_FREQY_PHASEZ:
    readaxis = YGRAD; blipaxis = ZGRAD; sliceaxis = XGRAD; break;
  case KS_FREQZ_PHASEY:
    readaxis = ZGRAD; blipaxis = YGRAD; sliceaxis = XGRAD; break;
  default:
    ks_error("ks_pg_epi_dephasers: loc.board is not valid: %d", loc.board);
    return FAILURE;
  }

  /* allocate time corresponding to the longest of the three, but push the dephasers to the right below */
  maxduration = IMax(3, epi->readphaser.duration, epi->blipphaser.grad.duration, epi->zphaser.grad.duration);

  /* read phaser (same KS_TRAP for DE/REphasing => 2 instances per EPI) */
  if (epi->readphaser.duration > 0) {
    tmploc.board = readaxis;
    tmploc.ampscale = loc.ampscale;
    tmploc.pos = loc.pos + maxduration - epi->readphaser.duration;
    if (ks_pg_trap(&epi->readphaser, tmploc, ctrl) == FAILURE)
      return FAILURE;
  }

  /* blip phaser (same KS_PHASER for DE/REphasing => 2 instances per EPI) */
  if (epi->blipphaser.grad.duration > 0) {
    tmploc.board = blipaxis;
    tmploc.ampscale = 1.0;
    tmploc.pos = loc.pos + maxduration - epi->blipphaser.grad.duration;
    if (ks_pg_phaser(&epi->blipphaser, tmploc, ctrl) == FAILURE)
      return FAILURE;
  }

  /* slice phaser (same KS_PHASER for DE/REphasing => 2 instances per EPI) */
  if (epi->zphaser.grad.duration > 0) {
    tmploc.board = sliceaxis;
    tmploc.ampscale = 1.0;
    tmploc.pos = loc.pos + maxduration - epi->zphaser.grad.duration;
    if (ks_pg_phaser(&epi->zphaser, tmploc, ctrl) == FAILURE)
      return FAILURE;
  }

  return SUCCESS;
} /* ks_pg_epi_dephasers */

ks_pg_epi_rephasers()

STATUS ks_pg_epi_rephasers	(	KS_EPI *	epi,
		KS_SEQLOC	loc,
		KS_SEQ_CONTROL *	ctrl
	)

Places out the rephasing gradients of a KS_EPI object (used by ks_pg_epi())

This function is called internally by ks_pg_epi() to place out the rephasing gradients of a KS_EPI object. See ks_pg_epi() for more details

For advanced usage of KS_EPI, it is possible to call ks_pg_epi_dephaser(), ks_pg_epi_echo() and ks_pg_epi_rephasers() separately instead of the single call to ks_pg_epi(). This allows the dephasing and rephasing gradients to be detached from the core EPI readout part

Parameters

[in,out]	epi	Pointer to a KS_EPI sequence object
[in]	loc	KS_SEQLOC struct to specify when to place the rephasers of the KS_EPI object
[in]	ctrl	Pointer to the KS_SEQ_CONTROL struct corresponding to the sequence module for this KS_EPI

Return values

STATUS

SUCCESS or FAILURE

                                                                             {
  int readaxis, blipaxis, sliceaxis;
  KS_SEQLOC tmploc = KS_INIT_SEQLOC;

  if (!epi) { return FAILURE; }

  /* loc.ampscale may only be +1 or -1 and will control the read polarity.
    The blip polarity is controlled in run time with ks_scan_epi_shotcontrol() */
  if (!areSame(loc.ampscale, 1.0) && !areSame(loc.ampscale, -1.0)) {
    return ks_error("ks_pg_epi_rephasers: loc.ampscale must be +1 or -1 (controls read polarity)");
  }

  loc.pos = RDN_GRD(loc.pos);

  switch (loc.board) {
  case KS_FREQX_PHASEY:
    readaxis = XGRAD; blipaxis = YGRAD; sliceaxis = ZGRAD; break;
  case KS_FREQY_PHASEX:
    readaxis = YGRAD; blipaxis = XGRAD; sliceaxis = ZGRAD; break;
  case KS_FREQX_PHASEZ:
    readaxis = XGRAD; blipaxis = ZGRAD; sliceaxis = YGRAD; break;
  case KS_FREQZ_PHASEX:
    readaxis = ZGRAD; blipaxis = XGRAD; sliceaxis = YGRAD; break;
  case KS_FREQY_PHASEZ:
    readaxis = YGRAD; blipaxis = ZGRAD; sliceaxis = XGRAD; break;
  case KS_FREQZ_PHASEY:
    readaxis = ZGRAD; blipaxis = YGRAD; sliceaxis = XGRAD; break;
  default:
    ks_error("ks_pg_epi_rephasers: loc.board is not valid: %d", loc.board);
    return FAILURE;
  }

  /* read phaser (same KS_TRAP for DE/REphasing => 2 instances per EPI) */
  if (epi->readphaser.duration > 0) {
    tmploc.board = readaxis;
    tmploc.pos = loc.pos;
    if (epi->etl % 2) /* same polarity of rephaser as dephaser if odd ETL */
      tmploc.ampscale = loc.ampscale;
    else
      tmploc.ampscale = -loc.ampscale;
    if (ks_pg_trap(&epi->readphaser, tmploc, ctrl) == FAILURE)
      return FAILURE;
  }

  /* blip phaser (same KS_PHASER for DE/REphasing => 2 instances per EPI) */
  if (epi->blipphaser.grad.duration > 0) {
    tmploc.board = blipaxis;
    tmploc.pos = loc.pos;
    tmploc.ampscale = 1.0;
    if (ks_pg_phaser(&epi->blipphaser, tmploc, ctrl) == FAILURE)
      return FAILURE;
  }

  /* slice phaser (same KS_PHASER for DE/REphasing => 2 instances per EPI) */
  if (epi->zphaser.grad.duration > 0) {
    tmploc.board = sliceaxis;
    tmploc.pos = loc.pos;
    tmploc.ampscale = 1.0;
    if (ks_pg_phaser(&epi->zphaser, tmploc, ctrl) == FAILURE)
      return FAILURE;
  }

  return SUCCESS;
} /* ks_pg_epi_rephasers */

ks_pg_epi_echo()

STATUS ks_pg_epi_echo	(	KS_EPI *	epi,
		KS_SEQLOC	loc,
		KS_SEQ_CONTROL *	ctrl
	)

Places out the core part a KS_EPI object (used by ks_pg_epi())

This function is called internally by ks_pg_epi() to place out the core part of a KS_EPI object. The core part is the EPI train without leading dephaser gradients or trailing rephaser gradients. See ks_pg_epi() for more details

For advanced usage of KS_EPI, it is possible to call ks_pg_epi_dephaser(), ks_pg_epi_echo() and ks_pg_epi_rephasers() separately instead of the single call to ks_pg_epi(). This allows the dephasing and rephasing gradients to be detached from the core EPI readout part

Parameters

[in,out]	epi	Pointer to a KS_EPI sequence object
[in]	loc	KS_SEQLOC struct to specify when to place the core part of the KS_EPI object
[in]	ctrl	Pointer to the KS_SEQ_CONTROL struct corresponding to the sequence module for this KS_EPI

Return values

STATUS

SUCCESS or FAILURE

                                                                        {
  int readaxis, blipaxis;
  KS_SEQLOC readloc, bliploc;
  int i;

  if (!epi || !epi->read.grad.description) { return FAILURE; }

  /* loc.ampscale may only be +1 or -1 and will control the read polarity.</
     The blip polarity is controlled in run time with ks_scan_epi_shotcontrol() */
  if (!areSame(loc.ampscale, 1.0) && !areSame(loc.ampscale, -1.0)) {
    return ks_error("ks_pg_epi_echo: loc.ampscale must be +1 or -1 (controls read polarity)");
  }

  loc.pos = RUP_GRD(loc.pos);

  readloc.pos = loc.pos;

  switch (loc.board) {
  case KS_FREQX_PHASEY:
    readaxis = XGRAD; blipaxis = YGRAD; break;
  case KS_FREQY_PHASEX:
    readaxis = YGRAD; blipaxis = XGRAD; break;
  case KS_FREQX_PHASEZ:
    readaxis = XGRAD; blipaxis = ZGRAD; break;
  case KS_FREQZ_PHASEX:
    readaxis = ZGRAD; blipaxis = XGRAD; break;
  case KS_FREQY_PHASEZ:
    readaxis = YGRAD; blipaxis = ZGRAD; break;
  case KS_FREQZ_PHASEY:
    readaxis = ZGRAD; blipaxis = YGRAD; break;
  default:
    ks_error("ks_pg_epi_echo: field 'board' in 2nd arg is not valid: %d", loc.board);
    return FAILURE;
  }

  if (!areSame(fabs(loc.ampscale), 1.0)) {
    return ks_error("ks_pg_epi_echo: field 'ampscale' in 2nd arg must be +1 or -1 (controls read lobe polarity)");
  }


  for (i = 0; i < epi->etl; i++) {

    /* read trapezoid */
    readloc.board = readaxis;
    readloc.ampscale = (float) (i % 2) ? -loc.ampscale : loc.ampscale; /* +1 or -1 */
    if (ks_pg_readtrap(&epi->read, readloc, ctrl) == FAILURE)
      return FAILURE;

    /* phase encoding blip */
    if (i < epi->etl - 1) {
      /* etl-1, since no blip after the last read lobe */
      bliploc.board = blipaxis;
      bliploc.pos = RUP_GRD(readloc.pos + epi->read.grad.duration - epi->blip.duration / 2 + epi->read_spacing / 2);
      bliploc.ampscale = 1.0;
      if (ks_pg_trap(&epi->blip, bliploc, ctrl) == FAILURE)
        return FAILURE;
    }

    /* read_spacing is additional gap between lobes (normally 0) */
    readloc.pos += RUP_GRD(epi->read.grad.duration + epi->read_spacing);

  } /* etl */


  return SUCCESS;

} /* ks_pg_epi_echo */

ks_pg_epi()

STATUS ks_pg_epi	(	KS_EPI *	epi,
		KS_SEQLOC	loc,
		KS_SEQ_CONTROL *	ctrl
	)

Places out a KS_EPI object (EPI train including dephaser and rephaser gradients)

This function should be called in the @pg section to place out a KS_EPI sequence object that creates an EPI readout including dephaser and rephaser gradients. The moments of all trapezoids in the KS_EPI object sum to zero on the two axes the KS_EPI object is placed on. The KS_EPI object is to be placed on two out of three gradients, why special values for the field loc.board must be used. The value should state which logical board (X,Y or Z) that should be used for the readout lobes (FREQ) and which logical board (X, Y or Z) that should be used for the blips (PHASE). One example is KS_FREQX_PHASEY, which will put the EPI readout lobes on XGRAD and the phase encoding blips on YGRAD

The same KS_EPI object can be placed out 16 times per sequence. This limitation is due to the hard limitation on the number of echoes (i.e. different k-spaces per image plane and image volume) that can be acquired per scan. Each time an instance of the KS_EPI object is placed out using ks_pg_epi(), the second argument (the KS_SEQLOC struct) should be modified:

• .board: Choose between KS_FREQX_PHASEY, KS_FREQY_PHASEX, KS_FREQX_PHASEZ, KS_FREQZ_PHASEX, KS_FREQY_PHASEZ, KS_FREQZ_PHASEY
• .pos: Absolute time in [us] of the start of the first dephaser gradient
• .ampscale: For KS_EPI objects, valid values are only +1.0 and -1.0, and this will control the polarity of the first readout gradient. This is rarely needed, and 1.0 should be the standard choice as this does only affect gradient delays and Nyquist ghosting, not the geometric distortion direction.

The sign of the EPI blips will control the direction of the geometric distortions, and this is not done via .ampscale but in run-time using ks_scan_epi_shotcontrol()

For advanced usage of KS_EPI, it is possible to call ks_pg_epi_dephaser(), ks_pg_epi_echo() and ks_pg_epi_rephasers() separately instead of the single call to ks_pg_epi(). This allows the dephasing and rephasing gradients to be detached from the core EPI readout part

Parameters

[in,out]	epi	Pointer to a KS_EPI sequence object
[in]	loc	KS_SEQLOC struct to specify when to place the core part of the KS_EPI object
[in]	ctrl	Pointer to the KS_SEQ_CONTROL struct corresponding to the sequence module for this KS_EPI

Return values

STATUS

SUCCESS or FAILURE

                                                                   {
  KS_SEQLOC tmploc = loc;

  /* loc.ampscale may only be +1 or -1 and will control the read polarity.
    The blip polarity is controlled in run time with ks_scan_epi_shotcontrol() */
  if (!areSame(loc.ampscale, 1.0)  && !areSame(loc.ampscale, -1.0)) {
    return ks_error("ks_pg_epi: loc.ampscale must be +1 or -1 (controls read polarity)");
  }

  if (ks_pg_epi_dephasers(epi, tmploc, ctrl) == FAILURE)
    return FAILURE;

  tmploc.pos += IMax(3, epi->readphaser.duration, epi->blipphaser.grad.duration, epi->zphaser.grad.duration);

  if (ks_pg_epi_echo(epi, tmploc, ctrl) == FAILURE) /* main epi train (w/o DE/REphasers) */
    return FAILURE;

  tmploc.pos += epi->read.grad.duration * epi->etl;
  if (ks_pg_epi_rephasers(epi, tmploc, ctrl) == FAILURE)
    return FAILURE;

  return SUCCESS;
} /* ks_pg_epi */

ks_pg_mod_fse_rfpulse_structs()

void ks_pg_mod_fse_rfpulse_structs	(	KS_SELRF *	rf1,
		KS_SELRF *	rf2,
		KS_SELRF *	rf3,
		const double *	flip_angles,
		const int	etl
	)

                                                  {

  float SAR_scale_1 = 0.0;
  float SAR_scale_2 = 0.0;
  float SAR_scale_3 = 0.0;
  int i;

  SAR_scale_1 = pow(flip_angles[0] / rf1->rf.flip, 2.0);
  SAR_scale_2 = pow(flip_angles[1] / rf2->rf.flip, 2.0);
  for (i = 2; i < etl; i++) {
    SAR_scale_3 += pow(flip_angles[i] / rf3->rf.flip, 2.0);
  }
  SAR_scale_3 /= etl - 2;

  rf1->rf.rfpulse.effwidth *= SAR_scale_1;
  rf1->rf.rfpulse.max_rms_b1 *= sqrt(SAR_scale_1);
  rf1->rf.rfpulse.abswidth *= sqrt(SAR_scale_1);

  rf2->rf.rfpulse.effwidth *= SAR_scale_2;
  rf2->rf.rfpulse.max_rms_b1 *= sqrt(SAR_scale_2);
  rf2->rf.rfpulse.abswidth *= sqrt(SAR_scale_2);

  rf3->rf.rfpulse.effwidth *= SAR_scale_3;
  rf3->rf.rfpulse.max_rms_b1 *= sqrt(SAR_scale_3);
  rf3->rf.rfpulse.abswidth *= sqrt(SAR_scale_3);

} /* ks_pg_mod_fse_rfpulse_structs */

ks_pg_fse_flip_angle_taperoff()

STATUS ks_pg_fse_flip_angle_taperoff	(	double *	flip_angles,
		int	etl,
		double	flip1,
		double	flip2,
		double	flip3,
		double	target_flip,
		int	start_middle
	)

                                                       {

  int i;

  flip_angles[0] = flip1;
  flip_angles[1] = flip2;
  for (i = 2; i < etl; i++) {
    flip_angles[i] = flip3;
  }

  if (flip3 <= target_flip || etl < 5) {
    /* flip3 must be larger than target_flip and etl must be larger than 4 */
    return SUCCESS;
  }

  /* after half of the echo train or third pulse, ramp down flip angles to last_flip */
  double first_flip = flip3;
  double last_flip = target_flip;
  int start_pulse = start_middle ? etl/2 : 2;
  for (i = start_pulse; i < etl; i++) {
    flip_angles[i] = first_flip + (((last_flip - first_flip)/(etl - start_pulse - 1)) * (i - start_pulse));
  }

  return SUCCESS;

} /* ks_pg_fse_flip_angle_taperoff */

ks_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 se