Matched-state satellite comparison and local dashboard

The updated package implements matched initial states, general Cartesian numerical propagation, configurable force models, a browser dashboard, saved input sessions, offline recomputation, and controlled sensitivity experiments. Both orbit sources feed the existing photon, timing, quantum-channel and full-PF implementation.

The reference is CelesTrak GP data propagated with SGP4. It is an orbit prediction, not live telemetry or a measured photon experiment. Initial matching makes the model comparison controlled; it does not establish either prediction's accuracy.

Windows with the existing Python 3.8

Extract the complete archive. Keep an existing .venv-pf38 if it already has the package's pinned dependencies. For a fresh installation run:

setup_python38.bat
setup_tracking_python38.bat

Existing installations need only setup_tracking_python38.bat if the optional tracking dependencies are missing. No Python upgrade, IBM account, web framework, JavaScript package install, map token or external dashboard service is required. The dashboard uses the Python standard library and bundled browser assets.

Run a complete offline example with captured real GP inputs and visible links:

run_comparison_python38.bat --config config_comparison_replay.json --output comparison_sessions\sr --dashboard --open-browser

The browser opens at http://127.0.0.1:8765/. The command computes both orbit branches and all three scenarios, then continues serving until Ctrl+C. Choose a new output folder for each experiment; completed sessions are never overwritten.

For GR, optional phase noise, and sensitivity:

run_comparison_python38.bat --config config_comparison_gr_replay.json --output comparison_sessions\gr
run_comparison_python38.bat --config config_comparison_gr_noise.json --sensitivity --sample-counts --output comparison_sessions\gr_noise
run_comparison_python38.bat --config config_comparison_drag_illustrative.json --output comparison_sessions\drag

The drag example includes explicitly illustrative spacecraft and atmosphere parameters. They demonstrate the force and sensitivity paths; they are not calibrated properties of ISS, TECHNOSAT or HST. The noise example is likewise an explicit assumed covariance. Phase noise is off in the other supplied presets; source depolarization remains enabled.

Shared execution choices and portable configuration

The scenario and matched-state comparison CLIs both leave finite-count sampling and channel controls off unless the configuration or command enables them. Exact fidelity, purity and expected collection rates are still calculated. Phase noise is a separate channel setting; enabling sampling does not enable phase noise, and disabling sampling does not suppress configured phase noise. The optional storage_channel block is separate again: it derives memory dephasing and independent memory loss from each computed release hold. Add the same top-level block from STORAGE_CHANNEL.md to a comparison or live configuration to enable it in either SR or GR. It is disabled by default.

The canonical configuration fragment is:

{
  "execution": {
    "sample_counts": false,
    "controls": false
  }
}

Only sample_counts and controls are accepted within execution, and their values must be JSON booleans. The legacy keys comparison.sample_counts and comparison.controls remain supported. If both spellings are present, their values must agree; disagreement is an error, including when a CLI override is supplied. After checking the input, each CLI applies any explicit option:

The enable and disable flags for one feature are mutually exclusive. Explicit disable flags override true in a valid configuration. Both runners print the effective choices. New comparison sessions capture the canonical execution object in inputs/config.json.

Both main runners and real_time_satellite_comparison.py use the same JSON input-path rules: tracking.cache_dir, tracking.leap_second_file and comparison.iers_file resolve relative to the configuration file's directory. If omitted, tracking.cache_dir is tracking_cache in that directory. Absolute paths are retained. A provided comparison.iers_file pins the specified IERS-A table for calculations in all three runners. The automatic bundled leap-second fallback remains relative to the installed module. CLI --output is relative to the current working directory; it is not relocated beside the configuration file. The supplied Windows batch launchers first change into the package directory, which therefore becomes the base for their relative command/output paths. Direct Python invocations keep the caller's working directory.

The two runners have different scientific workflows and preset files: run_python38.bat defaults to config.json and a scenario calculation; run_comparison_python38.bat defaults to config_comparison_replay.json and the matched-state two-source comparison. The shared execution policy does not make their orbital sampling grids or workflows interchangeable. Direct Python API calls retain their documented function defaults; the policy above describes the command-line runners.

Live forecasts

For current UTC tracking with GR and a dashboard:

run_comparison_python38.bat --config config_comparison_live_gr.json --live --live-iterations 10 --live-interval 30 --output comparison_sessions\live_gr --dashboard --open-browser

