param.parameters.Time

class param.parameters.Time(*, label, time_type, timestep, unit, until, name)

A callable object returning a number for the current time.

Here ‘time’ is an abstract concept that can be interpreted in any useful way. For instance, in a simulation, it would be the current simulation time, while in a turn-taking game it could be the number of moves so far. The key intended usage is to allow independent Parameterized objects with Dynamic parameters to remain consistent with a global reference.

The time datatype (time_type) is configurable, but should typically be an exact numeric type like an integer or a rational, so that small floating-point errors do not accumulate as time is incremented repeatedly.

When used as a context manager using the ‘with’ statement (implemented by the __enter__ and __exit__ special methods), entry into a context pushes the state of the Time object, allowing the effect of changes to the time value to be explored by setting, incrementing or decrementing time as desired. This allows the state of time-dependent objects to be modified temporarily as a function of time, within the context’s block. For instance, you could use the context manager to “see into the future” to collect data over multiple times, without affecting the global time state once exiting the context. Of course, you need to be careful not to do anything while in context that would affect the lasting state of your other objects, if you want things to return to their starting state when exiting the context.

The starting time value of a new Time object is 0, converted to the chosen time type. Here is an illustration of how time can be manipulated using a Time object:

>>> time = Time(until=20, timestep=1)
>>> 'The initial time is %s' % time()
'The initial time is 0'
>>> 'Setting the time to %s' % time(5)
'Setting the time to 5'
>>> time += 5
>>> 'After incrementing by 5, the time is %s' % time()
'After incrementing by 5, the time is 10'
>>> with time as t:  # Entering a context
...     'Time before iteration: %s' % t()
...     'Iteration: %s' % [val for val in t]
...     'Time after iteration: %s' % t()
...     t += 2
...     'The until parameter may be exceeded outside iteration: %s' % t()
'Time before iteration: 10'
'Iteration: [10, 11, 12, 13, 14, 15, 16, 17, 18, 19, 20]'
'Time after iteration: 20'
'The until parameter may be exceeded outside iteration: 22'
>>> 'After exiting the context the time is back to %s' % time()
'After exiting the context the time is back to 10'

Parameter Definitions

---

label = String(default='Time', label='Label')

The label given to the Time object. Can be used to convey more specific notions of time as appropriate. For instance, the label could be ‘Simulation Time’ or ‘Duration’.

time_type = Parameter(constant=True, default=<class 'int'>, label='Time type')

Callable that Time will use to convert user-specified time values into the current time; all times will be of the resulting numeric type. By default, time is of integer type, but you can supply any arbitrary-precision type like a fixed-point decimal or a rational, to allow fractional times. Floating-point times are also allowed, but are not recommended because they will suffer from accumulated rounding errors. For instance, incrementing a floating-point value 0.0 by 0.05, 20 times, will not reach 1.0 exactly. Instead, it will be slightly higher than 1.0, because 0.05 cannot be represented exactly in a standard floating point numeric type. Fixed-point or rational types should be able to handle such computations exactly, avoiding accumulation issues over long time intervals. Some potentially useful exact number classes: - int: Suitable if all times can be expressed as integers. - Python’s decimal.Decimal and fractions.Fraction classes: widely available but slow and also awkward to specify times (e.g. cannot simply type 0.05, but have to use a special constructor or a string). - fixedpoint.FixedPoint: Allows a natural representation of times in decimal notation, but very slow and needs to be installed separately. - gmpy2.mpq: Allows a natural representation of times in decimal notation, and very fast because it uses the GNU Multi-Precision library, but needs to be installed separately and depends on a non-Python library. gmpy2.mpq is gmpy2’s rational type.

timestep = Parameter(default=1.0, label='Timestep')

Stepsize to be used with the iterator interface. Time can be advanced or decremented by any value, not just those corresponding to the stepsize, and so this value is only a default.

until = Parameter(default=Infinity(), label='Until')

Declaration of an expected end to time values, if any. When using the iterator interface, iteration will end before this value is exceeded.

unit = String(allow_None=True, label='Unit')

The units of the time dimensions. The default of None is set as the global time function may on an arbitrary time base. Typical values for the parameter are ‘seconds’ (the SI unit for time) or subdivisions thereof (e.g. ‘milliseconds’).

__init__(**params)

Initialize a Parameterized instance with optional Parameter values.

Optional Parameter values must be supplied as keyword arguments (param_name=value), overriding their default values for this one instance. Any parameters not explicitly set will retain their defined default values.

If no name parameter is provided, the instance’s name attribute will default to an identifier string composed of the class name followed by an incremental 5-digit number.

Parameters:

**params – Optional keyword arguments mapping Parameter names to values.

Raises:

TypeError – If one of the keywords of params is not a Parameter name.

Examples

>>> import param
>>> class MyClass(param.Parameterized):
...     value = param.Number(default=10, bounds=(0, 20))
>>> obj = MyClass(value=15)

The value parameter is set to 15 for this instance, overriding the default.

Methods

__init__(**params)	Initialize a Parameterized instance with optional Parameter values.
advance(val)

Attributes

forever
label
name
param
timestep
unit
until