TimerFunctions¶

TimerFunction
LinearTimer
AcceleratingTimer
DeceleratingTimer
AsymptoticTimer

Overview¶

Functions for which initial and final values and a duration can be specified, for use with a TimerMechanism.

Types¶

There are four types that implement different functional forms, each of which is rising if initial is less than final and declining for the reverse:

LinearTimer - progresses linearly from initial to final value. (see interactive graph).
AcceleratingTimer - advances from initial <TimerFunction.initial>` to final value by progressively larger amounts at an adjustable exponential rate (see interactive graph).
DeceleratingTimer - advances from initial <TimerFunction.initial>` to final value by progressively smaller amounts at an adjustable exponential rate (see interactive graph).
AsymptoticTimer - progresses at a fixed exponential rate from initial to within tolerance of final

(see interactive graph).

Standard Attributes¶

TimerFunctions have the following Parameters:

initial: specifies the value that the function has when its variable is 0.

final: specifies the value that the function has when its variable is equal to duration.

duration: specifies the value of the variable at which the`value <Function_Base.value>` of the function is equal to final.

rate: specifies the rate at which the progression of the value of the function changes.

TimerFunction Class References¶

class psyneulink.core.components.functions.nonstateful.timerfunctions.LinearTimer(default_variable=None, initial=None, final=None, duration=None, params=None, owner=None, prefs=None)¶

function returns linear transform of variable.

\[\left(\frac{final-initial}{duration}\right) \cdot variable + initial\]

such that:

\[ \begin{align}\begin{aligned}value=initial \ for\ variable=0\\value=final\ for\ variable=duration\end{aligned}\end{align} \]

where:

initial determines the value of the function when its variable = 0.

final determines the value of the function when its variable = duration.

duration determines the value of variable at which the value of the function = final.

derivative returns the derivative of the LinearTimer Function:

\[\frac{final-initial}{duration}\]

See graph for interactive plot of the function using Desmos.

Parameters

default_variable (number or array : default class_defaults.variable) – specifies a template for the value to be transformed.
initial (float : default 1.0) – specifies the value the function should have when variable = 0; must be greater than or equal to 0.
final (float : default 1.0) – specifies the value the function should have when variable = duration; must be greater than initial.
duration (float : default 1.0) – specifies the value of variable at which the value of the function should equal final; must be greater than 0.
params (Dict[param keyword: param value] : default None) – a parameter dictionary that specifies the parameters for the function. Values specified for parameters in the dictionary override any assigned to those parameters in arguments of the constructor.
owner (Component) – component to which to assign the Function.
name (str : default see name) – specifies the name of the Function.
prefs (PreferenceSet or specification dict : default Function.classPreferences) – specifies the PreferenceSet for the Function (see prefs for details).

variable¶

contains value to be transformed.

Type: number or array

initial¶

determines the value of the function when variable = 0.

Type: float (>0)

final¶

determines the value of the function when variable = duration.

Type: float

duration¶

determines the value of variable at which the value of the function is equal to final.

Type: float (>0)

owner¶

component to which the Function has been assigned.

Type: Component

name¶

the name of the Function; if it is not specified in the name argument of the constructor, a default is assigned by FunctionRegistry (see Naming for conventions used for default and duplicate names).

Type: str

prefs¶

the PreferenceSet for function; if it is not specified in the prefs argument of the Function’s constructor, a default is assigned using classPreferences defined in __init__.py (see Preferences for details).

Type: PreferenceSet or specification dict : Function.classPreferences

_function(variable=None, context=None, params=None)¶

Parameters

variable (number or array : default class_defaults.variable) – a single value or array to be exponentiated.
params (Dict[param keyword: param value] : default None) – a parameter dictionary that specifies the parameters for the function. Values specified for parameters in the dictionary override any assigned to those parameters in arguments of the constructor.

Returns

LinearTimer rise transform of variable

Return type

number or array

derivative(input, output=None, context=None)¶

Derivative of function at input:

\[(final - initial) * \left(\frac{(1 + duration * e^{variable})}{duration * e^{duration}}\right)\]

Parameters: input (number) – value of the input to the LinearTimer transform at which derivative is to be taken.
Returns: derivative
Return type: number or array

class psyneulink.core.components.functions.nonstateful.timerfunctions.AcceleratingTimer(default_variable=None, initial=None, final=None, duration=None, params=None, owner=None, prefs=None)¶

