version: "1.0.1" name: matlab-simulate-radar-detections description: > Configure, simulate, debug, and analyze radarDataGenerator within radarScenario. Use for: interactively building radar detection scenarios from datasheets or performance requirements; diagnosing missed detections and configuration errors; interpreting sensor spherical, body, and scenario-frame outputs; deriving ReferenceRange from hardware specs via link budget; scan mode configuration (mechanical, electronic/AESA, hybrid); and validating simulation results against analytical predictions. license: https://www.mathworks.com/content/dam/mathworks/license/pmrl/license.md metadata: author: MathWorks version: "1.0"

Radar Data Generator — Statistical Detection Simulation

Build detection-level radar simulations using radarDataGenerator within radarScenario. This skill bridges user hardware specs and performance requirements to the Radar Toolbox statistical simulation API.

When to Use

• User wants to simulate radar detections on moving targets
• User has radar hardware specs (datasheet) or performance requirements and wants to build a simulation
• User mentions surveillance radar, scanning, revisit time, detection probability, or radar coverage
• User wants to compare scan strategies (mechanical vs electronic vs hybrid)
• User wants to generate detections to feed a tracker (trackerGNN, trackerJPDA) or do sensor fusion
• User wants Monte Carlo analysis, trade studies, or validation against link budget predictions
• User is studying radar placement or geometry to maximize coverage
• User has existing radarDataGenerator code that isn't working — missed detections, configuration errors
• User wants to validate simulation results against expected performance

When NOT to Use

• User needs I/Q-level waveform simulation (use radarTransceiver + pulse-Doppler chain)
• User needs CFAR detector design or beamforming
• User needs waveform design (ambiguity functions, chirp optimization)
• User already has detections and wants to process them
• User needs bistatic or multistatic radar configurations
• User needs interference or jamming modeling (EW scenarios)
• User wants to call radarDataGenerator standalone (without radarScenario) in a custom simulation loop

If the user needs signal-level fidelity, explain the tradeoff and hand off.

Detection Pathways

radarDataGenerator supports two detection pathways. This skill uses the target-pose pathway exclusively:

Properties from one pathway have zero effect on the other. Setting Sensitivity or DetectionThreshold in the target-pose pathway produces a "not relevant" warning.

Standalone mode: radarDataGenerator can also be called outside a scenario: [dets, numDets, config] = rdg(targetPoses, simTime). Use for integration into custom loops (Simulink, event-driven). Loses advance(), trajectory automation, multi-sensor aggregation, and coverage visualization. See references/detection-model.md for the full standalone API and pose struct requirements.

Workflow

Follow these 9 steps interactively. Do NOT silently choose parameters — engage the user at each decision point.

Step 1: Recommend Approach

Recommend statistical-level simulation using radarDataGenerator within radarScenario. Explain the tradeoff: fast iteration on scenario design vs less control over signal processing. If user needs I/Q-level fidelity, name the alternative path (radarTransceiver + pulse-Doppler + CFAR) and stop the structured 9-step flow.

When they confirm statistical-level, state the approach and name the APIs: radarScenario, radarDataGenerator, platform, waypointTrajectory/kinematicTrajectory/geoTrajectory.

Step 2: Confirm Use Case

Suggest a use case (e.g., ground-based surveillance scanning a sector). Confirm:

• Scan type: Propose mechanical, offer electronic or both
• Coordinate frame: NED (default), ENU, or Earth-centered. State implications.
• Configuration: Confirm monostatic
• Propagation environment: Default is FreeSpace (no refraction). If user mentions long range, low-elevation targets, or over-the-horizon, offer atmosphere models: atmosphere(scenario, model) — 'EffectiveEarth' (4/3 radius), 'RefractivityGradient', or 'CRPL'. These add refraction bias to propagation paths (ray bending), affecting reported target positions — they do NOT add atmospheric attenuation to the link budget. Weather/precipitation is NOT modeled at statistical level.

Step 3: Ask Parameter Sourcing Direction

"Which direction are you working? Top-down (specify requirements, derive hardware)? Bottom-up (specify hardware, derive performance)? Or a mix?"

If user provides a datasheet: follow the datasheet ingestion procedure in references/coupled-parameters.md — extract parameters, map to groups, identify gaps, close link budgets, flag conflicts.

The flow branches here:

Top-down path (Steps 4 → 5): User specifies performance requirements first, then derive hardware.

• Step 4: Propose reference performance (range, RCS, Pd, Pfa)
• Step 5: Present coupled-parameter table, derive hardware needed to meet requirements

Bottom-up path (Steps 5 → 4): User specifies hardware first, then derive performance.

