pypfilt.time¶
Two pre-defined simulation time scales are provided.
- class pypfilt.time.Scalar(settings=None)¶
A dimensionless time scale.
- __init__(settings=None)¶
- Parameters
settings – An optional dictionary of simulation settings.
- set_period(start, end, steps_per_unit)¶
Define the simulation period and time-step size.
- Parameters
start – The start of the simulation period.
end – The end of the simulation period.
steps_per_unit (int) – The number of time-steps per unit time.
- Raises
ValueError – if
start
and/orend
cannot be parsed, or ifsteps_per_unit
is not a positive integer.
- with_observation_tables(ctx, obs_tables, start=None)¶
Return a generator that yields a sequence of tuples that contain: the time-step number, the time-step details (
TimeStep
), and a list of observations.- Parameters
ctx (pypfilt.Context) – The simulation context.
obs_tables (Dict[str, numpy.ndarray]) – The observation data tables.
start – The starting time (set to
None
to use the start of the simulation period).
- Raises
ValueError – If observations are not sorted chronologically.
- time_step_of_next_observation(ctx, obs_tables, from_time)¶
Identify the first time-step after
from_time
for which there is at least one observation. If no such time-step exists,None
is returned.- Parameters
ctx (pypfilt.Context) – The simulation context.
obs_tables (Dict[str, numpy.ndarray]) – The observation data tables.
from_time – The starting time (set to
None
to use the start of the simulation period).
- Returns
The time-step number, time-step details, and a list of observations.
- Return type
Optional[TimeStepWithObservations]
- Raises
ValueError – If observations are not sorted chronologically.
- class pypfilt.time.Datetime(settings=None)¶
A
datetime
scale where the time unit is days.By default, times are converted to/from string using the format string
'%Y-%m-%d %H:%M:%S'
, with a fallback format string'%Y-%m-%d'
used to read date-only values. You can override these format strings by defining the following settings:[time] datetime_formats = ["%Y-%m-%d", "%d %m %Y"]
The first value will be used when saving times, and subsequent values will be used as fallback options for reading times.
- __init__(settings=None)¶
- Parameters
settings – An optional dictionary of simulation settings.
- custom_format_strings(format_strings)¶
Temporarily override the datetime format strings within a
with
statement.- Parameters
format_strings – The format strings used to convert datetime values to/from strings.
- Examples
>>> from datetime import datetime >>> from pypfilt.time import Datetime >>> time_scale = Datetime() >>> time_scale.to_unicode(datetime(2022, 8, 31)) '2022-08-31 00:00:00' >>> with time_scale.custom_format_strings(['%d %b %Y']): ... time_scale.to_unicode(datetime(2022, 8, 31)) '31 Aug 2022'
- set_period(start, end, steps_per_unit)¶
Define the simulation period and time-step size.
- Parameters
start – The start of the simulation period.
end – The end of the simulation period.
steps_per_unit (int) – The number of time-steps per unit time.
- Raises
ValueError – if
start
and/orend
cannot be parsed, or ifsteps_per_unit
is not a positive integer.
- with_observation_tables(ctx, obs_tables, start=None)¶
Return a generator that yields a sequence of tuples that contain: the time-step number, the time-step details (
TimeStep
), and a list of observations.- Parameters
ctx (pypfilt.Context) – The simulation context.
obs_tables (Dict[str, numpy.ndarray]) – The observation data tables.
start – The starting time (set to
None
to use the start of the simulation period).
- Raises
ValueError – If observations are not sorted chronologically.
- time_step_of_next_observation(ctx, obs_tables, from_time)¶
Identify the first time-step after
from_time
for which there is at least one observation. If no such time-step exists,None
is returned.- Parameters
ctx (pypfilt.Context) – The simulation context.
obs_tables (Dict[str, numpy.ndarray]) – The observation data tables.
from_time – The starting time (set to
None
to use the start of the simulation period).
- Returns
The time-step number, time-step details, and a list of observations.
- Return type
Optional[TimeStepWithObservations]
- Raises
ValueError – If observations are not sorted chronologically.
- class pypfilt.time.TimeStep(start: Any, end: Any, dt: float)¶
The definition of a time-step.
- start: Any¶
The beginning of the time-step.
- end: Any¶
The end of the time-step.
- dt: float¶
The time-step size.
- class pypfilt.time.TimeStepWithObservations(step_number: int, time_step: TimeStep, observations: List[Dict[str, Any]])¶
The details of a time-step for which there is at least one observation.
- step_number: int¶
The time-step number.
- observations: List[Dict[str, Any]]¶
The observations for this time-step.
Custom time scales¶
If neither of the above time scales is suitable, you can define a custom time scale, which should derive the following base class and define the methods listed here:
- class pypfilt.time.Time¶
The base class for simulation time scales, which defines the minimal set of methods that are required.
- abstract dtype(name)¶
Define the dtype for columns that store times.
- abstract native_dtype()¶
Define the Python type used to represent times in NumPy arrays.
- abstract is_instance(value)¶
Return whether
value
is an instance of the native time type.
- abstract to_dtype(time)¶
Convert from time to a dtype value.
- abstract from_dtype(dval)¶
Convert from a dtype value to time.
- abstract to_unicode(time)¶
Convert from time to a Unicode string.
This is used to define group names in HDF5 files, and for logging.
- abstract from_unicode(val)¶
Convert from a Unicode string to time.
This is used to parse group names in HDF5 files.
- abstract column(name)¶
Return a tuple that can be used with
read_table()
to convert a column into time values.
- abstract steps()¶
Return a generator that yields tuples of time-step numbers and
TimeStep
instances, which span the simulation period.The first time-step should be numbered 1 and occur at a time that is one time-step after the beginning of the simulation period.
- abstract step_count()¶
Return the number of time-steps required for the simulation period.
- abstract step_of(time)¶
Return the time-step number that corresponds to the specified time.
- abstract add_scalar(time, scalar)¶
Add a scalar quantity to the specified time.
- abstract time_of_obs(obs)¶
Return the time associated with an observation.