TimerMechanism¶

Contents¶

Overview

Creating a TimerMechanism

Structure

Execution

Examples

Class Reference

Overview¶

A TimerMechanism is a type of IntegratorMechanism the value of which begins at a specified start value, is changed monotonically each time it is executed, until it reaches a specified end value. The number of executions it takes to do so is determined by a combination of its duration and increment parameters, and whether or not it receives any input; and the path that its value takes is determined by its trajectory Function. It can be reset to its starting value by calling its reset method, or by modulating its reset Parameter with a ControlSignal.

A TimerMechanism can be used to implement a variety of time-based processes, such as the collapse of a boundary over time, or the rise of a value to a threshold. It can also be configured to execute multiple such processes in parallel, each with its own starting and ending values, as well as direction, increment and input (on a given execution), all of which use the same trajectory Function.

Creating a TimerMechanism¶

A TimerMechanism can be created directly by calling its constructor, or using the mechanism command and specifying TIMER_MECHANISM as its mech_spec argument. It can be created with or without a source of input. By default, a TimerMechanisms increments linearly, starting at 0, incrementing by 0.01 each time it is executed, and stopping when it reaches 1. However, the shape, starting, ending and rate of increment can all be configured. The shape of the timer’s progression is specified by it trajectory argument, which must be a TimerFunction or an appropriately configured UserDefinedFunction (see below for details); the starting and ending values of the timer are specified by its start and end arguments, respectively, and the ammount it progresses each time the Mechanimsm is executed (in the absence of input) is specified by its increment argument.

Structure¶

A TimerMechanism may or may not have a source of input, and has a single OutputPort. Its function is an SimpleIntegrator Function that determines the input to the TimerMechanism’s trajectory Function which, in turn, determines the value of the TimerMechanism. The TimerMechanism’s function is always a SimpleIntegrator that always starts at 0 and, each time it is executed, increments the value of the TimerMechanism based either on its input or, if it receives none, then its increment Parameter (see Execution for additional details).

The TimerMechanism’s function cannot be modified; its rate is set to the value specified for the TimerMechanism’s increment Parameter, and its initializer, noise and offset Parameters are fixed at 0

Its trajectory Function must be either a TimerFunction or a UserDefinedFunction that has initial, final and duration* parameters, and takes a single numeric value, a list or an np.array as its variable.

The trajectory Function is an auxilliary function that takes the result of the TimerMechanism’s function and transforms it to implement the specified trajectory of the timer’s value. The value of the start parameter is assigned as the initial Parameter of its trajectory Function; its end Parameter is assigned as the final Parameter of the trajectory Function, and its duration Parameter is assigned as the duration Parameter of the trajectory; which is also used to set the TimerMechanism’s finished attribute.

A TimerMechanism’s start, end and increment parameters can be modulated by a ControlMechanism.

Execution¶

When a TimerMechanism is executed, it advances its value by adding either its input or its increment Parameter to the previous_value of its function, that is then passed to the Function specified by its trajectory Parameter, the result of which is assigned to the value of the TimerMechansim’s primary OutputPort. If its default_variable is a scalar or of length 1, or its input_shapes is specified as 1, the TimerMechanism generates a scalar value as its output; otherwise, it generates an array of values, each element of which is independently advanced. If its increment Parameter is a single value, that is used for advancing all elements; if the increment Parameter is a list or array, then each element is used to increment the corresponding element of the timer array.

The TimerMechanism stops advancing after the value of its function equals the TimerMechanism’s duration Parameter. If the TimerMechanism receives no input, then it will stop advancing after the number of executions = duration / increment. If the TimerMechanism receives input, then the number of executions is determined by the number of times it is executed, and the amount of input it receives on each execution. When the TimerMechanism stops advancing, it sets its finished attribute to True, and its value remains equal to its end on any further executions, unless it is reset. If the TimerMechanism is reset, its value is set to its start value.

Hint

A TimerMechanism’s finished attribute can be used together with a Scheduler Condition to make the processing of other Mechanisms contingent on the TimerMechanism reaching its end value.

Note

The TimerMechanism’s finished attribute is not used to determine when it stops advancing; rather, it is set to True when the TimerMechanism’s value reaches its end value.

If a TimerMechanism continues to be executed after its finished attribute is True, its value remains equal to its end value. The TimerMechanism can be reset to its start value by setting its reset Parameter to a non-zero value, as described for a standard IntegratorMechanism.

Examples

The following example creates a TimerMechanism with a linear decay from 1 to 0:

>>> import psyneulink as pnl
>>> my_timer_mechanism = pnl.TimerMechanism(trajectory=LINEAR, start=1, end=0))

Class Reference¶

class psyneulink.library.components.mechanisms.processing.integrator.timermechanism.TimerMechanism(input_shapes=None, start=None, increment=None, function=None, trajectory=None, end=None, duration=None, params=None, name=None, prefs=None, **kwargs)¶

