Source code for hydrocouple.temporal
"""
HydroCouple temporal abstract base classes.
Python ABC mirrors of the C++ HydroCouple v2.0.0 interfaces defined in
``hydrocoupletemporal.h``: date/time representation, time spans,
time-marching model components, and time-series component data items.
"""
from __future__ import annotations
from abc import ABC, abstractmethod
from enum import IntEnum
from typing import TYPE_CHECKING
from hydrocouple.core import (
IComponentDataItem,
IDimension,
IModelComponent,
IPropertyChanged,
)
if TYPE_CHECKING:
import numpy as np
#: Two instants are the same instant when their Julian days differ by no more
#: than this (1e-8 days, about 0.86 ms). Mirrors C++
#: ``Temporal::TIME_EQUALITY_TOLERANCE_DAYS``; every "exact" time comparison
#: (``TimeInterpolation.NoInterpolation``, matching a consumer's times against
#: a provider's) uses it.
TIME_EQUALITY_TOLERANCE_DAYS = 1.0e-8
#: The ``interval_length`` of an item whose intervals are contiguous but not of
#: one length: interval *i* runs from time *i-1* to time *i*, interval 0 from
#: the start of ``time_span``. Mirrors C++
#: ``Temporal::INTERVAL_LENGTH_CONTIGUOUS``; any negative value means this.
INTERVAL_LENGTH_CONTIGUOUS = -1.0
[docs]
class TimeKind(IntEnum):
"""What a value's time coordinate refers to; mirrors C++
``Temporal::TimeKind``."""
Unknown = 0
Instantaneous = 1
IntervalMean = 2
IntervalMinimum = 3
IntervalMaximum = 4
Accumulated = 5
[docs]
class TimeInterpolation(IntEnum):
"""How a provider produces a value between held instants; mirrors C++
``Temporal::TimeInterpolation``."""
Unknown = 0
NoInterpolation = 1 # C++ ``None``; exact match within TIME_EQUALITY_TOLERANCE_DAYS
Previous = 2
Nearest = 3
Linear = 4
[docs]
class IDateTime(IPropertyChanged):
"""A date/time based on a Julian day.
Mirrors C++ ``Temporal::IDateTime``. The normative convention is the
astronomical Julian day number in the proleptic Gregorian ("standard")
calendar, UTC; persistence layers writing CF metadata should emit
``units = "days since ..."`` with ``calendar = "standard"``.
"""
@property
@abstractmethod
def julian_day(self) -> float:
"""Date and time as a Julian day value."""
raise NotImplementedError
@property
@abstractmethod
def modified_julian_day(self) -> float:
"""Modified Julian day value."""
raise NotImplementedError
@property
@abstractmethod
def serial_date(self) -> float:
"""Serial date number."""
raise NotImplementedError
[docs]
class ITimeSpan(IDateTime):
"""A time duration anchored at a start date/time.
Mirrors C++ ``Temporal::ITimeSpan``.
"""
@property
@abstractmethod
def duration(self) -> float:
"""Duration of the timespan in days."""
raise NotImplementedError
@property
@abstractmethod
def end_julian_day(self) -> float:
"""End of the interval: ``julian_day + duration``."""
raise NotImplementedError
[docs]
class ITimeModelComponent(IModelComponent):
"""A model component that advances through time during simulation.
Mirrors C++ ``Temporal::ITimeModelComponent``.
"""
@property
@abstractmethod
def current_date_time(self) -> IDateTime:
"""Current date and time of the model simulation."""
raise NotImplementedError
@property
@abstractmethod
def simulation_period(self) -> ITimeSpan:
"""The time horizon of the model."""
raise NotImplementedError
@property
@abstractmethod
def next_date_time_julian_day(self) -> float:
"""The Julian day the next ``update()`` will advance
:attr:`current_date_time` to; never earlier than the current time."""
raise NotImplementedError
[docs]
class ITimeSeriesComponentDataItem(IComponentDataItem):
"""An :class:`~hydrocouple.core.IComponentDataItem` with a temporal
dimension.
Mirrors C++ ``Temporal::ITimeSeriesComponentDataItem``. Canonical
dimension ordering: time is dimension 0 of :attr:`shape`; any
additional dimensions follow. Data access uses the inherited
:meth:`~hydrocouple.core.IComponentDataItem.get_values_into` /
:meth:`~hydrocouple.core.IComponentDataItem.set_values_from` hyperslab
API with the time index as ``start[0]``, so "current time step, all
entities" is a contiguous slab.
"""
[docs]
@abstractmethod
def time(self, time_index: int) -> IDateTime:
"""The :class:`IDateTime` at the given time index (spot queries)."""
raise NotImplementedError
@property
@abstractmethod
def time_count(self) -> int:
"""The number of times."""
raise NotImplementedError
@property
@abstractmethod
def times(self) -> "np.ndarray":
"""Bulk access to all time coordinates as Julian day values.
A float64 array of :attr:`time_count` elements ordered with the
time dimension; the accessor IO writers and interpolating adapters
must use.
"""
raise NotImplementedError
@property
@abstractmethod
def time_span(self) -> ITimeSpan:
"""The time span covered by this data item."""
raise NotImplementedError
@property
@abstractmethod
def time_dimension(self) -> IDimension:
"""The time dimension (dimension 0 of :attr:`shape`)."""
raise NotImplementedError
@property
@abstractmethod
def time_kind(self) -> TimeKind:
"""What each value's time coordinate refers to."""
raise NotImplementedError
@property
@abstractmethod
def interval_length(self) -> float:
"""Averaging/accumulation interval in days.
Positive: every interval has this length and ends at its time
coordinate. :data:`INTERVAL_LENGTH_CONTIGUOUS` (any negative value):
contiguous intervals of varying length. Zero: not declared (and what
instantaneous items return).
"""
raise NotImplementedError
@property
@abstractmethod
def time_interpolation(self) -> TimeInterpolation:
"""What this item does (output) or accepts (input) between held instants."""
raise NotImplementedError
@property
@abstractmethod
def time_extrapolation(self) -> TimeExtrapolation:
"""What this item does (output) or accepts (input) outside its held range."""
raise NotImplementedError
[docs]
class ITimeIdBasedComponentDataItem(ITimeSeriesComponentDataItem):
"""A time-series data item whose entity dimension is identifier-based.
Mirrors C++ ``Temporal::ITimeIdBasedComponentDataItem``. Canonical
dimension ordering: time is dimension 0, the identifier dimension is
dimension 1 of :attr:`shape`; any additional dimensions follow.
"""
@property
@abstractmethod
def identifiers(self) -> list[str]:
"""The identifiers of the identifier dimension."""
raise NotImplementedError
@property
@abstractmethod
def identifier_dimension(self) -> IDimension:
"""The identifier dimension (dimension 1 of :attr:`shape`)."""
raise NotImplementedError