All live options also support --spacetime flat_sr or --spacetime gr_static. Enable explicit phase noise in either mode with:

run_comparison_python38.bat --config config_comparison_live.json --live --live-iterations 10 --spacetime gr_static --phase-sigma-a 0.8 --phase-sigma-b 0.5 --phase-correlation 0.35 --phase-source "Illustrative Gaussian covariance" --output comparison_sessions\live_gr_noise

Every live update starts a new, explicitly named forecast segment at current UTC. Within that segment, GP inputs, EOP data and initial states stay frozen. New elements never silently reset a numerical trajectory. The interval is the minimum time between starts; computation can make it longer. GP downloads follow the configured cache refresh policy; SGP4 states are evaluated at each UTC epoch. Fresh GP records are not necessarily downloaded on every dashboard refresh.

View all saved sessions in a separate terminal, without recomputing anything:

run_dashboard_python38.bat --sessions comparison_sessions --port 8765 --open-browser

The dashboard shows trajectory projections, GCRS position/velocity differences, RIC components, UTC and data age, propagation/visibility status, emission holds, arrival times, full-PF selection and simultaneity diagnostics, conditional quantum metrics, expected accepted rates, and sensitivity results. It is read-only and binds to loopback. It displays failed or pending sessions explicitly. A zero accepted rate cannot supply a tomography estimate, even when the channel's conditional density matrix is defined.

Offline replay

run_comparison_python38.bat --replay comparison_sessions\gr_noise --output comparison_sessions\gr_noise_recomputed

Replay verifies captured hashes, pins the original GP/EOP/leap inputs, and blocks network refresh through an offline provider. It recomputes orbit rows, physical scenarios, seeded counts and sensitivity experiments and compares their numeric sections exactly with the original session. It writes replay_validation.json. Changing libraries or platforms can change floating-point results; a mismatch is reported rather than silently accepted. Original sessions remain unchanged. Replay uses the captured execution choices, including legacy configurations whose sampling setting was true. Do not add sampling/control flags to a replay command: enable flags and explicit disable flags are both rejected. Make a new experiment from a configuration if different choices are required.

Session manifests record source/dependency fingerprints, original acquisition provenance and input/output hashes. Source changes are visible in replay environment provenance; exact reproducibility is tested on the same supported runtime. Hash checks detect accidental changes relative to the manifest; they are not a cryptographic signature of a trusted data publisher. See SESSION_FORMAT.md for the complete input contract.

Model and time conventions

Each satellite starts at the reference's GCRS position and velocity at the exact same epoch. TLE mean elements are not substituted as osculating Kepler elements. numerical_model.model selects two_body, j2, or j2_drag. DOP853 integrates the six Cartesian state components, with bounded dense output and explicit failure on collision, invalid parameters, atmosphere-domain exit or interpolation outside the integration interval. --force-model can override the selection; drag still requires explicit spacecraft and bounded atmosphere inputs.

J2 uses a declared fixed GCRS symmetry axis. Drag uses velocity relative to the co-rotating atmosphere, area, mass, drag coefficient and a positive density table interpolated logarithmically inside its declared altitude range. There is no silent high-altitude extrapolation of a sea-level scale-height model. These are controlled force approximations, not a full precision orbit-determination system. Higher gravity harmonics, atmospheric winds, third bodies, radiation pressure and relativistic orbit forces are omitted. See NUMERICAL_ORBITS.md for equations, domains and integrator settings.

Orbit residuals use GCRS and TAI/TT-rate elapsed seconds. Scenario GR times use the package's TCG/Schwarzschild convention; the horizon is converted so both orbit branches refer to the same physical UTC epochs. The GR interface applies the existing spatial Jacobian and dTT/dTCG velocity factor. Selecting GR photon propagation does not turn J2/drag trajectories into Schwarzschild geodesics. They remain prescribed approximate satellite worldlines embedded in the static-monopole chart. The static spherical photon metric omits Earth's rotation and multipoles. Numerical forces use the configured reference radius (default 6,378,137 m); photon occultation retains the documented 6,371,000 m sphere.

Scenarios and interpretation

Each scenario runs once with the numerical orbit and once with SGP4. The output reports changes in emission holds, arrival times, visibility and accepted rates, and PF status/velocity where defined. Scenario 3 remains a per-pair diagnostic; it does not acquire a new predictive emission-delay law. In GR the full PF lives in the common anchor's tangent space, not a global inertial frame.

