FROSTYVERSE — PERIHELION / APSIDAL PRECESSION PYTHON TEST
========================================================

START HERE
----------
You do not need to accept the Frostyverse as a real theory to use this package.
This is a reproducibility/falsification tool: reproduce a known result, enter a
fresh orbit of your own, and see whether the calculation continues to behave as
claimed.

The shortest reviewer workflow is:
  1. Create/activate a Python virtual environment (recommended).
  2. Install the declared public dependencies from requirements.txt.
  3. Verify the three frozen historical archives.
  4. Reproduce a quick R20 reference case.
  5. Optionally reproduce R40 or the publication-resolution R80 case.
  6. Run the interactive menu and choose "2. Test your own orbit" for a fresh case.

REQUIREMENTS
------------
- Python 3.10 or newer (historical development runs used Python 3.10.6)
- NumPy
- SciPy (the preserved numerical field solver uses scipy.fft)

Install the public dependencies with:
  python -m pip install -r requirements.txt

No third-party library is bundled. Everything project-specific to this
Frostyverse test is included in this ZIP.

QUICK START — RECOMMENDED ISOLATED ENVIRONMENT
----------------------------------------------
First extract this ZIP, then open a terminal/console in the extracted
Frostyverse_Precession_Python_Test directory.

Windows PowerShell:
  py -3 -m venv .venv
  .\.venv\Scripts\Activate.ps1

Windows Command Prompt (alternative activation):
  py -3 -m venv .venv
  .venv\Scripts\activate.bat

macOS / Linux / WSL Ubuntu:
  python3 -m venv .venv
  source .venv/bin/activate

Once the environment is active, install dependencies:
  python -m pip install --upgrade pip
  python -m pip install -r requirements.txt

You should normally see the environment name, such as (.venv), at the start of
your terminal prompt after activation.

STEP 1 — VERIFY THE FROZEN RESEARCH ARCHIVES
--------------------------------------------
Run:
  python lab_test.py --verify

Expected success output includes:
  H2-087: archive hash OK
  H2-089: archive hash OK
  H2-092: archive hash OK

This check confirms that the three historical research ZIPs bundled under
original/ are byte-for-byte the preserved versions expected by the wrapper.

STEP 2 — REPRODUCE A REFERENCE RESULT
-------------------------------------
The command-line --reference flag lets you run a specific numerical resolution
without entering the interactive menu.

Quick reference test:
  python lab_test.py --reference 20

Recommended intermediate test:
  python lab_test.py --reference 40

Publication-resolution reference test:
  python lab_test.py --reference 80

Reference resolutions:
  R20  Quick. Roughly 64 MB main field array in the preserved solver.
  R40  Recommended. Roughly 0.51 GB main field array. Reproduces the archived
       Icarus R40 row on an ordinary modern workstation.
  R80  Publication resolution. Roughly 4.1 GB main field array before Python/
       NumPy/SciPy overhead. Use only if the machine has ample free RAM.

R80 is intentionally not replaced by a lower-memory fitted surrogate. The
historical result remains preserved in EXPECTED_RESULTS.txt.

STEP 3 — TEST YOUR OWN ORBIT (INTERACTIVE MODE)
----------------------------------------------
Run the program with no flags:
  python lab_test.py

The main menu will appear. Choose:
  2. Test your own orbit

The program then asks, in order, for:
  1. Case label — any descriptive name for your run.
  2. Central source — Sun, Earth, Jupiter, or a custom source GM.
  3. Secondary/body GM in km^3/s^2 — enter 0 for a test particle.
  4. Semi-major-axis unit — km or AU.
  5. Semi-major axis — the physical orbital semi-major axis.
  6. Eccentricity — must be greater than 0 and below the package limit.
  7. Resolution — R20, R40, or R80.
  8. Custom numerical normalization a_norm — normally answer N. This is an
     advanced numerical-coordinate option, not a physical fit parameter.

The Frostyverse result is calculated and sealed first. Only afterward does the
wrapper calculate and display the General Relativity comparison ruler for the
same physical orbit.

