legend-simflow 1.0.0__tar.gz

legend_simflow-1.0.0/.JuliaFormatter.toml

@@ -0,0 +1,45 @@
+style = "default"
+
+indent = 4
+margin = 120
+
+always_for_in = true
+
+short_to_long_function_def = true
+long_to_short_function_def = false
+force_long_function_def = false
+always_use_return = true
+
+remove_extra_newlines = false
+
+align_assignment = true
+align_struct_field = true
+align_pair_arrow = true
+align_conditional = true
+
+disallow_single_arg_nesting = false
+
+trailing_comma = false
+trailing_zero = true
+
+whitespace_in_kwargs = true #
+whitespace_typedefs = false
+whitespace_ops_in_indices = true #
+separate_kwargs_with_semicolon = false
+surround_whereop_typeparameters = false
+
+import_to_using = false
+pipe_to_function_call = false
+
+format_docstrings = false
+
+join_lines_based_on_source = true
+
+indent_submodule = false
+short_circuit_to_if = false
+
+format_markdown = false
+
+normalize_line_endings = "unix"
+
+ignore = []

legend_simflow-1.0.0/.gitattributes

@@ -0,0 +1,2 @@
+# SCM syntax highlighting & preventing 3-way merges
+pixi.lock merge=binary linguist-language=YAML linguist-generated=true

legend_simflow-1.0.0/.github/dependabot.yml

@@ -0,0 +1,7 @@
+version: 2
+updates:
+  # Maintain dependencies for GitHub Actions
+  - package-ecosystem: "github-actions"
+    directory: "/"
+    schedule:
+      interval: "monthly"

legend_simflow-1.0.0/.github/release.yml

@@ -0,0 +1,5 @@
+changelog:
+  exclude:
+    authors:
+      - dependabot[bot]
+      - pre-commit-ci[bot]

legend_simflow-1.0.0/.github/workflows/add-to-remage-project.yaml

@@ -0,0 +1,15 @@
+name: Add new issues to remage project
+
+on:
+  issues:
+    types:
+      - opened
+
+jobs:
+  add:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/add-to-project@v1.0.2
+        with:
+          project-url: https://github.com/orgs/legend-exp/projects/31 # remage
+          github-token: ${{ secrets.ADD_TO_REMAGE_PROJECT }}

legend_simflow-1.0.0/.github/workflows/distribution.yml

@@ -0,0 +1,48 @@
+name: distribute
+
+on:
+  workflow_dispatch:
+  pull_request:
+  push:
+    branches:
+      - main
+  release:
+    types:
+      - published
+
+concurrency:
+  group: ${{ github.workflow }}-${{ github.ref }}
+  cancel-in-progress: true
+
+env:
+  FORCE_COLOR: 3
+
+jobs:
+  dist:
+    name: Distribution build
+    runs-on: ubuntu-latest
+
+    steps:
+      - uses: actions/checkout@v6
+        with:
+          fetch-depth: 0
+
+      - uses: hynek/build-and-inspect-python-package@v2
+
+  publish:
+    needs: [dist]
+    name: Publish to PyPI
+    environment: pypi
+    permissions:
+      id-token: write
+    runs-on: ubuntu-latest
+    if: github.event_name == 'release' && github.event.action == 'published'
+
+    steps:
+      - uses: actions/download-artifact@v7
+        with:
+          name: Packages
+          path: dist
+
+      - uses: pypa/gh-action-pypi-publish@release/v1
+        if: github.event_name == 'release' && github.event.action == 'published'

legend_simflow-1.0.0/.github/workflows/main.yml

