file name: algrate.hpp, algrate.cpp
author: Klaus Schossmaier
classification: simulation
contents: class CRate, derived from class ACClockSyncAlgorithm
use: provides a convergence function that uses the optimal precision
(OP) function to compute a new clock value, a new accuracy interval, and
a new rate interval; the needed parameters for function OP are either provided
as constants or computed
global items used by CRate:
member variables and types of CRate:
struct
SRateTime: Type for relative rate measurement data; derived from SRate.
int cntDelay:
Gives the number of transmission delay measurements after startup.
default and reset value: 0
SINT32
nodeID: Gives the ID of the node.
default: the nodeID of the CSA.
int area:
Gives the area of the node.
default: the area of the CSA.
double
piHMinus: Parameter of function OP (negative part of maximal precision
interval).
double
piHPlus: Parameter of function OP (positive part of maximal precision
interval).
double
piOwnMinus: Parameter of function OP (negative part of own precision
interval).
double
piOwnPlus: Parameter of function OP (positive part of own precision
interval).
double
ups: Parameter of function OP (maximal state correction).
double
sigma: Gives the maximum oscillator stability.
double
gammaHMinus: Parameter of function OP (negative part of maximal consonance
interval).
double
gammaHPlus: Parameter of function OP (positive part of maximal consonance
interval).
double
gammaOwnMinus: Parameter of function OP (negative part of own consonance
interval).
double
gammaOwnPlus: Parameter of function OP (positive part of own consonance
interval).
double
thetaMax: Parameter of function OP (maximal rate correction).
EBool
rateRound: When True, it indicates that this round is also for rate
synchronization.
default value: False
member functions of CRate:
CRate (CClockSync
*cs): This constructor function initializes the members to their default
values, sets the resynchronization status of cs to True and calls
ClockChanged()
to initialize clock dependent data. If cs is NULL, an assert fails.
virtual
void ClockChanged (): Initializes the deterioration and the accuracy
interval maintained by the local clock, the precision intervals and maximal
state correction to parameterize function OP for state synchronization,
and the consonance intervals and maximal rate correction to parameterize
function OP for rate synchronization. The function first calls
ClockChanged()
of the base class to initialize the estimated rate. Then it calls GetClock()
to get a pointer to the local clock. If GetClock() returns NULL,
the function returns at this point. Otherwise, it sets the algorithm parameters
either directly by using macros or computes their values with the help
of various functions from class
ACClockSyncAlgorithm
and class
CClockInterface. The clock is set
accordingly.
Note: When initializing the clock, set the deterioration of
the accuracy intervals before their length.
virtual
EBool ConvergenceFunction (): The function gets first the associated
network calling GetAssociatedNetwork(). If it exists, it tries
to synchronize the rate and then the state of the clock. Whether a rate
synchronization takes place or not is controlled by the member variable
rateRound,
which can only be set to True by the member function
StoreRate().
Note: This easy way of rate round indication only works when
all nodes are in synch. In case of a rate round, Rate() is called
with the associated network. If the function returns True, the resulting
factor multStep affects register STEP of the clock, rateRound
is set to False, and the resulting rate interval is taken over. The latter
is deteriorated for the next state round and renews the deterioration of
the accuracy interval maintained by the local clock. Moreover, the
inherited function ReportRate() is called to notify the evaluation
of the new rate interval.
Then, State() is called with the associated network.
If the function returns True, the resulting reference point and accuracy
interval is stored in newClockValue, and timeValid
is set to True. Moreover, the inherited function
ReportInterval()
is called. If there is no associated network, or if Rate()
or State() returns False, timeValid is set to False.
The function returns True if a new timestamp and optional rate interval
could be computed, False if no associated network exists or if Rate()or
State() has failed.
Note: If no associated network exists, Rate() and State()
are not called and the database remains unchanged. If State()
is called and fails, all time intervals stored for the associated network
are discarded. If Rate() is called and fails, all rate information
stored for the associated network remains unchanged.
static ACClockSyncAlgorithm
*CreateRate (CClockSync *cs): Creates a new object of type CRate
(passes cs to the ctor) and returns a pointer to it.
EBool Rate
(double& multStep, double& theta_minus, double& theta_plus,
SINT32 networkID): Computes the new coupling factor and rate interval,
uses the rate information that are stored in database. The entries
of the given network are not deleted! The function returns True if the
computation was successful, in that case consIntResult contains
the new consonance interval and rateIntResult the new rate interval.
The parameters
multStep, theta_minus, theta_plus
are set (inclusive a normalization) to return the result. If the computation
has failed, False is returned.
Algorithm OP for Clock Rate Synchronization: The pre-processed
consonance intervals consonanceIntervals[] and rate intervals
rateIntervals[]
are calculated from database, with index 0 containing the own
ones. The Marzullo function ApplyMarzullo() is
applied on the consonance intervals, the resulting interval consIntMarz
is intersected with the own one, and the reference point is fixed, leading
to consIntResult. The Marzullo function is then applied on the
rate intervals, the resulting interval
rateIntMarz is intersected
with the own one, and extended to contain the reference point, leading
to rateIntResult.
Note: The debugging code to output the rate intervals on gnuplot-files
can be (de)activated by (un)defining the according macros.
EBool State
(CNtpTime& point, double& alpha_minus, double& alpha_plus,
SINT32 networkID): Computes the new clock interval for the network,
uses the time intervals that are stored in database. All interval
entries of the given network are then deleted. The function returns True
if the computation was successful, in that case preIntResult contains
the new precision interval and accIntResult the new accuracy interval.
The parameters point, alpha_minus, alpha_plus
are set to return the result. If the computation has failed, False is returned.
Algorithm OP for Clock State Synchronization: The pre-processed
precision intervals precisionIntervals[] and accuracy intervals
accuracyIntervals[]
are calculated from database, with index 0 containing the own
ones. The Marzullo function is applied on the precision intervals, the
resulting interval preIntMarz is intersected with the own one,
and the reference point is fixed, leading to preIntResult. The
Marzullo function is then applied on the accuracy intervals, the resulting
interval accIntMarz is intersected with the own one, and extended
to contain the reference point, leading to accIntResult.
Note: The debugging code to output the state intervals on gnuplot-files
can be (de)activated by (un)defining the according Macros.
virtual
EBool StoreDelay (double localDelay, double remoteDelay, const SRate&
remoteRate, SINT32 networkID, const CAddr& netAddress): Counts
the number of delay measurement rounds after startup in member cntDelay
and sets the resynchronization status of CS to False if StartSynchronization
rounds have passed (after that, the function stops counting). Calls StoreDelay()
of
the base class with the input parameters and propagates its return value.
virtual
EBool StoreRate (const SRate& remoteRate, const CNtpTime& localTime,
const CNtpTime& remoteTime, SINT32 networkID, const CAddr& netAddress,
int remoteArea): Computes the remote rate interval when a rate interval
arrives from a peer node and puts it into the database. ReportRate()
is called to report the new input rate interval to the evaluation. The
function returns True if successful, False if the computation cannot be
done. The function is called by ClockSync() whenever a rate measurement
message arrives. If there is an entry in the database, the quotient rate
interval quotInt is computed (relative rate measurement), followed
by the remote rate interval rateInt. Subsequently, the entry in
the database is updated accordingly and member variable rateRound is
set to True to indicate that this is a rate round as well. Otherwise, a
new entry in the database is created, which is not used before the next
call to StoreRate().
Note: The database holds only a pointer to the rate information
entry of type SRateTime.
local items of the implementation file:
const double
accMinusInitial: Initial value of negative accuracy interval.
const double
accPlusInitial: Initial value of positive accuracy interval.
Note: A delayed start could make the former two values incorrect.
#define CloseAcc():
The macro closes the accuracy file if GNU_ACC is defined, and
it evaluates to a null-statement otherwise.
#define CloseCons():
The macro closes the adjustments file if GNU_CONS is defined,
and it evaluates to a null-statement otherwise.
#define CloseDrift():
The macro closes the deteriorated accuracy file if GNU_DRIFT is
defined, and it evaluates to a null-statement otherwise.
#define ClosePre():
The macro closes the precision file if GNU_PRE is defined, and
it evaluates to a null-statement otherwise.
const double
EpsilonMinusInitial: Initial values for EpsilonMinus for the computation
of the precision intervals.
const double
EpsilonPlusInitial: Initial values for EpsilonPlus for the computation
of the precision intervals.
#define GAMMA_H:
Macro to define parameter of function OP (negative/positive part of maximal
consonance interval).
#define GAMMA_O:
Macro to define parameter of function OP (negative/positive part of own
consonance interval).
Note: If GAMMA_H is much larger than GAMMA_O the internal rate synchronization becomes at least as bad as their difference.
#define GNU_ACC:
Macro to produce debugging code for the output of accuracy intervals. The
file is overwritten in each call to State().
#define GNU_CONS:
Macro to produce debugging code for the output of consonance intervals.
The file is overwritten in each call to Rate().
#define GNU_DRIFT:
Macro to produce debugging code for the output of rate intervals. The file
is overwritten in each call to Rate().
#define GNU_PRE:
Macro to produce debugging code for the output of precision intervals.
The file is overwritten in each call to State().
#define NAME_ACC:
Contains the filename for accuracy output (acc.dat).
#define NAME_CONS:
Contains the filename for consonance output (cons.dat).
#define NAME_DRIFT:
Contains the filename for rate output (drift.dat).
#define NAME_PRE:
Contains the filename for precision output (pre.dat).
#define PI_H:
Macro to define parameter of function OP (negative/positive part of maximal
precision interval).
#define PI_O:
Macro to define parameter of function OP (negative/positive part of own
precision interval).
Note: If PI_H is much larger than PI_O the internal state synchronization becomes at least as bad as their difference.
#define RATE_MAX:
Macro to define upper bound of a rate interval (otherwise an assert fails).
#define RATE_MIN:
Macro to define lower bound of a rate interval (otherwise an assert fails).
#define RUN_RATE:
Macro to produce code for the run-time output of rate intervals.
#define RUN_SETTING:
Macro to produce code for the run-time output of the parameter settings.
#define SIGMA_MAX:
Macro to define the maximal oscillator stability (no calculation, no measurement).
const int
StartSynchronization: Number of delay measurements before the algorithm
starts using the delay data in StoreTime().
#define THETA_MAX:
Macro to define parameter of function OP (maximal rate correction).
const double
thetaMinusInitial: Initial value of negative rate drift.
const double
thetaPlusInitial: Initial value of positive rate drift.
Note: A delayed start could make the former two values incorrect.
#define UPSILON_MAX:
Macro to define parameter of function OP (maximal state correction).
local (static) functions of the implementation file:
void PlotInterval
(ostream& dataStream, double x, const asymInterval In): In a formatted
way the asymmetric interval In which has the index x
is written onto dataStream.
INT16 ThetaToLambda
(double theta, double fnom): Converts a computed rate drift theta
into type INT16 as needed for register LAMBDA at oscillator frequency
fnom,
so that the deterioration of an accuracy interval can be adjusted within
function ConvergenceFunction() and initialized within the constructor
CRate().
In case of an overflow, the positive maximum is returned.