Radcube Modules, Services, and Segments¶
A number of modules are included in the radcube project. A good portion of these are involved in the reading in of simulated air showers (see CoREAS Simulations) and the convolution of the simulated electric fields with the detector response, ultimately producing data that is in a format that is identical to that which would come from the Pole. In this way, the code can treat simulated and real data symmetrically when performing high level analyses. The remaining modules are involved in the pre-processing of data, removing the detector response and performing estimates of the shower properties. Note that the reconstruction itself is not done in this project, rather, it is contained solely in the Rock Bottom (RB) project.
Modules¶
AddElectronicNoise¶
This module adds noise to a trace which is consistent with what is measured in the DAQ hardware. The baseline inclusion of noise is that of the TAXI system. The noise profile of other DAQ configurations can also be chosen using input flags. Alternatively, noise with a flat spectrum can be added by setting the
FlatNoiseLevel
parameter to the desired dBm/Hz. The noise for the various settings is taken from an average frequency spectrum. Thus if the injected noise spectrum is plotted, it should always look the same. However, the phase of the noise is randomly assigned.
AddElectronicNoise
includes the following parameters:
ApplyInDAQ: If
True
, all sources of noise will be added in the Q-frame, otherwise the P-frameFlatNoiseLevel: If set, flat noise will be added wtih the input value (in dBm/Hz)
KeepNoiseOnly: If
True
, the pure noise waveform will be added to the frameInputName: Name of the
I3AntennaDataMap
in the frame to which noise will be addedOutputName: Name that the resultant
I3AntennaDataMap
that will be placed in the frameRandomServiceName: Name of the RandomService in the context used to generate random numbers (for the phases)
AddPhaseDelay¶
One of the properties of working in the Fourier domain is that the signals are guaranteed to be continuous from the last bin and wrapping back around to the first. Thus, it is possible to “roll” the signals within the bins and this module does just that. Given a delay time, it will roll the signal by that amount of time via the addition of a phase gradient \(\exp{(i\,f\,\Delta t)}\).
AddPhaseDelay
includes the following parameters:
DelayTime: The amount of time to delay the signals.
ApplyInDAQ: If
True
, all sources of noise will be added in the Q-frame, otherwise the P-frameInputName: Name of the
I3AntennaDataMap
or theEFieldTimeSeriesMap
in the frame to which noise will be addedOutputName: Name that the resultant
I3AntennaDataMap
orEFieldTimeSeriesMap
that will be placed in the frame
BandpassFilter¶
The
BandpassFilter
module is well named. It simply applies a filter to the selected set of waveforms.
BandpassFilter
includes the following parameters:
ApplyInDAQ: If
True
, the filtering will be performed in the Q-frame, otherwise the P-frameBoxTimeDelay: This is a delay parameter that can be added to the box-filter. It directly shifts the entire signal in the time domain by the selected about (in
I3Units
). Note that the trace is cyclic, so too negative of a number will put the trace at the end, giving potentially strange results.ButterworthOrder: This is the order of the Butterworth filter, describing the rate of attenuation outside of the bandpass region
FilterLimits: List containing the (low, high) limits of the filter to apply. Typically, the limits for a bandpass filter are defined as where the attenuation reaches -3dB.
FilterType: Type of filter to apply
InputName: Name of the
I3AntennaDataMap
orEFieldTimeSeriesMap
in the frame which will be filteredOutputName: Name that the resultant
I3AntennaDataMap
orEFieldTimeSeriesMap
that will be placed in the frame
BringTheNoise¶
This module has the ability to add thermal [1] and/or Cane noise. The Cane noise is a model that describes the average emission of electromagnetic radiation, as a function of frequency, from extra-terrestrial sources. For more information on the Cane model, see Cane Noise Brightness.
The amplitude of the selected noise sources is calculated then a random phase is added. These complex Fourier amplitudes are added to the requested trace. Additionally, an
I3AntennaDataMap
consisting of only the noise is also added to the frame for diagnostic purposes calledGeneratedNoiseMap
. Note that this noise is convolved with the antenna response (thus this module must be linked with theI3AntennaResponse
), but it is not convolved with the electronics.
BringTheNoise
includes the following parameters:
AntennaResponseName: (Required) Name of the
I3AntennaResponse
service in the frameInputName: Name of the
I3AntennaDataMap
in the frame to add noise toNoiseMultiplier: Multiply the noise spectrum amplitudes by this amount, (1 effectively does nothing)
OutputName: Name that the resultant
I3AntennaDataMap
will be placed in the frameRandomServiceName: The name of the I3RandomService in the tray to use for random number generation.
ThermalNoiseTemp: Temperature of the thermal noise to be added. Note: This must be passed in
I3Units
UseThermalNoise: If
True
, thermal noise will be includedUseCaneNoise: If
True
, noise based on the Cane Model (see Cane Noise Brightness) will be includedInsertNoiseOnly: If
True
, keep a copy of the pure noise in the frame
ChannelInjector¶
This module convolves the antenna response with the simulated electric field. This is done via the
I3AntennaResponse
service. The voltage in the antenna is calculated using the shower’s trajectory as an approximation for the Poynting vector of the radio emission of cosmic rays.Note
The Poynting vector of the radio emission is approximately one degree misaligned with the shower axis and this algorithm is thus an approximation.
The electric field, \(\vec E(f)\) is dotted with the antenna’s vector effective length \(\vec{ \mathcal{L}}(f, \theta, \phi)\). The math describing this process is given in Calculation of the Voltage in an Antenna.
ChannelInjector
includes the following parameters:
AntennaResponseName: Name of the
I3AntennaResponse
service in the frameInputName: Name of the
EFieldTimeSeriesMapConstPtr
in the frame to be transformed into a voltage.OutputName: Name that the resultant
I3AntennaDataMap
will be placed in the frame.
CoreasReader¶
This module’s job is to read in the CoREAS showers (see CoREAS Simulations) and put all of the relevant information in the frame. The complexity of this module comes from that fact that it has to able to run on an empty tray. Typically, modules have a constructor, a configuration, and specific functions that are called when the tray gets to a specific type of frame i.e.
DAQ()
is called for Q frames. Since we want the abililty for this module to run with an empty tray , it needs the ability to bootstrap all of the frames. Thus,CoreasReader
makes use of a number of non-standard module functions, such asShouldDoProcess()
. However, this reader is also compatible with having other modules do the “steering”, in which case you should set this to “PiggybackMode”.
CoreasReader
includes the following parameters:
AddToExistingGCD: If
True
, the respective radio data will instead be added to the G, C, and D frames if they already exist in the tray.DirectoryList: A list of directories of CoREAS showers, each in their own directory as defined in CoREAS Simulations
MakeDAQFrames: If
True
, the Q frames will be populated with the radio data, electric fields, even headers, etc.MakeGCDFrames: If
True
, will make the G, C, and D frames and put them in the tray. The geometry will be set by the first passed in simulation’s .list file.MakeGFrameForEach: If
True
, each event will have its own geometry frame made. This is useful of the geometry depends on the event trajectory.PiggybackMode: This mode is used if there is another steering module. In this case,
CoreasReader
canAddToExistingGCD
and/orMakeDAQFrames
, but it will notMakeDAQFrames
.The intended use cases for
CoreasReader
are:
Make only a radio simulation, beginning with a tray with nothing in it:
MakeGCDFrames = MadeDAQFrames = True
Make only a GCD file starting with an empty tray:
MakeGCDFrames = True
Add the radio data to a GCD file:
AddToExistingGCD = True
Perform a combined simulation of radio plus other arrays using a single simulated shower. In this case the other arrays would need to specify a GCD file beforehand since they cannot make them on the fly. One should set
PiggybackMode = MakeDAQFrames = True
andCoreasReader
should come after the steering module in the tray.Read in simulations for a star-shaped array where the antenna locations change based on the exact trajectory of the shower.
MakeGCDFrames = MakeGFrameForEach = MadeDAQFrames = True
CoREASToAntennaMap¶
This module converts an
EFieldTimeSeriesMap
to aAntennaDataMap
. This is a utility module which is used only for testing or in the rare cases that an algorithm works only on anAntennaDataMap
.
CoREASToAntennaMap
includes the following parameters:
InputName: Name of the
I3AntennaDataMap
to be analyzed in the frameOutputName: Name that the resultant
EFieldTimeSeriesMap
will be placed in the frame
EFieldCalculator¶
This module is the opposite of ChannelInjector. It solves the dot-product of voltage = (E-field) * (Vector effective length) to get the E-Field from the measured field in both channels. The simulated primary particle is read from the frame and taken to be the arrival direction of the electric field. The module puts an
EFieldTimeSeriesMap
into the frame with the E-field components.Note
The Poynting vector is not, in general, parallel to the shower axis, being off by a degree or so. Thus if you run ChannelInjector followed by EFieldCalculator, you will not end up exactly where you started. However, without making this approximation, calculating the 3-component E-field cannot be done with the two polarization measurements.
EFieldCalculator
includes the following parameters:
AntennaResponseName: Name of the
I3AntennaResponse
service in the frameInputName: Name of the
I3AntennaDataMap
to be analyzed in the frameOutputName: Name that the resultant
EFieldTimeSeriesMap
will be placed in the frame
ElectronicResponseAdder¶
This module convolves the response of the various electronics with an input signal (typically, a simulated air shower or background). The module is relatively simple as it just passes the requested
I3AntennaDataMap
to theI3ElectronicsResponse
to do all the required calculations to convolve the electronics response.
ElectronicsResponseAdder
includes the following parameters:
ElectronicsResponse: Name of the
I3ElectronicsResponse
service in the contextGeometryName: Name of the
I3Geometry
that has antennas in the frameInputName: Name of the
I3AntennaDataMap
in the frame to add the response toOutputName: Name that the resultant
I3AntennaDataMap
will be placed in the frame
ElectronicResponseRemover¶
This module is simply the inverse module of the ElectronicResponseAdder. Again, it simply relies on the
I3ElectronicsResponse
service to do all the heavy lifting.
ElectronicResponseRemover
includes the following parameters:
ElectronicsResponse: Name of the
I3ElectronicsResponse
service in the contextGeometryName: Name of the
I3Geometry
that has antennas in the frameInputName: Name of the
I3AntennaDataMap
in the frame of which the electronics response will be removedOutputName: Name that the resultant
I3AntennaDataMap
will be placed in the frame
EstimateRadioShower¶
This module is still under development. It will contain a few calculations to estimate the geometry of the shower. The direction will be estimated by fitting 3 (or more, see below) antennas to a plane front. The core location is taken to be the barycenter of the amplitude in the stations.
EstimateRadioShower
includes the following parameters:
AntennaBadList: Name of the list of antennas (
I3VectorOMKey
) in the frame which will be ignored during estimationInputName: Name of the antenna data (
I3AntennaDataMap
) in the frameHeightAboveBackground: If
UseOnlyTopThree = False
, this setting will be used to determine the minimum about an antenna’s signal must be above background to be used in the estimation.OutputName: Name of the
I3Particle
in the frameUseOnlyTopThree: If
True
, only the three antennas with the largest signal will be used in the estimation
MedianFrequencyFilter¶
This module applies a sort of averaging to the input
I3AntennaDataMap
. A sliding window of the specified size (in bins) is used to calculate a moving median of the frequency spectrum. TheFilterWindowWidth
is the full size of the window and thus the window extends (+/- size/2).
MedianFrequencyFilter
includes the following parameters:
FilterWindowWidth: Width of the sliding window, in bins, over which the filter will be applied. Value must be >2.
InputName: Name of the
I3AntennaDataMap
in the frame to which the median filter will be appliedOutputName: Name that the resultant
I3AntennaDataMap
will be placed in the frame
PedestalRemover¶
This module takes the data from the pole (or simulations) which is in ADC units. It removes the constant offset of the waveforms and, if requested, will convert the signals to voltage. So the
PedestalRemover
simply undoes the math performed in the digitization process (seeI3ElectronicsResponse
).
PedestalRemover
includes the following parameters:
ConvertToVoltage: If
True
the waveform is converted from ADC counts to voltage after removing the pedestalElectronicsResponse: Name of the
I3ElectronicsResponse
service in the contextInputName: Name of the
I3AntennaDataMap
in the frame whose pedestal will be removedOutputName: Name that the resultant
I3AntennaDataMap
will be placed in the frame
TraceResampler¶
The
TraceResampler
module upsamples/thins out the time trace to the specified binning. For instance, the default time binning of CoREAS is 0.2 ns. However, the binning of the digitizer might be less fine, \(\sim\) 1 ns. This module essentially just relies on theResamplingTools
to do all of the hard lifting. You can give this module either anEFieldTimeSeriesMap
or anI3AntennaDataMap
and it will place the same data type back into the frame after resampling. For more about this algorithm, see Waveform Resampling.
TraceResampler
includes the following parameters:
InputName: Name of the
EFieldTimeSeriesMap
orI3AntennaDataMap
in the frame to be resampledOutputName: Name that the resultant
I3AntennaDataMap
will be placed in the frameResampledBinning: Requested time-step that the
I3AntennaDataMap
will be resampled to.
WaveformChopper¶
This module simply truncates the traces for all antennas to the binnings requested length. This module works similarly to how a “slice” is done in python.
WaveformChopper
includes the following parameters:
ApplyInDAQ: If
True
, the truncating will be performed in the Q-frame, otherwise the P-frameInputName: Name of the
I3AntennaDataMap
in the frame to chopOutputName: Name that the resultant
I3AntennaDataMap
will be placed in the frameMinBin: Traces will now start at the bin specified
MaxBin: Traces will now end at the bin specified
Note that this means that the traces will have
MaxBin - MinBin + 1
entries after running this module.The code will throw and error if you request a bin range that is outside of the available range.
WaveformDigitizer¶
This module also leans heavily on the
I3ElectronicsResponse
service to give the conversions from voltage to ADC counts. However, this module can also add the internal TAXI noise (if selected in theI3ElectronicsResponse
). For each channel, a noise trace is read in from file, re-sampled if the binning of the TAXI trace does not match the signal’s and converted to voltage. The this sum is finally converted to ADC counts (and saturation is taken into account if selected in the response service) and put in the frame.
WaveformDigitizer
includes the following parameters:
InputName: Name of the
I3AntennaDataMap
in the frame to add the digitizeOutputName: Name that the resultant
I3AntennaDataMap
will be placed in the frameElectronicsResponse: (Required) Name of the
I3ElectronicsResponse
service in the context
ZeroPadder¶
This module also leans heavily on the
I3ElectronicsResponse
service to give the conversions from voltage to ADC counts. However, this module can also add the internal TAXI noise (if selected in theI3ElectronicsResponse
). For each channel, a noise trace is read in from file, re-sampled if the binning of the TAXI trace does not match the signal’s and converted to voltage. The this sum is finally converted to ADC counts (and saturation is taken into account if selected in the response service) and put in the frame. You can give this module either anEFieldTimeSeriesMap
or anI3AntennaDataMap
and it will place the same data type back into the frame after padding.
ZeroPadder
includes the following parameters:
AddToFront: If
True
, the zeros will be appended to the front of the time-series/spectrum, otherise they will be added to the back.AddToTimeSeries: If
True
, the zeros will be appended to the front/back of the time-series. Otherwise, they will be appended to the spectrum.AppendN: If this is set, then the module will append exactly this many bins worth of zeros. (Incompatible with FixedLength option.)
ApplyInDAQ: If
True
, the truncating will be performed in the Q-frame, otherwise the P-frameFixedLength: If this is set, zeros will be added such that the time-series/spectrum is exactly this long. (Incompatible with AppendN option.)
InputName: Name of the
I3AntennaDataMap
in the frame to add the digitizeOutputName: Name that the resultant
I3AntennaDataMap
will be placed in the frame
Services¶
I3ElectronicsResponseFactory¶
This service installs a copy of
I3ElectronicsResponse
into the context. It can be used to add/remove the effects of electrical components on an RF signal.The
ElectronicsResponseFactory
includes the following parameters:
AntennaType: The type of antenna whose LNA will be used (see
enum
inRadUtility.h
)AdditionalGain: An additional amount of amplitfication will be applied to the Radioboard’s response. Values should be given in dB.
ADCPedestalVolage: Ideally the digitized traces would sit in the middle of the ADC range. This setting allows you to shift the digitized traces up or down by the specified voltage first (see WaveformDigitizer).
ADCVoltageRange: Range of the ADC, if set to \(X\), this means that the digitizer ranges from \(+X\) to \(-X\) (see WaveformDigitizer).
CableLength: The length of the cables to use (affects attenuation amplitude)
CableTemperature: The temperature of the cables (affects attenuation amplitude)
IncludeBiasTee: If
True
, the bias-tee’s response will be includedIncludeCables: If
True
, the cables’s response will be includedIncludeElectronicNoise: If included, when the signal is digitized (see WaveformDigitizer), the measured TAXI traces will be linearly added to the simulated ones.
IncludeLNA: If
True
, the LNA’s response will be includedIncludeRadioBoard: If
True
, the radioboard’s response will be includedIncludeRadioBoardNoise: If
True
, this will use the noise of TAXI and the radio-boardIncludeSaturation: If
True
the ADC will be truncated below 0 or above \(2^\texttt{NADCBits}`\), see equations above.IncludeTaxi: If
True
, TAXI’s response will be includedInstallServiceAs: The name by which modules/services can find this service in the tray.
NADCBits: Number of bits that the digitizer has
OverrideHeadDir: The user can specify a default directory to look into for the radio response files. Note that they must be in an expected format, so this is not recommended unless you know what you are doing. However, this is useful if you want to work outside the cluster.
Note that
I3ElectronicsResponse
needs to load data tables that are normally stored in CVMFS. If you do not have access to CVMFS on the machine you are using to run this code, you must download the files, see Acquiring the Files.Finally, note that the
I3ElectronicsResponse
can also be used as a stand-alone class. For an example of this see$I3_BUILD/radcube/resources/examples/ExampleScript_ElectronicsResponse.py
.
I3AntennaResponseFactory¶
This service installs an instance of
I3AntennaResponse
into the context.I3AntennaResponseFactory
includes the following parameters:
AntennaType: The type of antenna whose LNA will be used (see
enum
inI3RadUtilities.h
)OverrideHeadDir: The user can specify a default directory to look into for the radio response files. Note that they must be in an expected format, so this is not recommended unless you know what you are doing. however, this is useful if you want to work outside the cluster.
InstallServiceAs: The name by which modules/services can find this service in the tray.
Note that
I3AntennaResponse
needs to load data tables that are normally stored in CVMFS. If you do not have access to CVMFS on the machine you are using to run this code, you must download the files, see Acquiring the Files.
Segments¶
The segments are strings of radcube modules which are used to perform a “standard”, or at least recommended, set of actions. The current ones are listed below (see $I3_SRC/radcube/python/segments
).
RadioInjection¶
The radio injection segment performs a combination of the module above to perform the complete simulation of an air shower event. It reads in a list of event locations, creates the GCD files, injects them into the antenna, adds noise, convolves it with the electronics’ responses, and digitizes it. At the conclusion of this segment the data should be in the exact same format as what would arrive from the pole. That is, nothing more need be added to the Q frame to run any script you would run on real data.
RadioInjection
has the following parameters:
InputFiles: List of directories, each containing one CoREAS simulation
ElectronicServiceName: Name of the I3ElectronicsService in the frame
AntennaServiceName Name of the I3AntennaService in the frame
RandomServiceName: Name of the random number generation service in the frame
MakeGCD: If
True
, the GCD files will be madeThermalNoiseTemp: Set the thermal noise temperature to be simulated
OutputName: Name of the I3AntennaDataMap to be put into the frame at the conclusion of this
PiggybackMode: If this is not the main steering module, set this to
True
(see CoreasReader)
RadioReconPrep¶
This segment runs a number of modules which take the simulated or real data, analayzes it, and prepares it for a reconstruction.
InputFiles: List of directories, each containing one CoREAS simulation
ElectronicServiceName: Name of the I3ElectronicsService in the frame
OutputName: Name of the I3AntennaDataMap to be put into the frame at the conclusion of this
BandwidthLimits: The data is filtered on a bandpass with these limits (low, high)
EstimateShower: If
True
the shower properies are estimated and anI3Particle
is put in the frame.
Footnotes