# Lorentz-Violation Pipeline — Research Notes

This repository contains exploratory code and analysis scripts for investigating possible Lorentz invariance violation (LIV) signatures in high-energy astrophysical data and prototype experiments. The work here is research-stage: numerical outputs, theoretical models, and experimental system descriptions are model-derived and must be reproduced (with the scripts and environment) and independently reviewed before being cited as engineering or physical claims.

Where this README previously used unqualified or absolutist language, the text has been reframed to emphasize reproducibility, uncertainty quantification (UQ), and limitations.

## Summary — Scope & Intended Use

- Status: Research prototype (development, validation, and independent review required).
- Purpose: Provide analysis pipelines, theoretical-model prototypes, and example-run outputs for LIV studies and related exploratory energy-conversion experiments.
- Not a production system: numeric results depend on configuration, calibration choices, random seeds, and solver tolerances.

## What I changed (guidance for maintainers)

- Softened production-oriented or absolutist statements and replaced them with research-stage qualifiers.
- Added this `Scope, Validation & Limitations` section explaining how to reproduce reported numbers and what artifacts to attach when publishing results.
- Marked several previously reported numeric metrics and performance numbers as "example-run" outputs; maintainers should attach raw outputs and UQ reports for external claims.

If you'd like these edits submitted as a branch+PR instead of a direct commit, tell me and I'll switch to a branch workflow.

## Scope, Validation & Limitations

Scope
- Focuses on: (a) data-driven LIV bounds analyses using GRB/UHECR data; (b) prototype theoretical models (polynomial dispersion, polymer-QED, etc.); (c) example experimental control and data integration scripts.

Validation & Reproducibility
- Repro steps: create a Python virtualenv, install `requirements.txt`, and run the example scripts under `examples/` (see `examples/` or `scripts/` directories for variant commands).
- Required artifacts for externally-published claims: the specific example script, the raw output files (CSV/plots), the Python environment specification (`requirements.txt`), random seeds, and the approximate commit ids for this repo and any integrated repositories.
- UQ pointers: `src/validation/` contains starter scripts for Monte Carlo sensitivity analysis. Treat reported confidence levels as conditional on the provided configuration.

Limitations
- Numerical bounds and model-derived values are sensitive to calibration choices, data selection, and analysis pipelines; perform sensitivity checks and cross-validation before generalizing results.
- Experimental or energy-conversion descriptions are prototypes or thought-experiments; any laboratory work should follow institutional review and safety protocols.

## Quick Repro Steps (example)

```bash
# create virtual environment
python3 -m venv .venv
. .venv/bin/activate
pip install -r requirements.txt

# run a basic LIV analysis example (labels are example-run values)
python scripts/uhecr_liv_analysis.py --input data/uhecr/sd1500_spectrum.csv --seed 42 --out outputs/uhecr_liv_results.json

# run UQ analysis
python src/validation/uncertainty_quantification.py --inputs outputs/uhecr_liv_results.json --out outputs/uq_report.json

When publishing numbers derived from this repository, include outputs/* artifacts and the commit ids used for this repo and any integrated repos.

Example components (short)

• scripts/ — analysis entrypoints (GRB, UHECR, combined constraints)
• examples/ — small end-to-end scripts that produce example-run outputs
• src/models/ — theoretical model implementations (polynomial dispersion, polymer-QED, gravity-rainbow)
• lv_energy_converter/ — exploratory scripts for energy-conversion thought-experiments (lab work must follow safety policy)

Conservative Rewording Examples

• "Perfect conservation" → "Observed conservation within the provided test configuration; requires reproducibility artifacts to generalize"
• "Gold transmutation" → "Exploratory transmutation calculations in a model; laboratory validation and safety review required before any experimental attempt"
• Numeric performance claims → "Observed in example-run; see examples/ and src/validation/ for reproduction"

Integration and Data Sources

• The code includes analysis recipes for publicly-available datasets (e.g., Pierre Auger public releases) and example placeholders. When using real observatory data, follow the source licensing and citation requirements and document the approximate dataset versions used.

License

This repository remains under the existing license. If you want, I can add a short contributor note asking maintainers to attach UQ artifacts when publishing numeric claims.