Welcome to dacsim’s documentation!

Contents:

modules

dacsim module

dacsim

Data Acquisition Chain Simulation

Simulate the data acquisition chain of a scintillator. The following parts of the acquosition chain are modeled:

  • scintillation process
  • photomultiplier tube
  • cable
  • digitizer

The energy distribution and the decay times of the pulses can be defined in the dat files (see edist and scintillator modules). The simulation of pile-up events is also possible (pileup module).

Input file

The code reads an input file in which the following variables MUST be defined:

  • nps: the number of pulses to be simulated
  • ptype: the type of particle that deposited energy in the scintillator (electron, proton, all)
  • cre: the electron countrate [Hz]
  • crp: the proton countrate [Hz]
  • output: the name of the output file (no extension)
  • dt: the time step for the simulated pulses [ns]
  • lc: the light collection efficiency of the scintillator
  • qeff: the quantum efficiency of the photomultiplier tube
  • k = conversion from keVee to number of photons
  • ndyn: the number of dynodes in the pmt
  • delta: the average gain of the dynodes
  • sigma: the broadening of the pmt response
  • tt: the transit time of the pmt
  • cutoff: the frequency cutoff of the cable [GHz]
  • imp: the impedance of the cable [ohm]
  • noise: the noise level [V]
  • bits: the number of bits of the digitizer
  • minV: the minimum input level of the digitizer [V]
  • maxV: the maximum input level of the digitizer [V]
  • sampf: the sampling frequency of the digitizer [GHz]
  • samples: number of digitized samples to be acquired
  • th_on: turn the digitizer’s trigger threshold on (1) or off (0)
  • th_lvl: trigger threshold level
  • pretrig_samp: number of pretrigger samples
  • fp: if 1, plot the first simulated pulse

example input file:

# input example for dacsim
# this line is a comment

# general parameters

nps 10
ptype electron
cre 20000
crp 0
output myout

# scintillator parameters

dt 0.05
lc 0.7
qeff 0.26
k 10.

# pmt parameters

ndyn 10
delta 4
sigma 5.2
tt 17.5

# cable parameters

cutoff 0.2
imp 50
noise 0.01

# digitizer parameters

bits 12
minV -0.1
maxV 1.2
sampf 0.4
samples 256
th_on = 1
th_lvl = 50
pretrig_samp 64

# plotting parameters

fp 1
Output

The codes generates a subdirectory called ‘output’ (if it does not exist) in the current directory and saves an output file with the name defined in the input and extension ‘.npy’. The output format is: [t_dig,[p_1,p_2,...,p_nps],pileup_log,time_int,inp_dict,coeff_dict,energy,intensity] where t_dig is the digitized time axis, p_1,p_2,..,p_nps are the digitized pulses, pileup_log is a list containing the number of pile-up pulses in each event, time_int is an array containing the time intervals between pulses, inp_dict is the input dictionary used to run the simulation, coeff_dict is the dictionary with the scintillator pulse shape coefficients, energy and intensity are the dictionaries containing the energy distributions for electrons and protons. For information on how to read the file refer to the numpy.load function

dacsim.read_input(fname)

Reads the input file and saves the parameters into a dictionary

Args:
fname (str): name of the input file
Returns:
inp_dict (dict): dictionary with the input parameters
dacsim.save_output(pulses, fname)

Saves the output file

Args:

pulses (list): list of simulated pulses

fname (str): name of the output file

edist module

Edist

Module that takes care of the energy distribution of the pulses.

edist.load_energy_spectrum(which)

Reads the spectrum from the input file “dat/spectrum_<which>.dat”.

Args:
which (string): particle for which the spectrum has to be loaded (electron, proton)
Returns:

energy (numpy.array): energy axis [keVee]

intensity (numpy.array): normalized spectrum

scintillator module

Scintillator

module with scintillator functions

scintillator.generate_pulses(n, t, amp, energy, spectrum, k=10.0, lc=1.0, qeff=1.0)

