Functions¶

Function

Function_Base

Example function:

ArgumentTherapy

Overview¶

A Function is a Component that “packages” a function for use by other Components. Every Component in PsyNeuLink is assigned a Function; when that Component is executed, its Function’s function is executed. The function can be any callable operation, although most commonly it is a mathematical operation (and, for those, almost always uses a call to one or more numpy functions). There are two reasons PsyNeuLink packages functions in a Function Component:

Manage parameters – parameters are attributes of a Function that either remain stable over multiple calls to the function (e.g., the gain or bias of a Logistic function, or the learning rate of a learning function); or, if they change, they do so less frequently or under the control of different factors than the function’s variable (i.e., its input). As a consequence, it is useful to manage these separately from the function’s variable, and not have to provide them every time the function is called. To address this, every PsyNeuLink Function has a set of attributes corresponding to the parameters of the function, that can be specified at the time the Function is created (in arguments to its constructor), and can be modified independently of a call to its function. Modifications can be directly (e.g., in a script), or by the operation of other PsyNeuLink Components (e.g., Modulatory Mechanisms) by way of ControlProjections.

Modularity – by providing a standard interface, any Function assigned to a Components in PsyNeuLink can be replaced with other PsyNeuLink Functions, or with user-written custom functions so long as they adhere to certain standards (the PsyNeuLink Function API).

Creating a Function¶

A Function can be created directly by calling its constructor. Functions are also created automatically whenever any other type of PsyNeuLink Component is created (and its function is not otherwise specified). The constructor for a Function has an argument for its variable and each of the parameters of its function. The variable argument is used both to format the input to the function, and assign its default value. The arguments for each parameter can be used to specify the default value for that parameter; the values can later be modified in various ways as described below.

Structure¶

Core Attributes¶

Every Function has the following core attributes:

variable – provides the input to the Function’s function.

function – determines the computation carried out by the Function; it must be a callable object (that is, a python function or method of some kind). Unlike other PsyNeuLink Components, it cannot be (another) Function object (it can’t be “turtles” all the way down!).

A Function also has an attribute for each of the parameters of its function.

Owner¶

If a Function has been assigned to another Component, then it also has an owner attribute that refers to that Component. The Function itself is assigned as the Component’s function attribute. Each of the Function’s attributes is also assigned as an attribute of the owner, and those are each associated with with a parameterPort of the owner. Projections to those parameterPorts can be used by ControlProjections to modify the Function’s parameters.

Modulatory Parameters¶

Some classes of Functions also implement a pair of modulatory parameters: multiplicative_param and additive_param. Each of these is assigned the name of one of the function’s parameters. These are used by ModulatorySignals to modulate the function of a Port and thereby its value (see Modulation and figure for additional details). For example, a ControlSignal typically uses the multiplicative_param to modulate the value of a parameter of a Mechanism’s function, whereas a LearningSignal uses the additive_param to increment the value of the matrix parameter of a MappingProjection.

Execution¶

Functions are executable objects that can be called directly. More commonly, however, they are called when their owner is executed. The parameters of the function can be modified when it is executed, by assigning a parameter specification dictionary to the params argument in the call to the function.

For Mechanisms, this can also be done by specifying runtime_params in the Run method of their Composition.

Class Reference¶

class psyneulink.core.components.functions.function.ArgumentTherapy(default_variable=None, propensity=Manner.CONTRARIAN, pertinacity=10.0, params=None, owner=None, prefs=None)¶

Return True or False according to the manner of the therapist.

Parameters:

variable (boolean or statement that resolves to one : default class_defaults.variable) – assertion for which a therapeutic response will be offered.
propensity (Manner value : default Manner.CONTRARIAN) – specifies preferred therapeutic manner
pertinacity (float : default 10.0) – specifies therapeutic consistency
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¶

assertion to which a therapeutic response is made.

Type:: boolean

propensity¶

determines therapeutic manner: tendency to agree or disagree.

Type:: Manner value : default Manner.CONTRARIAN

pertinacity¶

determines consistency with which the manner complies with the propensity.

Type:: float : default 10.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

class Manner(value)¶

_validate_variable(variable, context=None)¶

Validates variable and returns validated value

This overrides the class method, to perform more detailed type checking See explanation in class method. Note: this method (or the class version) is called only if the parameter_validation attribute is True

Parameters:

variable – (anything but a dict) - variable to be validated:
context – (str)

Return variable:

validated

_validate_params(request_set, target_set=None, context=None)¶

Validates variable and /or params and assigns to targets

This overrides the class method, to perform more detailed type checking See explanation in class method. Note: this method (or the class version) is called only if the parameter_validation attribute is True

