Using SNEWPY as a Front End for SNOwGLoBES

Install SNOwGLoBES

Important parts of SNEWPY’s functionality require the SNOwGLoBES (v1.2 recommended) and GLoBES libraries, which need to be installed separately. (See the respective documentation for instructions.)

Usage

The snewpy.snowglobes module contains functions for interacting with SNOwGLoBES.

SNOwGLoBES can estimate detected event rates from a given input supernova neutrino flux. It supports many different neutrino detectors, detector materials and interaction channels. There are three basic steps to using SNOwGLoBES from SNEWPY:

  • Generating input files for SNOwGLoBES:

    There are two ways to do this, either generate a time series or a fluence file. This is done taking as input the supernova simulation model. The first will evaluate the neutrino flux at each time step, the latter will compute the integrated neutrino flux (fluence) in the time bin. The result is a compressed .tar file containing all individual input files.

  • Running SNOwGLoBES:

    This step convolves the fluence generated in the previous step with the cross-sections for the interaction channels happening in various detectors supported by SNOwGLoBES. It takes into account the effective mass of the detector as well as a smearing matrix describing the energy-dependent detection efficiency. The output gives the number of events detected as a function of energy for each interaction channel, integrated in a given time window (or time bin), or in a snapshot in time.

  • Collating SNOwGLoBES outputs:

    This step puts together all the interaction channels and time bins evaluated by SNOwGLoBES in a single file (for each detector and for each time bin). The output tables allow to build the detected neutrino energy spectrum and neutrino time distribution, for each reaction channel or the sum of them.

snewpy.snowglobes.generate_time_series(model_path, model_type, transformation_type, d, output_filename=None, ntbins=30, deltat=None, snmodel_dict={})[source]

Generate time series files in SNOwGLoBES format.

This version will subsample the times in a supernova model, produce energy tables expected by SNOwGLoBES, and compress the output into a tarfile.

Parameters:

  • model_path (str) – Input file containing neutrino flux information from supernova model.

  • model_type (str) – Format of input file. Matches the name of the corresponding class in snewpy.models.

  • transformation_type (str) – Name of flavor transformation. See snewpy.flavor_transformation documentation for possible values.

  • d (int or float) – Distance to supernova in kpc.

  • output_filename (str or None) – Name of output file. If None, will be based on input file name.

  • ntbins (int) – Number of time slices. Will be ignored if deltat is also given.

  • deltat (astropy.Quantity or None) – Length of time slices.

  • snmodel_dict (dict) – Additional arguments for setting up the supernova model. See documentation of relevant SupernovaModel subclass for available options. (Optional)

Returns:

str – Path of compressed .tar file with neutrino flux data.

snewpy.snowglobes.generate_fluence(model_path, model_type, transformation_type, d, output_filename=None, tstart=None, tend=None, snmodel_dict={})[source]

Generate fluence files in SNOwGLoBES format.

This version will subsample the times in a supernova model, produce energy tables expected by SNOwGLoBES, and compress the output into a tarfile.

Parameters:

  • model_path (str) – Input file containing neutrino flux information from supernova model.

  • model_type (str) – Format of input file. Matches the name of the corresponding class in snewpy.models.

  • transformation_type (str) – Name of flavor transformation. See snewpy.flavor_transformation documentation for possible values.

  • d (int or float) – Distance to supernova in kpc.

  • output_filename (str or None) – Name of output file. If None, will be based on input file name.

  • tstart (astropy.Quantity or None) – Start of time interval to integrate over, or list of start times of the time series bins.

  • tend (astropy.Quantity or None) – End of time interval to integrate over, or list of end times of the time series bins.

  • snmodel_dict (dict) – Additional arguments for setting up the supernova model. See documentation of relevant SupernovaModel subclass for available options. (Optional)

Returns:

str – Path of compressed .tar file with neutrino flux data.

snewpy.snowglobes.simulate(SNOwGLoBESdir, tarball_path, detector_input='all', verbose=False, *, detector_effects=True)[source]

Takes as input the neutrino flux files and configures and runs the supernova script inside SNOwGLoBES, which outputs calculated event rates expected for a given (set of) detector(s). These event rates are given as a function of the neutrino energy and time, for each interaction channel.

Parameters:

  • SNOwGLoBESdir (str) – Path to directory where SNOwGLoBES is installed.

  • tarball_path (str) – Path of compressed .tar file produced e.g. by generate_time_series() or generate_fluence().

  • detector_input (str) – Name of detector. If "all", will use all detectors supported by SNOwGLoBES.

  • verbose (bool) – [DEPRECATED, DO NOT USE.]

  • detector_effects (bool) – Whether to account for detector smearing and efficiency.

snewpy.snowglobes.collate(SNOwGLoBESdir, tarball_path, detector_input='', skip_plots=False, verbose=False, remove_generated_files=True, *, smearing=True)[source]

Collates SNOwGLoBES output files and generates plots or returns a data table.

