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/or end cannot be parsed, or if steps_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. This is returned as a tuple that contains the time-step number, the time-step details (TimeStep), and a list of observations. 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).

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/or end cannot be parsed, or if steps_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. This is returned as a tuple that contains the time-step number, the time-step details (TimeStep), and a list of observations. 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).

Raises

ValueError – If observations are not sorted chronologically.

class pypfilt.time.TimeStep(start: Any, end: Any, dt: float)¶

The definition of a time-step.

Parameters

start – The beginning of the time-step.
end – The end of the time-step.
dt – The time-step size.

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.