• Step 5: Present coupled-parameter table, collect hardware specs (power, gain, NF, bandwidth, etc.)
• Step 4: Derive and present reference performance from hardware via radareqrng

Mixed/Datasheet: Collect what they have, fill gaps from both directions, flag inconsistencies.

Both paths converge at Step 6 (Target Set Design).

Step 4: Propose Reference Performance

Present as a reference target specification:

• Reference range, reference RCS (note: ReferenceRCS is in dBsm)
• Detection probability, false alarm rate (valid: [1e-7, 1e-3])
• Integration type and number of pulses (assume coherent; ask for N or CPI)
• Monostatic, clear sky

Top-down: Present concrete defaults. Let user react/modify. Bottom-up: Present values derived from their hardware. Show the derivation (which function, which inputs). For integration: assume coherent, ask number of pulses or CPI duration. Use detectability(Pd, Pfa, 1, 'SwerlingN') - 10*log10(N) for required SNR. The Swerling argument is a string: 'Swerling0', 'Swerling1', ..., 'Swerling4'. Never pass N to detectability for coherent systems — that applies non-coherent loss. See references/interaction-flow.md § Step 4 for the full decision table.

Step 5: Present Coupled-Parameter Table

Show the parameter-relationship table from references/coupled-parameters.md. This builds confidence, shows traceability, invites correction.

Top-down: Use the table to derive what hardware is needed to meet the agreed reference performance. Bottom-up: Use the table to collect the user's hardware specs and identify which groups are constrained.

Step 6: Target Set Design

Confirm geometry (radar placement, scan sector, airborne targets). Propose physically representative targets varying:

• RCS (UAV ~0.01 m², fighter ~1 m², commercial ~10 m²)
• Speed (50 m/s rotary, 250 m/s jet, 300+ m/s fast mover)
• Altitude (500 m nap, 5 km mid, 10 km high)

Offer Swerling models (I = slow-fluctuating, III = dominant scatterer). Configure per-target RCS via rcsSignature on each platform's Signatures property — see references/detection-model.md for patterns. Default platform RCS is 10 dBsm (Swerling0).

Sanity checks before proceeding:

1. Verify target geometry is within radar horizon using horizonrange(antennaHeight). If any target is beyond LOS at its specified altitude, flag this to the user.

1. Compute the expected 0.9 Pd reference range for each target. Report a table like:

Use: SNR_at_R = RadarLoopGain + RCS_dBsm - 40*log10(range), then map SNR to Pd with the correct Swerling formula (see references/radar-equation-tools.md). Flag any target where expected Pd < 0.5 — the user should know which targets will have unreliable detection before running the sim.

Ask: "Do you need terrain or ground returns, or is free-space sufficient?"

Step 7: Terrain / Occlusion

If applicable — see references/terrain-clutter-atmosphere.md for terrain options. Terrain and occlusion are additive after validating detections in free-space. landSurface for height maps, seaSurface for sea state, customSurface for user-defined. landSurface has occlusion() for LOS blocking. HasOcclusion on radarDataGenerator is target-to-target occlusion.

Step 8: Simulation Duration

Ask in user's terms: seconds, number of scans, number of target illuminations, or event-based. Convert between these once scan parameters are locked.

Step 9: Produce Requirements Sheet

Generate a standalone document with three sections — see references/requirements-sheet-template.md.

Key Functions

Conventions

Traceability

• Every stochastic quantity traces to a configured parameter
• radarDataGenerator provides built-in traceability — property names ARE the documentation
• If hand-rolling any computation, comment the model, its parameters, and how it connects to system design

Coordinate Frames

• Pick ONE frame and use it consistently throughout
• waypointTrajectory has 'ReferenceFrame' property: 'NED' or 'ENU' — use with IsEarthCentered = false
• kinematicTrajectory has NO ReferenceFrame — inherits from scenario — use with IsEarthCentered = false
• geoTrajectory uses geodetic waypoints [lat, lon, alt] in [deg, deg, m] — requires IsEarthCentered = true
• Has 'ReferenceFrame' ('NED'/'ENU') for velocity/orientation interpretation
• Also supports Course, GroundSpeed, ClimbRate as alternatives to Velocities
• DetectionCoordinates = 'Scenario' reports in ECEF (meters), not lat/lon
• Single waypoint = stationary platform (TimeOfArrival is ignored)
• Constraint: trajectory type and IsEarthCentered are strictly coupled — mixing produces an error
• NED: elevation is negative above horizon. ENU: elevation is positive above.
• Always validate: compute expected elevation analytically, compare to measured

Parameter Source Tags

Every parameter in the requirements sheet gets a tag:

• User-provided — they told us
• Domain assumption — reasonable default, justified
• Derived — computed from other params (show which function)