@@ -0,0 +1,108 @@
+name: legend-simflow
+
+on:
+  workflow_dispatch:
+  pull_request:
+  push:
+    branches:
+      - main
+      - "releases/**"
+
+concurrency:
+  group: ${{ github.workflow }}-${{ github.ref }}
+  cancel-in-progress: true
+
+env:
+  FORCE_COLOR: 3
+
+jobs:
+  pre-commit:
+    name: Format
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v6
+        with:
+          fetch-depth: 0
+      - uses: actions/setup-python@v6
+        with:
+          python-version: "3.x"
+      - name: Set up Julia
+        uses: julia-actions/setup-julia@v2
+        with:
+          version: "1.10"
+      - name: Set up JuliaFormatter
+        run: julia -e 'using Pkg; Pkg.add("JuliaFormatter")'
+      - uses: pre-commit/action@v3.0.1
+        with:
+          extra_args: --all-files --show-diff-on-failure
+
+  unit-tests:
+    name: Run legend-simflow unit tests
+    runs-on: ${{ matrix.os }}
+    strategy:
+      fail-fast: false
+      matrix:
+        python-version: ["3.12", "3.13"]
+        os: [ubuntu-latest, macos-latest]
+
+    steps:
+      - uses: actions/checkout@v6
+      - name: Set up Python ${{ matrix.python-version }}
+        uses: actions/setup-python@v6
+        with:
+          python-version: ${{ matrix.python-version }}
+      - name: Install non-python (homebrew) dependencies
+        if: ${{ matrix.os == 'macOS-latest' }}
+        run: |
+          brew update
+          brew install opencascade cgal gmp mpfr boost
+      - name: Get dependencies and install legend-simflow
+        run: |
+          python -m pip install --upgrade pip wheel setuptools
+          python -m pip install --upgrade .[test]
+      - name: Run unit tests
+        run: |
+          python -m pytest
+
+  test-coverage:
+    name: Calculate and upload test coverage
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v6
+        with:
+          fetch-depth: 2
+      - uses: actions/setup-python@v6
+        with:
+          python-version: "3.12"
+
+      - name: Generate Report
+        run: |
+          python -m pip install --upgrade pip wheel setuptools
+          python -m pip install --upgrade .[test]
+          python -m pytest --cov=legendsimflow --cov-report=xml
+      - name: Upload Coverage to codecov.io
+        uses: codecov/codecov-action@v5
+        with:
+          token: ${{ secrets.CODECOV_TOKEN }}
+  test_julia:
+    name: Run Julia tests
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v6
+        with:
+          fetch-depth: 0
+      - uses: prefix-dev/setup-pixi@v0
+      - name: Run Julia tests with coverage
+        run: |
+          pixi run julia workflow/src/legendsimflow/scripts/init-julia-env.jl
+          pixi run julia --code-coverage=user --project=workflow/src/LegendSimflow.jl -e 'using Pkg; Pkg.test(coverage=true)'
+      - name: Process Julia coverage
+        uses: julia-actions/julia-processcoverage@v1
+        with:
+          directories: workflow/src/LegendSimflow.jl/src
+      - name: Upload Julia coverage
+        uses: codecov/codecov-action@v5
+        with:
+          token: ${{ secrets.CODECOV_TOKEN }}
+          files: lcov.info
+          flags: julia

legend_simflow-1.0.0/.gitignore

