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.