SolarNuAna output analysis and reconstruction toolkit for DUNE solar-neutrino studies.
Turns SolarNuAna_module ROOT outputs into analysis products: detector-performance studies, truth-level weighting, oscillation templates, and oscillation-sensitivity plots covering Day-Night asymmetry, HEP flux measurement, and full Δm²/sin²θ sensitivity contours.
Full documentation lives in docs/ and is published at dune-solar.readthedocs.io.
src/
pipelines/ Top-level run macros (one per analysis block)
physics/
calibration/ Correction → calibration → discrimination → reconstruction → smearing
detector/
pds/ PDS optical-flash matching and efficiency
tpc/ TPC electron energy and cluster resolution
vertex/ Vertex smearing, fiducial, and reconstruction
preselection/ Production, efficiency, and clustering studies
truth/ Oscillation templates, background spectra, signal KDE
marley_cc_fraction.py — CC-fraction pkl per PDG (replaces TruthMarleyStacked.ipynb)
signal/ Fiducialization, rebinning, and analysis signal products
common/ Shared significance-plot macros
daynight/ Day-Night significance and exposure curves
hep/ HEP significance, exposure, and comparison plots
sensitivity/ Background/signal templates, cut optimisation, contour plots
03_template_compute.py — orchestrates 01+02 without writing files itself
tools/
presentations/ Auto-generated Reveal.js slide decks (daynight/hep/sensitivity)
optimize_smoothing.py KDE sigma optimiser; outputs sigma JSON to output/data/smoothing/
generate_data_index.py Regenerates output/data/index.json (tree index for external repos)
event_display.py
compare_backends.py
processing.py
lib/ Shared helpers (IO, smoothing, oscillation, fiducial, log, …)
config/ Per-detector-configuration JSON files
analysis/ Active analysis settings (backgrounds, physics, smoothing, …)
pkl_paths.json Central registry of every pkl/json file the pipeline produces or consumes
tests/ Regression tests
docs/ Sphinx documentation source
external/ Prob3plusplus and NuFast-Earth oscillation backends
output/
data/
index.json Tracked in git — nested tree of all output/data/ files for external repos
Regenerate: python3 src/tools/generate_data_index.py
All entry-points live in src/pipelines/. Each script is self-contained and accepts --verbose quiet|normal|verbose (default normal).
| Script | Block |
|---|---|
run_truth.py |
Oscillation templates + background PDFs + signal KDE |
run_calibration.py |
Detector calibration chain (single config/name) |
run_calibration_all.py |
Calibration over multiple configs |
run_sensitivity.py |
DayNight + HEP + Sensitivity analyses |
run_pds.py |
PDS (OpFlash) diagnostics |
run_tpc.py |
TPC energy resolution diagnostics |
run_vertex.py |
Vertex reconstruction diagnostics |
run_preselection.py |
Preselection efficiency diagnostics |
run_analysis.py |
All detector diagnostics (no calibration) |
run_all.py |
Full detector chain |
For a clean environment run blocks in order:
1. run_truth.py ← oscillation files + background PDFs
2. run_calibration.py ← detector response chain
3. run_sensitivity.py ← physics analyses
python3 src/pipelines/run_truth.py \
--config hd_1x2x6_centralAPA \
--names marley gamma neutron \
--folder Nominal \
--oscillation_backend nufast \
--no-rewriteKey flags:
| Flag | Default | Description |
|---|---|---|
--config |
from analysis/backgrounds.json |
Detector configuration(s) |
--names |
marley gamma neutron |
Signal and background sample names |
--folder |
Nominal |
Fiducial folder(s) for signal KDE |
--oscillation_backend |
file |
file / prob3 / nufast |
--oscillations |
off | Enable oscillation template step |
--no-spectra |
on | Skip background spectra step |
--verbose |
normal |
quiet / normal / verbose |
python3 src/pipelines/run_calibration.py \
--config hd_1x2x6_centralAPA \
--name marley# Full three-analysis run
python3 src/pipelines/run_sensitivity.py \
--config hd_1x2x6_centralAPA \
--names marley gamma neutron radiological \
--analysis DayNight HEP Sensitivity \
--folder Truncated \
--energy SolarEnergy \
--oscillation_backend nufast \
--no-rewrite \
--plot
# Sensitivity only, skip already-computed steps
python3 src/pipelines/run_sensitivity.py \
--analysis Sensitivity \
--oscillation_backend nufast \
--no-rewriteKey flags:
| Flag | Default | Description |
|---|---|---|
--config |
hd_1x2x6_centralAPA |
Detector configuration(s) |
--names |
marley gamma neutron radiological |
Sample names |
--analysis |
all three | DayNight / HEP / Sensitivity |
--folder |
Truncated |
Fiducial folder(s) |
--energy |
SolarEnergy |
Energy estimator |
--exposure |
30 (config) |
Exposure the analyses are run to, in years (ANALYSIS_EXPOSURES in config/analysis/config.json). Results are quoted at EVALUATION_EXPOSURE_YEARS — 20 yr for DayNight/HEP, 30 yr for Sensitivity, which also gets a 10 yr secondary pass. |
--oscillation_backend |
file |
file / prob3 / nufast |
--no-computation |
Plot-only mode (skip all computation) | |
--no-significance |
Skip DayNight/HEP/Sensitivity computation | |
--no-fiducialization |
Skip fiducialization step | |
--no-rebin |
Skip signal rebin step | |
--rewrite / --no-rewrite |
rewrite | Overwrite existing outputs |
--plot / --no-plot |
plot | Generate output figures |
--verbose |
normal |
quiet / normal / verbose |
| Flag | Default | Description |
|---|---|---|
--save_weighted / --no-save_weighted |
off | Write per-cut weighted DataFrame to output/data/solar/weighted/ (needed by 04_weighted.py; disabled by default) |
--export_raw / --no-export_raw |
on | Export raw event arrays (energy, mask, weights) as pkl checkpoints |
--export_fiducial |
off | Export FiducializationMask per analysis before quality cuts |
--skip_scan |
off | Export raw arrays and exit without running the cut scan |
--best_cuts_only |
off | Scan only the best-cut point from JSON (Pass 3 / post-analysis export) |
All pipelines share a common verbosity model backed by lib/log.py:
| Level | What is shown |
|---|---|
quiet |
Errors and warnings only |
normal |
Progress markers and key results (default) |
verbose |
All output, including per-file debug messages |
The selected level is propagated to every subprocess via the SOLAR_VERBOSE environment variable so child scripts filter their own WorkflowLogBuffer output consistently.
# Run sensitivity with full debug output
python3 src/pipelines/run_sensitivity.py --verbose verbose ...
# Run truth pipeline silently (CI/batch use)
python3 src/pipelines/run_truth.py --verbose quiet ...The sensitivity pipeline applies a policy layer before launching per-sample jobs.
BACKGROUND_SAMPLES.ANALYSESinanalysis/backgrounds.jsondefines which background components each analysis (DAYNIGHT,HEP,SENSITIVITY) uses.BACKGROUND_SAMPLES.ESSENTIALmarks components as required (true) or optional (false).
Behavior:
- Non-essential + not listed for selected analyses → not processed.
- Essential + missing input files → hard stop.
- Optional + missing input files → skipped with warning.
Example config snippet:
"BACKGROUND_SAMPLES": {
"ESSENTIAL": {
"gamma": true,
"neutron": true,
"alpha": false,
"radiological": false
},
"ANALYSES": {
"DAYNIGHT": ["gamma", "neutron"],
"HEP": ["gamma", "neutron"],
"SENSITIVITY": ["gamma", "neutron"]
}
}This allows passing optional components (e.g. radiological) via --names without forcing failures in configurations where those productions do not exist.
Three backends are supported for oscillation probability computation:
| Backend | Description |
|---|---|
file |
Load pre-computed ROOT oscillogram files and rebin to analysis grid |
prob3 |
Compute on-the-fly with Prob3plusplus |
nufast |
Compute on-the-fly with NuFast-Earth (faster) |
Select via --oscillation_backend in any pipeline that accepts it.
All three physics-level scripts (01_fiducialize.py, 02_signal_template.py, 03_analysis.py) apply identical quality cuts so signal and background event populations are consistent. The optical-flash plane cut is centrally configured:
// config/analysis/config.json
"QUALITY_CUTS": {
"OPFLASH_PLANE": 0
}Changing OPFLASH_PLANE propagates to all scripts automatically via load_analysis_info().
src/physics/hep/01_hep.py and lib/sigma.py implement a global background normalization model: a single scale factor β ~ Gaussian(1, σ_rel) is profiled across all bins jointly. The legacy per-bin model was over-parameterized (N independent dials to absorb signal bin-by-bin), producing an artificial flat significance region. A global β correctly represents a correlated rate systematic; the saturation threshold is f ~ 1/(B_total · σ_rel²).
Exposure curves are post-processed with Gaussian kernel smoothing (scipy.ndimage.gaussian_filter1d, σ = 3 grid units) followed by isotonic regression (PAVA) for strict monotonicity.
Follows the energy-spectral counting approach of Super-Kamiogande [Abe et al. PRD 94, 052010 (2016); Renshaw et al. PRL 112, 091805 (2014)]:
- DUNE's
$Z_{global}^2 = \sum_i Z_i^2 = \sum_i (\Delta S_i)^2 / B_i$ is equivalent to Super-K's energy-spectral$\chi^2$ in the statistical-only limit. - Background model embeds the daytime solar signal in the null hypothesis:
$B_i = B_i^{raw}/2 + S_i^{day}$ . - Baseline is statistical-only; a second curve adds background uncertainty in quadrature.
git clone https://github.com/CIEMAT-Neutrino/SOLAR.git
cd SOLAR
python3 -m venv .venv
source .venv/bin/activate
pip install -r docs/requirements.txtapptainer pull dune-solar.sif docker://dune/dune-solar:latestIf working against shared CIEMAT storage, source scripts/setup.sh mounts the expected data directories via sshfs.
# Prob3plusplus
cd external/Prob3plusplus && make && cd python && make
# NuFast-Earth
cd external/NuFast-Earth && make && cd python && makecd docs && make htmlOutput: docs/_build/html/.
python3 -m pytest tests/test_smoothing.py