relativistic-simulator 0.1.0__tar.gz

relativistic_simulator-0.1.0/.gitignore

@@ -0,0 +1,20 @@
+# Python-generated files
+__pycache__/
+*.py[oc]
+build/
+dist/
+wheels/
+*.egg-info
+
+# Virtual environments
+.venv
+.wheel-test
+
+# Example and benchmark output
+examples/output/
+benchmark-results.txt
+
+# Tool caches
+.pytest_cache/
+.ruff_cache/
+.mypy_cache/

relativistic_simulator-0.1.0/.python-version

@@ -0,0 +1 @@
+3.12

relativistic_simulator-0.1.0/CHANGELOG.md

@@ -0,0 +1,21 @@
+# Changelog
+
+All notable changes to this project will be documented here.
+
+## [0.1.0] - 2026-09-13
+
+### Added
+
+- 1D special-relativistic massive-particle dynamics under constant force.
+- Numerically stable relativistic kinematics, energy, momentum, and proper-time functions.
+- Exact analytical solver and independent RK4 cross-check integrator.
+- Vectorized reproducible NumPy dataset generation.
+- Quantitative physical validation reports.
+- Optional pandas conversion and matplotlib plotting utilities.
+- Pytest test suite, examples, and uv/PyPI packaging configuration.
+
+### Scientific scope
+
+The model assumes flat Minkowski spacetime, one spatial dimension, constant rest mass,
+and an externally applied constant 1D force. It does not model gravity, fields,
+radiation reaction, quantum effects, or faster-than-light trajectories.

relativistic_simulator-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Mayank
+
+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.

relativistic_simulator-0.1.0/PKG-INFO