Parameters:

request_set – (dict) - params to be validated
target_set – (dict) - destination of validated params

Return none:

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

Returns a boolean that is (or tends to be) the same as or opposite the one passed in.

Parameters:

variable (boolean : default class_defaults.variable) – an assertion to which a therapeutic response is made.
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:

therapeutic response

Return type:

boolean

parameters = <psyneulink.core.components.functions.function.ArgumentTherapy.Parameters object> : ( changes_shape = Parameter( default_value=False delivery_condition=<LogCondition.OFF: 0> dependencies=None fallback_value=<class 'psyneulink.core.globals.parameters.ParameterNoValueError'> function_arg=True history={} history_max_length=1 history_min_length=0 loggable=False mdf_name=None name='changes_shape' parse_spec=False pnl_internal=True port=None reference=False specify_none=False stateful=False structural=False user=True values={} ), enable_output_type_conversion = Parameter( default_value=False delivery_condition=<LogCondition.OFF: 0> dependencies=None fallback_value=<class 'psyneulink.core.globals.parameters.ParameterNoValueError'> function_arg=True history={} history_max_length=1 history_min_length=0 loggable=False mdf_name=None name='enable_output_type_conversion' parse_spec=False pnl_internal=True port=None reference=False specify_none=False stateful=False structural=False user=True values={} ), execute_until_finished = Parameter( default_value=True delivery_condition=<LogCondition.OFF: 0> dependencies=None fallback_value=<class 'psyneulink.core.globals.parameters.ParameterNoValueError'> function_arg=True history={} history_max_length=1 history_min_length=0 loggable=True mdf_name=None name='execute_until_finished' parse_spec=False pnl_internal=True port=None reference=False specify_none=False stateful=True structural=False user=True values={} ), execution_count = Parameter( default_value=array(0) delivery_condition=<LogCondition.OFF: 0> dependencies=None fallback_value='default' function_arg=True history={} history_max_length=1 history_min_length=0 loggable=False mdf_name=None name='execution_count' parse_spec=False pnl_internal=True port=None read_only=True reference=False specify_none=False stateful=False structural=False user=True values={} ), has_initializers = Parameter( default_value=False delivery_condition=<LogCondition.OFF: 0> dependencies=None fallback_value=<class 'psyneulink.core.globals.parameters.ParameterNoValueError'> function_arg=True history={} history_max_length=1 history_min_length=0 loggable=True mdf_name=None name='has_initializers' parse_spec=False pnl_internal=True port=None reference=False setter=<function _has_initializers_setter> specify_none=False stateful=True structural=False user=True values={} ), is_finished_flag = Parameter( default_value=True delivery_condition=<LogCondition.OFF: 0> dependencies=None fallback_value=<class 'psyneulink.core.globals.parameters.ParameterNoValueError'> function_arg=True history={} history_max_length=1 history_min_length=0 loggable=False mdf_name=None name='is_finished_flag' parse_spec=False pnl_internal=False port=None reference=False specify_none=False stateful=True structural=False user=True values={} ), max_executions_before_finished = Parameter( default_value=array(1000) delivery_condition=<LogCondition.OFF: 0> dependencies=None fallback_value=<class 'psyneulink.core.globals.parameters.ParameterNoValueError'> function_arg=True history={} history_max_length=1 history_min_length=0 loggable=True mdf_name=None name='max_executions_before_finished' parse_spec=False pnl_internal=True port=None reference=False specify_none=False stateful=True structural=False user=True values={} ), num_executions = Parameter( default_value=Time(run: 0, trial: 0, pass: 0, time_step: 0) delivery_condition=<LogCondition.OFF: 0> dependencies=None fallback_value='default' function_arg=True history={} history_max_length=1 history_min_length=0 loggable=False mdf_name=None name='num_executions' parse_spec=False pnl_internal=True port=None read_only=True reference=False specify_none=False stateful=True structural=False user=True values={} ), num_executions_before_finished = Parameter( default_value=array(0) delivery_condition=<LogCondition.OFF: 0> dependencies=None fallback_value=<class 'psyneulink.core.globals.parameters.ParameterNoValueError'> function_arg=True history={} history_max_length=1 history_min_length=0 loggable=True mdf_name=None name='num_executions_before_finished' parse_spec=False pnl_internal=True port=None read_only=True reference=False specify_none=False stateful=True structural=False user=True values={} ), output_type = Parameter( default_value=<FunctionOutputType.DEFAULT: 3> delivery_condition=<LogCondition.OFF: 0> dependencies=None fallback_value=<class 'psyneulink.core.globals.parameters.ParameterNoValueError'> function_arg=True history={} history_max_length=1 history_min_length=0 loggable=False mdf_name=None name='output_type' parse_spec=False pnl_internal=True port=None reference=False specify_none=False stateful=False structural=False user=True valid_types=(<enum 'FunctionOutputType'>,) values={} ), pertinacity = Parameter( default_value=array(10.) delivery_condition=<LogCondition.OFF: 0> dependencies=None fallback_value=<class 'psyneulink.core.globals.parameters.ParameterNoValueError'> function_arg=True history={} history_max_length=1 history_min_length=0 loggable=True mdf_name=None name='pertinacity' parse_spec=False pnl_internal=False port=None reference=False specify_none=False stateful=True structural=False user=True values={} ), propensity = Parameter( default_value=<Manner.CONTRARIAN: 1> delivery_condition=<LogCondition.OFF: 0> dependencies=None fallback_value=<class 'psyneulink.core.globals.parameters.ParameterNoValueError'> function_arg=True history={} history_max_length=1 history_min_length=0 loggable=True mdf_name=None name='propensity' parse_spec=False pnl_internal=False port=None reference=False specify_none=False stateful=True structural=False user=True values={} ), value = Parameter( default_value=array([0]) delivery_condition=<LogCondition.OFF: 0> dependencies=None fallback_value=<class 'psyneulink.core.globals.parameters.ParameterNoValueError'> function_arg=True history={} history_max_length=1 history_min_length=0 loggable=True mdf_name=None name='value' parse_spec=False pnl_internal=True port=None read_only=True reference=False specify_none=False stateful=True structural=False user=True values={} ), variable = Parameter( constructor_argument='default_variable' default_value=array([0]) delivery_condition=<LogCondition.OFF: 0> dependencies=None fallback_value=<class 'psyneulink.core.globals.parameters.ParameterNoValueError'> function_arg=True history={} history_max_length=1 history_min_length=0 loggable=True mdf_name=None name='variable' parse_spec=False pnl_internal=True port=None read_only=True reference=False specify_none=False stateful=True structural=False user=True values={} ), )¶

