Scenario kind pagesEdit on GitHubSource: docs/kinds/by-kind/optical-atmosphere.md

optical-atmosphere (scenario kind)

Scenario kind of the engine v0.38.0, family Optical PNT. Advisory: analysis output from a research and engineering tool, not type-approved navigation equipment and not a safety-of-life service. Every label here is the engine's or the verification matrix's; a kind is MODELLED unless the matrix says otherwise (how a label is earned: the README's Evidence section).

What it does#

MODELLED optical PNT through the atmosphere: for an optical link and a set of ground sites with stated cloud climates it reports the wavelength- and elevation-dependent clear-air loss (Kim visibility law plus Rayleigh), the Hufnagel-Valley turbulence state (Rytov variance, scintillation index, gamma-gamma parameters, aperture averaging), the weather-driven availability against the link margin (cloud optical depth from a log-normal liquid-water climate, geometric-optics extinction, independent turbulence fade), the link margin needed for target availabilities, the outage-duration distribution, the timing and ranging error growth per outage through the clock holdover model, distance-correlated site-diversity availability, and what-if gains for enhancement techniques (wavelength, receive aperture, adaptive-optics scintillation reduction, extra margin). VALIDATED as implementation of the stated formulas against an independent mpmath oracle: Rytov variance, scintillation index, gamma-gamma fade probability, aperture-averaging factor, cloud and clear-air optical depth. MODELLED: every weather, technique and clock input and the independence and copula assumptions; no measured availability record has been compared. Advisory analysis, not a certified availability or navigation product.

One run of scenarios/optical-atmosphere-network.toml summarises as: optical-atmosphere: 1550 nm at 30 deg elevation, margin 19.2 dB before the atmosphere; best site southern 74.66 %; 3-site network 92.72 % independent / 91.62 % correlated weather (MODELLED, advisory)

Inputs#

From the schema (kshana kinds --json):

  • Required fields: none
  • Optional fields: wavelength_nm, elevation_deg, availability_targets_pct, link, atmosphere, site, network, technique, clock, timeseries

The example scenarios/optical-atmosphere-network.toml sets, among others:

Field Value Unit
atmosphere.aerosol_scale_height_m 1200 m
atmosphere.cloud_effective_radius_um 10 not stated
atmosphere.direction downlink text
atmosphere.hv_ground_cn2 1.7000e-14 not stated
atmosphere.hv_wind_ms 21 ms
atmosphere.path_eff_km 10 km
atmosphere.top_km 30 km
atmosphere.visibility_km 23 km
atmosphere.wave plane text
availability_targets_pct [40, 50, 60, 70] %
clock.classes [ocxo, rafs, dsac] not stated
clock.threshold_ns 100 ns

Run it#

kshana scenarios/optical-atmosphere-network.toml

2 bundled scenarios use this kind; the others are in scenarios/.

What it gives#

The scalar results of that run, with the units the engine states:

Result Value Unit
inputs.correlation_length_km 500 km
inputs.direction downlink text
inputs.elevation_deg 30 deg
inputs.wave plane text
inputs.wavelength_nm 1550 nm
inputs.zenith_deg 60 deg
link.footprint_m 15.5 m
link.geometric_loss_db 31.765434 dB
link.margin_no_atmosphere_db 19.213966 dB
link.received_power_no_atmosphere_dbm -10.786034 dBm

Result label (the engine's): MODELLED — optical PNT through the atmosphere: clear-air extinction (Kim visibility law + Rayleigh), cloud optical depth from a stated liquid-water climate (P.840 amount, geometric-optics extinction), Hufnagel-Valley turbulence with gamma-gamma fades and aperture averaging, availability against the

The chart the engine writes for scenarios/optical-atmosphere-network.toml, kind optical-atmosphere

Evidence#

MODELLED: the verification matrix rows that name this kind.

  • MODELLED Hufnagel-Valley Cn2 integrated along a slant path for the plane- and spherical-wave Rytov variance (uplink and downlink), the Andrews-Phillips scintillation index and gamma-gamma parameters, the gamma-gamma fade probability and fade margin, Tests: optical_atmosphere_reference.rs.
  • MODELLED Availability of an optical link against a stated link margin from a log-normal cloud liquid-water climate (ITU-R P.840 amount, geometric-optics extinction) and the independent gamma-gamma turbulence fade, the link margin needed for target a Tests: optical_atmosphere_identities.rs.
  • MODELLED The outage-duration distribution of an optical site coupled to the closed-form coast variance of the clock holdover model: timing and ranging error at stated outage quantiles, the holdover to a timing threshold, the fraction of outages and Tests: optical_atmosphere_identities.rs.
  • MODELLED An opt-in [timeseries] table (duration, step, seed) makes the optical-atmosphere kind also write, per site, one seeded realisation of the stated site model through time: cloud episodes (clear spells exponential, cloud outages log-normal Tests: optical_atmosphere_timeseries.rs.

The rows the run itself exercised, with the oracle the matrix gives each (the public sources are named there):

  • MODELLED Deterministic, scenario-hashed, SBOM + cross-platform golden gates. Oracle (ExternalDataset): SBOM conformance to the official CycloneDX 1.5 JSON Schema (+ valid SPDX identifiers) — an external published standard, zero validation errors over the full dependency graph; the FoM-determinism / byte-reproducibility part remains a pinned self-consistency check, so the row stays MODELLED
  • MODELLED Hufnagel-Valley Cn2 integrated along a slant path for the plane- and spherical-wave Rytov variance (uplink and downlink), the Andrews-Phillips scintillation ind. Oracle (ExternalDataset): The numerics are compared with an independent program (xval/optical-atmosphere/oracle.py, mpmath 1.4.1 at 30 digits, tanh-sinh quadrature on the original height variable and Bessel-K gamma-gamma densities) that shares no code with Kshana, under bars fixed before any implementation existed (xval/optical-atmosphere/PREREGISTRATION.md). WHY MODELLED: that oracle evaluates the same published formulas, so it checks the im
  • MODELLED Availability of an optical link against a stated link margin from a log-normal cloud liquid-water climate (ITU-R P.840 amount, geometric-optics extinction) and . Oracle (InternalConsistency): Internal consistency: closed-form limits and monotonicity of the diversity model, the cloud-ceiling closed form, and the log-normal outage identities. NO external oracle is claimed and none has been compared: no measured optical-ground-station availability or cloud-free-line-of-sight record is used. WHY MODELLED: the cloud climate (probability of cloud, median and spread of the liquid-water column, outage durations),
  • MODELLED The outage-duration distribution of an optical site coupled to the closed-form coast variance of the clock holdover model: timing and ranging error at stated ou. Oracle (InternalConsistency): Internal consistency with the holdover module, bit for bit; NO external oracle is claimed. The class PSDs are the synthesised long-tau floors the holdover module already carries, so the figures inherit its stated caveat that holdover to a tight threshold is governed by the assumed red-noise floor and not by the cited Allan deviation. The outage durations are a log-normal model with stated parameters, not a measured c

Limitations#

What the run's own report says is not modelled or not validated:

  • MODELLED — optical PNT through the atmosphere: clear-air extinction (Kim visibility law + Rayleigh), cloud optical depth from a stated liquid-water climate (P.840 amount, geometric-optics extinction), Hufnagel-Valley turbulence with gamma-gamma fades and aperture averaging, availability against the link margin, outage durations coupled to clock holdover, and distance-correlated site diversity. The numerics are checke (result label)
  • MODELLED optical PNT through the atmosphere: for an optical link and a set of ground sites with stated cloud climates it reports the wavelength- and elevation-dependent clear-air loss (Kim visibility law plus Rayleigh), the Hufnagel-Valley turbulence state (Rytov variance, scintillation index, gamma-gamma parameters, aperture averaging), the weather-driven availability against the link margin (cloud optical depth fro (kind catalogue (kshana kinds --json))
  • MODELLED: every weather, technique and clock input and the independence and copula assumptions; no measured availability record has been compared. (kind catalogue (kshana kinds --json))
  • Optical PNT through the atmosphere: three ILLUSTRATIVE ground sites (a cloudier northern site, a middling central site and a clearer southern site) viewing a LEO optical terminal at 30 degrees elevation at 1550 nm. The cloud climates are stated inputs, not measurements or any dataset's values, so every availability below is MODELLED. The run reports per site the clear-air loss, the Hufnagel-Valley turbulence state, t (scenario file comment, lines 1 to 8)
  • One seeded realisation of each site's link through time (MODELLED; a draw from the model above, not the climate). Absent, no series is written and the result is the 0.37 document. (scenario file comment, lines 78 to 79)
  • Reproducibility & software assurance is MODELLED, not validated: a sub-claim is externally checked, but the whole capability composes modelled pieces, so the capability stays Modelled. (verification matrix (docs/MODELLED-RATIONALE.md))
  • Optical slant-path atmosphere numerics: Rytov variance, scintillation, gamma-gamma fade probability, aperture averaging, cloud and clear-air optical depth is MODELLED, not validated: a sub-claim is externally checked, but the whole capability composes modelled pieces, so the capability stays Modelled. (verification matrix (docs/MODELLED-RATIONALE.md))
  • Weather-driven optical ground-site availability and distance-correlated site diversity is MODELLED, not validated: checked against its own closed-form / analytic identity — catches transcription and coefficient errors, but is not an external oracle. (verification matrix (docs/MODELLED-RATIONALE.md))

See also#