CEvNS-pyEFT

Current public preview: v0.1.0-alpha.1

CEvNS-pyEFT is a Python toolkit for coherent elastic neutrino-nucleus scattering (CEvNS) calculations in an effective field theory framework. It provides reusable components for event-rate evaluation, detector-response handling, fast-scan kernel construction, chi-square scans, cutoff-limit estimates, and UV dim-6 matching utilities.

This repository is currently in public preview. APIs, numerical settings, and output formats may change before v1.0.0.

The package is intended for reproducible phenomenology studies related to COHERENT, PandaX-4T, XENONnT, and CEvNS/nonstandard-interaction analyses.

Features

• CEvNS cross-section, event-rate, and detector-response utilities.
• Matrixized fast-scan kernels for Wilson-coefficient studies.
• One- and two-parameter chi-square scan workflows.
• Single- and multi-experiment cutoff-limit tools.
• Dim-6 UV-to-LEFT matching utilities.
• Streamlit interface for interactive exploration.

Repository Layout

apps/streamlit/                  Streamlit app entry point and page modules
data/datafiles/                  Tabulated detector and spectrum inputs
data/kernels/reference/          Lightweight reference kernel metadata
data/responses/                  Nuclear-response input data
docs/theory/                     Theory notes and formula references
examples/                        Small runnable examples
src/cevns_pyeft/                 Python package source
tests/                           Import and path smoke tests

Python Environment

Use Python 3.11 or newer. Python 3.11 is recommended.

Runtime dependencies are listed in requirements.txt and mirrored in pyproject.toml:

numpy
pandas
matplotlib
scipy
streamlit
pillow

Create and install the project environment from the repository root:

python -m venv venvCEvNSpyEFT
.\venvCEvNSpyEFT\Scripts\Activate.ps1
python -m pip install --upgrade pip setuptools wheel
python -m pip install -r requirements.txt
python -m pip install -e .

A convenience setup script is provided for Windows PowerShell:

.\setup_env.ps1

If the package is not installed in editable mode, set PYTHONPATH before running examples or the Streamlit app:

$env:PYTHONPATH = "$PWD/src"

Quick Checks

From the repository root:

.\venvCEvNSpyEFT\Scripts\Activate.ps1
python -m py_compile src/cevns_pyeft/core/engine.py src/cevns_pyeft/statistics/cutoff_single.py src/cevns_pyeft/statistics/cutoff_multi.py src/cevns_pyeft/statistics/chi2_2d.py src/cevns_pyeft/eft/uv_dim6.py
python -c "from cevns_pyeft.core import engine; print(len(engine.li2026_left_basis_current()))"

The import check should print 22.

Run the Streamlit App

From the repository root:

.\venvCEvNSpyEFT\Scripts\Activate.ps1
$env:PYTHONPATH = "$PWD/src"
$env:STREAMLIT_BROWSER_GATHER_USAGE_STATS = "false"
python -m streamlit run apps/streamlit/Home.py --server.address 127.0.0.1 --server.port 8610

A convenience launcher is also provided:

.\run_streamlit.ps1

Open:

http://127.0.0.1:8610

The app sidebar uses repository-relative defaults:

Workflow base directory: .
responses_all.json path: data/responses/responses_all.json
Shared data directory: data
App output directory: outputs/app_outputs

Public Python Interface

from cevns_pyeft.core import engine
from cevns_pyeft.statistics import cutoff_single, cutoff_multi, chi2_2d
from cevns_pyeft.eft import uv_dim6

Data and Generated Outputs

The repository includes lightweight data files required for packaged workflows. Generated arrays, plots, scans, and app outputs should remain outside source control unless intentionally published as release artifacts.

Ignored generated output patterns include:

outputs/
app_outputs/
*_outputs/
*.npz
*.npy

Scientific References

This program is associated with the following works:

@article{Li:2024iij,
    author = "Li, Gang and Song, Chuan-Qiang and Tang, Feng-Jie and Yu, Jiang-Hao",
    title = "{Constraints on neutrino nonstandard interactions from COHERENT, PandaX-4T and XENONnT}",
    eprint = "2409.04703",
    archivePrefix = "arXiv",
    primaryClass = "hep-ph",
    doi = "10.1103/PhysRevD.111.035002",
    journal = "Phys. Rev. D",
    volume = "111",
    number = "3",
    pages = "035002",
    year = "2025"
}

@article{Li:2026mco,
    author = "Li, Gang and Song, Chuan-Qiang and Tang, Feng-Jie and Yu, Jiang-Hao",
    title = "{A Comprehensive Effective Field Theory Framework for Coherent Elastic Neutrino-Nucleus Scattering}",
    eprint = "2601.19883",
    archivePrefix = "arXiv",
    primaryClass = "hep-ph",
    month = "1",
    year = "2026"
}

License

This project is distributed under the license included in LICENSE.