Improve radar physics fidelity and model validation

Author: SpaceEngineerSS

README.md

@@ -62,7 +62,7 @@
 | Feature | Details |
 |---------|---------|
 | **Ground Clutter** | Weibull distribution, σ⁰ coefficients |
-| **Sea Clutter** | **GIT Model**, Douglas sea states (1-6) |
+| **Sea Clutter** | **NRL five-parameter model**, sea states 0-6, HH/VV |
 | **Rain Physics** | ITU-R P.838 Attenuation + Marshall-Palmer Clutter |
 | **MTI Filtering** | Velocity threshold, slow-mover rejection |
 
@@ -260,4 +260,4 @@ If you use RadarSim in academic work, please cite:
 
 <p align="center">
   <b>Built with ❤️ for the Radar Community</b>
-</p>
+</p>

docs/MODEL_FIDELITY.md

@@ -0,0 +1,102 @@
+# Model Fidelity and Intended Use
+
+RadarSim separates fast scenario-level analysis from signal-level processing. Results are
+meaningful only when the selected model, its inputs, and its validation domain match the
+question being studied. A model name or literature citation is not, by itself, evidence that a
+result is valid.
+
+## Fidelity levels
+
+### Scenario level
+
+The scenario engine advances target truth states, evaluates line-of-sight geometry, computes
+mean received power and SNR, samples target RCS, and draws detections from a statistical
+detector model. It is intended for Monte Carlo detection, tracking, coverage, and engagement
+studies where individual ADC samples are not required.
+
+The detector is a square-law detector with a threshold derived from probability of false alarm.
+For non-fluctuating targets, conditional integrated power is evaluated with the non-central
+chi-square distribution. Swerling I through IV returns are averaged over their gamma RCS
+distributions. Slow cases retain an RCS realization across the integration interval; fast cases
+decorrelate pulse to pulse.
+
+### Signal level
+
+The pulse-Doppler processor synthesizes complex baseband samples at the output of range
+compression and processes a coherent pulse interval with MTI, slow-time windowing, and a
+Doppler FFT. This is a parametric range-compressed model. It is not yet a receiver-front-end or
+raw-ADC model and must not be used to study quantization, saturation, phase noise, oscillator
+instability, fractional-delay filters, or analogue impairments.
+
+### Imaging level
+
+SAR and ISAR processing is currently experimental. Image products are useful for algorithm and
+interface development, but are not radiometrically calibrated products. Quantitative resolution,
+PSLR, ISLR, geolocation, or image-quality claims require acquisition-geometry and point-target
+validation before release.
+
+## Parameter authority
+
+Scenario files are the authority for radar, receiver, atmosphere, target, and simulation
+parameters. The loader rejects non-physical values and transfers the following quantities to the
+runtime model:
+
+- carrier frequency, peak power, antenna gain and azimuth/elevation beamwidth;
+- PRF, pulse width, receiver noise bandwidth, noise figure, system temperature and losses;
+- probability of false alarm and number of integrated pulses;
+- atmospheric temperature, pressure and water-vapour density;
+- clutter enablement, terrain class, sea state and rain rate;
+- target kinematics, mean RCS, Swerling case and onboard jammer power.
+
+Values omitted by a scenario use documented defaults. A saved run must record both supplied and
+resolved values so that the result can be reproduced.
+
+## Verification and validation policy
+
+Each quantitative model must have:
+
+1. a mathematical definition and an identified source;
+2. units, conventions, assumptions, and a stated validity domain;
+3. independent reference points that were not generated by the implementation under test;
+4. boundary, monotonicity, conservation, and stochastic-distribution tests where applicable;
+5. an uncertainty statement and known limitations;
+6. traceability from scenario input through runtime state to exported result.
+
+Verification establishes that the equations were implemented correctly. Validation establishes
+that the selected equations adequately represent the intended real system. Both are required for
+a model to be described as validated. This policy follows the credibility structure of
+NASA-STD-7009B and its separation of implementation verification, solution verification,
+validation, input pedigree, uncertainty characterization, and result robustness.
+
+## Baseline references
+
+- NASA-STD-7009B, *Standard for Models and Simulations*, 2024.
+- IEEE Std 686-2017, *IEEE Standard Radar Definitions*.
+- M. I. Skolnik, *Radar Handbook*, 3rd edition, 2008.
+- M. A. Richards, *Fundamentals of Radar Signal Processing*, 2nd edition, 2014.
+- P. Swerling, “Probability of Detection for Fluctuating Targets,” IRE Transactions on
+  Information Theory, 1960, DOI: 10.1109/TIT.1960.1057561.
+- W. J. Albersheim, “A Closed-Form Approximation to Robertson's Detection Characteristics,”
+  Proceedings of the IEEE, 1981, DOI: 10.1109/PROC.1981.12082.
+- ITU-R P.676-13, *Attenuation by atmospheric gases and related effects*, 2022.
+- ITU-R P.838-3, *Specific attenuation model for rain for use in prediction methods*, 2005.
+- V. Gregers-Hansen and R. Mital, "An Improved Empirical Model for Radar Sea Clutter
+  Reflectivity," IEEE Transactions on Aerospace and Electronic Systems, 2012,
+  DOI: 10.1109/TAES.2012.6324732.
+
+## Known baseline limitations
+
+- Gaseous attenuation uses the P.676-13 Annex 1 line-by-line equations for a homogeneous
+  terrestrial path. Slant paths through height-dependent atmospheric profiles are not yet
+  represented.
+- Land-clutter terrain-class coefficients remain an empirical screening model and require
+  site-specific measurement or calibrated soil/vegetation inputs for quantitative use. Sea clutter
+  uses the NRL model within its stated frequency, grazing-angle, and sea-state domain.
+- Scenario-level ECM does not yet model receiver saturation or waveform-dependent processing.
+- Pulse-Doppler synthesis starts from a range-compressed representation.
+- SAR/ISAR processing is not yet quantitatively validated.
+- Classifier training data is synthetic and must not be interpreted as operational recognition
+  performance.
+
+These limitations must remain visible in documentation and releases until the corresponding
+validation evidence exists.