@@ -0,0 +1,196 @@
+Metadata-Version: 2.5
+Name: relativistic-simulator
+Version: 0.1.0
+Summary: 1D special-relativistic constant-force massive-particle dynamics simulator: a ground-truth physics engine for machine-learning research.
+Project-URL: Homepage, https://github.com/mayank/relativistic-simulator
+Project-URL: Repository, https://github.com/mayank/relativistic-simulator
+Project-URL: Changelog, https://github.com/mayank/relativistic-simulator/blob/main/CHANGELOG.md
+Author: Mayank
+License-Expression: MIT
+License-File: LICENSE
+Keywords: machine-learning,physics,relativity,scientific-computing,simulation,special-relativity,synthetic-data
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Science/Research
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Scientific/Engineering :: Physics
+Classifier: Typing :: Typed
+Requires-Python: >=3.10
+Requires-Dist: numpy>=1.24
+Provides-Extra: all
+Requires-Dist: matplotlib>=3.5; extra == 'all'
+Requires-Dist: pandas>=2.0; extra == 'all'
+Provides-Extra: pandas
+Requires-Dist: pandas>=2.0; extra == 'pandas'
+Provides-Extra: plot
+Requires-Dist: matplotlib>=3.5; extra == 'plot'
+Description-Content-Type: text/markdown
+
+# relativistic-simulator
+
+Research-grade, lightweight Python simulator for **1D special-relativistic massive-particle dynamics under a constant external force**.
+
+This package is the ground-truth physics engine for a synthetic-data/ML research pipeline. It generates data from known equations; it does not discover physics and it does not contain an ML model.
+
+## Scientific assumptions
+
+- flat Minkowski spacetime and special relativity;
+- one spatial dimension;
+- constant rest mass;
+- externally applied constant 1D force;
+- SI units;
+- no gravity, curved spacetime, electromagnetic-field model, radiation reaction, quantum effects, or FTL dynamics.
+
+The governing equation is `dp/dt = F` with `p = gamma*m*v`, not classical `F = m*a`.
+
+## Installation
+
+```bash
+pip install relativistic-simulator
+pip install "relativistic-simulator[all]"  # optional pandas + matplotlib
+```
+
+Development uses uv:
+
+```bash
+uv sync
+```
+
+## Quick start
+
+```python
+from relativistic_simulator import C, simulate
+
+result = simulate(
+    mass=1000.0, force=1e6, initial_velocity=0.9 * C,
+    duration=100.0, dt=0.01,
+)
+
+print(result.beta)
+print(result.gamma)
+print(result.momentum)
+print(result.kinetic_energy)
+print(result.total_energy)
+print(result.proper_time)
+print(result.validate().summary())
+```
+
+`simulate()` returns a `Trajectory` exposing `time`, `position`, `velocity`, `beta`, `gamma`, `momentum`, `kinetic_energy`, `total_energy`, and `proper_time`, plus `to_numpy()`, `to_dict()`, `to_dataframe()`, and `final_state()`.
+
+## Equations and numerical method
+
+For initial momentum `p0 = gamma0*m*v0`:
+
+```text
+p(t) = p0 + F*t
+q(t) = p(t)/(m*c)
+gamma(t) = hypot(1, q(t))
+v(t) = c*q(t)/gamma(t)
+E(t) = c*hypot(m*c, p(t))
+K(t) = p(t)^2*c^2 / (E(t) + m*c^2)
+x(t) = x0 + c*t*(q(t) + q0)/(gamma(t) + gamma0)   [F != 0]
+```
+
+The position formula is algebraically equivalent to `(K-K0)/F`, but avoids catastrophic cancellation at high beta and small impulse. Proper time uses `dτ = dt/gamma` and a stable `log1p` rapidity-increment form. `simulate(method="numerical")` supplies an independent RK4 cross-check.
+
+See [`docs/physics.md`](docs/physics.md) for derivations and precision details.
+
+## Relativity API
+
+```python
+from relativistic_simulator import (
+    C, beta_from_velocity, velocity_from_beta, gamma_from_beta,
+    gamma_from_velocity, momentum_from_velocity, velocity_from_momentum,
+    energy_from_velocity, energy_from_momentum,
+    kinetic_energy_from_velocity, kinetic_energy_from_momentum, rest_energy,
+)
+
+gamma = gamma_from_beta(0.99999)
+```
+
+All functions accept scalars and NumPy arrays where practical. Massive-particle states must satisfy `abs(v) < C` and `abs(beta) < 1`; invalid states raise typed exceptions and are never silently clipped.
+
+## Dataset generation
+
+```python
+from relativistic_simulator import generate_dataset
+
+dataset = generate_dataset(
+    n_samples=100_000,
+    mass_range=(100.0, 10_000.0),
+    force_range=(1e4, 1e7),
+    beta_range=(0.0, 0.8),
+    time_range=(0.0, 100.0),
+    random_seed=42,
+)
+
+dataset.to_csv("train.csv")
+print(dataset.input_columns)
+print(dataset.output_columns)
+print(dataset.validate().summary())
+```
+
+Generation is fully vectorized with NumPy and uses `numpy.random.default_rng`, so seeded datasets are reproducible without global randomness. Inputs are `mass`, `force`, `initial_velocity`, `initial_beta`, and `time`; targets are exact `position`, `velocity`, `beta`, `gamma`, `momentum`, `kinetic_energy`, `total_energy`, and `proper_time`.
+
+Regimes are configurable rather than hard-coded:
+
+```python
+low = generate_dataset(beta_range=(0.0, 0.5), random_seed=1)
+relativistic = generate_dataset(beta_range=(0.5, 0.9), random_seed=2)
+ultra = generate_dataset(beta_range=(0.9, 0.9999), random_seed=3)
+training = generate_dataset(beta_range=(0.0, 0.8), random_seed=42)
+extrapolation = generate_dataset(beta_range=(0.8, 0.9999), random_seed=43)
+```
+
+## Validation
+
+`validate_trajectory` and `validate_dataset` report quantitative errors for `p = gamma*m*v`, `E = gamma*m*c²`, the energy-momentum invariant, central finite differences for `dp/dt` and `dx/dt`, proper time, initial conditions, velocity bound, and `tau <= t`. They use independent routes rather than merely repeating the generating expression.
+
+```python
+report = result.validate()
+print(report.max_energy_momentum_error)
+print(report.max_force_error)
+print(report.max_velocity_difference_error)
+print(report.passed)
+```
+
+## Optional plotting and classical comparison
+
+```python
+from relativistic_simulator.plotting import plot_trajectory, plot_gamma_vs_beta
+plot_trajectory(result, path="trajectory.png", show=False)
+plot_gamma_vs_beta(path="gamma.png", show=False)
+```
+
+The `classical` module is comparison-only: it provides Newtonian `p=m*v`, `K=0.5*m*v**2`, and `x=x0+v0*t+0.5*(F/m)*t**2`. It is not used by the relativistic engine.
+
+## Examples
+
+```bash
+uv run python examples/basic_simulation.py
+uv run python examples/high_beta.py
+uv run python examples/generate_dataset.py
+uv run python examples/benchmark.py
+```
+
+## Development, testing, and build
+
+```bash
+uv sync
+uv run pytest
+uv build
+```
+
+The suite covers high beta through `0.99999c`, invalid physical states, exact/RK4 agreement, vectorization, reproducibility, dataset validation, and optional plotting. `uv build` creates wheel and source distributions in `dist/`. Review and test those artifacts before any deliberate `uv publish`.
+
+## Precision and limitations
+
+The numerical representation is IEEE-754 float64. The package rejects `|v| >= c` rather than clipping and rejects states for which floating-point arithmetic cannot represent a strictly subluminal velocity. It does not model gravity, curved spacetime, electromagnetic fields, variable mass, radiation reaction, quantum effects, or FTL/spacelike trajectories.
+
+## License
+
+MIT License. See [`LICENSE`](LICENSE).