Fidelity and purity are evaluated against the declared Bell state, independently of Scenario 1. No geometry-dependent covariance or proximity-to-baseline score is introduced. With the same quantum channel, timing changes can change accepted counts without changing the conditional polarization density matrix when memory is disabled. With enabled memory, different proper storage durations can also change conditional fidelity and purity. The fixed covariance remains unchanged; the memory map is a separate configured physical interaction. Scenario 3's history remains identical to Scenario 2, including its memory factors. Sensitivity probes deliberately changing apparatus covariance can change that density matrix; they are labeled as different apparatus assumptions.

Memory parameters are explicit assumptions and must be calibrated for a device before apparatus-specific predictions can be made. Supplied source rates assume enough independent memory modes; no occupancy or loading/dead-time saturation model is included. Enabling memory produces schema-6 scenario results with recorded proper-time quadrature and factors; disabled runs retain schema 5. Unknown holds produce null final quantum-state predictions, not ideal states. See STORAGE_CHANNEL.md and manual Chapter 19 for the full contract.

Sensitivity is one-at-a-time experimentation, not inferred uncertainty or a fitted correction. --sensitivity runs configured comparison.sensitivity entries or four default positive/negative initial-state probes. Baseline state and frozen reference are retained. See SENSITIVITY_ANALYSIS.md for selectors and units.

Outputs and validation

Each session contains:

• comparison.json: orbit rows, scenario summaries, effects and sensitivity.
• session_manifest.json and inputs/: reproducible input capture and hashes.
• reference/ and numerical/: full scenario JSON, run manifest and independent physical/quantum validation report for each orbit source.
• sensitivity/: full numerical scenario outputs and validation for every probe.
• replay_validation.json: exact numeric comparison when replay was requested.

Both numerical invariant tests and pipeline tests are included. Run:

.venv-pf38\Scripts\python.exe -m pytest -q

The simulation pipelines write their own validation reports before sealing session hashes. A later validate_results.py --results SESSION\reference or --results SESSION\numerical recheck is read-only by default. Use --report with a new path outside the captured session if a separate audit report is needed. See SESSION_FORMAT.md for preservation and integrity checks.

FULL_COMPARISON_VALIDATION.md records the actual executed checks and limits. SCIENTIFIC_COMPARISON_REVIEW.md gives equations, primary sources and the distinction between mathematical verification and empirical validation.

The earlier run_python38.bat commands remain available. The older standalone real_time_satellite_comparison.py retains its explicitly unmatched circular comparison for compatibility. Use run_comparison_python38.bat for this new matched-state workflow.

Dashboard capture corrections

The updated viewer fixes the element-age summary, lists available photon UTC epochs when the selected orbit sample has no ensemble, and keeps orbit charts labeled GCRS in both propagation modes. It also adds dedicated print layout styles. Replace the dashboard folder and refresh the browser to use these changes with existing saved sessions. See DASHBOARD_CAPTURE_REVIEW.md for checks and the remaining print-preview verification limit.

Standalone plots of saved scenario results

Use plot_comparison.py to plot saved scenario JSON without rerunning the simulation. Inputs may be reordered or renamed when they retain their recorded scenario identity. For example, after copying Scenario 3 to full_pf.json and Scenario 1 to coincident.json:

.venv-pf38\Scripts\python.exe plot_comparison.py full_pf.json coincident.json --output plots\selected_scenarios.png

The legends still identify Scenario 3 and Scenario 1 correctly. The r6 identity rules are:

Each recorded value must be a JSON integer from 1 to 3; booleans, strings, floating-point values and null are invalid. Recorded identity takes precedence over the filename, even if a renamed file has another scenario's canonical name. Files without either recorded identity or a canonical filename are rejected: input order cannot establish which scenario a file represents. Invalid or conflicting identities and duplicate scenario numbers are rejected before a figure is written.

For older anonymous results, work on a copy outside any captured session and restore the correct canonical filename only when the original scenario is known. To compare the same scenario across experiments, make separate figures; one figure accepts at most one file for each scenario number. Leave archived session files unchanged so their recorded hashes remain valid. Choose an output path outside captured sessions for regenerated figures.

That revision-6 correction affected standalone plot labels. Its physics and runner policies were unchanged. Revision 7 additionally introduces optional memory dynamics; see RELEASE_NOTES_R7.md and the included manual, edition 1.3, at documentation/PF_Simulation_Complete_End_User_Manual.pdf; its editable LaTeX source remains in documentation/latex/.