docs/physics.md

@@ -59,9 +59,12 @@ Where $\theta$ is the 3-dB beamwidth in degrees.
 
 ## Atmospheric Attenuation
 
-### ITU-R P.676-12 Model
+### ITU-R P.676-13 Model
 
-RadarSim implements the ITU-R Recommendation P.676-12 for atmospheric gas attenuation, covering frequencies up to 1000 GHz.
+RadarSim implements the Annex 1 line-by-line oxygen and water-vapour equations from
+Recommendation ITU-R P.676-13 over 1-1000 GHz. The spectroscopic line tables, pressure
+broadening, oxygen interference terms, dry-air continuum, and water-vapour continuum are
+evaluated for the scenario temperature, dry-air pressure, and water-vapour density.
 
 ### Total Attenuation
 
@@ -79,15 +82,8 @@ Key absorption features:
 - **60 GHz complex**: Strong O₂ resonance (~15 dB/km at peak)
 - **118.75 GHz line**: Secondary O₂ absorption
 
-```python
-# Normalized pressure and temperature
-rp = pressure_hpa / 1013.25
-rt = 288.0 / temperature_k
-
-# 60 GHz peak
-if 57 < frequency_ghz < 63:
-    gamma_o = 15.0 * rp * (rt ** 0.5)
-```
+The implementation is verified against the official ITU-R Study Group 3 validation workbook at
+12, 20, 60, 90, and 130 GHz, separately for oxygen and water vapour.
 
 ### Water Vapor Absorption
 
@@ -109,11 +105,14 @@ Where:
 
 | Freq (GHz) | $k_H$ | $\alpha_H$ |
 |------------|-------|------------|