relativistic_simulator-0.1.0/README.md

@@ -0,0 +1,164 @@
+# relativistic-simulator
+
+Research-grade, lightweight Python simulator for **1D special-relativistic massive-particle dynamics under a constant external force**.
+
+This package is the ground-truth physics engine for a synthetic-data/ML research pipeline. It generates data from known equations; it does not discover physics and it does not contain an ML model.
+
+## Scientific assumptions
+
+- flat Minkowski spacetime and special relativity;
+- one spatial dimension;
+- constant rest mass;
+- externally applied constant 1D force;
+- SI units;
+- no gravity, curved spacetime, electromagnetic-field model, radiation reaction, quantum effects, or FTL dynamics.
+
+The governing equation is `dp/dt = F` with `p = gamma*m*v`, not classical `F = m*a`.
+
+## Installation
+
+```bash
+pip install relativistic-simulator
+pip install "relativistic-simulator[all]"  # optional pandas + matplotlib
+```
+
+Development uses uv:
+
+```bash
+uv sync
+```
+
+## Quick start
+
+```python
+from relativistic_simulator import C, simulate
+
+result = simulate(
+    mass=1000.0, force=1e6, initial_velocity=0.9 * C,
+    duration=100.0, dt=0.01,
+)
+
+print(result.beta)
+print(result.gamma)
+print(result.momentum)
+print(result.kinetic_energy)
+print(result.total_energy)
+print(result.proper_time)
+print(result.validate().summary())
+```
+
+`simulate()` returns a `Trajectory` exposing `time`, `position`, `velocity`, `beta`, `gamma`, `momentum`, `kinetic_energy`, `total_energy`, and `proper_time`, plus `to_numpy()`, `to_dict()`, `to_dataframe()`, and `final_state()`.
+
+## Equations and numerical method
+
+For initial momentum `p0 = gamma0*m*v0`:
+
+```text
+p(t) = p0 + F*t
+q(t) = p(t)/(m*c)
+gamma(t) = hypot(1, q(t))
+v(t) = c*q(t)/gamma(t)
+E(t) = c*hypot(m*c, p(t))
+K(t) = p(t)^2*c^2 / (E(t) + m*c^2)
+x(t) = x0 + c*t*(q(t) + q0)/(gamma(t) + gamma0)   [F != 0]
+```
+
+The position formula is algebraically equivalent to `(K-K0)/F`, but avoids catastrophic cancellation at high beta and small impulse. Proper time uses `dτ = dt/gamma` and a stable `log1p` rapidity-increment form. `simulate(method="numerical")` supplies an independent RK4 cross-check.
+
+See [`docs/physics.md`](docs/physics.md) for derivations and precision details.
+
+## Relativity API
+
+```python
+from relativistic_simulator import (
+    C, beta_from_velocity, velocity_from_beta, gamma_from_beta,
+    gamma_from_velocity, momentum_from_velocity, velocity_from_momentum,
+    energy_from_velocity, energy_from_momentum,
+    kinetic_energy_from_velocity, kinetic_energy_from_momentum, rest_energy,
+)
+
+gamma = gamma_from_beta(0.99999)
+```
+
+All functions accept scalars and NumPy arrays where practical. Massive-particle states must satisfy `abs(v) < C` and `abs(beta) < 1`; invalid states raise typed exceptions and are never silently clipped.
+
+## Dataset generation
+
+```python
+from relativistic_simulator import generate_dataset
+
+dataset = generate_dataset(
+    n_samples=100_000,
+    mass_range=(100.0, 10_000.0),
+    force_range=(1e4, 1e7),
+    beta_range=(0.0, 0.8),
+    time_range=(0.0, 100.0),
+    random_seed=42,
+)
+
+dataset.to_csv("train.csv")
+print(dataset.input_columns)
+print(dataset.output_columns)
+print(dataset.validate().summary())
+```
+
+Generation is fully vectorized with NumPy and uses `numpy.random.default_rng`, so seeded datasets are reproducible without global randomness. Inputs are `mass`, `force`, `initial_velocity`, `initial_beta`, and `time`; targets are exact `position`, `velocity`, `beta`, `gamma`, `momentum`, `kinetic_energy`, `total_energy`, and `proper_time`.
+
+Regimes are configurable rather than hard-coded:
+
+```python
+low = generate_dataset(beta_range=(0.0, 0.5), random_seed=1)
+relativistic = generate_dataset(beta_range=(0.5, 0.9), random_seed=2)
+ultra = generate_dataset(beta_range=(0.9, 0.9999), random_seed=3)
+training = generate_dataset(beta_range=(0.0, 0.8), random_seed=42)
+extrapolation = generate_dataset(beta_range=(0.8, 0.9999), random_seed=43)
+```
+
+## Validation
+
+`validate_trajectory` and `validate_dataset` report quantitative errors for `p = gamma*m*v`, `E = gamma*m*c²`, the energy-momentum invariant, central finite differences for `dp/dt` and `dx/dt`, proper time, initial conditions, velocity bound, and `tau <= t`. They use independent routes rather than merely repeating the generating expression.
+
+```python
+report = result.validate()
+print(report.max_energy_momentum_error)
+print(report.max_force_error)
+print(report.max_velocity_difference_error)
+print(report.passed)
+```
+
+## Optional plotting and classical comparison
+
+```python
+from relativistic_simulator.plotting import plot_trajectory, plot_gamma_vs_beta
+plot_trajectory(result, path="trajectory.png", show=False)
+plot_gamma_vs_beta(path="gamma.png", show=False)
+```
+
+The `classical` module is comparison-only: it provides Newtonian `p=m*v`, `K=0.5*m*v**2`, and `x=x0+v0*t+0.5*(F/m)*t**2`. It is not used by the relativistic engine.
+
+## Examples
+
+```bash
+uv run python examples/basic_simulation.py
+uv run python examples/high_beta.py
+uv run python examples/generate_dataset.py
+uv run python examples/benchmark.py
+```
+
+## Development, testing, and build
+
+```bash
+uv sync
+uv run pytest
+uv build
+```
+
+The suite covers high beta through `0.99999c`, invalid physical states, exact/RK4 agreement, vectorization, reproducibility, dataset validation, and optional plotting. `uv build` creates wheel and source distributions in `dist/`. Review and test those artifacts before any deliberate `uv publish`.
+
+## Precision and limitations
+
+The numerical representation is IEEE-754 float64. The package rejects `|v| >= c` rather than clipping and rejects states for which floating-point arithmetic cannot represent a strictly subluminal velocity. It does not model gravity, curved spacetime, electromagnetic fields, variable mass, radiation reaction, quantum effects, or FTL/spacelike trajectories.
+
+## License
+
+MIT License. See [`LICENSE`](LICENSE).

