Skip to content

Using FERS

Jump to bottom
github-actions[bot] edited this page Aug 21, 2026 · 5 revisions

Using FERS

FERS runs a .fersxml scenario and writes receiver I/Q data to HDF5 files. A normal workflow is:

  1. Create or choose a scenario. You can write XML directly or use FERS UI to build it visually.
  2. Run it with fers-cli or from the UI Simulation Run view.
  3. Open the generated HDF5 files in an analysis script.
  4. Compare the simulated signals with the radar effect you expected.

Run A Scenario

./build/release/packages/fers-cli/fers-cli path/to/scenario.fersxml --out-dir=./results

If --out-dir is omitted, FERS writes results beside the scenario file.

Generate KML instead of running the simulation:

./build/release/packages/fers-cli/fers-cli path/to/scenario.fersxml --kml=scene.kml

What A Scenario Describes

A scenario describes the radar scene, not the analysis you want to run afterward.

At a high level it contains:

  • Global settings, such as start time, end time, sample rate, and KML/geospatial reference settings.
  • Waveforms, including pulsed files, finite HDF5-backed CW/FMCW signals, generated CW tones, and generated FMCW chirps.
  • Timing sources, which model oscillator frequency, phase, and noise behavior.
  • Antennas, which determine gain as a function of direction.
  • Platforms, which move through the scene.
  • Radar objects on platforms: transmitters, receivers, monostatic radars, and targets.
  • Optional schedules, which turn transmitters and receivers on only during selected time intervals.

The complete XML reference is in XML Schema Reference.

Choose The Right Radar Mode

Mode Use when Scenario pieces
Pulsed You have a pulse waveform and want range-gated receiver windows. <pulsed_from_file>, <pulsed_mode>, prf, window_skip, window_length.
CW You want continuous-wave Doppler-style output. Prefer <cw_from_file>; <cw/> generates a simple tone. Use <cw_mode/>.
FMCW You want chirp-based ranging or range-Doppler analysis. Prefer <fmcw_from_file>; generated <fmcw_linear_chirp> and <fmcw_triangle> remain available. Use <fmcw_mode> and optional dechirp settings.
SFCW You want stepped narrowband RF dwells that synthesize a wider range profile without one wide baseband waveform. <stepped_frequency>, <sfcw_mode/>, step size/count, dwell time, and step period.

The waveform type and radar mode must match. For example, <cw_from_file> and <cw/> use <cw_mode/>, while <fmcw_from_file>, <fmcw_linear_chirp>, and <fmcw_triangle> use <fmcw_mode>.

Monostatic And Bistatic Layouts

Use <monostatic> when the transmitter and receiver are colocated and share the same antenna, waveform, and timing reference.

Use separate <transmitter> and <receiver> elements when you need a bistatic or multistatic scene. The transmitter and receiver can be on different platforms, use different antennas, and have separate schedules.

Output Files

FERS writes one HDF5 file per receiver:

<receiver-name>_results.h5

Monostatic radars also write through their receiver side, using the monostatic name.

Pulsed Output

Pulsed receivers write one pair of datasets per receiver window:

chunk_000000_I
chunk_000000_Q
chunk_000001_I
chunk_000001_Q
...

Each chunk represents one receiver window. Use window_skip and window_length from the scenario, plus the metadata stored in the HDF5 file, to convert samples to range.

CW, FMCW, And SFCW Output

Streaming receivers write:

I_data
Q_data

For FMCW with dechirping enabled, these datasets contain the dechirped IF output. Without dechirping, they contain the received complex baseband signal. File-backed CW/FMCW sources stop after their final HDF5 sample and do not wrap implicitly. File-backed FMCW metadata reports sampled duration and count instead of inferred analytic chirp parameters. SFCW output is raw streaming complex baseband; the HDF5 metadata records the step timing and RF frequencies needed for downstream range-profile reconstruction.

Reconstruct Physical I/Q Values

FERS normalizes stored samples. To recover the physical sample values, multiply by the fullscale attribute.

import h5py

with h5py.File("Rx_results.h5", "r") as h5:
    fullscale = h5.attrs["fullscale"]
    iq = (h5["I_data"][:] + 1j * h5["Q_data"][:]) * fullscale

For pulsed chunks, fullscale is stored on the chunk datasets:

with h5py.File("PulsedRadar_results.h5", "r") as h5:
    i = h5["chunk_000000_I"][:]
    q = h5["chunk_000000_Q"][:]
    fullscale = h5["chunk_000000_I"].attrs["fullscale"]
    iq = (i + 1j * q) * fullscale