-| 10 (X-Band)| 0.0101| 1.276 |
-| 20 (K-Band)| 0.0367| 1.154 |
-| 35 (Ka-Band)| 0.0751| 1.099 |
+| 10 (X-Band)| 0.01217| 1.2571 |
+| 20 (K-Band)| 0.09164| 1.0568 |
+| 35 (Ka-Band)| 0.3374| 0.9047 |
+
+The implementation evaluates the P.838-3 curve-fit equations continuously from 1 to 1000 GHz
+and combines horizontal and vertical coefficients for path elevation and polarization tilt.
 
-**Implementation:** `src/simulation/engine.py` step loop
+**Implementation:** `src/physics/rain.py::ITU_R_P838`
 
 ---
 

src/advanced/eccm.py

@@ -390,8 +390,7 @@ def calculate_sjnr_db(self, snr_db: float) -> float:
         """
         Calculate Signal-to-Jamming-plus-Noise Ratio.
 
-        SJNR = SNR / (1 + J/S)  [linear]
-        SJNR_dB = SNR_dB - 10·log₁₀(1 + 10^(JSR_eff/10))
+        SJNR = 1 / (1/SNR + J/S)  [linear]
 
         Args:
             snr_db: Signal-to-noise ratio [dB]
@@ -405,9 +404,8 @@ def calculate_sjnr_db(self, snr_db: float) -> float:
         if jsr_eff < -50:
             return snr_db  # No significant jamming
 
-        jsr_linear = 10.0 ** (jsr_eff / 10.0)
-        sjnr_db = snr_db - 10.0 * np.log10(1.0 + jsr_linear)
-        return sjnr_db
+        inverse_sjnr = 10.0 ** (-snr_db / 10.0) + 10.0 ** (jsr_eff / 10.0)
+        return float(-10.0 * np.log10(inverse_sjnr))
 
     def get_status(self) -> dict:
         """Get combined ECCM status for UI."""
@@ -464,8 +462,7 @@ def validate_eccm() -> dict:
     # ── Test 3: SJNR with Jamming ──
     ctrl = ECCMController(center_freq_hz=10e9, n_freq_hops=10)
     ctrl.set_jamming_environment(True, jsr_db=20.0)
-    sjnr_no_eccm = 20.0 - 10.0 * np.log10(1.0 + 10.0 ** (20.0 / 10.0))
-    sjnr_with_eccm = ctrl.calculate_sjnr_db(snr_db=20.0)
+    sjnr_no_eccm = -10.0 * np.log10(10.0 ** (-20.0 / 10.0) + 10.0 ** (20.0 / 10.0))
 
     # Without ECCM, SJNR should be much lower
     ctrl.enable_frequency_agility()

src/io/exporter.py

@@ -36,6 +36,8 @@ def export_scenario_to_yaml(
                 "description": description
                 or f"Exported on {datetime.now().strftime('%Y-%m-%d %H:%M')}",
                 "version": "1.0",
+                "duration_seconds": max(float(engine.current_time), float(engine.dt)),
+                "update_rate_hz": 1.0 / float(engine.dt),
             },
             "radar": _extract_radar_config(engine),
             "targets": _extract_targets(engine),
@@ -66,10 +68,24 @@ def _extract_radar_config(engine) -> Dict[str, Any]:
     radar = engine.radar
 
     return {
+        "name": str(radar.radar_id),
+        "type": "pulse_doppler",
         "frequency_hz": float(radar.frequency_hz),
         "power_watts": float(radar.power_watts),
-        "antenna_gain_db": float(radar.antenna_gain_db),
-        "beamwidth_deg": float(radar.beamwidth_deg),
+        "antenna": {
+            "gain_db": float(radar.antenna_gain_db),
+            "beamwidth_az_deg": float(radar.to_dict()["beamwidth_deg"]),
+            "beamwidth_el_deg": float(radar.to_dict()["beamwidth_el_deg"]),
+            "polarization_tilt_deg": float(radar.polarization_tilt_deg),
+        },
+        "receiver": {
+            "noise_figure_db": float(radar.noise_figure_db),
+            "bandwidth_hz": float(radar.receiver_bandwidth_hz),
+            "system_temperature_k": float(radar.system_temperature_k),
+        },
+        "prf_hz": float(radar.prf_hz),
+        "pulse_width_s": float(radar.pulse_width_s),
+        "system_losses_db": float(radar.system_losses_db),
         "scan_rate_rpm": float(radar.scan_rate_rpm),
         "position": {
             "x_m": float(radar.position[0]),
@@ -85,19 +101,19 @@ def _extract_targets(engine) -> list:
 
     for t in engine.targets:
         target_data = {
-            "id": int(t.target_id),
+            "name": f"Target_{int(t.target_id)}",
             "type": str(getattr(t, "target_type", "aircraft")),
-            "position_m": {
-                "x": float(t.position[0]),
-                "y": float(t.position[1]),
-                "z": float(t.position[2]) if len(t.position) > 2 else 0.0,
+            "initial_position": {
+                "x_m": float(t.position[0]),
+                "y_m": float(t.position[1]),
+                "z_m": float(t.position[2]) if len(t.position) > 2 else 0.0,
             },
-            "velocity_mps": {
-                "vx": float(t.velocity[0]),
-                "vy": float(t.velocity[1]),
-                "vz": float(t.velocity[2]) if len(t.velocity) > 2 else 0.0,
+            "velocity": {
+                "vx_mps": float(t.velocity[0]),
+                "vy_mps": float(t.velocity[1]),
+                "vz_mps": float(t.velocity[2]) if len(t.velocity) > 2 else 0.0,
             },
-            "rcs_m2": float(t.rcs_m2),
+            "rcs_m2": float(t.rcs_mean),
             "swerling_model": (
                 int(t.swerling_model.value)
                 if hasattr(t.swerling_model, "value")
@@ -107,10 +123,14 @@ def _extract_targets(engine) -> list:
 
         # Optional jammer settings
         if hasattr(t, "jammer_active") and t.jammer_active:
-            target_data["jammer"] = {
-                "active": True,
-                "power_watts": float(getattr(t, "jammer_power", 1000)),
-            }
+            target_data["has_ecm"] = True
+            target_data["ecm_type"] = str(getattr(t, "ecm_type", "noise_barrage"))
+            target_data["ecm_power_watts"] = float(
+                getattr(t, "jammer_power_watts", 1000)
+            )
+            target_data["ecm_bandwidth_hz"] = float(
+                getattr(t, "jammer_bandwidth_hz", 100e6)
+            )
 
         targets.append(target_data)
 
@@ -121,9 +141,14 @@ def _extract_environment(engine) -> Dict[str, Any]:
     """Extract environment settings from engine."""
     env = {
         "enable_atmospheric": bool(engine.enable_atmospheric),
+        "temperature_c": float(engine.atmospheric_temperature_c),
+        "pressure_hpa": float(engine.atmospheric_pressure_hpa),
+        "water_vapor_gpm3": float(engine.water_vapor_density_g_m3),
+        "rain_rate_mm_hr": float(engine.rain_rate_mm_hr),
         "clutter": {
             "enabled": bool(getattr(engine, "clutter_enabled", False)),
             "terrain_type": str(getattr(engine, "terrain_type", "rural")),
+            "sea_state": int(getattr(engine, "sea_state", 0)),
         },
     }
 
@@ -140,8 +165,10 @@ def _extract_environment(engine) -> Dict[str, Any]:
 def _extract_simulation_params(engine) -> Dict[str, Any]:
     """Extract simulation parameters from engine."""
     params = {
-        "dt": float(engine.dt),
-        "detection_threshold_db": float(engine.detection_threshold_db),
+        "enable_atmospheric_loss": bool(engine.enable_atmospheric),
+        "enable_clutter": bool(engine.clutter_enabled),
+        "pfa": float(engine.probability_false_alarm),
+        "pulses_integrated": int(engine.pulses_integrated),
     }
 
     # Advanced features