relativistic_simulator-0.1.0/docs/benchmarks.md

@@ -0,0 +1,11 @@
+# Benchmarks
+
+Run the benchmark yourself with:
+
+```bash
+uv run python examples/benchmark.py
+```
+
+The script reports wall-clock time, samples per second, and the NumPy storage footprint
+for 10,000, 100,000, and 1,000,000 vectorized observations. Benchmark values are
+machine-dependent and are intentionally not hard-coded in this document.

relativistic_simulator-0.1.0/docs/physics.md

@@ -0,0 +1,65 @@
+# Physics and numerical method
+
+## Model
+
+The package models a massive particle in one spatial dimension in flat Minkowski
+spacetime. Units are SI: mass in kg, force in N, position in m, velocity in m/s,
+time in s, momentum in kg m/s, and energy in J. The speed of light is the exact
+constant `C = 299792458.0 m/s`.
+
+The dynamical law is
+
+\[
+\frac{dp}{dt}=F, \qquad p=\gamma m v,
+\]
+
+not `F = m a`.
+
+## Exact solution
+
+For initial momentum \(p_0=\gamma_0mv_0\),
+
+\[
+p(t)=p_0+Ft,
+\quad q=\frac{p}{mc},
+\quad \gamma=\sqrt{1+q^2},
+\quad v=c\frac{q}{\gamma}.
+\]
+
+The total and kinetic energies are
+
+\[
+E=\sqrt{m^2c^4+p^2c^2},\qquad
+K=\frac{p^2c^2}{E+mc^2}.
+\]
+
+For nonzero force, position is evaluated in the cancellation-free form
+
+\[
+x(t)=x_0+ct\frac{q+q_0}{\gamma+\gamma_0}.
+\]
+
+This is algebraically equivalent to \(x_0+(K-K_0)/F\), but avoids subtracting two
+large nearly equal kinetic energies in high-beta, small-impulse cases. For zero force,
+\(x=x_0+v_0t\).
+
+Proper time is accumulated from \(d\tau=dt/\gamma\). The implementation uses a
+`log1p` rapidity-increment form, avoiding cancellation in
+`asinh(q) - asinh(q0)` when the impulse is tiny compared with the initial momentum.
+
+## Numerical safety
+
+- Inputs with `|v| >= c`, `|beta| >= 1`, nonpositive mass, nonfinite values, or invalid
+  integration steps raise typed exceptions.
+- Values are never silently clipped to the light cone.
+- `hypot` is used for square roots of sums of squares.
+- `gamma - 1` and `E - mc²` are evaluated through rationalized identities.
+- The exact solver is independent of the RK4 integrator used for cross-checking.
+
+## Validity limits
+
+This is not a general relativistic engine. It excludes gravity, curved spacetime,
+electromagnetic-field models, radiation reaction, variable mass, quantum effects,
+and spacelike/FTL trajectories. Float64 precision also limits how close a represented
+state can be to the light cone; such states are rejected if the computed velocity can
+no longer be represented as strictly subluminal.

