radiapy 0.1.0__tar.gz

radiapy-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2024 Radiapy Contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

radiapy-0.1.0/PKG-INFO

@@ -0,0 +1,285 @@
+Metadata-Version: 2.4
+Name: radiapy
+Version: 0.1.0
+Summary: Interactive visualization of radiation experiments and radiation-matter interactions
+Author: Radiapy Contributors
+License: MIT License
+        
+        Copyright (c) 2024 Radiapy Contributors
+        
+        Permission is hereby granted, free of charge, to any person obtaining a copy
+        of this software and associated documentation files (the "Software"), to deal
+        in the Software without restriction, including without limitation the rights
+        to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+        copies of the Software, and to permit persons to whom the Software is
+        furnished to do so, subject to the following conditions:
+        
+        The above copyright notice and this permission notice shall be included in all
+        copies or substantial portions of the Software.
+        
+        THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+        IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+        FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+        AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+        LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+        OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+        SOFTWARE.
+        
+Project-URL: Homepage, https://github.com/radviz/radiapy
+Project-URL: Documentation, https://radiapy.readthedocs.io
+Project-URL: Bug Tracker, https://github.com/radviz/radiapy/issues
+Keywords: radiation,physics,visualization,geiger,attenuation,beer-lambert
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Science/Research
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Scientific/Engineering :: Physics
+Classifier: Topic :: Scientific/Engineering :: Visualization
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: plotly>=5.15.0
+Requires-Dist: pandas>=2.0.0
+Requires-Dist: numpy>=1.24.0
+Requires-Dist: scipy>=1.10.0
+Requires-Dist: click>=8.1.0
+Provides-Extra: dev
+Requires-Dist: pytest>=7.0; extra == "dev"
+Requires-Dist: pytest-cov; extra == "dev"
+Requires-Dist: jupyter>=1.0.0; extra == "dev"
+Requires-Dist: kaleido>=0.2.1; extra == "dev"
+Requires-Dist: build>=1.0.0; extra == "dev"
+Requires-Dist: twine>=4.0.0; extra == "dev"
+Dynamic: license-file
+
+# Radiapy
+
+**Interactive visualization of radiation experiments and radiation-matter interactions.**
+
+Radiapy is an open-source Python library for analysing and visualising Geiger-counter radiation attenuation experiments. It implements the Beer-Lambert law, the inverse-square law, and NIST photon attenuation data, and renders every plot as an interactive Plotly figure exportable to standalone HTML — no ROOT, VTK, or GEANT4 required.
+
+---
+
+## Installation
+
+```bash
+pip install radiapy
+```
+
+Or from source:
+
+```bash
+git clone https://github.com/radviz/radiapy
+cd radiapy
+pip install -e ".[dev]"
+```
+
+**Requirements:** Python ≥ 3.10, plotly, pandas, numpy, scipy, click
+
+---
+
+## Quick start
+
+```python
+from radviz import RadViz
+
+rv = RadViz("radviz/demo/dataset_geiger.csv")
+
+# Generate a complete standalone HTML dashboard
+rv.generate_dashboard("dashboard.html")
+
+# Individual interactive plots
+fig = rv.plot_attenuation()           # Bar chart: T by material + NIST overlay
+fig = rv.plot_inverse_square()        # Counts vs distance + 1/r² fit
+fig = rv.plot_heatmap()               # 2-D transmission heatmap
+fig = rv.plot_comparison()            # Cd109 vs Am241 side-by-side
+fig = rv.plot_particles()             # Animated photon trajectories
+fig.show()
+
+# Physics report
+print(rv.physics_report())
+```
+
+## Command-line interface
+
+```bash
+# Full dashboard
+radviz dashboard dataset_geiger.csv --output dashboard.html
+
+# Physics report
+radviz report dataset_geiger.csv
+
+# Particle animation (no CSV needed)
+radviz simulate --isotope Cd109 --material Pb --output anim.html
+
+# Legacy single-command form
+radviz --input dataset_geiger.csv --output dashboard.html
+```
+
+---
+
+## Dataset format
+
+The bundled `dataset_geiger.csv` has the following columns:
+
+| Column | Description |
+|--------|-------------|
+| `isotope` | Source isotope (`Cd109` or `Am241`) |
+| `distance_cm` | Source-detector distance (10, 20, 30 cm) |
+| `counts_free` | Raw counts without absorber |
+| `counts_Al` | Counts through aluminium filter |
+| `counts_Cu` | Counts through copper filter |
+| `counts_Pb` | Counts through lead filter |
+| `counts_free_mean` | Mean free-field counts for this (isotope, distance) group |
+| `Al_ratio` | Transmission fraction: `counts_Al / counts_free` |
+| `Cu_ratio` | Transmission fraction: `counts_Cu / counts_free` |
+| `Pb_ratio` | Transmission fraction: `counts_Pb / counts_free` |
+
+To use a custom CSV, pass a `schema` dict to `RadViz`:
+
+```python
+schema = {
+    "isotope_col": "source",
+    "distance_col": "dist_cm",
+    "free_count_col": "N_free",
+    "filter_cols": {"Al": "N_Al", "Cu": "N_Cu", "Pb": "N_Pb"},
+}
+rv = RadViz("my_data.csv", schema=schema)
+```
+
+---
+
+## Physics Background
+
+### Beer-Lambert attenuation law
+
+When a beam of photons passes through a material of thickness *x* (cm), its intensity is reduced according to:
+
+```
+I = I₀ · exp(−μ · x)
+```
+
+where:
+- `I₀` is the incident intensity (counts without absorber),
+- `I` is the transmitted intensity,
+- `μ` (cm⁻¹) is the **linear attenuation coefficient**, which depends on the material and the photon energy,
+- `T = I / I₀ ∈ [0, 1]` is the **transmission fraction**.
+
+The linear coefficient relates to the tabulated **mass attenuation coefficient** as `μ = (μ/ρ) · ρ`, where `ρ` is the material density (g/cm³).
+
+Radiapy fits `μ` experimentally from the measured transmission ratios via `scipy.optimize.curve_fit` (with full covariance matrix for uncertainty propagation), and compares each fitted value against the NIST reference. The experimental coefficient is back-calculated as `μ_exp = −ln(T_exp) / x`.
+
+### Inverse-square law
+
+For a point source radiating isotropically, the intensity at distance *r* from the source falls off as:
+
+```
+I(r) = A / r²
+```
+
+where `A` is a constant proportional to the source activity and detector efficiency. This geometric dilution of intensity over the surface of an expanding sphere means that doubling the distance reduces counts to one quarter. Radiapy fits `A` with uncertainty via `scipy.optimize.curve_fit` and reports R² as a goodness-of-fit metric.
+
+A diagnostic plot of `I · r²` vs `r` (the "1/r² diagnostic" tab) should yield a horizontal line; deviations indicate room scatter, geometry effects, or a non-point-like source.
+
+### The Pb K-edge and the counterintuitive Cd-109 / Am-241 reversal
+
+Every element has characteristic **absorption edges** — energies at which a new inner-shell photoelectric absorption channel opens as photon energy increases past the binding energy of that electron shell. For **lead (Pb)**, the K-shell binding energy is **88.005 keV**.
+
+The two isotopes in this experiment straddle that edge:
+
+| Isotope | Main γ energy | Position relative to Pb K-edge |
+|---------|--------------|-------------------------------|
+| Am-241  | 59.54 keV    | **Below** — K shell cannot be ionised |
+| Cd-109  | 88.034 keV   | **Just above** — K shell is ionised |
+
+This creates a **counterintuitive reversal**: even though Cd-109 photons are *higher energy* than Am-241 photons (and high-energy photons generally penetrate matter more easily), Pb attenuates Cd-109 *more strongly* because the K-shell photoelectric cross-section is suddenly available. The `μ/ρ` of Pb jumps from ~2.0 cm²/g just below the edge to ~13.9 cm²/g just above — a ~7× increase. This effect is clearly visible in the **Cd109 vs Am241** comparison tab of the dashboard.
+
+### NIST reference data
+
+All theoretical values are taken from:
+
+- **NIST XCOM** — *Photon Cross Sections Database*, Standard Reference Database 8 (XGAM).  
+  Berger, M.J., Hubbell, J.H., Seltzer, S.M., Chang, J., Coursey, J.S., Sukumar, R., Zucker, D.S., and Olsen, K.  
+  https://physics.nist.gov/PhysRefData/Xcom/html/xcom1.html
+
+- **NIST Standard Reference Database 126** — *X-Ray Mass Attenuation Coefficients*, J.H. Hubbell and S.M. Seltzer.  
+  https://www.nist.gov/pml/x-ray-mass-attenuation-coefficients
+
+---
+
+## NIST data
+
+Hardcoded `μ/ρ` values (cm²/g) from [NIST XCOM](https://physics.nist.gov/PhysRefData/Xcom/html/xcom1.html):
+
+| Material | ρ (g/cm³) | μ/ρ @ 59.5 keV | μ/ρ @ 88.034 keV |
+|----------|-----------|----------------|------------------|
+| Al | 2.699 | 0.3219 | 0.2226 |
+| Cu | 8.960 | 0.8156 | 0.5082 |
+| Pb | 11.35 | 5.549 | 13.93* |
+
+\* Above Pb K-edge (88.005 keV).
+
+---
+
+## Demo dataset
+
+Regenerate the synthetic demo dataset (Poisson-distributed, 50 replicates × 6 conditions):
+
+```bash
+python scripts/generate_demo_data.py
+```
+
+---
+
+## Project structure
+
+```
+radiapy/
+├── __init__.py          # from radiapy import RadViz
+├── __main__.py          # python -m radiapy CSV [--output FILE]
+├── core.py              # RadViz orchestrator class
+├── cli.py               # Click CLI (radiapy dashboard / report / simulate)
+├── parsers/
+│   ├── base_parser.py   # Abstract base + GroupStats + ParsedDataset
+│   ├── csv_parser.py    # Generic CSV → ParsedDataset
+│   └── geant4_parser.py # GEANT4 ASCII output → ParsedDataset
+├── physics/
+│   ├── attenuation.py   # Beer-Lambert fit (curve_fit + pcov)
+│   ├── inverse_square.py# 1/r² fit
+│   └── nist_data.py     # NIST μ/ρ table, filter thicknesses
+├── visualizers/
+│   ├── attenuation_viz.py
+│   ├── distance_viz.py
+│   ├── comparison_viz.py
+│   └── particle_viz.py  # Photon trajectories with thickness slider
+├── exporters/
+│   └── html_exporter.py # Standalone HTML dashboard (Plotly.js inline)
+└── demo/
+    └── dataset_geiger.csv
+```
+
+---
+
+## Citation
+
+If you use Radiapy in scientific work, please cite:
+
+```bibtex
+@software{radiapy2024,
+  title   = {Radiapy: Interactive visualization of radiation experiments},
+  year    = {2024},
+  url     = {https://github.com/radviz/radiapy},
+  version = {0.1.0}
+}
+```
+
+Dataset: experimental Geiger-counter measurements of Cd-109 and Am-241 attenuation through Al, Cu, and Pb absorbers.
+
+---
+
+## License
+
+MIT — see [LICENSE](LICENSE).

radiapy-0.1.0/README.md

@@ -0,0 +1,228 @@
+# Radiapy
+
+**Interactive visualization of radiation experiments and radiation-matter interactions.**
+
+Radiapy is an open-source Python library for analysing and visualising Geiger-counter radiation attenuation experiments. It implements the Beer-Lambert law, the inverse-square law, and NIST photon attenuation data, and renders every plot as an interactive Plotly figure exportable to standalone HTML — no ROOT, VTK, or GEANT4 required.
+
+---
+
+## Installation
+
+```bash
+pip install radiapy
+```
+
+Or from source:
+
+```bash
+git clone https://github.com/radviz/radiapy
+cd radiapy
+pip install -e ".[dev]"
+```
+
+**Requirements:** Python ≥ 3.10, plotly, pandas, numpy, scipy, click
+
+---
+
+## Quick start
+
+```python
+from radviz import RadViz
+
+rv = RadViz("radviz/demo/dataset_geiger.csv")
+
+# Generate a complete standalone HTML dashboard
+rv.generate_dashboard("dashboard.html")
+
+# Individual interactive plots
+fig = rv.plot_attenuation()           # Bar chart: T by material + NIST overlay
+fig = rv.plot_inverse_square()        # Counts vs distance + 1/r² fit
+fig = rv.plot_heatmap()               # 2-D transmission heatmap
+fig = rv.plot_comparison()            # Cd109 vs Am241 side-by-side
+fig = rv.plot_particles()             # Animated photon trajectories
+fig.show()
+
+# Physics report
+print(rv.physics_report())
+```
+
+## Command-line interface
+
+```bash
+# Full dashboard
+radviz dashboard dataset_geiger.csv --output dashboard.html
+
+# Physics report
+radviz report dataset_geiger.csv
+
+# Particle animation (no CSV needed)
+radviz simulate --isotope Cd109 --material Pb --output anim.html
+
+# Legacy single-command form
+radviz --input dataset_geiger.csv --output dashboard.html
+```
+
+---
+
+## Dataset format
+
+The bundled `dataset_geiger.csv` has the following columns:
+
+| Column | Description |
+|--------|-------------|
+| `isotope` | Source isotope (`Cd109` or `Am241`) |
+| `distance_cm` | Source-detector distance (10, 20, 30 cm) |
+| `counts_free` | Raw counts without absorber |
+| `counts_Al` | Counts through aluminium filter |
+| `counts_Cu` | Counts through copper filter |
+| `counts_Pb` | Counts through lead filter |
+| `counts_free_mean` | Mean free-field counts for this (isotope, distance) group |
+| `Al_ratio` | Transmission fraction: `counts_Al / counts_free` |
+| `Cu_ratio` | Transmission fraction: `counts_Cu / counts_free` |
+| `Pb_ratio` | Transmission fraction: `counts_Pb / counts_free` |
+
+To use a custom CSV, pass a `schema` dict to `RadViz`:
+
+```python
+schema = {
+    "isotope_col": "source",
+    "distance_col": "dist_cm",
+    "free_count_col": "N_free",
+    "filter_cols": {"Al": "N_Al", "Cu": "N_Cu", "Pb": "N_Pb"},
+}
+rv = RadViz("my_data.csv", schema=schema)
+```
+
+---
+
+## Physics Background
+
+### Beer-Lambert attenuation law
+
+When a beam of photons passes through a material of thickness *x* (cm), its intensity is reduced according to:
+
+```
+I = I₀ · exp(−μ · x)
+```
+
+where:
+- `I₀` is the incident intensity (counts without absorber),
+- `I` is the transmitted intensity,
+- `μ` (cm⁻¹) is the **linear attenuation coefficient**, which depends on the material and the photon energy,
+- `T = I / I₀ ∈ [0, 1]` is the **transmission fraction**.
+
+The linear coefficient relates to the tabulated **mass attenuation coefficient** as `μ = (μ/ρ) · ρ`, where `ρ` is the material density (g/cm³).
+
+Radiapy fits `μ` experimentally from the measured transmission ratios via `scipy.optimize.curve_fit` (with full covariance matrix for uncertainty propagation), and compares each fitted value against the NIST reference. The experimental coefficient is back-calculated as `μ_exp = −ln(T_exp) / x`.
+
+### Inverse-square law
+
+For a point source radiating isotropically, the intensity at distance *r* from the source falls off as:
+
+```
+I(r) = A / r²
+```
+
+where `A` is a constant proportional to the source activity and detector efficiency. This geometric dilution of intensity over the surface of an expanding sphere means that doubling the distance reduces counts to one quarter. Radiapy fits `A` with uncertainty via `scipy.optimize.curve_fit` and reports R² as a goodness-of-fit metric.
+
+A diagnostic plot of `I · r²` vs `r` (the "1/r² diagnostic" tab) should yield a horizontal line; deviations indicate room scatter, geometry effects, or a non-point-like source.
+
+### The Pb K-edge and the counterintuitive Cd-109 / Am-241 reversal
+
+Every element has characteristic **absorption edges** — energies at which a new inner-shell photoelectric absorption channel opens as photon energy increases past the binding energy of that electron shell. For **lead (Pb)**, the K-shell binding energy is **88.005 keV**.
+
+The two isotopes in this experiment straddle that edge:
+
+| Isotope | Main γ energy | Position relative to Pb K-edge |
+|---------|--------------|-------------------------------|
+| Am-241  | 59.54 keV    | **Below** — K shell cannot be ionised |
+| Cd-109  | 88.034 keV   | **Just above** — K shell is ionised |
+
+This creates a **counterintuitive reversal**: even though Cd-109 photons are *higher energy* than Am-241 photons (and high-energy photons generally penetrate matter more easily), Pb attenuates Cd-109 *more strongly* because the K-shell photoelectric cross-section is suddenly available. The `μ/ρ` of Pb jumps from ~2.0 cm²/g just below the edge to ~13.9 cm²/g just above — a ~7× increase. This effect is clearly visible in the **Cd109 vs Am241** comparison tab of the dashboard.
+
+### NIST reference data
+
+All theoretical values are taken from:
+
+- **NIST XCOM** — *Photon Cross Sections Database*, Standard Reference Database 8 (XGAM).  
+  Berger, M.J., Hubbell, J.H., Seltzer, S.M., Chang, J., Coursey, J.S., Sukumar, R., Zucker, D.S., and Olsen, K.  
+  https://physics.nist.gov/PhysRefData/Xcom/html/xcom1.html
+
+- **NIST Standard Reference Database 126** — *X-Ray Mass Attenuation Coefficients*, J.H. Hubbell and S.M. Seltzer.  
+  https://www.nist.gov/pml/x-ray-mass-attenuation-coefficients
+
+---
+
+## NIST data
+
+Hardcoded `μ/ρ` values (cm²/g) from [NIST XCOM](https://physics.nist.gov/PhysRefData/Xcom/html/xcom1.html):
+
+| Material | ρ (g/cm³) | μ/ρ @ 59.5 keV | μ/ρ @ 88.034 keV |
+|----------|-----------|----------------|------------------|
+| Al | 2.699 | 0.3219 | 0.2226 |
+| Cu | 8.960 | 0.8156 | 0.5082 |
+| Pb | 11.35 | 5.549 | 13.93* |
+
+\* Above Pb K-edge (88.005 keV).
+
+---
+
+## Demo dataset
+
+Regenerate the synthetic demo dataset (Poisson-distributed, 50 replicates × 6 conditions):
+
+```bash
+python scripts/generate_demo_data.py
+```
+
+---
+
+## Project structure
+
+```
+radiapy/
+├── __init__.py          # from radiapy import RadViz
+├── __main__.py          # python -m radiapy CSV [--output FILE]
+├── core.py              # RadViz orchestrator class
+├── cli.py               # Click CLI (radiapy dashboard / report / simulate)
+├── parsers/
+│   ├── base_parser.py   # Abstract base + GroupStats + ParsedDataset
+│   ├── csv_parser.py    # Generic CSV → ParsedDataset
+│   └── geant4_parser.py # GEANT4 ASCII output → ParsedDataset
+├── physics/
+│   ├── attenuation.py   # Beer-Lambert fit (curve_fit + pcov)
+│   ├── inverse_square.py# 1/r² fit
+│   └── nist_data.py     # NIST μ/ρ table, filter thicknesses
+├── visualizers/
+│   ├── attenuation_viz.py
+│   ├── distance_viz.py
+│   ├── comparison_viz.py
+│   └── particle_viz.py  # Photon trajectories with thickness slider
+├── exporters/
+│   └── html_exporter.py # Standalone HTML dashboard (Plotly.js inline)
+└── demo/
+    └── dataset_geiger.csv
+```
+
+---
+
+## Citation
+
+If you use Radiapy in scientific work, please cite:
+
+```bibtex
+@software{radiapy2024,
+  title   = {Radiapy: Interactive visualization of radiation experiments},
+  year    = {2024},
+  url     = {https://github.com/radviz/radiapy},
+  version = {0.1.0}
+}
+```
+
+Dataset: experimental Geiger-counter measurements of Cd-109 and Am-241 attenuation through Al, Cu, and Pb absorbers.
+
+---
+
+## License
+
+MIT — see [LICENSE](LICENSE).

radiapy-0.1.0/pyproject.toml

@@ -0,0 +1,60 @@
+[build-system]
+requires = ["setuptools>=61", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "radiapy"
+version = "0.1.0"
+description = "Interactive visualization of radiation experiments and radiation-matter interactions"
+readme = "README.md"
+license = {file = "LICENSE"}
+authors = [
+    {name = "Radiapy Contributors"}
+]
+keywords = ["radiation", "physics", "visualization", "geiger", "attenuation", "beer-lambert"]
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "Intended Audience :: Science/Research",
+    "License :: OSI Approved :: MIT License",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Topic :: Scientific/Engineering :: Physics",
+    "Topic :: Scientific/Engineering :: Visualization",
+]
+requires-python = ">=3.10"
+dependencies = [
+    "plotly>=5.15.0",       # interactive figures + offline JS bundle
+    "pandas>=2.0.0",        # CSV parsing and DataFrame operations
+    "numpy>=1.24.0",        # numerical arrays and Poisson statistics
+    "scipy>=1.10.0",        # curve_fit (Beer-Lambert + 1/r² fits), t-distribution
+    "click>=8.1.0",         # CLI (radiapy dashboard / report / simulate)
+]
+
+[project.optional-dependencies]
+dev = [
+    "pytest>=7.0",
+    "pytest-cov",
+    "jupyter>=1.0.0",
+    "kaleido>=0.2.1",       # static image export (PNG/SVG) from Plotly figures
+    "build>=1.0.0",         # python -m build
+    "twine>=4.0.0",         # twine upload dist/*
+]
+
+[project.scripts]
+radiapy = "radiapy.cli:main"
+
+[project.urls]
+Homepage = "https://github.com/radviz/radiapy"
+Documentation = "https://radiapy.readthedocs.io"
+"Bug Tracker" = "https://github.com/radviz/radiapy/issues"
+
+[tool.setuptools.packages.find]
+where = ["."]
+include = ["radiapy*"]
+
+[tool.setuptools.package-data]
+# The demo CSV is in demo/ at the project root, not inside the package.
+# Users access it via the bundled path or their own datasets.
+radiapy = []

radiapy-0.1.0/radiapy/__init__.py

@@ -0,0 +1,20 @@
+"""
+Radiapy — Interactive visualization of radiation experiments.
+
+Quick start::
+
+    from radiapy import RadViz
+
+    rv = RadViz("dataset_geiger.csv")
+    rv.generate_dashboard("dashboard.html")
+
+Or visualize a single plot::
+
+    fig = rv.plot_attenuation()
+    fig.show()
+"""
+
+from radiapy.core import RadViz
+
+__version__ = "0.1.0"
+__all__ = ["RadViz"]

radiapy-0.1.0/radiapy/__main__.py

@@ -0,0 +1,82 @@
+"""Entry point for ``python -m radiapy CSV_FILE [options]``.
+
+Usage
+-----
+    python -m radiapy demo/dataset_geiger.csv
+    python -m radiapy demo/dataset_geiger.csv --output my_report.html
+    python -m radiapy demo/dataset_geiger.csv --report-only
+"""
+
+from __future__ import annotations
+
+import argparse
+import sys
+from pathlib import Path
+
+
+def _parse_args(argv: list[str] | None = None) -> argparse.Namespace:
+    p = argparse.ArgumentParser(
+        prog="python -m radiapy",
+        description="Radiapy — interactive radiation experiment visualizer",
+        formatter_class=argparse.RawDescriptionHelpFormatter,
+        epilog="""
+examples:
+  python -m radiapy demo/dataset_geiger.csv
+  python -m radiapy demo/dataset_geiger.csv --output report.html
+  python -m radiapy demo/dataset_geiger.csv --report-only
+        """,
+    )
+    p.add_argument("csv_file", metavar="CSV_FILE", help="Geiger-counter CSV dataset")
+    p.add_argument(
+        "--output", "-o",
+        default="dashboard.html",
+        metavar="FILE",
+        help="Output HTML dashboard path (default: dashboard.html)",
+    )
+    p.add_argument(
+        "--report-only",
+        action="store_true",
+        help="Print the physics report to stdout without generating HTML",
+    )
+    return p.parse_args(argv)
+
+
+def main(argv: list[str] | None = None) -> int:
+    args = _parse_args(argv)
+    csv_path = Path(args.csv_file)
+
+    if not csv_path.exists():
+        print(f"ERROR: file not found — {csv_path}", file=sys.stderr)
+        return 1
+
+    from radiapy.core import RadViz
+
+    print("=" * 60)
+    print("  Radiapy v0.1.0 — Radiation Experiment Visualizer")
+    print("=" * 60)
+
+    rv = RadViz(csv_path)
+
+    print(f"\nDataset loaded:  {csv_path}")
+    print(f"  Isotopes   : {', '.join(rv.dataset.isotopes)}")
+    print(f"  Distances  : {rv.dataset.distances} cm")
+    print(f"  Materials  : {', '.join(rv.dataset.materials)}")
+    print(f"  Total rows : {len(rv.dataset.raw)}")
+    print()
+
+    print(rv.physics_report())
+
+    if args.report_only:
+        return 0
+
+    out = rv.generate_dashboard(args.output)
+    size_kb = out.stat().st_size // 1024
+    print(f"\nDashboard saved : {out.resolve()}")
+    print(f"File size       : {size_kb} KB")
+    print(f"\nOpen in browser :")
+    print(f"  open {out}")
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())