Parameters:

  • SNOwGLoBESdir (str) – [DEPRECATED, DO NOT USE.]

  • tarball_path (str) – Path of compressed .tar file produced e.g. by generate_time_series() or generate_fluence().

  • detector_input (str) – [DEPRECATED, DO NOT USE. SNEWPY will use all detectors included in the tarball.]

  • skip_plots (bool) – If False, it gives as output the plot of the energy distribution for each time bin and for each interaction channel.

  • verbose (bool) – [DEPRECATED, DO NOT USE.]

  • remove_generated_files (bool) – [DEPRECATED, DO NOT USE.]

  • smearing (bool) – Also consider results with smearing effects.

Returns:

dict – Dictionary of data tables: One table per time bin; each table contains in the first column the energy bins, in the remaining columns the number of events for each interaction channel in the detector.

Low-level interface

The module snewpy.snowglobes_interface contains a low-level Python interface for SNOwGLoBES v1.2.

Note

Users should only use the high-level interface described above. This low-level interface is not guaranteed to be stable and may change at any time without warning, e.g. to support new SNOwGLoBES versions.

class snewpy.snowglobes_interface.SNOwGLoBES(base_dir: Path = '')[source]

SNOwGLoBES interface.

This class manages the input and output files of the SNOwGLoBES application, and allows running the simulation for one or several setups:

from snewpy.snowglobes_interface import SNOwGLoBES
sng = SNOwGLoBES()

On construction, this class will read

  • a table of detectors known to SNOwGLoBES from <base_dir>/detector_configurations.dat,

  • a dictionary with a list channels for each detector material from <base_dir>/channels/channel_*.dat

  • a dictionary of efficiencies for each detector and channel from <base_dir>/effic/effic_*.dat

into the attributes sng.detectors, sng.channels, sng.efficiencies, respectively.

The method SNOwGLoBES.run() then performs the simulation for one or more flux files, and returns the resulting tables as a list containing a pandas.DataFrame for each input file:

flux_files = ['fluxes/fluence_timeBin1.dat', 'fluxes/fluence_timeBin2.dat']
result = sng.run(flux_files, detector='icecube')

# get results, summed over all energies and all channels:
Ntotal_0 = results[0].smeared.weighted.sum().sum()
Ntotal_1 = results[1].smeared.weighted.sum().sum()

# get only sum of ibd channel in the second time bin
Nibd_1 = results[1].smeared.weighted.ibd.sum()
Parameters:

base_dir (Path or None) – Path to the SNOwGLoBES installation. If empty, try to get it from $SNOWGLOBES environment variable.

run(flux_files, detector: str, material: Optional[str] = None)[source]

Run the SNOwGLoBES simulation for given configuration, collect the resulting data and return it in pandas.DataFrame

Parameters:

  • flux_files (list(str) or str) – An iterable of flux table filenames to process, or a single filename

  • detector (str) – Detector name, known to SNOwGLoBES

  • material (str or None) – Material name, known to SNOwGLoBES. If None, we’ll try to guess it

Returns:

list(pd.DataFrame or Exception) – List with the data table for each flux_file, keeping the order. Each table containing Energy (GeV) as index values, and number of events for each energy bin, for all interaction channels. Columns are hierarchical: (is_weighted, is_smeared, channel), so one can easily access the desired final table. If run failed with exception, this exception will be returned (not raised).

Raises:

  • ValueError – if material or detector value is invalid

  • RuntimeError – if SNOwGLoBES run has failed

class snewpy.snowglobes_interface.SimpleRate(base_dir: Path = '')[source]

Simple rate calculation interface. Computes expected rate for a perfect detector (100% efficiencies, no smearing) without using GLOBES. The formula for the rate is

Rate = [cross-section in 10^-38 cm^2] x 10^-38 x [fluence in cm^-2] x [target mass in kton]

x [Dalton per kton] x [energy bin size in GeV]

with [target mass in kton] x [Dalton per kton] = number of reference targets in experiment.

On construction the code will read:

  • detectors from <base_dir>/detector_configurations.dat,

  • channels from <base_dir>/channels/channel_*.dat

After that use SimpleRate.run() method to run the simulation for specific detector and flux file.

Parameters:

base_dir (Path or None) – Path to the directory where the cross-section, detector, and channel files are located If empty, try to get it from $SNOWGLOBES environment var

run(flux_files, detector: str, material: Optional[str] = None)[source]

Compute expected rates for given configuration, collect the resulting data and return it in pandas.DataFrame

Parameters:

  • flux_files (list(str) or str) – An iterable of flux table filenames to process, or a single filename

  • detector (str) – Detector name, SNOwGLoBES style

  • material (str or None) – Material name, SNOwGLoBES style. If None, we’ll try to guess it

Returns:

list(pd.DataFrame or Exception) – List with the data table for each flux_file, keeping the order. Each table containing Energy (GeV) as index values, and number of events for each energy bin, for all interaction channels. Columns are hierarchical: (is_weighted, channel), so one can easily access the desired final table. If run failed with exception, this exception will be returned (not raised).

Raises:

ValueError – if material or detector value is invalid