Metadata

FERS stores metadata in the HDF5 output, including receiver mode, sample rates, sample counts, time span, fullscale values, and FMCW or SFCW settings when applicable.

Use the metadata whenever possible instead of hard-coding assumptions in analysis scripts.

SFCW HDF5 Metadata

Complete native SFCW metadata uses this hierarchy:

/metadata/sfcw
└── sources
    ├── source_0
    │   ├── waveform
    │   └── segments
    │       ├── segment_0
    │       └── ...
    └── source_1
        └── ...

Each source group records transmitter and waveform identity. Its waveform group records carrier, step grid, dwell timing, sweep count, and derived range values. Each segment group records schedule bounds, first emitted step time, and emitted step count when available. This hierarchy represents every SFCW source in a receiver output and is semantically equivalent to sfcw_sources inside fers_metadata_json.

Root-level sfcw_* attributes remain compatibility summaries for single-source files. They do not contain source or schedule nesting and must not be treated as complete multi-source metadata. sfcw_flat_attributes_are_summary marks this explicitly, while sfcw_metadata_path points to the complete native hierarchy.

Sample Rates

The most important rates are:

Setting Meaning
<rate> Base output sample rate in Hz. Raw CW/FMCW/SFCW streaming output is written at this rate.
<simSamplingRate> Rate used for geometry interpolation in pulsed response generation.
<oversample> Internal oversampling multiplier. FMCW aliasing checks and legacy full-rate dechirped IF output use <rate> * <oversample>.
<if_sample_rate> Optional receiver-local FMCW IF output rate after dechirping and resampling.

Use a high enough <rate> and <oversample> to represent the signal bandwidth you expect. Generated FMCW waveforms must also satisfy the baseband sweep-edge checks described in XML Schema Reference. For file-backed CW/FMCW, <rate> is the HDF5 sample rate; FERS does not infer bandwidth, sweep direction, or repetition from the samples. For SFCW, <rate> must be high enough to capture the dwell intervals you want to analyze; the wide effective bandwidth comes from RF step metadata, not a wide instantaneous baseband waveform.

Validation

By default, FERS validates the XML structure before running:

./build/release/packages/fers-cli/fers-cli scenario.fersxml

You can skip XML validation:

./build/release/packages/fers-cli/fers-cli scenario.fersxml --no-validate

Use --no-validate only when diagnosing a file. A file that skips schema validation can still fail later if references, numbers, radar modes, or physics settings are invalid.

KML Export

KML export helps inspect platform paths and scenario geometry in a map or geospatial viewer:

./build/release/packages/fers-cli/fers-cli scenario.fersxml --out-dir=./results --kml

Default output:

<out-dir>/<scenario-name>.kml

KML generation uses the scenario's KML/geospatial <origin> and <coordinatesystem> settings to place exported geometry in latitude/longitude. These settings do not affect the signal simulation.

If KML generation fails, fers-cli exits with a nonzero status and logs the reason. Common causes are an invalid output path, missing parent directory, scenario loading failure, or invalid KML/geospatial settings.

Troubleshooting

Symptom Likely cause
XML validation fails Elements are out of order, required attributes are missing, or a mode block does not match the schema.
Scenario loads but does not run A referenced waveform, antenna, timing source, or platform object name is wrong.
Output is all zeros Receiver schedule/window may miss the return, antenna pointing may be wrong, target may be outside the simulated time span, or path loss may make the signal very small.
Pulsed range looks offset Check window_skip, window_length, waveform sample rate, and speed of propagation c.
Generated FMCW run fails validation Check chirp bandwidth, chirp duration, chirp period, count fields, start_frequency_offset, <rate>, <oversample>, and IF-chain settings.
CW/FMCW file waveform fails to load Use an HDF5 .h5 file with equal-length one-dimensional /I/value and /Q/value datasets; CSV is supported only for pulsed file waveforms.
File-backed CW/FMCW output stops early File playback is finite and does not wrap; provide enough samples for the active transmitter interval or schedule another active segment to restart playback.
SFCW run fails validation Check step_size, step_count, dwell_time, step_period, sweep_count, and that every RF step remains positive.
KML looks wrong geographically Check KML/geospatial <origin>, <coordinatesystem>, UTM zone, and hemisphere.

Old XML Files

Run the migration script for legacy files:

python3 scripts/migrate_fers_xml.py old.fersxml migrated.fersxml

Then inspect the result manually. Old <export> and <multipath> settings are not supported in the current scenario format.

FERS

Clone this wiki locally