Timing Offset Handling

Description

This capability handles the configuration and application of static offsets to the phase and frequency components of a Timing source model. It supports both user-defined constant offsets and randomly generated offsets (based on a White Gaussian Noise - WGN model) specified in the simulation configuration. If both a random and a constant offset are specified for the same component (e.g., phase), the random offset takes precedence and the constant offset is ignored (with an error logged).

Assumptions

• Assumes the noise_utils::wgnSample function provides statistically suitable random values for generating the random offsets when requested.
• Assumes that logging an error message is sufficient notification if both a constant and a random offset are defined for the same component (phase or frequency) in the XML configuration, allowing the simulation to proceed using the random value.
• Assumes that the offset values, once determined (either the constant value from configuration or the randomly generated value at initialization), are correctly interpreted and utilized by the underlying ClockModelGenerator class.

Limitations

• Single Sampling for Random Offsets: Random offsets (both phase and frequency) are sampled only once during the initialization phase of the Timing model (specifically within Timing::initializeModel via calls to PrototypeTiming::getPhaseOffset / PrototypeTiming::getFreqOffset). The single random value drawn from the WGN distribution at this time is then treated as a fixed constant offset for the entire duration of that specific simulation run for that Timing instance. It does not represent a time-varying random jitter or wander applied per-sample or per-pulse.
• Optional Constant Offsets: If constant offsets are not specified in the XML configuration, they default to 0.

Related Components

• Code:
  • prototype_timing.cpp: Contains getPhaseOffset, getFreqOffset (implements the logic for choosing random over constant), setPhaseOffset, setFrequencyOffset, setRandomPhaseOffset, setRandomFrequencyOffset (stores configuration values, performs conflict checks/logging).
  • noise_utils.cpp: Contains wgnSample function used for generating the random offset values.
  • Timing::initializeModel: The function where the offset determination logic is invoked during setup.
  • ClockModelGenerator: The class that likely consumes the determined offset values as part of its noise generation process (details within Core Timing and Noise Generation).
• Wiki Pages:
  • Timing
  • Timing Configuration (XML)
  • Core Timing and Noise Generation
  • Noise Models
  • WGN Sample (Basic)

Validation Status

• Needs Verification: The precise behavior regarding the single sampling of random offsets and the override logic should be confirmed through targeted testing.
• Key Areas for Validation:
  • Confirm experimentally (e.g., multiple runs with random offsets enabled) that the generated offset remains constant throughout a single simulation run.
  • Verify that specifying a random offset in the XML correctly overrides a simultaneously specified constant offset for the same parameter (phase or frequency) and that the appropriate error message is logged.
  • Check that constant offsets correctly default to 0 if the corresponding XML elements are omitted.
  • Verify that the chosen/generated offset value is correctly passed to the ClockModelGenerator (the functional impact within the generator might be validated as part of Core Timing and Noise Generation).
• Priority: Medium