Namespace inertialsim::time¶

Namespace List > inertialsim > time

Time representation and manipulation utilities. More...

Classes¶

Type	Name
struct	SampleRateTolerances Sample rate tolerances for time validation.
class	TimeTolerances Singleton class for managing time tolerance settings.

Public Types¶

Type	Name
typedef std::tuple< double, double, double, double >	SampleStats Tuple holding sample statistics.

Public Attributes¶

Type	Name
constexpr double	kDefaultTolerance = `1[e](namespaceinertialsim.md#typedef-matrix)-9` Default tolerance for timestamp comparisons (1 nanosecond).

Public Functions¶

Type	Name
Timestamps	InsertMidpoints (const Timestamps & time) Insert midpoints into time array.
std::optional< Timestamps >	Merge (const std::optional< Timestamps > & time1, const std::optional< Timestamps > & time2, std::optional< double > tolerance=std::nullopt) Merge two compatible time arrays.
SampleStats	SamplePeriodStatistics (const Timestamps & time) Calculate sample period statistics.
SampleStats	SampleRateStatistics (const Timestamps & time) Calculate sample rate statistics.
Timestamps	Span (double start, double end, double dt) Create a time array with evenly spaced values.
Timestamps	Validate (const Timestamps & time, std::optional< double > expected_sample_rate=std::nullopt, std::optional< SampleRateTolerances > tolerance=std::nullopt) Validate time array.

Detailed Description¶

The time namespace provides:

methods to create, validate, and analyze standardized time arrays.

Public Types Documentation¶

typedef SampleStats¶

Tuple holding sample statistics.

using inertialsim::time::SampleStats = typedef std::tuple<double, double, double, double>;

Returns (minimum, maximum, median, standard_deviation) as a tuple of doubles.

Public Attributes Documentation¶

variable kDefaultTolerance¶

Default tolerance for timestamp comparisons (1 nanosecond).

constexpr double inertialsim::time::kDefaultTolerance;

Value: 1e-9

Public Functions Documentation¶

function InsertMidpoints¶

Insert midpoints into time array.

Timestamps inertialsim::time::InsertMidpoints (
    const  Timestamps & time
)

Insert midpoints between consecutive time values. The output array will have size = 2N-1 if the input has size N. The midpoints are calculated as the average of consecutive time values.

Inputs time must be pre-validated.

Parameters:

time Time array of size N.

Returns:

Time array of size 2N-1 with midpoints inserted.

Exception:

std::invalid_argument if time has fewer than 2 values.

function Merge¶

Merge two compatible time arrays.

std::optional< Timestamps > inertialsim::time::Merge (
    const std::optional< Timestamps > & time1,
    const std::optional< Timestamps > & time2,
    std::optional< double > tolerance=std::nullopt
)

If both inputs are nullopt, returns nullopt. If only one of the inputs is nullopt, returns the other input. If both inputs are not nullopt, checks they are close to each other element-wise and return the first input if they are. Otherwise raises a std::invalid_argument.

Parameters:

time1 The first time array.
time2 The second time array.
tolerance Tolerance for comparing time1 and time2 for equality (seconds). If nullopt, the default tolerance is used.

Returns:

Merged timestamps, or nullopt if both inputs are nullopt.

Exception:

std::invalid_argument if time arrays have incompatible sizes or values are not mutually consistent within tolerance.

function SamplePeriodStatistics¶

Calculate sample period statistics.

SampleStats inertialsim::time::SamplePeriodStatistics (
    const  Timestamps & time
)

Calculate the minimum, maximum, median, and sample deviation of sampling periods from the time array input. The sampled period is the difference between consecutive times. A robust estimate of the standard deviation is calculated to reduce the effect of outliers.

Inputs should be pre-validated with Validate().

Parameters:

time An array of timestamps.

Returns:

Tuple containing:

minimum: Minimum sample period (s).
maximum: Maximum sample period (s).
median: Median sample period (s).
standard_deviation: Standard deviation of sample periods (s).

Exception:

std::invalid_argument if time has fewer than 2 values.

function SampleRateStatistics¶

Calculate sample rate statistics.

SampleStats inertialsim::time::SampleRateStatistics (
    const  Timestamps & time
)

Calculate the minimum, maximum, median, and sample deviation of sampling rates from the time array input. The sample rate is the inverse of the difference between consecutive times. A robust estimate of the standard deviation is calculated to reduce the effect of outliers.

Inputs should be pre-validated with Validate().

Parameters:

time An array of timestamps.

Returns:

Tuple containing:

minimum: Minimum sample rate (Hz).
maximum: Maximum sample rate (Hz).
median: Median sample rate (Hz).
standard_deviation: Standard deviation of sample rates (Hz).

Exception:

std::invalid_argument if time has fewer than 2 values.

function Span¶

Create a time array with evenly spaced values.

Timestamps inertialsim::time::Span (
    double start,
    double end,
    double dt
)

The end time is included in the result. The inclusion of the end time is dependent on dt being a near integer multiple of (start - end) in the presence of floating point round-off.

The end point must be larger than the start point, and dt must be greater than 0.

Parameters:

start Start time in seconds.
end End time in seconds.
dt Time delta in seconds.

Returns:

Timestamps.

Exception:

std::invalid_argument if end <= start or dt <= 0.

function Validate¶

Validate time array.

Timestamps inertialsim::time::Validate (
    const  Timestamps & time,
    std::optional< double > expected_sample_rate=std::nullopt,
    std::optional< SampleRateTolerances > tolerance=std::nullopt
)

Several classes take optional time inputs (see inertialsim::geodesy::Coordinates, inertialsim::geometry::Rotation, inertialsim::sensors::Measurement, etc.). This function provides common validation across classes. Time inputs must be unique, monotonically increasing, and (optional) match the expected sample rate.

If time contains non-finite values (inf, nan); duplicate values; or is not sorted, a std::invalid_argument is raised.

If expected_sample_rate is input and time has more than one value, optional sample rate checks are performed using the tolerance input. Outliers, like duplicated timestamps or missing data, are common. They are particularly problematic in inertial algorithms that require numerical differentiation, integration, or interpolation. A std::invalid_argument is raised if any of the tolerances are exceeded.

Parameters:

time Array of timestamps.
expected_sample_rate Expected sample rate. Must be a positive value (Hz). If nullopt, no sample rate validation is performed.
tolerance Sample rate tolerances. If nullopt, the default tolerances are used.

Returns:

Validated timestamps.

Exception:

std::invalid_argument if time values are not finite, not unique, not strictly increasing, or if sample rate tolerances are exceeded.

The documentation for this class was generated from the following file cpp/include/inertialsim/time/time.h