# Shenron Radar Architecture Breakdown

This document provides a precise architectural analysis of the Shenron radar simulation pipeline, focusing on ownership, energy flow, and multi-radar extensibility.

### 🏗️ Radar Abstraction & Ownership

1.  **Radar Instance Representation**: Represented as a `radar` class in `ConfigureRadar.py`. It is a configuration-heavy object containing both hardware specs (frequency, bandwidth) and physics parameters (beamwidth, gain).
2.  **Signal Generation Ownership**: Each `ShenronRadarModel` (in `model_wrapper.py`) own its own `radar_obj`. The pipeline is private to the instance; radars share the input **Semantic LiDAR** but do not share intermediate artifacts like ADC cubes or calculated losses.
3.  **Metadata Storage**: All sensor-specific metadata (mount pose, FOV, waveform, noise floor) is stored as attributes of the `radar` class. It is accessed by name (e.g., `radar_type='awrl1432'`) during model initialization.
4.  **Sequential vs Parallel**: Processing is currently **sequential**. Within a single frame, the orchestrator iterates through defined radar profiles, generating one set of ADC samples and one point cloud at a time.

### ⚡ Energy Flow & Reuse

5.  **Reflected Energy Stage**: First computed in `Sceneset.py` within the `get_loss_3` function.
6.  **Energy Form**: Linear power (normalized unitless factor representing RCS + Path Loss).
7.  **Storage Granularity**: Stored **per-point** in a 1D array of length $N_{pts}$.
8.  **Reuse vs Recompute**: It is currently **recomputed** for every radar profile. Even if the points are identical, `get_loss_3` is called fresh for each radar instance to account for radar-specific gains.
9.  **Radar-Agnostic Stages**: Only the raw `semantic_lidar_data` ingestion and the basic axis-swap in `lidar.py` are truly radar-agnostic. Once the data enters `Cropped_forRadar`, it becomes radar-dependent.

### 🌐 Coordinate Frames & Angular Knowledge

10. **Transformation Point**: Points are transformed into radar-local coordinates in `lidar.py` inside `Cropped_forRadar` via the `rotate_points` function and mount-offset subtraction (e.g., `CARLA_X - 2.0`).
11. **Derived Quantities**: Azimuth (`theta`) and Elevation (`elev_angle`) are computed derivationally in `specularpoints()` (Lines 221-222) before being passed to the loss function. They are not currently stored in the point structure.
12. **Re-casting Rays**: Points are represented in Cartesian XYZ; azimuth and elevation can be (and are) computed analytically without re-casting rays.
13. **Occlusion & Incidence**: Occlusion is strictly **radar-dependent** (calculated from the `radar.center` viewpoint). Incidence angle is calculated relative to surface normals and is partially shared as it is scene-dependent, but its power-contribution is radar-dependent.

### 📉 Loss / Gain Modeling

14. **Modular Support**: Modular support is limited. Code uses fixed functions (`get_loss_3`); there is no plug-in architecture for gain blocks yet.
15. **Application Relative Order**: Applied in the following order: Range Loss ($1/R^2$ transmit) → Material Permittivity Loss → Surface Roughness Loss → Vertical Antenna Gain. Horizontal gain is currently missing.
16. **Mathematical Domain**: Applied **multiplicatively in linear space**.
17. **Scaling Mechanism**: Scaling is currently injected via the `radar.gain` and `radar.vertical_beamwidth` properties passed into the physics functions.

### 🛡️ Multi‑Radar Safety

18. **Shared Tick Structures**: The incoming `semantic_lidar_data` numpy array is the primary shared structure.
19. **Contamination Risk**: Low. `lidar.py` and `Sceneset` operate on slices or copies (e.g., `skew_pc`, `new_pc`). Internal modifications to `pc[:, 4]` exist but usually target local copies.
20. **Immutability**: Not strictly enforced by Python, but the workflow treats the input LiDAR as a read-only source.
21. **Attribute Cloning**: Introducing per-radar antenna loss would **not** require cloning the whole attribute list; it simply requires a new temporary array produced by the radar-specific loss function.

### 📡 ADC & Noise Injection

22. **Thermal Noise Stage**: Added during the ADC synthesis in `heatmap_gen_fast.py` (Line 146). It is added to the clean signal after beamforming.
23. **ADC Sharing**: Strictly **per-radar**. ADC cubes are not shared across profiles.
24. **SNR Variation**: Easily introduced via the `radar.noise_amp` property in the profile.
25. **Power Preservation**: Signal power and noise power are calculated separately and summed; they are not tracked as separate streams after summation.

### ⚙️ Configuration & Extensibility

26. **Profile Loading**: Hardcoded Python classes/dictionaries in `ConfigureRadar.py`.
27. **Sensor LUTs**: Existing precedent in `lidar.py` for semantic-to-material mapping tables.
28. **Radiation Patterns**: Can be attached as scalar beamwidths (current) or arrays/LUTs (feasible).
29. **Runtime Switching**: Fully supported via the `ShenronRadarModel` wrapper.

### 🚀 Performance & Scaling

30. **Point Budget**: 5,000 – 15,000 points per radar per frame (post-cropping).
31. **LUT Performance**: Highly acceptable; NumPy vectorized lookups for material/angle coefficients are not a bottleneck.
32. **Memory Pressure**: Low for point data. High for ADC cubes and large Range-Doppler FFT matrices if many radars run concurrently.

### 🐞 Validation & Debugging

33. **Logging Hooks**: The `last_metrology` dictionary in `model_wrapper.py` serves as the primary hook for internal diagnostics.
34. **Energy Annotation**: The internal `loss` array is calculated but usually discarded; it is not currently appended to the return point cloud.
35. **Comparison Hook**: Radars can be compared frame-by-frame by running two model instances on the same `semantic_lidar_data` buffer.

### 🔮 Future‑Proofing

36. **MIMO/Virtual Antennas**: Logic lives in `heatmap_gen_fast.py` inside the torch-accelerated phase-delay loop.
37. **Physics Separation**: A partial separation exists. `Sceneset.py` is "Scene Physics" (Reflection/Scattering), while `ConfigureRadar.py` is "Sensor Physics."
38. **Antenna Pattern Logic**: Logically belongs to the **Sensor Model** (`ConfigureRadar`) but must be applied during the **Scene Physics** stage to attenuate incident rays before they become ADC signals.

***
*Generated by Antigravity AI | Fox Radar ADAS Pipeline Architecture Review*