System Parameters vs Simulation Parameters

Once the user's requirements and use case are confirmed (Steps 2–6), distinguish between:

• System parameters (user's design): FieldOfView, CenterFrequency, Bandwidth, MaxAzimuthScanRate, ReferenceRange, antenna height, etc. Never change these to fix a simulation issue.
• Simulation parameters (our configuration): UpdateRate, RangeLimits, scenario UpdateRate, DetectionCoordinates, simulation duration. These can be tuned freely.

If a simulation artifact occurs (e.g., missed detections due to beam stepping), fix it by adjusting simulation parameters. If the fix requires changing a system parameter, surface it to the user with physical intuition — it's a design insight, not a sim fix.

Self-Consistency

After deriving all parameters, validate the loop closes:

• Compute Rmax from hardware via radareqrng
• Configure ReferenceRange = Rmax
• Run simulation, confirm ~Pd at reference range
• If mismatch, diagnose and flag

Common Mistakes

Scan Mode Quick Reference

Convenience constructors: radarDataGenerator(id, 'Raster'), 'Rotator', 'Sector', 'Custom'.

Mechanical Scan Rate Model (Critical)

The actual scan rate for mechanical mode is:

actualScanRate = min(FieldOfView(1) * sensorUpdateRate, MaxAzimuthScanRate)  [deg/s]
stepPerScenarioUpdate = actualScanRate / scenarioUpdateRate  [deg]

Default sensor `UpdateRate` is 1 Hz. If not set explicitly, a 2-deg beam scans at only 2 deg/s regardless of MaxAzimuthScanRate. Always set sensor UpdateRate explicitly:

radar = radarDataGenerator(1, 'Sector', ...
    'UpdateRate', 20, ...  % MUST set — default 1 Hz causes very slow scan
    'FieldOfView', [2; 20], ...
    'MaxAzimuthScanRate', 36, ...
    ...);
% actualRate = min(2*20, 36) = 36 deg/s ✓

To achieve a desired scan rate with a narrow beam:

• sensorUpdateRate >= desiredRate / FieldOfView(1)
• Example: 36 deg/s with 2-deg beam needs UpdateRate >= 18 Hz

Scenario vs Sensor UpdateRate

The sensor fires at its own UpdateRate; the scenario UpdateRate controls how often advance()/detect() execute. If scenario rate < sensor rate, only a fraction of dwell positions are sampled — targets between sampled positions produce zero detections silently.

Rule: Always set scenario UpdateRate = sensor UpdateRate unless you specifically want sparse detection cadence.

Detection Model

SNR = RadarLoopGain + RCS_dBsm - 40*log10(Range)

• RadarLoopGain: read-only, derived from ReferenceRange + ReferenceRCS + DetectionProbability + FalseAlarmRate. The reference SNR uses Swerling0 (non-fluctuating) internally — target fluctuation models are applied separately at detection time.
• No hardware knobs (Pt, Gain, NF) — all lumped into reference performance
• CenterFrequency/Bandwidth affect resolution only, not detection range
• Measurement accuracy: σ² = (Δ/√(2·SNR))² + (BiasFraction·Δ)² — Cramér-Rao plus bias floor. Defaults: AzimuthBiasFraction=0.1, RangeBiasFraction=0.05, ElevationBiasFraction=0.1. At high SNR the bias floor dominates (0.3° azimuth, 3.75m range).
• Pd vs range depends on target FluctuationModel — default platforms are Swerling0 (non-fluctuating). Use marcumq for Swerling0, Pfa^(1/(1+SNR)) for Swerling1. Using the wrong formula gives ~40% Pd error. See references/radar-equation-tools.md for the full recipe.

The agent's job is to bridge between user hardware specs and this statistical interface using radar equation tools as the translation layer.

Troubleshooting

Programmatic Verification

Detection accuracy check — verify measurement errors are within expected bounds. This must account for DetectionCoordinates mode — raw .Measurement values cannot be compared to scenario-frame truth unless using 'Scenario' mode:

% Convert detection to scenario frame FIRST (required for all non-Scenario modes)
mp = dets{k}.MeasurementParameters(1);  % first element = position transform
meas = dets{k}.Measurement;
switch mp.Frame
    case 'Spherical'
        az = meas(1); el = meas(2); R = meas(3);
        posSensor = [R*cosd(el)*cosd(az); R*cosd(el)*sind(az); R*sind(el)];
        measScenario = mp.Orientation * posSensor + mp.OriginPosition(:);
    case 'Rectangular'
        measScenario = mp.Orientation * meas(1:3)' + mp.OriginPosition(:);
end
posError = norm(measScenario - truthPos);
expectedSigma = sqrt(trace(dets{k}.MeasurementNoise(1:3,1:3)));
assert(posError < 5*expectedSigma, 'Position error exceeds 5-sigma');

SNR check — verify reported SNR matches link budget prediction (within ~1 dB):

expectedSNR = radar.RadarLoopGain + rcs_dBsm - 40*log10(slantRange);
reportedSNR = dets{k}.ObjectAttributes{1}.SNR;
assert(abs(reportedSNR - expectedSNR) < 1.0, 'SNR mismatch > 1 dB');

See Coordinates & Transforms — Verification for full mode-aware verification patterns.

Debugging: Isolate Beam Pointing

When diagnosing "no detections" or unexpected detection gaps, isolate whether the problem is beam pointing vs. something else:

1. Release the sensor, then go omnidirectional:

origFoV = radar.FieldOfView;
origScan = radar.ScanMode;
release(radar);
radar.FieldOfView = [360; 180];
radar.ScanMode = 'No scanning';

1. Restart and re-run the scenario (restart(scenario) + advance loop)
2. Interpret:

• Detections appear → problem is beam pointing (scan limits, MountingAngles, FoV, scan stepping over target)
• Still no detections → problem is elsewhere (RangeLimits, UpdateRate aliasing, ReferenceRange, horizon, target RCS)

1. Release and restore original config before continuing:

release(radar);
radar.FieldOfView = origFoV;
radar.ScanMode = origScan;

Note: radarDataGenerator is a System object. Non-tunable properties (FieldOfView, ScanMode, AzimuthResolution, scan limits, etc.) cannot be changed after detect() has been called without first calling release(radar). Always release() before modifying non-tunable properties.

Do this BEFORE drilling into individual parameters — it splits the problem space in half with one test.

Debugging Order

1. Omnidirectional isolation (above) — rules out beam pointing in one test
2. Inspect systematic causes — RangeLimits gate, scan sector bounds, UpdateRate aliasing. These produce deterministic failures (0% Pd) and are identifiable from a single run.
3. Monte Carlo trials (last) — only after systematic causes are ruled out. Use repeated runs to characterize stochastic behavior: Swerling fluctuation, intermittent detections near the detection boundary, empirical Pd vs analytical Pd. Never run Monte Carlo to diagnose a target that gets 0 detections — that is always a systematic cause.

Fix Forward: Step Hierarchy

When validation fails, fix the latest step that could be wrong. Never change a system parameter (Steps 1–5) to accommodate a scenario choice (Steps 6–7). If the radar's FoV doesn't cover a target, the target is out of coverage — don't widen FoV to "fix" it. Only revisit earlier steps when there is a genuine design error.

Analyzing Simulation Outputs

Critical NED traps that cause silent errors:

• Geometric elevation (positive up): atand(-dx(3) ./ horizRange) — negate D-axis so airborne targets get positive angle. Sensor spherical elevation has opposite sign for NED (sensor +z = Down): airborne targets get negative el.
• Azimuth: atan2d(East, North) — swapping arguments gives azimuth from East (90° error)
• Empirical Pd: platformID = targetIndex + 1 (radar is platform 1) — off-by-one is common
• Analytical Pd: Default is Swerling0 (marcumq), not Swerling I — using wrong formula gives 40% error
• SNR: RadarLoopGain + RCS_dBsm - 40*log10(R) — do NOT add integration gain (already in RLG)

See Coordinates & Transforms for full conversion recipes and verification patterns.

Output Requirements

1. Requirements sheet — standalone document (see template in references)
2. MATLAB script — runnable, with design-rationale comments and coupled-parameter table
3. Validation — compare simulation detections to analytical predictions

Code Generation Rules

• Never rely on defaults for `radarDataGenerator`. Set every relevant property explicitly in the constructor, even when using the default value. This makes the code self-documenting — a reader should see every parameter choice without consulting documentation. Hidden defaults are hidden assumptions. Exception — property gating: Do NOT set properties that are irrelevant to the current configuration. Setting gated properties produces warnings ("not relevant in this configuration"). See the property-gating table below.
• Tag each parameter value with its source: user-provided, derived (from which inputs), or domain assumption (with justification).

Property-Gating Rules

Properties gated by Has* flags — do NOT set these when the flag is false:

Properties gated by ScanMode:

Never set HasScanLoss — it warns in all scan modes (not valid in any current configuration).

When EmissionsInputPort=true: do NOT set ScanMode, FieldOfView, or any scan-limit/rate properties (scan is driven by emissions).

Properties gated by TargetReportFormat:

Properties gated by DetectionMode:

References

Load only what the task requires — do not read all references for every prompt.

Copyright 2026 The MathWorks, Inc.