Metadata-Version: 2.4
Name: legend_simflow
Version: 1.4.0
Summary: Python package for processing LEGEND simulations
Author-email: Luigi Pertoldi <gipert@pm.me>
Maintainer: The LEGEND Collaboration
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: Science/Research
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: MacOS
Classifier: Operating System :: POSIX
Classifier: Operating System :: Unix
Classifier: Programming Language :: Python
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Topic :: Scientific/Engineering
Requires-Python: >=3.11
Description-Content-Type: text/markdown
Requires-Dist: awkward
Requires-Dist: dbetto>=1.4
Requires-Dist: h5py
Requires-Dist: hist
Requires-Dist: legend-dataflow-scripts>=0.3.0a5
Requires-Dist: legend-lh5io>=0.2
Requires-Dist: legend-pydataobj>=2
Requires-Dist: legend-pygeom-l200>=0.10.1
Requires-Dist: legend-pygeom-tools>=0.5
Requires-Dist: legend-pygeom-hpges>=0.9
Requires-Dist: matplotlib
Requires-Dist: mplhep>=1.0
Requires-Dist: numpy
Requires-Dist: psutil
Requires-Dist: pyg4ometry
Requires-Dist: dspeed>=2.1.4
Requires-Dist: pygama>=2.3.6
Requires-Dist: pylegendmeta>=1.7
Requires-Dist: pyyaml
Requires-Dist: reboost<0.13,>=0.12.3
Requires-Dist: revertex>=0.1.2
Requires-Dist: ruamel.yaml
Requires-Dist: snakemake<9.20,>=9.19
Requires-Dist: snakemake-argparse-bridge>=0.2.0
Requires-Dist: snakemake-storage-plugin-fs
Requires-Dist: snakemake-executor-plugin-slurm
Requires-Dist: snakemake-logger-plugin-rich>=0.4.2
Requires-Dist: snakemake-logger-plugin-snkmt>=0.1.7
Provides-Extra: test
Requires-Dist: pylegendtestdata; extra == "test"
Requires-Dist: pytest>=6; extra == "test"
Requires-Dist: pytest-cov>=3; extra == "test"
Provides-Extra: docs
Requires-Dist: sphinx>=7.0; extra == "docs"
Requires-Dist: myst_parser>=0.13; extra == "docs"
Requires-Dist: sphinx_inline_tabs; extra == "docs"
Requires-Dist: sphinx_copybutton; extra == "docs"
Requires-Dist: sphinx_autodoc_typehints; extra == "docs"
Requires-Dist: sphinxcontrib-mermaid; extra == "docs"
Requires-Dist: furo>=2023.08.17; extra == "docs"
Provides-Extra: all
Requires-Dist: legend_simflow[docs,test]; extra == "all"
Requires-Dist: pre-commit; extra == "all"

# legend-simflow

<img src=".github/logo.jpg" alt="legend-simflow logo" align="left" height="170">

[![PyPI](https://img.shields.io/pypi/v/legend-simflow?logo=pypi)](https://pypi.org/project/legend-simflow/)
![GitHub tag (latest by date)](https://img.shields.io/github/v/tag/legend-exp/legend-simflow?logo=git)
[![GitHub Workflow Status](https://img.shields.io/github/checks-status/legend-exp/legend-simflow/main?label=main%20branch&logo=github)](https://github.com/legend-exp/legend-simflow/actions)
[![pre-commit](https://img.shields.io/badge/pre--commit-enabled-brightgreen?logo=pre-commit&logoColor=white)](https://github.com/pre-commit/pre-commit)
[![Codecov](https://img.shields.io/codecov/c/github/legend-exp/legend-simflow?logo=codecov)](https://app.codecov.io/gh/legend-exp/legend-simflow)
[![Read the Docs](https://img.shields.io/readthedocs/legend-simflow?logo=readthedocs)](https://legend-simflow.readthedocs.io)
![GitHub issues](https://img.shields.io/github/issues/legend-exp/legend-simflow?logo=github)
![GitHub pull requests](https://img.shields.io/github/issues-pr/legend-exp/legend-simflow?logo=github)
![License](https://img.shields.io/github/license/legend-exp/legend-simflow)

End-to-end Snakemake workflow to run Monte Carlo simulations of signal and
background signatures in the LEGEND experiment and produce probability-density
functions (pdfs). Configuration metadata (e.g. rules for generating simulation
macros or post-processing settings) is stored at
[legend-simflow-config](https://github.com/legend-exp/legend-simflow-config).

## Features

- Tier-based Snakemake workflow taking Geant4
  ([_remage_](https://remage.readthedocs.io)) Monte Carlo events all the way to
  analysis-ready pdfs.
- Simulated statistics weighted by the livetime of a user-selected list of data
  taking runs (run partitioning).
- Fully metadata-driven: a production is configured by editing a single YAML
  file, no code required. Runs locally or on HPC sites through ready-made
  Snakemake profiles.

### Detector response models

Physics and detector models tuned to real LEGEND-200 data and applied during
post-processing:

- **HPGe energy**: per-detector energy scale and measured energy resolution
  FWHM(E) used to smear the simulated energy.
- **HPGe active volume**: dead-layer / active-volume model from detector
  geometry and metadata.
- **HPGe pulse shape and PSD**: Extraction of the A/E PSD observables based on
  drift-time maps and ideal pulse-shape libraries computed with
  [_SolidStateDetectors.jl_](https://juliaphysics.github.io/SolidStateDetectors.jl).
  This is combined with an electronics-response model's fitted to data
  waveforms.
- **Liquid-argon scintillation and SiPMs**: scintillation photon generation,
  photoelectron detection sampled from optical maps, per-photoelectron amplitude
  resolution, and time clustering reproducing the SiPM time response.
- **Detector status**: per-run usability and PSD-usability flags.
- **Event building**: time-coincidence maps (TCM) across detectors to group hits
  into physics events.

## Documentation

Full documentation is hosted at
[legend-simflow.readthedocs.io](https://legend-simflow.readthedocs.io). Good
entry points:

- [Overview and key concepts](https://legend-simflow.readthedocs.io/en/latest/)
- [Installation and configuration](https://legend-simflow.readthedocs.io/en/latest/manual/setup.html)
- [Running a production](https://legend-simflow.readthedocs.io/en/latest/manual/prod.html)
- [Configuration metadata and file naming](https://legend-simflow.readthedocs.io/en/latest/manual/meta.html)