relativistic_simulator-0.1.0/docs/validation.md

@@ -0,0 +1,15 @@
+# Validation methodology
+
+`validate_trajectory` and `validate_dataset` return measured errors rather than a
+single opaque boolean. Checks include:
+
+- `p = gamma*m*v`;
+- `E = gamma*m*c²`;
+- `E² - p²c² = m²c⁴`;
+- central finite differences for `dp/dt = F` and `dx/dt = v`;
+- trapezoidal integration of `dt/gamma` against proper time;
+- initial conditions and `tau <= t`;
+- independent RK4 versus analytical trajectory comparison in tests.
+
+The finite-difference checks intentionally use interior central differences. One-sided
+edge stencils can amplify floating-point roundoff even for bitwise-constant arrays.

relativistic_simulator-0.1.0/examples/basic_simulation.py

@@ -0,0 +1,43 @@
+"""Example 1: basic simulation of a massive particle under constant force.
+
+A 1000 kg object starting at rest, pushed by a constant 1e6 N force in +x
+for 100 seconds.  In the classical picture this would reach 1e5 m/s
+(0.03% of c) after 100 s; the relativistic solution is essentially identical
+because beta stays tiny.
+"""
+from __future__ import annotations
+
+import numpy as np
+
+from relativistic_simulator import C, simulate
+
+def main() -> None:
+    result = simulate(
+        mass=1000.0,           # kg
+        force=1e6,             # N
+        initial_velocity=0.0,  # m/s (at rest)
+        duration=100.0,        # s
+        dt=0.01,               # s
+    )
+
+    final = result.final_state()
+    classical_v = (1e6 / 1000.0) * 100.0  # v = (F/m) * t, Newtonian
+    classical_K = 0.5 * 1000.0 * classical_v**2
+
+    print("Basic simulation: 1000 kg at rest, F = 1e6 N, t = 100 s")
+    print(f"  n_points            : {result.n_points}")
+    print(f"  final position      : {final['position']:.6e} m")
+    print(f"  final velocity      : {final['velocity']:.6e} m/s  (beta = {final['beta']:.6e})")
+    print(f"  classical velocity  : {classical_v:.6e} m/s")
+    print(f"  final gamma         : {final['gamma']:.12f}")
+    print(f"  final momentum      : {final['momentum']:.6e} kg*m/s  (classical m*v = {1000*classical_v:.6e})")
+    print(f"  final kinetic energy: {final['kinetic_energy']:.6e} J  (classical = {classical_K:.6e} J)")
+    print(f"  proper time         : {final['proper_time']:.9f} s (<= 100 s: {final['proper_time'] <= 100.0})")
+
+    report = result.validate()
+    print()
+    print(report.summary())
+
+
+if __name__ == "__main__":
+    main()

