{'fraction_non_alphanumeric': 0.028860287527336607, 'fraction_numerical': 0.010862940522711792, 'mean_word_length': 5.079773321708806, 'pattern_counts': {'":': 0, '<': 0, '<?xml version=': 0, '>': 0, 'https://': 0, 'lorem ipsum': 0, 'www.': 0, 'xml': 0}, 'pii_count': 0, 'substrings_counts': 0, 'word_list_counts': {'cursed_substrings.json': 0, 'profanity_word_list.json': 0, 'sexual_word_list.json': 0, 'zh_pornsignals.json': 0}}
LeptonInjector and LeptonWeighter: A neutrino event generator and weighter for neutrino observatories

We present a high-energy neutrino event generator, called LeptonInjector, alongside an event weighter, called LeptonWeighter. Both are designed for large-volume Cherenkov neutrino telescopes such as IceCube. The neutrino event generator allows for quick and flexible simulation of neutrino events within and around the detector volume, and implements the leading Standard Model neutrino interaction processes relevant for neutrino observatories: neutrino-nucleon deep-inelastic scattering and neutrino-electron annihilation. In this paper, we discuss the event generation algorithm, the weighting algorithm, and the main functions of the publicly available code, with examples.

LeptonWeighter: Reweight Monte Carlo events, generated by a set of LeptonInjector Generators, to any desired physical neutrino flux or cross section. Solution method: LeptonInjector: Projected ranges of generated leptons and the extent of the detector, in terms of column depth, are used to inject events in and around the detector volume. Event kinematics follow distributions provided in cross section files.
LeptonWeighter: Event generation probabilities are calculated for each Generator, which are then combined into a generation weight and used to calculate an overall event weight.

Introduction
Neutrinos have been measured in a wide energy range from MeV energies in solar and reactor experiments to PeV energies in neutrino telescopes [1]. Different neutrino interaction processes [2] are relevant in this wide energy range, from e.g. coherent-neutrino scattering [3] at very small momentum (Q 2 ) transfer, to very large Q 2 processes which create W bosons [4,5,6,7,8] and heavy quark flavors [9]. However, deep-inelastic scattering [10] is always the dominant process above ∼ 10 GeV. This broad energy range has led to the development of various neutrino event generators used by experiments to simulate neutrino interactions [11,12,13,14], most of which have been optimized for GeV neutrino energy ranges and sub-megaton target mass detectors [12]. Such generators are not optimal for gigaton-scale neutrino detectors, often known as neutrino telescopes, such as the currently operating IceCube Neutrino Observatory at the Amundsen-Scott South Pole Station [15] and next-generation observatories such as KM3NeT [16] in the Mediterranean Sea and GVD in Lake Baikal [17].
The first neutrino telescope event generators started their simulation at the Earth's surface [18,19,20,21], which required solving two distinct problems: neutrino transport through the planet and the generation of neutrino events near the sensitive volume. The first such event generator was NUSIM [19], developed in the 1990s for the Antarctic Muon and Neutrino Detector Array (AMANDA); see also [22] for a similar effort for ANTARES. NUSIM established the fundamental concepts of what would later evolve into this project by breaking the problem of event generation into a three-step procedure. First a neutrino energy was randomly drawn from a prior distribution, then forced to interact somewhere near the detector, and finally an event weight would be calculated and applied [19]. This process relied on costly calculations of survival probability of the neutrino through the entirety of the Earth, and tightly coupled the generation and interaction of each neutrino to the calculation of its event weight.
In 2005, NUSIM was ported to C++ and released as the All Neutrino Interaction Simulation (ANIS) [20], and then modified and adopted into the IceCube internal framework [23] as neutrinogenerator, or NuGen. The basic simulation scheme remained unchanged, although with each 4 update of the software the scope of features grew and the fundamental features and techniques of the algorithm were further refined and optimized. In the past five years, efficient algorithms to solve the neutrino transport problem have become publicly available [21,24,25,26,27,28,29], allowing the possibility of simplifying event generation to only consider the problem of event generation in and around a volume near the detector. This allowed the event generation scheme to be separated into two standalone and publicly-available software projects: LeptonInjector [30] and LeptonWeighter [31]. This separation is not only convenient from software maintenance point of view, but also facilitates optimizations in different energy ranges. For example, IceCube's analyses focusing in EeV energies [32], where the Earth is opaque to neutrinos, have used the JAVA-based JULIeT [21,33] software package for neutrino transport. JULIeT, much like the C++based nuSQuIDS [24,25] package, has the computational advantage of solving Earth propagation using a set of differential equations instead of a Monte Carlo approach. The combination of software presented in this work allows for the user to choose the neutrino transport solution that best suits their needs. This simulation technique, the LeptonInjector/LeptonWeighter (LI/W), and traditional techniques are illustrated in Figure 1.1 In this paper, we will describe the structure and function of the LeptonInjector software package, as well as a companion package called LeptonWeighter. In Section II we describe the basic functionality of LeptonInjector, focusing on the structure of the software (Section II.A), the injection of particles into the detector (Section II.B), and a comparison between the output of LeptonInjector and NuGen. Section III contains a description of LeptonWeighter and provides examples of reweighted neutrino samples from various physical sources of neutrinos. We conclude in Section IV. Details of the event and file structures provided by the software packages, as well as example driver scripts, are provided in Supplemental Material.

