path: root/src/zdab_utils.h

/* Copyright (c) 2019, Anthony Latorre <tlatorre at uchicago>
 *
 * This program is free software: you can redistribute it and/or modify it
 * under the terms of the GNU General Public License as published by the Free
 * Software Foundation, either version 3 of the License, or (at your option)
 * any later version.

 * This program is distributed in the hope that it will be useful, but WITHOUT
 * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
 * FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for
 * more details.

 * You should have received a copy of the GNU General Public License along with
 * this program. If not, see <https://www.gnu.org/licenses/>.
 */

#ifndef ZDAB_UTILS
#define ZDAB_UTILS

#include "Record_Info.h"
#include <stdint.h>
#include <stdlib.h> /* for size_t */
#include "event.h"
#include "zebra.h"

// the builder won't put out events with NHIT > 10000
// (note that these are possible due to hardware problems)
// but XSNOED can write an event with up to 10240 channels
#define MAX_NHIT 10240

#ifdef SWAP_BYTES
#define SWAP_INT32(a,b) swap_int32((int32_t *)(a),(b))
#define SWAP_INT16(a,b) swap_int16((int16_t *)(a),(b))
#else
#define SWAP_INT32(a,b)
#define SWAP_INT16(a,b)
#endif

/* Links for the MCVX bank. */
#define KMCVX_MCVXG 4
#define KMCVX_MCPM  3
#define KMCVX_MCTKI 2
#define KMCVX_MCTK  1

/* Links for the MC bank. */
#define KMC_MCNS 6
#define KMC_MCNH 5
#define KMC_MCPM 4
#define KMC_EGS4 3
#define KMC_MCVX 2
#define KMC_MCGN 1

/* Links for the EV bank. */
#define KEV_NPFA     32
#define KEV_NECL     31
#define KEV_NPA      30
#define KEV_NEMG_PAR 29
#define KEV_NEMG     28
#define KEV_NES      27
#define KEV_NESG     26
#define KEV_RSP      25
#define KEV_NECK     24
#define KEV_BUTT     23
#define KEV_ANAL     22
#define KEV_FECD     21
#define KEV_LG 	     20
#define KEV_OWL      19
#define KEV_PMT      18
#define KEV_CL 	     17
#define KEV_PIF      16
#define KEV_PIT0     15
#define KEV_PIT      14
#define KEV_PIHS     13
#define KEV_PIHL     12
#define KEV_PILX     11
#define KEV_PIN      10
#define KEV_PT0      9
#define KEV_PLX      8
#define KEV_PHS      7
#define KEV_ZDAB     6
#define KEV_PF       5
#define KEV_PN       4
#define KEV_PHL      3
#define KEV_PT       2
#define KEV_FT       1

/* Links for the MAST bank. */
#define KMAST_RLOG 25 /* Runlog data. */
#define KMAST_RLAI 24 /* Runlog analysis data. */
#define KMAST_LABL 12 /* Tape label information. */
#define KMAST_CAAC 11 /* AV Status. */
#define KMAST_CAST 10 /* Manipulator status. */
#define KMAST_SOSF 9  /* LED status. */
#define KMAST_SOSX 8  /* Manipulator source status. */
#define KMAST_TRIG 7  /* Trigger information bank. */
#define KMAST_EPED 6  /* Electronics calibration pedestal bank. */
#define KMAST_RHDR 5  /* Top level run header bank. */
#define KMAST_ANAL 4  /* Analysis top level bank. */
#define KMAST_DSML 3  /* Data structure manager log bank. */
#define KMAST_MC   2  /* Monte carlo top level bank. */
#define KMAST_EV   1  /* First event trigger bank. */

/* MAST bank data words. */
#define KMAST_SNOMAN_VER 1
#define KMAST_SNOMAN_VER_ORG 2

/* Status bits for the MC Vertex bank.
 *
 * See http://www.lip.pt/~barros/SNO/doc/snoman/companion_frames.html. */
