SIREN (Sampling and Injection for Rare EveNts) generates and weights particle interactions in detector geometries. It supports neutrino and beyond-Standard-Model processes, including interaction chains with secondary decays, through Python and C++ interfaces.
SIREN grew out of LeptonInjector and supports atmospheric, accelerator, and decay-at-rest neutrino experiments. Users can supply their own processes, fluxes, and detector geometries alongside the models included below.
python -m pip install sirenSIREN supports Linux and macOS and requires Python >= 3.8. Python dependencies are installed automatically. Download the datasets needed by your simulation before running the example. For source builds and C++ use, see Installation.
The following example injects 1e4 muon-neutrino DIS events in IceCube and computes their physical weights:
import siren
# Load detector geometry and interaction cross sections
detector_model = siren.utilities.load_detector("IceCube")
primary_type = siren.dataclasses.Particle.ParticleType.NuMu
primary_processes, _ = siren.utilities.load_processes(
"CSMSDISSplines",
primary_types=[primary_type],
target_types=[siren.dataclasses.Particle.ParticleType.Nucleon],
isoscalar=True,
process_types=["CC"],
)
# Configure the injector: energy spectrum, direction, and position
injector = siren.injection.Injector()
injector.number_of_events = int(1e4)
injector.detector_model = detector_model
injector.primary_type = primary_type
injector.primary_interactions = primary_processes[primary_type]
injector.primary_injection_distributions = [
siren.distributions.PrimaryMass(0),
siren.distributions.PowerLaw(2, 1e3, 1e6),
siren.distributions.IsotropicDirection(),
siren.distributions.ColumnDepthPositionDistribution(
600, 600.0, siren.distributions.LeptonDepthFunction()
),
]
# Generate events
from siren._util import GenerateEvents, SaveEvents
events, gen_times = GenerateEvents(injector)
# Weight events using physical distributions
weighter = siren.injection.Weighter()
weighter.injectors = [injector]
weighter.detector_model = detector_model
weighter.primary_type = primary_type
weighter.primary_interactions = primary_processes[primary_type]
weighter.primary_physical_distributions = [
siren.distributions.PowerLaw(2, 1e3, 1e6),
siren.distributions.IsotropicDirection(),
]
weights = [weighter(event) for event in events]
# Save results to HDF5 and Parquet
SaveEvents(events, weighter, gen_times, output_filename="my_output")More examples — including BSM dipole-portal injection and MARLEY low-energy interactions — are in resources/examples/.
SIREN separates injection from weighting. Injection samples vertices, energies, directions, and secondary processes to produce an interaction tree. Weighting corrects for the difference between those sampling distributions and the physical flux and interaction probabilities. A generated sample can then be reweighted for different physical models without regenerating events.
For optional BSM support via DarkNews:
python -m pip install "siren[DarkNews]"Source builds require a C++17 compiler, CMake >= 3.20, Python development headers/libraries, CFITSIO, and SuiteSparse.
git clone --recurse-submodules https://github.com/Harvard-Neutrino/SIREN.git
cd SIREN
python -m pip install . --config-settings='build-dir=build-pip'From the source checkout, build a wheel with pip:
python -m pip wheel . --no-deps --wheel-dir distOr use CMake, selecting the interpreter that will import SIREN:
cmake -S . -B build -DSIREN_PYTHON_PACKAGE=ON \
-DPython_EXECUTABLE="$(python -c 'import sys; print(sys.executable)')"
cmake --build build --target python_package --parallelInstall the CMake-built wheel explicitly with that interpreter:
python -m pip install build/dist_wheels/siren-*.whlRepeating this command leaves an unchanged installation in place. After rebuilding a wheel with the same version, reinstall it with:
python -m pip install --force-reinstall --no-deps build/dist_wheels/siren-*.whlThis assumes the dependencies from the first install are still satisfied.
For the pip-built wheel, use dist/siren-*.whl instead. The install_wheel
target runs that same reinstall command with the configured interpreter after
rebuilding the wheel:
cmake --build build --target install_wheelcmake --install installs native artifacts only; it never invokes pip.
The Python interpreter and pip determine where the wheel is installed.
Before distributing locally built wheels, repair their native dependencies
with delocate-wheel on macOS or auditwheel repair on Linux, as release CI
does. See the packaging guide for offline builds,
platform settings, staging, and validation.
From the same source checkout, build and install the standalone library:
cmake -S . -B build-native -DSIREN_PYTHON_PACKAGE=OFF \
-DCMAKE_INSTALL_PREFIX="$PWD/install"
cmake --build build-native --parallel
cmake --install build-nativeChoose your destination with CMAKE_INSTALL_PREFIX; DESTDIR supports staged
native installations. Set SIREN_PYTHON_PACKAGE=ON if this build should also
produce a wheel, then install that wheel separately with pip.
Use the standalone native library and Python wheel in separate processes. Importing SIREN checks for an already loaded standalone core where library inspection is available; the restriction applies in either loading order. See native library layout and loading for details and CMake consumer requirements.
With HepMC3 >= 3.3 available at build time, SIREN can export weighted events using the NuHepMC conventions:
from siren._util import SaveEvents
SaveEvents(events, weighter, gen_times, output_filename="my_output", save_hepmc3=True)Add hepmc3_gzip=True for compressed output. The HepMC3 guide
explains weight policies, deferred weighting, combining simulation sets, and
reading the output. To require this capability in a source build, configure
CMake with SIREN_REQUIRE_HEPMC3=ON.
SIREN includes detector geometry definitions for the following experiments:
| Experiment | Model name |
|---|---|
| ATLAS | ATLAS |
| CCM | CCM |
| DUNE Far Detector | DUNEFD |
| Hyper-Kamiokande | HyperK |
| IceCube | IceCube |
| KM3NeT/ORCA | KM3NeTORCA |
| MINERvA | MINERvA |
| MiniBooNE | MiniBooNE |
| ND280 | ND280 |
| ND280 Upgrade | ND280UPGRD |
| SINE | SINE |
| UNDINE | UNDINE |
Each detector is defined by a materials file and a density profile. To load one:
detector_model = siren.utilities.load_detector("IceCube")Contributions of new detector geometries are welcome.
| Model | Description |
|---|---|
CSMSDISSplines |
Deep inelastic scattering (CC and NC) on nucleons, using photospline cross-section tables |
MarleyCrossSection |
Low-energy neutrino interactions via MARLEY |
DarkNewsTables |
BSM processes (dark photons, dipole portal, HNLs) via DarkNews — see example2 |
HNLDISSplines |
Heavy neutral lepton (HNL) production via neutrino neutral current deep inelastic scattering on nucleons, using photospline cross-section tables |
DipoleHNLDISSplines |
Heavy neutral lepton (HNL) production via neutrino dipole-portal (i.e., via a transition magnetic moment) deep inelastic scattering on nucleons, using photospline cross-section tables |
| Model | Description |
|---|---|
BNB |
Booster Neutrino Beam (FHC and RHC modes) |
NUMI |
NuMI beamline (low-energy and medium-energy) |
T2K_NEAR |
T2K near detector flux |
HE_SN |
Supernova neutrino flux |
Atmospheric |
A suite of atmospheric neutrino flux models |
To load a flux model:
flux = siren.utilities.load_flux("BNB", tag="FHC_numu")Download process tables and flux models after installing SIREN:
siren-download --processes
siren-download --fluxThe data are stored under resources/processes and resources/fluxes in the
SIREN installation.
The Python API, C++ modules, and detectors, fluxes, processes, and examples live in separate directories. CMake support and wheel tooling handle builds and packaging.
Create a branch off of main named $GitHubUsername/$YourSubProject. When your changes are stable, pull from main and open a pull request.
If you use SIREN in your research, please cite the repository:
https://github.com/Harvard-Neutrino/SIREN
SIREN is licensed under the GNU Lesser General Public License v3.0.