OPTIONAL — RUN A CUSTOM CASE ENTIRELY WITH FLAGS
-----------------------------------------------
Reviewers who prefer non-interactive/repeatable command lines can bypass the
menu with --custom. For example, an Earth-Moon-style input can be entered as:

  python lab_test.py --custom --label MOON_EXAMPLE --source-name Earth --source-gm 398600.436 --body-gm 4902.800 --a-km 384400 --e 0.0554 --R 20

Required custom flags are:
  --source-gm   central-source GM in km^3/s^2
  --a-km        semi-major axis in km
  --e           eccentricity

Useful optional custom flags include:
  --label NAME
  --source-name NAME
  --body-gm VALUE
  --R 20|40|80
  --workers N
  --a-norm VALUE              advanced numerical-coordinate override
  --no-coordinate-check       disables the alternate-normalization check

To see the command-line options supplied by your copy of the program:
  python lab_test.py --help

MAIN MENU
---------
1. Reproduce the Icarus reference calculation.
2. Test your own orbit.
3. Run the unchanged historical H2-087 blind-prediction package.
4. Run the unchanged historical H2-089 pair-mass audit.
5. Run the unchanged historical H2-092 structural 4x audit.
6. Verify bundled archive hashes.
0. Exit.

CUSTOM ORBIT PHYSICS INPUTS
---------------------------
The custom mode accepts:
- source gravitational parameter GM in km^3/s^2 (Sun/Earth/Jupiter presets or
  a custom value),
- secondary/body GM in km^3/s^2 (0 is allowed for a test particle),
- semi-major axis in km or AU,
- eccentricity,
- numerical resolution.

The final selected two-body bookkeeping from H2-089 is used in custom mode:
  M_pair = M1 + M2
for both the effective field-scale and relative-orbit scale.

The final H2-092 structural response factor is used as:
  H_total = H_stable + 4 D
where the 4 is a response-context multiplicity, not four energy copies.

GENERAL RELATIVITY FIREWALL
---------------------------
Custom mode generates and seals the Frostyverse prediction first. Only after
that does the wrapper evaluate the standard weak-field GR perihelion formula
for the same physical input and print the comparison.

The GR result is not passed into the Frostyverse orbit calculation.

The GR ruler printed here is the isolated weak-field two-body relativistic
apsidal contribution for the entered source/body pair. It does not include
third-body perturbations, source oblateness, tides, or other classical apsidal
effects that can dominate the observed total precession of some real systems.

NUMERICAL NORMALIZATION
-----------------------
The historical solver uses a dimensionless numerical orbit inside a finite
radial profile. Custom mode chooses a numerical semi-major-axis normalization
from the orbit geometry only, never from the GR target. A second valid
normalization is also evaluated when possible and reported as a coordinate-
sensitivity check.

Very low eccentricity is intrinsically delicate for perihelion-angle extraction.
The program prints a warning for e < 0.02. The current finite profile also limits
custom inputs to approximately e < 0.88.

HISTORICAL ARCHIVES
-------------------
The original/ directory contains exact frozen archives:
- Frostyverse-Test-H2-087.zip — blind cross-source precession prediction
- Frostyverse-Test-H2-089.zip — pair-mass / single-mode audit
- Frostyverse-Test-H2-092.zip — final 48-to-12 response-multiplicity audit

lab_test.py verifies their SHA-256 hashes before running them. They are never
modified in place.

RESULT FILES
------------
Runs create timestamped text/JSON output under results/. Historical runs are
executed from temporary extracted copies so the frozen ZIPs stay unchanged.

TROUBLESHOOTING
---------------
If the program says that NumPy is required even though NumPy appears installed,
make sure BOTH NumPy and SciPy were installed from requirements.txt. Some of the
preserved numerical modules import NumPy and scipy.fft together.

Check the active interpreter and dependencies with:
  python --version
  python -c "import numpy, scipy; print('NumPy', numpy.__version__); print('SciPy', scipy.__version__)"

If "python" is not recognized before creating a virtual environment, use
"py -3" on Windows or "python3" on macOS/Linux/WSL for the environment-creation
step shown above.

PROJECT
-------
https://frostyverse.FrostCandy.com