#define KMCVX_SRC 0x00000001  /* Source */
#define KMCVX_BOU 0x00000002  /* Boundary */
#define KMCVX_INT 0x00000004  /* Interaction */
#define KMCVX_SNK 0x00000008  /* Sink */
#define KMCVX_PSC 0x00000010  /* Pre-source */
#define KMCVX_CRE 0x00000100  /* Creation i.e. vertex creates new particle (ignoring Cerenkov photon). */
#define KMCVX_IPM 0x00000200  /* Indirect MCPM. The MCPM hit comes indirectly from the vertex. */

/* Status bits for the MC Track bank.
 *
 * Bits 4-17 are used to store the "history" of Cerenkov photons. The bit
 * structure is the same as in the MCPM bank status word. More details are
 * available on the MCPM bank page.
 *
 * See http://www.lip.pt/~barros/SNO/doc/snoman/companion_frames.html. */
#define KMCTK_IVX        0x00000002  /* Indirect vertex. Track does not come directly from its
                                        supporting vertex, see Notes below. */
#define KMCTK_SPARE1     0x00000004  /* Spare (Not part of Cerenkov history) */
#define KMCTK_SPARE2     0x00000008  /* Spare (Not part of Cerenkov history) */
#define KMCTK_INDIRECT   0x00000010  /* Indirect photon. */
#define KMCTK_RSCAT      0x00000020  /* Photon was Raleigh scattered. */
#define KMCTK_PSUP_SREF  0x00000040  /* Photon had a spectral reflection from the PSUP. */
#define KMCTK_PSUP_DREF  0x00000080  /* Photon had a diffuse reflection from the PSUP. */
#define KMCTK_AV_SREF    0x00000100  /* Photon had a spectral reflection from the AV. */
#define KMCTK_AV_DREF    0x00000200  /* Photon had a diffuse reflection from the AV. */
#define KMCTK_NCD_SREF   0x00000400  /* Photon had a spectral reflection from the NCD OVL. */
#define KMCTK_NCD_DREF   0x00000800  /* Photon had a diffuse reflection from the NCD OVL. */
#define KMCTK_PMT_REF    0x00001000  /* Photon entered and then escaped the PMT code (vxpmt). */
#define KMCTK_IN_PMT     0x00002000  /* Photon was produced inside a PMT. */
#define KMCTK_THROUGH_AV 0x00004000  /* Photon passed through the AV at least once. */

/* Bit masks for the PMT flags field in the PMT bank. */
#define KPF_DIS      0x00000001
#define KPF_NOI      0x00000004
#define KPF_PRP      0x00000008
#define KPF_AFP      0x00000010
#define KPF_FECD     0x00000020
#define KPF_FT_MASK1 0x00000040
#define KPF_XT       0x04000000
#define KPF_NO_CAL   0x08000000
#define KPF_BAD_CAL  0x10000000

/* Links for the MCGN bank. */
#define KMCGN_MCTK 1

/* Links for the MCTK bank. */
#define KMCTK_MCVX 1

typedef struct MCGNBank {
    /* Particle id. */
    uint32_t id;
    /* Number of outgoing particles generated. */
    uint32_t num;
    /* Radiative process if any. */
    uint32_t radcor_proc;
    /* +1 particle brems and produces a gamma.
     * -1 particle is a gamma produced by brem. */
    uint32_t radcor_made_gamma;
    /* Spares. */
    uint32_t spare5;
    uint32_t spare6;
    uint32_t spare7;
    uint32_t spare8;
    uint32_t spare9;
    uint32_t spare10;
    /* Correction to total cross sections. */
    float radcor_xtot;
    /* Correction to differential cross sections. */
    float radcor_xdif;
    /* Value of exponential parameter used for generating particle start times,
     * if time type IDTEX1 was selected. */
    float gentim_xpar;
    /* More spares. */
    float spare14;
    float spare15;
    float spare16;
    float spare17;
    float spare18;
    float spare19;
    float spare20;
} MCGNBank;