Subclass of IntegratorMechanism that advances its input until it reaches a specified value. See IntegratorMechanism for additional arguments and attributes.

Parameters:

start (scalar, list or array : default 0) – specifies the starting value of the timer; if a list or array, the length must be the same as specified for default_variable or input_shapes (see Execution for additional details).
increment (scalar, list or array : default 1) – specifies the amount by which the previous_value of the TimerMechanism’s function is incremented each time the TimerMechanism is executed in the absence of input; if a list or array, the length must be the same as specified for default_variable or input_shapes (see Execution for additional details).
function (IntegratorFunction : default SimpleIntegrator(rate=1)) – specifies the function used to increment the input to the TimerMechanism’s trajectory Function; must take a single numeric value, or a list or np.array of values, and return one of the same shape.
trajectory (TransferFunction or UserDefinedFunction : default LinearTimer) – specifies the shape of the timer’s trajectory; must be a supported TransferFunction (see trajectory function)
end (scalar, list or array : default 1) – specifies the value of its trajectory function at which the timer stops advancing; if a list or array, the length must be the same as specified for default_variable or input_shapes (see Execution for additional details).
duration (scalar, list or array : default 1) – specifies the value of its variable at which the timer stops advancing; if a list or array, the length must be the same as specified for default_variable or input_shapes (see Execution for additional details).
reset_default (number, list or np.ndarray : default 0) – specifies the default value used for the reset parameter.

start¶

determines the starting value of the timer; assigned as the start Parameter of the TimerMechanism’s trajectory if it has one; otherwise, it is computed if possible or, an error is raised (see Execution for additional details).

Type:: scalar, list or array

increment¶

determines the amount by which the previous_value of the TimerMechanism’s function is incremented each time the TimerMechanism is executed in the absence of input; assigned as the rate of the TimerMechanism’s function (see Execution for additional details).

Type:: scalar, list or array

function¶

determines the function used to advance the input to the TimerMechanism’s trajectorytrajectory Function; if the TimerMechanism receives an external input, that is used to advance the timer; otherwise, the increment Parameter is used.

Type:: IntegratorFunction

trajectory¶

determines the Function used to transform the ouput of the TimerMechanism’s function to generate its output; this determines the shape of the trajectory of the TimerMechanism’s value.

Type:: TimerFunction or UserDefinedFunction

end¶

determines the value of its trajectory function at which the timer stops advancing; if a list or array, the length must be the same as specified for default_variable or input_shapes (see Execution for additional details).

Type:: scalar, list or array : default 1

duration¶

determines the value at which the timer stops advancing, after which it sets its finished Parameter to True and value remains equal to its duration value.

Type:: scalar, list or array

finished¶

indicates whether the TimerMechanism has reached its duration value (see Execution for additional details).

Type:: bool

reset¶

if non-zero, the TimerMechanism’s reset method is called, which resets the value of the TimerMechanism to its initial value (see TimerMechanism_Reset for additional details).

Type:: int, float or 1d array of length 1 : default 0

_execute(variable=None, context=None, runtime_params=None, **kwargs)¶: Override to check for call to reset by ControlSignal

reset(*args, force=False, context=None, **kwargs)¶

Reset value if Mechanisms is stateful.

If the mechanism’s function is an IntegratorFunction, or if the mechanism has and integrator_function (see TransferMechanism), this method effectively begins the function’s accumulation over again at the specified value, and updates related attributes on the mechanism. It also clears the value history, thus effectively setting the previous value to None.

If the mechanism’s function is an IntegratorFunction, its reset method:

Calls the function’s own reset method (see Note below for details)

Sets the mechanism’s value to the output of the function’s reset method

Updates its output ports based on its new value

If the mechanism has an integrator_function, its reset method:

(1) Calls the `integrator_function's <TransferMechanism.integrator_function>` own `reset
    <IntegratorFunction.reset>` method (see Note below for details)

(2) Executes its `function <Mechanism_Base.function>` using the output of the `integrator_function's
    <TransferMechanism.integrator_function>` `reset <IntegratorFunction.reset>` method as
    the function's variable

(3) Sets the mechanism's `value <Mechanism_Base.value>` to the output of its function

(4) Updates its `output ports <Mechanism_Base.output_port>` based on its new `value
    <Mechanism_Base.value>`

Note

The reset method of an IntegratorFunction Function typically resets the function’s previous_value (and any other stateful_attributes) and value to the quantity (or quantities) specified. If reset is called without arguments, the initializer value (or the values of each of the attributes in initializers) is used instead. The reset method may vary across different Integrators. See individual functions for details on their stateful_attributes, as well as other reinitialization steps that the reset method may carry out.

exception psyneulink.library.components.mechanisms.processing.integrator.timermechanism.TimerMechanismError(message, component=None)¶