LeptonInjector
LeptonInjector is written in C++ with boost-python bindings, and uses Photospline [34] for the cross sections needed for kinematic variable sampling. A standalone version of the code is publicly available from the IceCube GitHub repository [30]. In the description of the software that follows, we use monospace font to refer to libraries and packages, bold font to refer to classes, and italic font to refer to members of a class..
LeptonInjector is capable of simulating neutrino events of all flavors over a wide range of energies from 10 GeV to 100 PeV and beyond, undergoing neutrino-nucleon interaction in the Deep Inelastic Scattering (DIS) regime and antineutrino-electron scattering producing W in a Glashow Resonance (GR) interaction, (ν e + e − → W − ). The initial event energy is sampled according to a single power-law spectrum at any desired spectral index, and final state kinematics are sampled from spline interpolations of the differential cross sections for the relevant interaction. These splines are saved in FITS files generated by Photospline [34]. For optimum efficiency, the spectrum of generated events would match the physical one. Atmospheric and astrophysical neutrino fluxes, for example, follow a power-law flux. As it is often desirable to maintain large sample size at high energies, events can be generated at one flux and subsequently reweighted to any physical flux using LeptonInjector's sister software package LeptonWeighter, available at [31]. Because the event generation starts from near the detector, the primary neutrino energy will be guaranteed to follow the spectral index of event generation; this is not the case for event generators beginning at the Earth's surface.
To facilitate the reweighting, LeptonInjector creates configuration objects complete with a full description of all relevant event generation parameters. LeptonWeighter uses these configuration files to reweight events to any desired physical distribution.
Following the event generation, described in this work, the IceCube Monte Carlo proceeds using the following publicly available packages. First, leptons are propagated using PROPOSAL [35], a software package based on MMC [36], while hadronic or electromagnetic showers are propagated by the Cascade Monte Carlo (CMC) package, which implements the physics described in [37] and [38,39,40]. Next, Cherenkov photons arising from the charged particles are simulated by direct photon propagation using CLSim [41,42] or PPC [43,44]. Finally, a detector response is produced using a proprietary detector simulation.
LeptonInjector requires two kinds of objects: one or more Injectors and a Controller. An Injector object represents one primary neutrino type and one interaction channel, one cross section model to guide interactions, a number of neutrinos to be injected, and one parameter to control the sampling of the interaction vertex: ranged or volume mode, which are described in Section 2.1. In practice, the type of primary neutrino and interaction channel are specified in the Injector as a pair of particles that would be generated in such an interaction. These final state particles are called finalType1 and finalType2, and the order of these particles are strictly defined in Table 2.1. A 'Hadrons' particle is used to represent the hadronic shower produced by the recoiling nucleus from the DIS interaction and the hadronic decay channel from a W produced in a GR interaction. Ideally the propagation of the hadronic showers would be simulated directly using GEANT4 or a similar particle interaction framework, although this process is far too computationally expensive to be practical. Instead, a parametrization is used for the propagation of the hadronic shower, developed through GEANT4 simulations, as described in [38].
The Controller defines energy ranges, azimuth and zenith ranges, and a spectral index of the primary neutrino as shown in Table 2.2. One or more Injector objects must be assigned to a Controller as well as the destinations for the output files. Once the Controller is configured, the simulation is initialized by calling the Execute member function. The Controller iterates over its member Injectors, with each combining the Controller's flux properties with its own injection parameters into a Generator, and generating events until reaching their target number as set by the user. This process is illustrated in Figure 2  Injectors generate a 'primary' neutrino according to a power-law spectrum with the configured spectral index. This 'primary' neutrino is the neutrino as it was in the instant before interaction. The direction of the primary neutrino is sampled uniformly from the allowed ranges in azimuth and cosine of zenith. The event location is selected according to the injection mode, which is described in detail later in Section 2.1.