@@ -0,0 +1,183 @@
+*.swp
+*.swo
+workflow/src/legendsimflow/_version.py
+.snakemake
+/inputs
+/simflow-config.yaml
+/generated
+tests/dummyprod/generated
+tests/dummyprod/inputs/hardware/configuration
+tests/dummyprod/inputs/datasets
+
+# Byte-compiled / optimized / DLL files
+__pycache__/
+*.py[cod]
+*$py.class
+
+# C extensions
+*.so
+
+# Distribution / packaging
+.Python
+build/
+develop-eggs/
+dist/
+downloads/
+eggs/
+.eggs/
+lib/
+lib64/
+parts/
+sdist/
+var/
+wheels/
+share/python-wheels/
+*.egg-info/
+.installed.cfg
+*.egg
+MANIFEST
+fontlist-*.json
+
+# PyInstaller
+#  Usually these files are written by a python script from a template
+#  before PyInstaller builds the exe, so as to inject date/other infos into it.
+*.manifest
+*.spec
+
+# Installer logs
+pip-log.txt
+pip-delete-this-directory.txt
+
+# Unit test / coverage reports
+htmlcov/
+.tox/
+.nox/
+.coverage
+.coverage.*
+.cache
+nosetests.xml
+coverage.xml
+*.cover
+*.py,cover
+.hypothesis/
+.pytest_cache/
+cover/
+
+# Translations
+*.mo
+*.pot
+
+# Django stuff:
+*.log
+local_settings.py
+db.sqlite3
+db.sqlite3-journal
+
+# Flask stuff:
+instance/
+.webassets-cache
+
+# Scrapy stuff:
+.scrapy
+
+# Sphinx documentation
+/docs/build/
+/docs/source/api
+
+# PyBuilder
+.pybuilder/
+target/
+
+# Jupyter Notebook
+.ipynb_checkpoints
+
+# IPython
+profile_default/
+ipython_config.py
+
+# pyenv
+#   For a library or package, you might want to ignore these files since the code is
+#   intended to run in multiple environments; otherwise, check them in:
+# .python-version
+
+# pipenv
+#   According to pypa/pipenv#598, it is recommended to include Pipfile.lock in version control.
+#   However, in case of collaboration, if having platform-specific dependencies or dependencies
+#   having no cross-platform support, pipenv may install dependencies that don't work, or not
+#   install all needed dependencies.
+#Pipfile.lock
+
+# poetry
+#   Similar to Pipfile.lock, it is generally recommended to include poetry.lock in version control.
+#   This is especially recommended for binary packages to ensure reproducibility, and is more
+#   commonly ignored for libraries.
+#   https://python-poetry.org/docs/basic-usage/#commit-your-poetrylock-file-to-version-control
+#poetry.lock
+
+# pdm
+#   Similar to Pipfile.lock, it is generally recommended to include pdm.lock in version control.
+#pdm.lock
+#   pdm stores project-wide configurations in .pdm.toml, but it is recommended to not include it
+#   in version control.
+#   https://pdm.fming.dev/#use-with-ide
+.pdm.toml
+
+# PEP 582; used by e.g. github.com/David-OConnor/pyflow and github.com/pdm-project/pdm
+__packages__/
+
+# Celery stuff
+celerybeat-schedule
+celerybeat.pid
+
+# SageMath parsed files
+*.sage.py
+
+# Environments
+.env
+.venv
+env/
+venv/
+ENV/
+env.bak/
+venv.bak/
+
+# Spyder project settings
+.spyderproject
+.spyproject
+
+# Rope project settings
+.ropeproject
+
+# mkdocs documentation
+/site
+
+# mypy
+.mypy_cache/
+.dmypy.json
+dmypy.json
+
+# Pyre type checker
+.pyre/
+
+# pytype static type analyzer
+.pytype/
+
+# Cython debug symbols
+cython_debug/
+
+# PyCharm
+#  JetBrains specific template is maintained in a separate JetBrains.gitignore that can
+#  be found at https://github.com/github/gitignore/blob/main/Global/JetBrains.gitignore
+#  and can be added to the global gitignore or merged into this file.  For a more nuclear
+#  option (not recommended) you can uncomment the following to ignore the entire idea folder.
+#.idea/
+
+# julia
+Manifest.toml
+
+# AI
+.aider*
+# pixi environments
+.pixi/*
+!.pixi/config.toml
+pixi.lock

legend_simflow-1.0.0/.pre-commit-config.yaml

@@ -0,0 +1,102 @@
+ci:
+  autoupdate_commit_msg: "chore: update pre-commit hooks"
+  autoupdate_schedule: "quarterly"
+  autofix_commit_msg: "style: pre-commit fixes"
+
+repos:
+  - repo: https://github.com/adamchainz/blacken-docs
+    rev: "1.20.0"
+    hooks:
+      - id: blacken-docs
+        additional_dependencies: [black==24.*]
+        exclude: ^README.md
+
+  - repo: https://github.com/pre-commit/pre-commit-hooks
+    rev: "v6.0.0"
+    hooks:
+      - id: check-added-large-files
+      - id: check-case-conflict
+      - id: check-merge-conflict
+      - id: check-symlinks
+      - id: check-yaml
+      - id: check-json
+      - id: check-toml
+      - id: check-docstring-first
+      - id: debug-statements
+      - id: end-of-file-fixer
+      - id: forbid-new-submodules
+      - id: mixed-line-ending
+      - id: name-tests-test
+        args: ["--pytest-test-first"]
+      - id: requirements-txt-fixer
+      - id: trailing-whitespace
+
+  - repo: https://github.com/astral-sh/ruff-pre-commit
+    rev: "v0.14.4"
+    hooks:
+      - id: ruff
+        args: ["--fix", "--show-fixes"]
+      - id: ruff-format
+
+  - repo: https://github.com/codespell-project/codespell
+    rev: "v2.4.1"
+    hooks:
+      - id: codespell
+        args: ["-L", "nd,unparseable,compiletime,livetime,livetimes,puls"]
+
+  - repo: https://github.com/shellcheck-py/shellcheck-py
+    rev: "v0.11.0.1"
+    hooks:
+      - id: shellcheck
+
+  - repo: https://github.com/pre-commit/pygrep-hooks
+    rev: "v1.10.0"
+    hooks:
+      - id: rst-backticks
+      - id: rst-directive-colons
+      - id: rst-inline-touching-normal
+
+  - repo: https://github.com/rbubley/mirrors-prettier
+    rev: "v3.6.2"
+    hooks:
+      - id: prettier
+        types_or: [yaml]
+      - id: prettier
+        types_or: [markdown, html, css, scss, javascript, json]
+        args: [--prose-wrap=always]
+
+  - repo: local
+    hooks:
+      - id: disallow-caps
+        name: Disallow improper capitalization
+        language: pygrep
+        entry: PyBind|Cmake|CCache|Github|PyTest
+        exclude: .pre-commit-config.yaml
+
+  - repo: https://github.com/abravalheri/validate-pyproject
+    rev: "v0.24.1"
+    hooks:
+      - id: validate-pyproject
+        additional_dependencies: ["validate-pyproject-schema-store[all]"]
+
+  - repo: https://github.com/python-jsonschema/check-jsonschema
+    rev: "0.35.0"
+    hooks:
+      - id: check-dependabot
+      - id: check-github-workflows
+      - id: check-readthedocs
+
+  - repo: https://github.com/snakemake/snakefmt
+    rev: v0.11.2
+    hooks:
+      - id: snakefmt
+
+  - repo: local
+    hooks:
+      - id: julia-format
+        name: JuliaFormatter
+        entry: julia --color=yes -e 'using JuliaFormatter; format(ARGS)'
+        language: system
+        files: '\.jl$'
+        exclude: '^\.pixi/'
+        pass_filenames: true

legend_simflow-1.0.0/.readthedocs.yaml

@@ -0,0 +1,23 @@
+version: 2
+
+build:
+  os: "ubuntu-22.04"
+  tools:
+    python: "3.12"
+  commands:
+    - asdf plugin add uv
+    - asdf install uv latest
+    - asdf global uv latest
+    - uv venv
+    - uv pip install .[docs]
+    - rm -rf docs/source/api
+    - .venv/bin/python -m sphinx.ext.apidoc
+      --private
+      --module-first
+      --force
+      --output-dir docs/source/api
+      workflow/src
+      workflow/src/legendsimflow/scripts
+    - python docs/tools/generate_rule_docs.py
+    - .venv/bin/python -m sphinx -W --keep-going -T -b html -d docs/_build/doctrees -D
+      language=en docs/source $READTHEDOCS_OUTPUT/html

legend_simflow-1.0.0/AGENTS.md

@@ -0,0 +1,93 @@
+# AGENTS.md
+
+## Project Overview
+
+This repository hosts the workflow to run the Monte Carlo simulation pipeline
+for the LEGEND experiment (often called "the Simflow"). Snakemake is used to
+orchestrate routines based on the remage simulation ecosystem.
+
+You can learn about the project from the markdown documentation source in
+`docs/source/`:
+
+- `index.md`: overview, key concepts
+- `manual/meta.md`: configuration metadata, file naming conventions,
+  partitioning
+- `manual/setup.md`: install the software and main configuration file
+- `manual/prod.md`: how to run the workflow
+- `manual/sites.md`: computing site specific docs
+- `manual/tips.md`: tips and tricks
+
+## Dependencies & Tooling
+
+Python package. See `pyproject.toml` for dependencies and build config,
+including Pixi configuration.
+
+## Common Commands
+
+- Install (dev): `uv pip install -e ".[all]"` — run once after cloning or after
+  dependency changes
+- Test: `pixi run test` — run all tests (Python + Julia) before committing;
+  Python only: `pixi run test-python`; Julia only: `pixi run test-julia`; single
+  Python test: `pytest tests/test_foo.py::test_bar`
+- Lint/format: `pre-commit run --all-files` — run before committing; every
+  commit must pass
+- Build docs: `cd docs && make` — verify after any documentation change
+
+## Architecture
+
+To understand the workflow, start with `workflow/Snakefile`, then follow the
+imported modules under `workflow/rules/`.
+
+- `workflow`: project source code
+  - `src/legendsimflow`: Python package
+    - `patterns.py`: filesystem paths used in Snakemake rules
+    - `aggregate.py`: functions to build list of files for the Simflow
+    - `hpge_pars.py`/`spms_pars.py`: routines to compute the HPGe/SiPM
+      parameters to be used in the `hit` and `opt` tiers, based on information
+      from the LEGEND-200 data
+    - `scripts`: scripts directly used in Snakemake rules
+      - `tier/`: scripts used to build the various tiers
+      - `plots/`: scripts used to generate validation plots
+      - `init-julia-env.jl`: initializes the Julia environment at first run
+  - `src/LegendSimflow.jl`: Julia package used in the Simflow
+    - `Project.toml`: Julia package manifest
+    - `src/LegendSimflow.jl`: module entrypoint
+    - `test/`: Julia package tests
+  - `rules`: Snakemake modules imported by the main `Snakefile`. Rules belonging
+    to each tier are organized in separate modules. The `aux.smk` module is used
+    for other auxiliary rules.
+  - `profiles`: Snakemake workflow profiles with common Snakemake CLI options
+  - `Snakefile`: the main Snakefile
+- `templates`: template Simflow configuration files that users copy and adapt
+  when setting up a new production
+
+## Testing
+
+See [`tests/AGENTS.md`](tests/AGENTS.md).
+
+## Linting
+
+- Formatting/linting is enforced by pre-commit, hooks are listed in
+  `.pre-commit-config.yaml`, while further configuration is in `pyproject.toml`
+
+## Documentation
+
+See [`docs/AGENTS.md`](docs/AGENTS.md) for documentation conventions, docstring
+style, and Snakemake rule docstring conventions.
+
+## Code Conventions
+
+See [`workflow/AGENTS.md`](workflow/AGENTS.md).
+
+## Git Workflow
+
+- Commit style: Conventional Commits (https://www.conventionalcommits.org)
+- Every commit must pass linting and testing
+- PRs require passing CI
+- Make sure to include a concise description of the changes in a PR and link the
+  relevant related PRs or issues
+
+## Boundaries
+
+- ALWAYS: make sure linting, testing and docs building succeed **before**
+  committing