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. 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/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. 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.

time_step: TimeStep#

The time-step details.

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.