typedef struct MCVXBank {
    /* Class:  = 1 Source, = 2 Boundary, = 3 Interaction, = 4 Sink
	       = 5 Pre-source. */
    uint32_t cls;
    /* Interaction code. */
    uint32_t inc;
    /* Position X. */
    float x;
    /* Position Y. */
    float y;
    /* Position Z. */
    float z;
    /* Time in ns since MC Generation time (in MC bank). */
    double tim;
    /* First region code. */
    uint32_t rgn;
    /* First physical media code. */
    uint32_t idm;
    /* Second region code. */
    uint32_t rg2;
    /* Second physical media code. */
    uint32_t im2;
    /* Boundary normal X (only defined if boundary status bit set). */
    float bnx;
    /* Boundary normal Y (only defined if boundary status bit set). */
    float bny;
    /* Boundary normal Z (only defined if boundary status bit set). */
    float bnz;
    /* Number of Cerenkov photons. Only non-zero for CBV vertex. */
    uint32_t cer;
} MCVXBank;

typedef struct MCTKBank {
    /* Particle id code. */
    uint32_t idp;
    /* Direction cosine X. */
    float drx;
    /* Direction cosine Y. */
    float dry;
    /* Direction cosine Z. */
    float drz;
    /* Total energy (except for neutrons where it is kinetic). */
    float ene;
    /* Region code. */
    uint32_t rgn;
    /* Physical media code. */
    uint32_t idm;
    /* Polarization X. */
    float plx;
    /* Polarization Y. */
    float ply;
    /* Polarization Z. */
    float plz;
    /* Track step size. */
    float stp;
    /* Minimum distance to nearest boundary or 0. */
    float near;
} MCTKBank;

typedef struct EVBank {
    /* Run number. */
    uint32_t run;
    /* Event number. */
    uint32_t evn;
    /* Data type. */
    uint32_t dtp;
    /* Julian date. */
    uint32_t jdy;
    /* Universal time (seconds). */
    uint32_t ut1;
    /* Universal time (nanoseconds). */
    uint32_t ut2;
    /* Date (format: yyyymmdd) */
    uint32_t dte;
    /* Time (format: hhmmsscc - cc is centisec). */
    uint32_t hmsc;
    /* Global trigger time in nsec (first word). */
    uint32_t gtr1;
    /* Second word. */
    uint32_t gtr2;
    /* Number of PMTs that fired. */
    uint32_t npm;
    /* Integrated charge in the event. */
    uint32_t nph;
    /* Sub-run number, or -1 if unknown. Only defined for run number >= 10614. */
    uint32_t sub_run;
    /* Packed word. */
    uint32_t mc_pck;
    /* ZDAB input/output record type, e.g. PMT, NCD, CMA, RUN, etc. */
    uint32_t rec;
    /* ZDAB_PMT format number (x10). */
    uint32_t vpck;
    /* Global trigger ID. */
    uint32_t gtr_id;
    /* Trigger word. */
    uint32_t trg_type;
    /* Digitized peak of analog sum. */
    uint32_t peak;
    /* Analog sum derivative. */
    uint32_t diff;
    /* Digitized integral of analog sum. */
    uint32_t integral;
    /* Trigger error bits plus spares. */
    uint32_t err;
    /* Data splitter blindness word. */
    uint32_t data_set;
    uint32_t spare1[3];
    uint32_t ncd_status;
    /* Number of multiplexer global records. */
    uint32_t num_muxg;
    /* Number of multiplexer records. */
    uint32_t num_mux;
    /* Number of scope records. */
    uint32_t num_scope;
    uint32_t spare2[5];
    /* Upper 24 bits of flock */
    uint32_t ncd_clk_up;
    /* Lower clock register (32 bits). */
    uint32_t ncd_clk_lw;
    /* Latch register id. */
    uint32_t ncd_reg;
    /* GTID. */
    uint32_t ncd_gtid;
    /* Sync clear error. */
    uint32_t ncd_sync;
    uint32_t spare3[10];
} EVBank;

/* PMT Bank struct. This is a struct which mimics the PMT data bank in SNOMAN.
 * The fields and comments were taken from the SNOMAN companion. */
