Example: Calculating effective volume
This tutorial gives a full example to simulate the effective volume of a high-energy radio neutrino detector.
Run an effective volume simulation
An effective volume simulation consists of the following steps
generation of neutrino interactions in a cylindrical volume
calculating the Askaryan signal (ray tracing)
propagating the radio signal to your antennas
accounting for signal attenuation
simulating the antenna response
simulating the trigger
A working example is provided in NuRadioMC/examples/01_Veff_simulation
. Do NOT execute this example within this directory but copy it to a separate place outside of the NuRadioMC github repository. E.g.
mkdir $HOME/simulations
cp -r $HOME/software/NuRadioMC/NuRadioMC/examples/01_Veff_simulation $HOME/simulations/
cd $HOME/simulations/01_Veff_simulation
To run a simulation you need
an input event list specifying the neutrino vertices, energy, direction, flavor, type of interaction (charged current or neutral current), etc.
a detector description defining the positions of your antennas, the antenna type and orientation, sampling frequency, etc.
a NuRadioMC config file that e.g. specifies which Askaryan module and ice model to use
a main run script that also defines the details of the detector simulation
Generating the input event list
Generating the input event list is easy using the NuRadioMC event generator. Just execute
python T01generate_event_list.py
The script will generate two event lists. One with 1000 events at 1e19 eV neutrino energy and one with 10,000 events at 1e18 eV neutrino energy.
Running the simulation
To run the simulation execute
python T02RunSimulation.py 1e19_n1e3.hdf5 surface_station_1GHz.json config.yaml 1e19_n1e3_output.hdf5
The simulation only takes a few seconds (with the _C_ ray tracing implementation installed). The final output should be something like (small differences in the number of triggered events are expected because of random differences in the input data set)
WARNING:sim:fraction of triggered events = 18/1000 = 0.018
WARNING:sim:Veff = 22 km^3 sr
WARNING:sim:1000 events processed in 35 seconds = 35.26ms/event
and all triggered events are saved in the 1e19_n1e3_output.hdf5
hdf5 output file. In this example only three events triggered.
The output file only contains meta information such as the incoming signal direction, the ray tracing solutions, the polarization etc.
If you also want to save the pulse forms just add another command line argument.
python T02RunSimulation.py 1e19_n1e3.hdf5 surface_station_1GHz.json config.yaml 1e19_n1e3_output.hdf5 1e19_n1e3_output.nur
The waveforms are saved in a custom binary format (.nur) that serializes the complete NuRadioReco event structure into a file. This has the advantage that you can read it into NuRadioReco again to e.g. perform a reconstruction on the simulated data.
You can run the same simulation on the other input file with 10,000 events
python T02RunSimulation.py 1e18_n1e4.hdf5 surface_station_1GHz.json config.yaml 1e18_n1e4_output.hdf5
which takes 71 seconds on my laptop and leads to 29 triggered events.
More details: the detector description
The detector is defined in a JSON file and allows you to specify every detail of your detector that can have a relevance for the simulation or later reconstruction.
For our simple example though, it contains many parameters that we don’t need to worry about, e.g. details about the ADC, so just ignore those fields.
The file surface_station_1GHz.json
defines a ‘surface station’ consisting of 4 downward pointing LPDAs at -2m depth and 4 bicone antennas at -5m depth.
You can also use your own detector description, or one of the detector descriptions included with NuRadioMC under NuRadioReco/detector/{detector_name}/
.
More info about detector files can be found here.
More details: the config file
An overview of all parameters can be found in the default config file config_default.
Everything defined in the local configuration file config.yaml
will override the default parameters. The config file uses the YAML format, an easy to use and human readable format.
It is similar to JSON but easier to type down.
Visualization of results
NuRadioMC includes visualization tools. To produce the typical debugging plots of an effective volume simulation execute
python $HOME/software/NuRadioMC/NuRadioMC/simulation/scripts/T05visualize_sim_output.py 1e18_n1e4_output.hdf5
Please note that the number of triggered events is so small that some of the plots won’t make a lot of sense.