relativistic_simulator-0.1.0/examples/benchmark.py

@@ -0,0 +1,21 @@
+"""Measure vectorized dataset-generation throughput on the current machine."""
+from __future__ import annotations
+
+import time
+
+from relativistic_simulator import generate_dataset
+
+
+def main() -> None:
+    print(f"{'samples':>12} {'seconds':>12} {'samples/sec':>16} {'MiB':>12}")
+    print("-" * 56)
+    for n in (10_000, 100_000, 1_000_000):
+        start = time.perf_counter()
+        dataset = generate_dataset(n_samples=n, random_seed=42)
+        elapsed = time.perf_counter() - start
+        mib = dataset.to_numpy().nbytes / (1024.0**2)
+        print(f"{n:12,d} {elapsed:12.6f} {n / elapsed:16,.0f} {mib:12.2f}")
+
+
+if __name__ == "__main__":
+    main()

relativistic_simulator-0.1.0/examples/generate_dataset.py

@@ -0,0 +1,87 @@
+"""Example 3: generate a ground-truth dataset for the future ML experiment.
+
+Research pipeline this supports (the ML part is NOT part of this package):
+
+    physics equations
+      -> relativistic-simulator (this package, exact physics)
+        -> thousands/millions of synthetic observations
+          -> (external) ML model
+            -> predictions on unseen ultra-relativistic regimes
+              -> comparison against exact physics
+
+Here we generate:
+  * a training regime      beta in (0.0, 0.8)
+  * an extrapolation regime beta in (0.8, 0.9999)
+with a fixed random seed for reproducibility, and save both to CSV.
+"""
+from __future__ import annotations
+
+from pathlib import Path
+
+import numpy as np
+
+from relativistic_simulator import generate_dataset
+
+OUTPUT_DIR = Path(__file__).parent / "output"
+N_TRAIN = 100_000
+N_EXTRAP = 20_000
+SEED = 42
+
+
+def main() -> None:
+    OUTPUT_DIR.mkdir(exist_ok=True)
+
+    print("Generating ground-truth data (exact physics, seeded) ...")
+    train = generate_dataset(
+        n_samples=N_TRAIN,
+        mass_range=(100.0, 10_000.0),
+        force_range=(1e4, 1e7),
+        beta_range=(0.0, 0.8),          # training regime
+        time_range=(0.0, 100.0),
+        random_seed=SEED,
+    )
+    extrap = generate_dataset(
+        n_samples=N_EXTRAP,
+        mass_range=(100.0, 10_000.0),
+        force_range=(1e4, 1e7),
+        beta_range=(0.8, 0.9999),       # unseen ultra-relativistic regime
+        time_range=(0.0, 100.0),
+        random_seed=SEED + 1,
+    )
+
+    train_csv = OUTPUT_DIR / "train_beta_0_0.8.csv"
+    extrap_csv = OUTPUT_DIR / "extrap_beta_0.8_0.9999.csv"
+    train.to_csv(str(train_csv))
+    extrap.to_csv(str(extrap_csv))
+
+    print()
+    print(f"train    : {len(train):>7} rows, beta in [{train.initial_beta.min():.4f}, "
+          f"{train.initial_beta.max():.4f}] -> {train_csv.name}")
+    print(f"extrap   : {len(extrap):>7} rows, beta in [{extrap.initial_beta.min():.4f}, "
+          f"{extrap.initial_beta.max():.4f}] -> {extrap_csv.name}")
+    print()
+    print("input columns :", train.input_columns)
+    print("target columns:", train.output_columns)
+
+    report = train.validate()
+    assert report.passed, report.summary()
+    print()
+    print(f"train physics validation: passed={report.passed}, "
+          f"max invariant err = {report.max_energy_momentum_error:.2e}, "
+          f"max momentum err  = {report.max_momentum_relation_error:.2e}")
+
+    # Reproducibility check: same seed -> bitwise-identical data
+    again = generate_dataset(
+        n_samples=N_TRAIN,
+        mass_range=(100.0, 10_000.0),
+        force_range=(1e4, 1e7),
+        beta_range=(0.0, 0.8),
+        time_range=(0.0, 100.0),
+        random_seed=SEED,
+    )
+    assert np.array_equal(train.momentum, again.momentum)
+    print("reproducibility: same seed reproduces bitwise-identical data")
+
+
+if __name__ == "__main__":
+    main()