Parameter Description
Allowed ranges Injected primary azimuth angle [0, 2π]  The event kinematics are defined in terms of the Bjorken x and Bjorken y kinematic variables. As shown in Eq. (2.1), Bjorken y is the fractional energy carried away by the out-going lepton in a DIS interaction and Bjorken x is the fraction of primary-particle momentum transferred by the weak interaction. These two variables are given by where θ is the angle between the trajectories of the initial-and final-state leptons, m p the proton mass, and E i and E f are the energies of the initial and final state lepton, respectively. The Bjorken quantities are sampled, using b-splines from a joint 3D probability density function in the logarithm of each of E i , x, and y space, using the Metropolis-Hastings algorithm [45]. Final state particle energies and deviations from the injected primary direction are then calculated analytically according to these kinematic variables. Events are written to an HDF5 file as they are generated, and a LeptonInjector Configuration (LIC) file is written in parallel storing the exact configuration settings used for generation including both differential and total cross sections used. These LIC files are structured binary data files containing a header for meta-data, including a version number, and may evolve over time. The backwards-compatibility of LIC files is of importance, and will be maintained in future versions of LeptonInjector and 7 LeptonWeighter. The structure of the HDF5 files and exact specifications of the LIC files are described in Appendices Appendix A and Appendix B, respectively.

Injection
The two modes for injecting events are ranged mode and volume mode; each accepts and requires the parameters described in Table 2.3.
In volume mode, a cylinder, oriented vertically, is constructed around the origin according to specified parameters and an interaction point is selected uniformly within that cylinder's volume. This injection mode is suitable for simulating events which are approximately point-like for the purposes of detection, such as neutral-current interactions and charged-current ν e interactions which produce particle showers which are fairly short in dense media compared to the size of the detector.
The ranged mode process is illustrated in Figure 2.3. This mode is intended as a counterpart of the volume injection mode. Ranged mode is suitable for simulating events where the detection is due to visible daughter particles (µ ± , τ ± ) which travel through dense media for distances comparable to or larger than the size of the detector. It ensures sampling of interaction positions, over the whole volume of a target detector, both as far away as possibly visible to the detector due to daughter particles leaving the interaction, and proportional to local material density. A typical example of an interaction type in this category is the charged-current ν µ interaction.
During generation in ranged mode, a direction for the primary neutrino is first chosen within the allowed range of azimuth and zenith angles; this is shown in Figure 2.3a. Then, as in Figure 2.3b, a point is randomly chosen from a disk of radius InjectionRadius centered at the origin and perpendicular to the sampled direction; this point will be the point of closest approach (PCA) of the injected neutrino's projected path. The distance from the sampled PCA to the origin is called the impact parameter. Next, a range of possible positions along this path is determined in which the interaction position may be sampled. This includes two 'endcaps,' specified as lengths (EndcapLength) on either side of the disk containing the PCA, and a maximum lepton 'range.' The endcaps are added to ensure that events are sampled over the entire volume of the detector, and the range is computed to account for the maximum distance that the charged lepton daughter of the interaction may travel. This maximum distance is calculated according to . R µ and R τ represent the maximum ranges, in meters water equivalent, for 99.9 % of muons and taus of energy E in GeV respectively. The factor of 1.2 is to account for the observed deviations from the fits producing these max range functions. The maximum deviation was less than 20 %, and as such d b is appropriately scaled. The range of possible positions is converted to common units of column depth by taking into account the density of the material along the line formed by the two endcap lengths, including both local material around the detector and the Earth more generally, using a variation of the Preliminary Reference Earth Model (PREM) [47], which we have extended with three uniformdensity layers: a 2.6 km thick clear-ice layer, a 200 m thick firn layer, and a 103 km atmosphere layer; these are demonstrated in Appendix Appendix C. These extra layers cover the entire Earth, and are required to accurately distribute the events, with respect to depth, in ranged mode. This gives the preliminary maximum column depth within which the generator should ideally sample the interaction point. The geometry of this calculation is shown in Figure 2.3c. The model of the surrounding material is then integrated again, to determine whether the amount of column depth desired from the preliminary calculation actually exists along the path; at high energies it may not if the lepton range is sufficient to extend outside the outermost layer of the Earth model. In this case, the maximum column depth is reduced to the physically available value, as in Figure 2.3d. The resulting column depth is called the total column depth. The amount of column depth the neutrino should traverse before interacting is then sampled uniformly between zero and this total column depth, and then converted to a physical position along the chosen path by a final integration of the material model as shown in Figure 2.3e.

