Motion

The Motion record that sets how often the world is resampled inside a frame, its five constructors, the adaptive tolerances and the replay modes.

Motion says how often Radar resamples the world inside one frame. Pass it as motion= to simulate, trace or stream. Build it with one of the five class methods; they are the only way to express a sampling choice.

from witwin.radar import Motion

The trade-offs between the modes are on Motion sampling.

Shared arguments#

Every constructor takes these two keyword arguments.

rediscover_every_framesint | Nonedefault None

How often to rediscover the path topology, in frames. None rediscovers at every observation, the only setting that cannot miss a new path.

worldstrdefault 'frozen_world'

How compiled geometry is replayed between rediscoveries. "frozen_world" retires paths that disappear and finds new ones. "fixed_winner_replay" keeps the discovered path set fixed: a path that disappears gives zero rows, and new paths are not added. Both refuse a change of topology, material or material assignment.

Motion.auto#

Motion.auto(*, rediscover_every_frames=None, world='frozen_world') -> Motion

Resample at every ADC instant when anything moves, else once per frame. "Moves" means a structure trajectory or deformation, an endpoint trajectory, a target trajectory, or oscillator phase noise in the receiver. This is the default when motion=None.

Motion.static#

Motion.static(*, rediscover_every_frames=None, world='frozen_world') -> Motion

One observation per frame. Refused with ValueError for a world that moves.

Motion.chirp#

Motion.chirp(*, rediscover_every_frames=None, world='frozen_world') -> Motion

Stop and hop: the geometry is frozen within each chirp, symbol or pulse and resampled between them. Captures Doppler across the frame but not range migration inside one chirp.

Motion.adc#

Motion.adc(*, rediscover_every_frames=None, world='frozen_world') -> Motion

Resample at every ADC instant. The exact reference, and the most expensive mode.

Motion.adaptive#

Motion.adaptive(*, phase_error=0.02, relative_amplitude_error=0.02, max_interval=0.002, nodes=2,
                max_evaluations=8192, batch_observations=256, rediscover_every_frames=None,
                world='frozen_world') -> Motion

Evaluate the world at error-controlled probe times and interpolate between them. FMCW only. On the scenes in the repository benchmarks it is 3 to 64 times faster than Motion.adc().

phase_errorfloatdefault 0.02

Largest tested round-trip phase error an accepted interval may have, rad.

relative_amplitude_errorfloatdefault 0.02

Largest tested relative amplitude error, dimensionless.

max_intervalfloatdefault 0.002

Longest spacing between two probes, s. Always enforced. Motion that repeats at exactly the probe step is invisible to the tests, and this bound sets that step.

nodesintdefault 2

Sampled instants one accepted interval interpolates through. 2 is linear interpolation, 5 is quartic.

max_evaluationsintdefault 8192

Discovery budget. Running out raises instead of returning an unchecked cube.

batch_observationsintdefault 256

Observations per batched replay.

Raises NotImplementedError at simulation for a non-FMCW waveform. RuntimeError when the evaluation budget runs out before every interval meets the tolerances.

The interpolation certifies nothing between probes: a very short path appearance can be missed. The Result therefore reports two flags. motion_sampling_exhaustive is False whenever an observation was interpolated. path_set_complete is True only when the candidate path set was proved complete. Per-frame details are in Result.adaptive_diagnostics.

result = radar.simulate(scene, targets, times=times, motion=Motion.adaptive(phase_error=0.01))
print(result.motion_sampling, result.path_set_complete, result.motion_sampling_exhaustive)
print(result.adaptive_diagnostics[0]["evaluations"])

Fields#

Motion is a frozen dataclass. Its fields are the arguments above plus kind, one of "auto", "static", "chirp", "adc" and "adaptive". The tolerance fields are ignored by every kind except "adaptive".

Raises ValueError for an unknown kind.