function returns acceleratingTimer rise transform of variable; this is the inverse of the AcceleratingTimer Function.

\[initial+\left(final-initial\right)\left(\frac{variable}{duration}\right)^{rate}e^{\left(\left( \frac{variable}{duration}\right)^{rate}-1\right)}\]

such that:

\[ \begin{align}\begin{aligned}value=initial \ for\ variable=0\\value=final\ for\ variable=duration\end{aligned}\end{align} \]

where:

initial determines the value of the function when its variable = 0.

final determines the value of the function when its variable = duration.

duration determines the value of variable at which the value of the function = final.

rate determines the rate of acceleration of the function.

derivative returns the derivative of the AcceleratingTimer Function:

\[(final-initial) \cdot \left[ rate \cdot \left(\frac{variable}{duration}\right)^{rate-1} \cdot \frac{1}{duration} \cdot e^{\left(\left(\frac{variable}{duration}\right)^{rate}-1\right)} + \left(\frac{variable}{duration}\right)^{rate} \cdot e^{\left(\left(\frac{variable}{duration}\right)^{ rate}-1\right)} \cdot rate \cdot \frac{1}{duration}\right]\]

See graph for interactive plot of the function using Desmos.

Parameters

default_variable (number or array : default class_defaults.variable) – specifies a template for the value to be transformed.
initial (float : default 1.0) – specifies the value the function should have when variable = 0; must be greater than or equal to 0.
final (float : default 1.0) – specifies the value the function should have when variable = duration; must be greater than initial.
duration (float : default 1.0) – specifies the value of variable at which the value of the function should equal final; must be greater than 0.
rate (float : default 1.0) – specifies the rate at which the value of the function accelerates; must be greater than 0.
params (Dict[param keyword: param value] : default None) – a parameter dictionary that specifies the parameters for the function. Values specified for parameters in the dictionary override any assigned to those parameters in arguments of the constructor.
owner (Component) – component to which to assign the Function.
name (str : default see name) – specifies the name of the Function.
prefs (PreferenceSet or specification dict : default Function.classPreferences) – specifies the PreferenceSet for the Function (see prefs for details).

variable¶

contains value to be transformed.

Type: number or array

initial¶

determines the value of the function when variable = 0.

Type: float (>0)

final¶

determines the value of the function when variable = duration.

Type: float

duration¶

determines the value of variable at which the value of the function is equal to final.

Type: float (>0)

rate¶

determines the rate at which the value of the function accelerates.

Type: float (>1.0)

owner¶

component to which the Function has been assigned.

Type: Component

name¶

the name of the Function; if it is not specified in the name argument of the constructor, a default is assigned by FunctionRegistry (see Naming for conventions used for default and duplicate names).

Type: str

prefs¶

the PreferenceSet for function; if it is not specified in the prefs argument of the Function’s constructor, a default is assigned using classPreferences defined in __init__.py (see Preferences for details).

Type: PreferenceSet or specification dict : Function.classPreferences

_function(variable=None, context=None, params=None)¶

Parameters

variable (number or array : default class_defaults.variable) – a single value or array to be exponentiated.
params (Dict[param keyword: param value] : default None) – a parameter dictionary that specifies the parameters for the function. Values specified for parameters in the dictionary override any assigned to those parameters in arguments of the constructor.

Returns

AcceleratingTimer rise transform of variable

Return type

number or array

derivative(input, output=None, context=None)¶

Derivative of function at input:

\[(final - initial) * \left(\frac{(1 + duration * e^{variable})}{duration * e^{duration}}\right)\]

Parameters: input (number) – value of the input to the AcceleratingTimer transform at which derivative is to be taken.
Returns: derivative
Return type: number or array

class psyneulink.core.components.functions.nonstateful.timerfunctions.DeceleratingTimer(default_variable=None, initial=None, final=None, duration=None, rate=None, params=None, owner=None, prefs=None)¶

function returns exponentially decaying transform of variable:

\[\frac{\left(initial-final-direction\right)}{e^{\ln\left(-direction\left(initial\ -\ final-direction\right)\right)\left(\frac{variable}{duration}\right)^{ rate}}}+final+direction\]

such that:

\[ \begin{align}\begin{aligned}value = initial + offset\ for\ variable=0\\value = (initial * final) + offset\ for\ variable=duration\end{aligned}\end{align} \]