Comparisons
Prior to this generator, in IceCube, the primary neutrino event generator has been NuGen. Similar to LeptonInjector, NuGen has been used to generate both up-and down-going neutrino events of all flavors and neutrino type; it has been used for the Monte Carlo event generation of numerous studies in IceCube and is thoroughly vetted. As part of the development of LeptonInjector, comparisons were made between identical MC samples generated by LeptonInjector and NuGen's 'Detector Mode,' which uses an injection scheme roughly analogous to LeptonInjector's ranged mode. Events of all flavor, for both neutrino and anti-neutrino primaries, were generated for each neutrino type at a spectrum of E −1 over all azimuth angles and up-going zenith angles. A comparison of the spectra of injected lepton energies are shown in Figure 2.5, and a comparison of the average inelasticity parameter as a function of primary neutrino energy is shown in Figure 2.4b. Additional comparisons were carried out for distributions of Bjorken x and y, and the opening angle between injected particles, and were all found to be in agreement.
LeptonInjector was also verified to produce events with a realistic distribution of final state kinematics. Among other tests, to this end, we compared a large sample of generated events with the theoretical predictions of the final states resulting from CC, NC, and GR interactions, for (a) A direction (orange) is chosen and a perpendicular disc of radius InjectionRadius (red) is constructed.
(b) A point of closest approach is randomly sampled on that InjectionRadius disk.
(c) Preliminary column depth calculation of the lepton range (red) plus two EndcapLengths (blue) (d) If the actual column depth available is less than the column depth computed in part (c), reduce it appropriately.
(e) Sample uniformly from the total column depth available for insertion depth.  which we use [48] to model the DIS interactions and the analytical expressions given in [4,10] for the GR. Figure 2.4a compares the average inelasticity for an interaction of a given energy for neutral-and charged-current interactions with both neutrinos and anti-neutrinos; results from a five-year IceCube study on inelasticity distributions are overlaid [49] along with a flux-averaged LeptonInjector sample. This trend closely follows the predictions of [48]; see [50] for an extended discussion.

LeptonWeighter
The events produced by the LeptonInjector algorithm described in Section 2 are generated at an arbitrary rate chosen by the user; LeptonWeighter allows these events to then be reweighted to any physical neutrino flux and interaction cross section. Here, we briefly explain the reweighting procedure.
Suppose a sample of events was generated according to some ansatz distribution Φ(E), e.g.
where E is the neutrino energy and dN/dE is the expected flux density. To re-weight the sample to a uniform distribution in energy, a weight w event is applied to each event, inversely proportional to the generating probability density: where E 0 is the energy of the event. Suppose instead two sub-samples were generated from distributions Φ a and Φ b , with the same domain in energy, and were then combined into one. To re-weight events in the combined sample to a uniform distribution, a weight of

13
(a) Top: injected lepton energy for an anti-neutrino events. Bottom: relative difference between LeptonInjector and NuGen.
(b) Top: injected lepton energy for neutrino events. Bottom: relative difference between LeptonInjector and NuGen. would be applied. This is the generation weight, and accounts for the probability that either distribution could produce any given event. Events can then be re-weighted to a new distribution by evaluating their probability density in the new distribution and dividing by the generation weight.
Extending this to LeptonInjector, the probability density that a given Generator could have produced an event for each event is where Ω gen is the solid angle over which events were generated, Φ(E) is the power-law flux spectrum of the Generator, A gen is the integrated area of the sampling surface, ρ gen ( ) is the local mass density of targets, X col gen is total column depth of targets in the sampling region, N gen is the total number of generated events, and ∂ xy σ and σ total are the differential and total cross sections evaluated for the event, respectively. As a result, p MC has units of sr −1 cm −3 GeV −1 . For a single MC generator, whose exact definitions are discussed in [51], the generation weight is the inverse of the generation probability density: In the regime of small neutrino interaction probability, an event's final weight, in units of s −1 , is approximately given by where {gen} indicates the set of generators, M target is the molar mass of the target, Φ physical is the desired physical flux of neutrinos at the detector, N A is Avogadro's constant, X col physical is calculated 14 along the path the particle would take to interact, and ∂ xy σ is the differential cross section evaluated for the event. Note that X col physical is the physical column density between the generation boundaries f and i , which are not necessarily the same across different generators. If the physical and generation density models are the same, then the ρ physical ( )/X col physical and ρ gen ( )/X col gen terms cancel. For a more complete description of the weighting that covers non-negligible interaction probabilities, see Appendix Appendix D.
This weighting calculation procedure is implemented in the LeptonWeighter C++ library and Python module; it is available in [31]. LeptonWeighter uses the LIC files generated by LeptonInjector to calculate the above generation weights, then a user-specified cross section and flux to calculate event weights.

