Frequency Offset Estimator

class ptp.frequency.Estimator(data, delta=1, pkts=None, N_pkts=128)[source]

Frequency offset estimator

Parameters

  • data – Array of objects with simulation data

  • delta – (int > 0) Observation interval in samples. When set to 1, estimates the frequency offsets based on consecutive data entries. When set to 2, estimates frequency offset i based on timestamps from the i-th iteration and from iteration ‘i-2’, and so on.

  • pkts – Packet selection/filtering strategy to apply before computing unbiased frequency offet estimates (sample-min or sample-max). When set to None, disables the pre-filtering stage.

  • N_pkts – Packet selection window length.

estimate_drift()[source]

Estimate the incremental drifts due to frequency offset

On each iteration, the true time offset changes due to the instantaneous frequency offset. On iteration n, with freq. offset y[n], it will roughly change w.r.t. the previous iteration by:

drift[n] = y[n] * (t1[n] - t1[n-1])

Estimate these incremental changes and save on the dataset.

loop(damping=1.0, loopbw=0.001, settling=0.2)[source]

Estimate time offset drifts using PI loop

The PI loop tries to minimize the error between the input time offset estimate and the time offset that is expected based on not only the previous estimate, but also the loop’s notion of frequency offset. In the long term, the loop should converge to learning the average time offset drift (or frequency offset) such that the error is minimized.

The time offset drift estimates that are produced by the loop are only saved in the main data list after the loop settles. Other blocks will use the presence of drift estimates to infer when drift estimates are locked. In other words, if the “drift” key is not in a dict of the data list, the loop is not locked yet at this point.

Note that the convergence of the loop is not explicitly tested here. Instead, we simply define the portion of the dataset that can be used for settling. All estimates produced past this portion of the dataset are saved, the other values are discarded. The rationale is that the optimizer also considers the same settling time margin. Hence, if the damping and loopbw parameters came from the optimizer, the values past the chosen settling time are already optimal and very likely effectively settled (converged).

Parameters

  • damping – Damping factor

  • loopbw – Loop bandwidth

  • settling – Fraction of the dataset over which the loop can settle. Results are only saved after this portion of the dataset.

optimize_loop(criterion='cumulative', loss='mse', cache=None, cache_id='loop', force=False, max_transient=0.2)[source]

Find loop parameters that minimize the drift estimation error

Tries some pre-defined damping factor and loop bandwidth values.

By default the damping factor and loop bandwidth are tuned using the cumulative drift instead of the absolute. This is because the latter leads to a time offset drift estimation that is very close to the ‘optimize_to_y’, while the former yield the best estimation performance.

Parameters

  • criterion – Error criterion used for tuning: cumulative or instantaneous time offset drift error.

  • loss – Loss function (mse or max-error).

  • cache – Cache handler used to save the optimal configuration on a JSON file.

  • cache_id – Cache object identifier

  • force – Force processing even if a configuration file with the optimal parameters already exists in cache.

  • max_transient – Maximum fraction of the dataset to be occupied by the transient phase of the loop. This parameter controls the maximum tolerable latency to obtain the first drift estimates.

optimize_to_drift(strategy, loss='mse', criterion='cumulative', max_window_span=0.2, cache=None, cache_id='drift_estimator', force=False)[source]

Optimize the observation interval used for freq. offset estimation

Optimize based on the time offset drift estimation errors. This optimizer can lead to better performance because, in the end, what we really care about is predicting drifts accurately.

Parameters

  • strategy – Unbiased frequency offset estimation strategy.

  • loss – Loss function used to optimize the window length (mse or max-error).

  • criterion – Whether the loss function is applied to the cumulative time offset drift or the instantaneous time offset drift error.

  • max_window_span – Maximum fraction of the dataset to be occupied by the observation window. This parameter controls the maximum tolerable latency to obtain the first frequency offset and time offset drift estimates (by the end of the first observation window).

  • cache – Cache handler used to save the optimal configuration on a JSON file.

  • cache_id – Cache object identifier.

  • force – Force processing even if a configuration file with the optimal parameters already exists in cache.

Note

The cumulative criterion typically leads to better optimization performance. The absolute criterion considers estimation errors that are often masked by the uncertainty on dataset labels. For example, if the truth labels have an uncertainty of +-8 ns and the instantaneos drift error is < 1 ns, then the instataneous drift error becomes negligible relative to the uncertainty. In contrast, the cumulative criterion accumulates error such that the cumulative values are significantly greater than the intrinsic uncertainty on dataset labels. For example, if the instantaneous drift is in the order of 1 ns and is accumulated over 200 samples, the cumulative result (around 200 ns) becomes significantly greater than the truth uncertainty (e.g., 8 ns). Consequently, the optimization based on cumulative error considers the actual drift estimation errors.

optimize_to_y(strategy, loss='mse', max_window_span=0.2)[source]

Optimize the observation interval used for freq. offset estimation

Optimizes the observation interval used for unbiased frequency offset estimations in order to minimize the error between the estimates and the true frequency offset. This minimization can be either in terms of the mean square error (MSE) or the maximum absolute error (max|error|).

The problem with this approach is that the truth in “y” (the true frequency offset) is questionable. Since the true y values are also computed based on windows, the window length used for the truth computation affects results and may render the optimization below less effective for drift compensation.

Parameters

  • strategy – Unbiased frequency offset estimation strategy.

  • loss – Loss function used to optimize the window length (mse or max-error).

  • max_window_span – Maximum fraction of the dataset to be occupied by the observation window. This parameter controls the maximum tolerable latency to obtain the first frequency offset estimate (by the end of the first observation window).

process(strategy='two-way')[source]

Process the data

Estimate the frequency offset relative to the reference over all the data. Do so by comparing interval measurements of the slave and the master. This is equivalent to differentiating the time offset measurements.

Compute one of the following:

y_est_1[n] = (t21[n] - t21[n-N]) / (t1[n] - t1[n-N]),

or

y_est_2[n] = -(t43[n] - t43[n-N]) / (t4[n] - t4[n-N]),

or

y_est_3[n]   = (y_est_1[n] + y_est_2[n]) / 2.

These are the one-way, reversed one-way, and two-way implementations, respectively.

Parameters

strategy – Select between one-way, one-way-reversed, and two-way. The one-way strategy uses the m-to-s timestamps (t1 and t2) only. The two-way strategy relies on the two-way time offset measurements (x_est), namely on all timestamps (t1, t2, t3, and t4). The reversed one-way strategy uses the s-to-m timestamps (t3 and t4) only.

set_truth(delta=None)[source]

Set “true” frequency offset based on “true” time offset measurements

Parameters

delta – (int > 0) Observation interval in samples. When set to 1, estimates the frequency offsets based on consecutive data entries. When set to 2, estimates frequency offset i based on timestamps from the i-th iteration and from iteration ‘i-2’, and so on. When set to None, use the delta value set in self.delta (default: None)