class psyneulink.core.components.functions.function.Function_Base(default_variable, params=None, owner=None, name=None, prefs=None)¶

Abstract base class for Function category of Component class

Parameters:

variable (value : default class_defaults.variable) – specifies the format and a default value for the input to function.
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¶

format and default value can be specified by the variable argument of the constructor; otherwise, they are specified by the Function’s class_defaults.variable.

Type:: number

function¶

called by the Function’s owner when it is executed.

Type:: function

value¶

the result returned by calling the Function.

Type:: number

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

_specified_variable_shape_flexibility = 2¶: The DefaultsFlexibility ._variable_shape_flexibility takes on when variable shape was manually specified

_parse_arg_generic(arg_val)¶: Argument parser for any argument that does not have a specialized parser

_validate_parameter_spec(param, param_name, numeric_only=True)¶: Validates function param Replace direct call to parameter_spec in tc, which seems to not get called by Function __init__()’s

property _model_spec_parameter_blacklist¶: A set of Parameter names that should not be added to the generated constructor string

_assign_to_mdf_model(model, input_id)¶

Adds an MDF representation of this function to MDF object model, including all necessary auxiliary functions. input_id is the input to the singular MDF function or first function representing this psyneulink Function, if applicable.

Returns:: the identifier of the final MDF function representing this psyneulink Function
Return type:: str

_get_pytorch_fct_param_value(param_name, device, context)¶: Return the current value of param_name for the function Use default value if not yet assigned Convert using torch.tensor if val is an array

class psyneulink.core.components.functions.function.RandomMatrix(center=0.0, range=1.0)¶

Function that returns matrix with random elements distributed uniformly around center across range.

The center and range arguments are passed at construction, and used for all subsequent calls. Once constructed, the function must be called with two floats, sender_size and receiver_size, that specify the number of rows and columns of the matrix, respectively.

Can be used to specify the matrix parameter of a MappingProjection, and to specify a default matrix for Projections in the construction of a Pathway (see Projection Specifications) or in a call to a Composition’s add_linear_processing_pathway method.

A call to the class calls random_matrix, passing sender_size and receiver_size to random_matrix as its num_rows and num_cols arguments, respectively, and passing the center-0.5 and range attributes specified at construction to random_matrix as its offset and scale arguments, respectively.

Parameters:

center (float) – specifies the value around which the matrix elements are distributed in all calls to the function.
range (float) – specifies range over which all matrix elements are distributed in all calls to the function.

center¶

determines the center of the distribution of the matrix elements;

Type:: float

range¶

determines the range of the distribution of the matrix elements;

Type:: float