Code Structure
LeptonWeighter divides its functionality into distinct components: fluxes, cross sections, Generators, and Weighters. Flux objects are constructed to define a flux to which a sample should be weighted. CrossSection objects are similarly constructed with paths to locally saved FITS files of the same format as those used by LeptonInjector, and are used to define the cross sections used to weight the sample's events. LeptonWeighter constructs Generators by reading LIC files from disk and deserializing them. These Generators contain the exact simulation parameters used by LeptonInjector to generate events, and are able to calculate the generation weight for any event following a process illustrated in Figure 3.

2.
LeptonWeighter creates a Weighter object by using a list of Generators, a Flux object, and a CrossSection object. The Weighter object uses an event's properties, see Figure A.1 in the Appendix, to calculate a weight as defined by Eq. (3.6). Figure 3.1 demonstrates an all-flavor Monte Carlo sample composed of equal parts neutral-and charged-current DIS events, generated using an E −2 spectrum, and re-weighted to multiple different fluxes. The top-left plot shows the unweighted sample; the top-right left plot shows the sample reweighed to an astrophysical flux and weighted to the CSMS calculation of the DIS cross section [48]; the bottom-left is re-weighted to an atmospheric neutrino flux and convolved with the same DIS cross sections [48]; the bottom-right plot shows the sample re-weighted to an atmospheric neutrino flux, with nonstandard neutrino interaction (NSI) parameter strength of ε µτ = 2 × 10 −1 . See [52] for a precise definition of this parameter and nuSQuIDS [24,25] for the NSI implementation used.
In general, the weighting scheme allows to modify an already generated Monte Carlo set to any cross section that maps onto the same final states. For example, the DIS cross section could be a perturbative QCD calculation such as the CSMS@NLO [48] or the BGR@NNLO calculation given in [53] or a phenomenological estimate using the colour-dipole model [25]. Similarly for the Glashow process one could use the original tree-level calculation in [4] or the updated calculation including radiative corrections given in [54].

Broader applications
Although LeptonInjector and LeptonWeighter have principally been developed for use by IceCube, the injection and weighting techniques are broadly applicable for experiments that need to simulate natural sources of neutrinos above 10 GeV. To adapt the software to other experiments we must account for differences in detector geometry and material composition within and around the detector.
The size of the injection region can be easily adjusted by changing the InjectionRadius, EndcapLength, CylinderRadius, and CylinderHeight parameters to encompass the extent of the detector. As long as the detector occupies a significant fraction of this cylindrical volume, the event injection remains efficient.
The material model used by LeptonInjector and LeptonWeighter has a simple implementation that models the Earth as a series of cylindrical shells with a radially varying polynomial density distribution. The polar ice cap is modeled as an offset spherical shell, also with a radially varying polynomial density. This implementation works well for detectors embedded in media that conform to spherical symmetry such as KM3NeT [16] in the Mediterranean Sea. However, this approach to the material model breaks down when the symmetry is broken, as is the case for GVD in Lake Baikal [17] and the 17 kt liquid Argon modules planned for DUNE [55]  would need to be implemented. As long as the injection and weighting procedures query the updated material mode, no other modifications should be necessary.

Conclusions
Here we have presented the first publicly available neutrino telescope event generator for GeV-PeV+ energy ranges that factorizes the problem of Earth and atmospheric propagation from the event generation. The valid energy range of the generator is not limited by the software, but by the input cross sections provided by the user. The default CSMS cross section [48] provided with the code has less than 5 % uncertainty in the 100 GeV to 100 EeV energy range. The factorization allows for streamlined and efficient production of neutrino events. LeptonInjector, along with its sister software LeptonWeighter, satisfy the needs of generating events for gigatonscale neutrino observatories. The current implementation contains the most significant processes relevant to current analyses performed by these observatories, however we expect that this work will be extended as new calculations are made available and newer experimental needs arise. To this end, the code discussed in this paper follows an open-source model. Improvements recently proposed in the literature include: adding sub-leading neutrino interactions such as interactions with the nuclear coulomb field [5,6,7,8], which is expected to be a 10 % contribution at 1 PeV; use of updated DIS models such as those given in [29]; inclusion of trident neutrino events [56,57,58,59,8]; inclusion of nuclear effects on interactions [53]; inclusion of new physics processes such as production of heavy-neutral leptons [60,61,62] or dark neutrinos [63,64,65,66,67]; inclusion of new neutrino interactions mediated by light Z-prime [68,69,70]; among others.