where:

initial, together with offset, determines the value of the function when variable = 0, and is used together with final to determine the value of the function when variable = duration.

duration determines the value of variable at which the value of the function should equal \(initial * final + offset\).

final is the fraction of initial when, added to offset, is used to determine the value of the function when variable should equal duration.

rate determines the rate of deceleration of the function.

direction is +1 if final > initial, otherwise -1, and is used to determine the direction of the progression (rising or decaying) of the TimerFunction.

derivative returns the derivative of the DeceleratingTimer Function:

\[\frac{direction \cdot rate \cdot(initial-final-direction)\cdot\ln(direction(final-initial+direction)) \cdot \left(\frac{ variable}{duration}\right)^{rate-1}}{duration\cdot e^{\ln(direction(final-initial+direction))\left(\frac{variable}{ duration}\right)^{rate}}}\]

See graph for interactive plot of the function using Desmos.

Parameters

default_variable (number or array : default class_defaults.variable) – specifies a template for the value to be transformed.
initial (float : default 1.0) – specifies, together with offset, the value of the function when variable = 0; must be greater than 0.
final (float : default 0.01) – specifies the fraction of initial when added to offset, that determines the value of the function when variable = duration; must be between 0 and 1.
duration (float : default 1.0) – specifies the value of variable at which the value of the function should equal `initial * final + offset; must be greater than 0.
rate (float : default 1.0) – specifies the rate at which the value of the function decelerates; must be greater than 0.
params (Dict[param keyword: param value] : default None) – a parameter dictionary that specifies the parameters for the function. Values specified for parameters in the dictionary override any assigned to those parameters in arguments of the constructor.
owner (Component) – component to which to assign the Function.
name (str : default see name) – specifies the name of the Function.
prefs (PreferenceSet or specification dict : default Function.classPreferences) – specifies the PreferenceSet for the Function (see prefs for details).

variable¶

contains value to be transformed.

Type: number or array

initial¶

determines, together with offset, the value of the function when variable = 0.

Type: float

final¶

determines the fraction of initial when added to offset, that determines the value of the function when variable = duration.

Type: float

duration¶

determines the value of variable at which the value of the function should equal initial * final + offset.

Type: float (>0)

rate¶

determines the rate at which the value of the function decelerates.

Type: float (>1.0)

owner¶

component to which the Function has been assigned.

Type: Component

name¶

the name of the Function; if it is not specified in the name argument of the constructor, a default is assigned by FunctionRegistry (see Naming for conventions used for default and duplicate names).

Type: str

prefs¶

the PreferenceSet for function; if it is not specified in the prefs argument of the Function’s constructor, a default is assigned using classPreferences defined in __init__.py (see Preferences for details).

Type: PreferenceSet or specification dict : Function.classPreferences

_function(variable=None, context=None, params=None)¶

Parameters

variable (number or array : default class_defaults.variable) – amount by which to increment timer on current execution; if this is not specified, the timer is incremented by the value of increment.
params (Dict[param keyword: param value] : default None) – a parameter dictionary that specifies the parameters for the function. Values specified for parameters in the dictionary override any assigned to those parameters in arguments of the constructor.

Returns

Exponentially decayed value of variable

Return type

number or array

derivative(input, output=None, context=None)¶: Derivative of function at input:

\[ \begin{align}\begin{aligned}\frac{direction \cdot rate \cdot(initial-final-direction)\cdot\ln(direction( final-initial+direction))\cdot \left(\frac{variable}{duration}\right)^{rate-1}}{duration\cdot e^{\ln( direction(final-initial+direction))\left(\frac{variable}{duration}\right)^{rate}}}\\Arguments ---------\\input : number value of the input to the DeceleratingTimer transform at which derivative is to be taken.\\Derivative of `function <DeceleratingTimer._function>` at **input**.\\Returns ------- derivative : number or array\end{aligned}\end{align} \]

class psyneulink.core.components.functions.nonstateful.timerfunctions.AsymptoticTimer(default_variable=None, initial=None, final=None, tolerance=None, duration=None, params=None, owner=None, prefs=None)¶

function returns exponentially progressing transform of variable toward an asymptoticTimer value that reaches duration when it falls within the specified tolerance of final:

\[(initial - final) * \frac{\ln(tolerance)}{duration} *e^{\left(\frac{variable * \ln(tolerance)} {duration}\right)} + final\]

such that:

\[ \begin{align}\begin{aligned}value = initial for\ variable=0\\value = ((initial - final) \cdot tolerance) for\ variable=duration\end{aligned}\end{align} \]

where:

initial, determines the value of the function when variable = 0, and is used together with final and tolerance to determine the value of the function at which variable = duration.

final is the asymptoticTimer value toward which the function decays.

tolerance is the fraction of initial - final used to determine the value of the function when variable is equal to duration.

duration determines the value of variable at which the value of the function is equal to \(initial \cdot final\).

derivative returns the derivative of the AsymptoticTimer Function:

\[\frac{initial\cdot\ln(tolerance)}{duration}\cdot e^{\frac{variable\cdot\ln(tolerance)}{duration}}\]

See graph for interactive plot of the function using Desmos.

Parameters

default_variable (number or array : default class_defaults.variable) – specifies a template for the value to be transformed.
initial (float : default 1.0) – specifies the value of the function when `variable<AsymptoticTimer.variable>`=0; must be greater than 0.
final (float : default 0.0) – specifies the asymptoticTimer value toward which the function decays.
tolerance (float : default 0.01) – specifies the fraction of initial-final that determines the value of the function when variable = `duration; must be between 0 and 1.
duration (float : default 1.0) – specifies the value of variable at which the value of the function should equal `initial * final; must be greater than 0.
params (Dict[param keyword: param value] : default None) – a parameter dictionary that specifies the parameters for the function. Values specified for parameters in the dictionary override any assigned to those parameters in arguments of the constructor.
owner (Component) – component to which to assign the Function.
name (str : default see name) – specifies the name of the Function.
prefs (PreferenceSet or specification dict : default Function.classPreferences) – specifies the PreferenceSet for the Function (see prefs for details).

variable¶

contains value to be transformed.

Type: number or array

initial¶

determines the value of the function when variable = 0.

Type: float (>0)

final¶

determines the asymptoticTimer value toward which the function decays.

Type: float

tolerance¶

determines the fraction of initial - final <AsymptoticTimer.final> that determines the value of the function when variable = duration.

Type: float (0,1)

duration¶

determines the value of variable at which the value of the function should equal initial * final.

Type: float (>0)

bounds¶

Type: (None, None)

owner¶

component to which the Function has been assigned.

Type: Component

name¶

the name of the Function; if it is not specified in the name argument of the constructor, a default is assigned by FunctionRegistry (see Naming for conventions used for default and duplicate names).

Type: str

prefs¶

the PreferenceSet for function; if it is not specified in the prefs argument of the Function’s constructor, a default is assigned using classPreferences defined in __init__.py (see Preferences for details).

Type: PreferenceSet or specification dict : Function.classPreferences

_function(variable=None, context=None, params=None)¶

Parameters

variable (number or array : default class_defaults.variable) – amount by which to increment timer on current execution; if this is not specified, the timer is incremented by the value of increment.
params (Dict[param keyword: param value] : default None) – a parameter dictionary that specifies the parameters for the function. Values specified for parameters in the dictionary override any assigned to those parameters in arguments of the constructor.

Returns

Exponentially decayed value of variable

Return type

number or array

derivative(input, output=None, context=None)¶

Derivative of function at input:

\[\frac{initial\cdot\ln(tolerance)}{duration}\cdot e^{\frac{variable\cdot\ln(tolerance)}{duration}}\]

Parameters

input (number) – value of the input to the AsymptoticTimer transform at which derivative is to be taken.
input. (Derivative of function at) –

Returns

derivative

Return type

number or array

class psyneulink.core.components.functions.nonstateful.timerfunctions.TimerFunction(default_variable, params, owner=None, name=None, prefs=None, context=None, **kwargs)¶

Subclass of TransferFunction that allows a initial, final and duration value to be specified; for use with a TimerMechanism.

variable¶

contains value to be transformed.

Type: number or array

initial¶

determines the value of the function when variable = 0.

Type: float (>0)

final¶

determines the value of the function when variable = duration.

Type: float

duration¶

determines the value of variable at which the value of the function is equal to final.

Type: float (>0)

rate¶

determines the rate at which the value of the function accelerates.

Type: float (>1.0)