# 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: ```bat 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: ```bat 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: ```bat 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: ```json { "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: | Feature | Enable | Disable | If neither flag is supplied | |---|---|---|---| | Finite-count tomography | `--sample-counts` | `--no-sampling` or `--no-sample-counts` | Use configuration; otherwise off | | Additional channel controls | `--controls` | `--no-controls` | Use configuration; otherwise off | 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: ```bat 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: ```bat 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: ```bat 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 ```bat 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 | Scenario | Physical input in each orbit branch | Construction | |---|---|---| | 1 | Detector 1 worldline used for both channels | Existing coincident schedule | | 2 | Separate detector worldlines | Retained old frame selector with corrected SR/GR event handling | | 3 | Exact Scenario 2 release and reception events | New supplied full construction, separately for each event pair | 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: ```bat .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`: ```bat .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: | Saved identity | Plotter behavior | |---|---| | `metadata.scenario` | Use this current-format identity | | Legacy top-level `scenario` only | Use the legacy identity | | Both fields | Require valid, equal values | | Neither field | Accept only a canonical `scenario1.json`, `scenario2.json` or `scenario3.json` filename | 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/`.