typedef struct PMTBank {
    /* Tube number. For FECD, which has no associated tube number, this word is
     * a copy of PIN. */
    uint32_t pn;
    /* Set of 1-bit flags. All undefined bits are set to zero. The following
     * bits are defined:
     *
     * 0  KPF_DIS       Discard hit for all processing including fitting.
     * 2  KPF_NOI       Noise.
     * 3  KPF_PRP       Pre-pulse.
     * 4  KPF_AFP       After-pulse.
     * 5  KPF_FECD      Front-End Card Data i.e. non-PMT channel.
     *                  Should only be set on the FECD bank.
     * 6  KPF_FT_MASK+i Discarded by fitter method i (i = 1,2,..).
     *                  For description of fitter methods see the FTx bank.
     * 26 KPF_XT        Crosstalk.
     * 27 KPF_NO_CAL    No calibration.
     * 28 KPF_BAD_CAL   Bad calibration. */
    uint32_t pf;
    /* Time in nano-secs relative to event T0 - see EV. */
    float pt;
    /* Integrated charge. */
    float phl;
    /* Short-time integrated charge. */
    float phs;
    /* Low-gain integrated charge. */
    float plx;
    /* Time with the PMT jitter removed. */
    float pt0;
    /* Set of n-bit flags for the ith hit in list. All undefined bits are set
     * to zero. The following bits are defined:
     *
     * Bit Field  DAQ Meaning
     * 0-3        NCELL     (CMOS Cell address 0 to 15)
     * 4-5        FLAG1      Bit 4 = CGT ES16.
     *                       Bit 5 = CGT ES24.
     * 6-9        FLAG2      Bit 6 = Missed Count
     *                       Bit 7 = NC/CC Flag
     *                       Bit 8 = LGISELECT (1=long sample)
     *                       Bit 9 = CMOS ES16. */
    uint32_t pif;
    /* Uncalibrated times. */
    float pit;
    /* Uncalibrated high-gain, long int. charge. */
    float pihl;
    /* Uncalibrated high-gain, short int. charge. */
    float pihs;
    /* Uncalibrated log-gain, long int. charge. */
    float pilx;
    /* Uncalibrated unjittered time. */
    float pit0;
    /* PMT channel cell number. */
    uint32_t cell;
    /* CCC DAQ Circuit Number
     *     = 1024*card + 32*crate + channel.
     * Before uncalibration it holds the tube no. */
    uint32_t pin;
    /* TSLH of PMT. */
    float tslh;
    /* HCA information. */
    float hca;
    /* ECA validation status word. */
    uint32_t eca_val;
    /* PCA validation status word. */
    uint32_t pca_val;
    /* ANXX validation status word. */
    uint32_t anxx;
    /* ECA calibrated time (nsec). */
    float ept;
    /* ECA calibrated QHL (pedestal subtracted). */
    float ehl;
    /* ECA calibrated QHS (pedestal subtracted). */
    float ehs;
    /* ECA calibrated QLX (pedestal subtracted). */
    float elx;
    /* Non-walk corrected PMT time. */
    float pt1;
    /* Multiphoton PCA time. */
    float ptm;
    /* Multiphoton PCA PMT transit time RMS. */
    float ptms;
    /* Best charge (either QHS or QLX). */
    float qm;
    /* Best charge status word. */
    uint32_t qms;
    /* Charge correction for rate-dependent shifting. */
    float qrc;
} PMTBank;

void unpack_mcgn(uint32_t *data, MCGNBank *b);
void unpack_mcvx(uint32_t *data, MCVXBank *b);
void unpack_mctk(uint32_t *data, MCTKBank *b);
void unpack_ev(uint32_t *data, EVBank *b);
void unpack_pmt(uint32_t *data, PMTBank *b);

size_t get_nhit(event *ev);
int get_event(zebraFile *f, event *ev, zebraBank *bev);
int isOrphan(aPmtEventRecord *pmtRecord);
void swap_int32(int32_t *val_pt, int count);
void swap_int16(int16_t *val_pt, int count);
int swap_PmtRecord(aPmtEventRecord *aPmtRecord, size_t size);
void swap_TrigRecord(struct TriggerInfo *aTrigRecord);
void swap_RunRecord(struct RunRecord *aRunRecord);

#endif