1 /** 2 @file 3 @ingroup interface 4 @brief Front end interface structure definitions and handlers. 5 6 This header contains the front-end interface structures and handlers 7 for libbpm. They define a set of user friendly structures like 8 bpmconf_t, bpmcalib_t, beamconf_t etc... to work with the bpm data. 9 */ 10 11 /** @addtogroup interface */ 12 /** @{ */ 13 14 #ifndef BPMINTERFACE_H__ 15 #define BPMINTERFACE_H__ 16 17 /* --------------------------------------------------------------------------------------- 18 // includes 19 // ------------------------------------------------------------------------------------ */ 20 #include <stdio.h> 21 #include <stdlib.h> 22 #include <string.h> 23 #include <bpm/bpm_defs.h> 24 #include <bpm/bpm_wf.h> 25 #include <bpm/bpm_dsp.h> 26 27 /* ---------------------------------------------------------------------------------------- 28 // macro definitions 29 // ------------------------------------------------------------------------------------- */ 30 31 /* ---------------------------------------------------------------------------------------- 32 // typedefs, enums and other declarations 33 // ------------------------------------------------------------------------------------- */ 34 #ifdef __cplusplus 35 extern "C" { 36 #endif 37 38 /** 39 BPM cavity ( of better signal ) type 40 */ 41 enum bpmtype_t { 42 diode, /**< rectified bpm signal ( trigger pulse ) */ 43 monopole, /**< reference cavity signal ( monopole ) */ 44 dipole /**< position sentivive cavity signal ( dipole ) */ 45 }; 46 47 /** 48 Diode behavior type 49 */ 50 enum triggertype { 51 positive, /**< Positive half-period of the waveform is detected */ 52 negative, /**< Negative half-period of the waveform is detected */ 53 bipolar /**< The both half-periods are detected */ 54 }; 55 56 /** 57 BPM polarisation plane, basically a difficult way to say x or y ;) 58 */ 59 enum bpmpol_t { 60 horiz, /**< Horizontal plane, or x in most cases */ 61 vert /**< Vertical plane, or y in most cases */ 62 }; 63 64 /** 65 BPM electronics phase lock type 66 */ 67 enum bpmphase_t { 68 randomised, /**< unlocked phase */ 69 locked /**< locked phase */ 70 }; 71 72 73 typedef struct bpmconf bpmconf_t; /**< type definition for BPM configuration */ 74 typedef struct bpmcalib bpmcalib_t; /**< type definition for calibrations */ 75 typedef struct bpmproc bpmproc_t; /**< type definition for processed BPM signals */ 76 typedef struct beamconf beamconf_t; /**< type definition for beam configurations */ 77 typedef struct bunchconf bunchconf_t; /**< type definition for bunch configurations */ 78 typedef struct bpmmode bpmmode_t; 79 typedef struct rfmodel rfmodel_t; 80 81 typedef enum triggertype triggertype_t; 82 83 /** 84 Structure containing the BPM configuration 85 */ 86 struct bpmconf { 87 char name[20]; /**< a BPM should have a name */ 88 89 enum bpmtype_t cav_type; /**< BPM type */ 90 enum bpmpol_t cav_polarisation; /**< BPM polarisation */ 91 enum bpmphase_t cav_phasetype; /**< BPM phase type */ 92 93 rfmodel_t *cav_model; 94 double cav_length; /**< length of the cavity */ 95 double cav_freq; /**< cavity freq (MHz) */ 96 double cav_decaytime; /**< cavity decay time (microsec) */ 97 double cav_phase; /**< phase advance wrt. reference (fixed or random) */ 98 double cav_iqrotation; /**< cavity IQ rotation */ 99 double cav_chargesens; /**< charge sensitivity (volt/nC) */ 100 double cav_possens; /**< pos sensitivity at 1.6nC charge (volt/micron) */ 101 double cav_tiltsens; /**< tilt sensitivity at 1.6nC charge (volt/micron) */ 102 103 double rf_LOfreq; /**< LO frequency to mix down with (in MHz) */ 104 105 // digitisation configuration parameters 106 double digi_trigtimeoffset; /**< time (usec) to offset bunch arrival times by */ 107 double digi_freq; /**< digitization frequency (MHz) */ 108 int digi_nbits; /**< number of bits in ADC for digitisation */ 109 int digi_nsamples; /**< number of samples in ADC digitisation */ 110 double digi_ampnoise; /**< amplitude noise in ADC channels (pedestal width)*/ 111 int digi_voltageoffset; /**< voltage offset (pedestal position) in counts */ 112 double digi_phasenoise; /**< phase noise */ 113 114 115 /* ------------------- normal waveform processing parameters ----------------------- */ 116 double t0; /**< start time of pulse */ 117 118 // ddc processing configuration parameters 119 double ddc_freq; /**< Frequency of downmixed waveform (MHz) */ 120 double ddc_tdecay; /**< Decay time (usec) */ 121 double ddc_tOffset; /**< Always have offset from t0 for sampling !!! */ 122 filter_t *ddc_filter; /**< DDC 2 omega filter */ 123 124 // fit processing configuration parameters 125 double fit_inifreq; /**< Initial frequency for fitting */ 126 double fit_initdecay; /**< Initial decay time for fitting */ 127 double fit_tOffset; /**< Offset from t0 to start fitting */ 128 129 /* -------------------- caltone waveform processing parameters --------------------- */ 130 double ddc_ct_freq; /**< caltone frequency for the ddc algorithm */ 131 filter_t *ddc_ct_filter; /**< filter for the caltone ddc */ 132 int ddc_ct_iSample; /**< sample number to sample from ddc for amp/phase */ 133 134 135 /* -------------------- geometry of the BPM in the beamline ------------------------ */ 136 double geom_pos[3]; /**< position of the BPM in the beamline */ 137 double geom_tilt[3]; /**< tilt of the BPM (0: xrot, 1: yrot, 2: zrot) */ 138 139 /* --------------------- indices to use for user programs -------------------------- */ 140 int ref_idx; /**< reference cavity index for this BPM */ 141 int diode_idx; /**< reference diode index for this BPM */ 142 int forced_trigger; /**< this cavity is abused as trigger signal */ 143 144 /* ------------------------- some processing buffers ------------------------------- */ 145 doublewf_t* ddc_buffer_re; /**< pointer to a doublewf_t buffer */ 146 doublewf_t* ddc_buffer_im; /**< pointer to a doublewf_t buffer */ 147 }; 148 149 /** 150 A structure containing the calibration information : purely calibration ! 151 */ 152 struct bpmcalib { 153 // ddc calibration constants 154 double ddc_IQphase; /**< processed IQ phase for the ddc routine */ 155 double ddc_posscale; /**< processed position scale for the ddc routine */ 156 double ddc_slopescale; /**< processed slope scale for the fit routine */ 157 double ddc_ct_amp; /**< calibration tone amplitude at time of calibration */ 158 double ddc_ct_phase; /**< calibration tone phase at time of calibration */ 159 160 // fit calibration constants 161 double fit_IQphase; /**< processed IQ phase for the fit routine */ 162 double fit_posscale; /**< position scale for the fit routine */ 163 double fit_slopescale; /**< slope scale for the fit routine */ 164 double fit_ct_amp; /**< calibration tone amplitude at time of calibration */ 165 double fit_ct_phase; /**< calibration tone phase at time of calibration */ 166 }; 167 168 /** 169 A structure containing the processed waveform information 170 */ 171 struct bpmproc { 172 double ampnoise; /**< calculated (processed) amplitude noise */ 173 double voltageoffset; /**< calculated voltage offset */ 174 175 double t0; /**< trigger t0 for int, copied from bpmconf_t::t0 for ext */ 176 177 int saturated; /**< this signal was saturated */ 178 int iunsat; /**< the last unsaturated sample index */ 179 180 complexwf_t *dc; /**< The signal's DC waveform */ 181 complexwf_t *ft; /**< The signal's fourier transform */ 182 183 // FFT parameters 184 int fft_success; /**< do we have proper fft info ? */ 185 double fft_amp; /**< amplitude of fft */ 186 double fft_freq; /**< frequency obtained from fft (MHz) */ 187 double fft_tdecay; /**< decay time obtained from fft (usec) */ 188 double fft_offset; /**< offset of fft in fit */ 189 190 // DDC parameters 191 int ddc_success; /**< do we have proper ddc info ? */ 192 double ddc_tSample; /**< time at which the ddc was sampled, t0+t0Offset */ 193 int ddc_iSample; /**< index of sample at which ddc sample was taken */ 194 double ddc_Q; /**< ddc Q value */ 195 double ddc_I; /**< ddc I value */ 196 double ddc_amp; /**< downconverted amplitude */ 197 double ddc_phase; /**< downconverted phase */ 198 double ddc_tdecay; /**< downconverted decay time of waveform */ 199 200 double ddc_pos; /**< calculated position from ddc */ 201 double ddc_slope; /**< calculated slope from ddc */ 202 203 double ddc_ct_amp; /**< last measured calibration tone amplitude for this bpm */ 204 double ddc_ct_phase; /**< last measured calibration tone phase for this bpm */ 205 206 // FIT parameters 207 int fit_success; /**< do we have proper fit info ? */ 208 double fit_Q; /**< fit Q value */ 209 double fit_I; /**< fit I value */ 210 double fit_amp; /**< fitted amplitude */ 211 double fit_phase; /**< fitted phase */ 212 double fit_freq; /**< fitted frequency (MHz) */ 213 double fit_tdecay; /**< fitted decay time of waveform (usec) */ 214 double fit_offset; /**< fitted offset for waveform */ 215 216 double fit_pos; /**< calculated position from fit */ 217 double fit_slope; /**< calculated slope from fit */ 218 219 double fit_ct_amp; /**< last measured calibration tone amplitude for this bpm */ 220 double fit_ct_phase; /**< last measured calibration tone phase for this bpm */ 221 }; 222 223 /** 224 This structure contains the global beam parameters as well as 225 a pointer to the array of bunches 226 */ 227 struct beamconf { 228 int train_num; /**< seq number of the train (evt num) */ 229 230 double beamrate; /**< beam repetition rate (train to train) */ 231 double bunchrate; /**< bunch repetition rate (in the train) */ 232 int nbunches; /**< number of bunches per train */ 233 234 bunchconf_t *bunch; /**< list of pointers to the bunch conf structures */ 235 236 double position[2]; /**< beam position at the origin */ 237 double positionsigma[2]; /**< position spread at the origin */ 238 239 double slope[2]; /**< beam slope at the origin */ 240 double slopesigma[2]; /**< slope spread at the origin */ 241 242 double tilt[2]; /**< bunch tilt at the origin */ 243 double tiltsigma[2]; /**< tilt spread at the origin */ 244 245 double bunchlength; /**< bunch length at the origin */ 246 double bunchlengthsigma; /**< length spread at the origin */ 247 248 double energy; /**< beam energy (in GeV) at the origin */ 249 double energysigma; /**< beam energy spread */ 250 double charge; /**< bunch charge (in nC) */ 251 double chargesigma; /**< charge spread */ 252 }; 253 254 /** 255 This structure contains information on a single bunch inside the 256 bunchtrain, which has its own energy, internal energy spread, charge, 257 length, position/slope/tilt in the world coo frame and 258 position/slope/tilt in the BPM local coo frame. 259 */ 260 struct bunchconf { 261 int train_num; /**< seq number of the train this bunch belongs to */ 262 int bunch_num; /**< seq number of the bunch in the train */ 263 264 double energy; /**< energy of the bunch */ 265 double energyspread; /**< energy spread inside the bunch */ 266 double charge; 267 double length; /**< the bunch length */ 268 double arrival_time; /**< arrival time of bunch */ 269 double position[2]; /**< the bunch position x,y at the bpm coo */ 270 double slope[2]; /**< the bunch slope x',y' at the bpm coo */ 271 double tilt[2]; /**< the bunch tilt x',y' at the bpm coo */ 272 273 double bpmposition[3]; /**< where the beam hits the BPM in the BPM local co */ 274 double bpmslope[2]; /**< slope of beam through the BPM in BPM local co */ 275 double bpmtilt[2]; /**< bunch tilt in the BPM local co */ 276 }; 277 278 /** 279 This structure defines a BPM resonant mode which is defined by 280 it's resonant frequency, Q factor and sensitivities to the 281 beam charge, slope and bunch tilt. */ 282 struct bpmmode { 283 char name[20]; /**< The name for the BPM mode, e.g "dipolex" */ 284 double frequency; /**< The resonant frequency of the mode */ 285 double Q; /**< The Q factor for the mode */ 286 int order; /**< The mode order, 0:monopole, 1:dipole, 2:quadrupole... */ 287 enum bpmpol_t polarisation; /**< The mode polarisation: horiz, vert */ 288 double sensitivity; /**< The sensitivity of the mode, units depend on order */ 289 complexwf_t *response; /**< Pointer to the mode response buffer */ 290 doublewf_t *buffer; /**< Pointer to the mode's buffer */ 291 }; 292 293 /** 294 This structure contains the complete RF model for a BPM, which is 295 essentially a collection of it's resonant modes and sensitivities */ 296 struct rfmodel { 297 char name[20]; /**< A name for the cavity's RF model */ 298 int nmodes; /**< The number of BPM modes in the model */ 299 bpmmode_t *mode; /**< A list of pointers to the array of modes */ 300 }; 301 302 303 304 305 /* ----------------------------------------------------------------------------- 306 function prototypes and declarations 307 -------------------------------------------------------------------------- */ 308 EXTERN int bpm_verbose; /**< be a bit verbose in libbpm */ 309 EXTERN int libbpm_evtnum; /**< the global event number in the processing */ 310 311 312 #ifdef __cplusplus 313 } 314 #endif 315 316 317 #endif /* #ifndef BPMINTERFACE_H__ */ 318 /*@}*/ 319 /* ================================ end of file ============================= */ 320