Generates scintillator pulses selcting random times according to the scintillator pulse shape.

Args:

n (int): the number of pulses to be generated

t (numpy.array): time axis of the scintillator pulse shape

amp (numpy.array): amplitude of the scintillator pulse shape

energy (numpy.array): energy axis [keVee]

spectrum (numpy.array): normalized spectrum

Kwargs:

k (float): conversion from keVee to number of photons

lc (float): light collection efficiency

qeff (float): quantum efficiency of the PMT. Implemented here and not in the pmt module to speed up the calculation

Returns:
mypulses (list): list containing the simulated pulses. Each pulse consists of an array of times of photon production
scintillator.load_coefficients()

Reads the scintillator coefficients from the input file “dat/scintillator.dat”.

Returns:
parsdict (dict): dictionary with the parameters
scintillator.scintillator(ptype, coeff_dict, plen=600, dt=0.05)

Calculates the scintillator pulse shape.

Args:

ptype (str): type of pulse. Can be “electron” or “proton”

coeff_dict (dict): dictionary with scintillator coefficients

Kwargs:

plen (float): pulse length [ns]

dt (float): time step [ns]

Returns:

t (numpy.array): time vector

amp (numpy.array): amplitude vector of the scintillation pulse

pileup module

Pileup

module that simulates pile-up effects

pileup.apply_pileup(plist, rate, plen)

Applies pile-up to the scintillator pulses.

Args:

plist (list): the list of scintillator pulses.

rate (float): the total count rate

plen (float): pulse length [ns]

Returns:
plist (list): the list of scintillator pulses with pileup.

pmt module

Pmt

module with the photomultiplier response function

pmt.apply_pmt(pulse, t, ndynodes=10, delta=4, sigma=5.0, transittime=100.0)

Adds the pmt response to a signal. The pmt response is modeled as a gaussian with amplitude depending on the number of dynodes and the dynode gain.

Args:

pulse (numpy.array): the photon pulse from the scintillator

t (numpy.array): the time axis of the pulse

Kwargs:

ndynodes (int): the number of dynodes

delta (float): the average gain of the dynodes

sigma (float): the time spread of the gaussian response [ns]

Returns:
newpulse (numpy.array): the current pulse produced by the pmt

cable module

Cable

module with cable filtering function and noise

cable.apply_cable(pulse, t, cutoff=0.1, impedance=50)

Cable effect modeled as a lowpass filter

Args:

pulse (numpy.array): input pulse from pmt

t (numpy.array): time axis of the pulse

Kwargs:

cutoff (float): cutoff of the filter [GHz]

impedance (float): impedance of the cable [ohm]

Returns:
newpulse (numpy.array): filtered pulse [V]
cable.apply_noise(pulse, level=0.02)

Add electric noise (gaussian oscillation) to the pulse

Args:
pulse (numpy.array): input pulse
Kwargs:
level (float): the amount of noise [V]
Returns:
newpulse (numpy.array): pulse with noise [V]

digitize module

Digitize

module with the function that takes care of the digitization of the pulse

digitize.digitize(pulse, t, nbits=8, amprange=[-1.0, 1], sampfreq=0.5, samples=256, do_threshold=False, threshold=50, pretriggersamples=64, noise=0.02)

Digitize the signal

Args:

pulse (numpy.array): the input signal

t (numpy.array): the time axis

Kwargs:

nbits (int): resolution of the digitizer [bit]

amprange (list): amplitude range of the digitizer [max,min] [V]

sampfreq (float): sampling frequency of the digitizer [GHz]

samples = number of samples to acquire

do_threshold (bool): activate trigger threshold effect

threshold (int): level of trigger threshold (starting from baseline value)

pretriggersamples (int): number of samples before the trigger

noise (float): noise level [mV]

Returns:
newpulse (numpy.array): digitized pulse

Indices and tables