ParameterState

Overview

ParameterStates belong to either a Mechanism or a Projections and are used to represent, and possibly modify the, values of all of the configurable parameters of the Component or those of its function. A ParameterState can receive one or more ControlProjections and/or LearningProjections that modify the value of the parameter. The Projections received by a ParameterState are listed in its mod_afferents attribute. The ParameterState’s function combines the values of those Projections, and uses the result to modify the value of the parameter, that is then used by the Component or its function when it executes.

Creating a ParameterState

ParameterStates are created automatically when the Mechanism or Projection to which they belong is created. The owner of a ParameterState must be a Mechanism or `MappingProjection. One ParameterState is created for each configurable parameter of its owner, as well as for each configurable parameter of the owner’s function (the configurable parameters of a Component are listed in its user_params and function_params <Component.function_params>` dictionaries. Each ParameterState is created using the value specified for the corresponding parameter, as described below. The ParameterStates for the parameters of a Mechanism or Projection are listed in its parameter_states attribute.

Specifying Parameters

Parameters can be specified in one of several places:

  • In a parameter specification dictionary assigned to the params argument in the constructor for the Component to which the parameter belongs. The entry for each parameter must use the name of the parameter (or a corresponding keyword) as its key, and the parameter’s specification as its value (see examples below). Parameters for a Component’s function can be specified in an entry with the key FUNCTION_PARAMS, and a value that is itself a parameter specification dictionary containing an entry for each of the function’s parameters to be specified. When a value is assigned to a parameter in a specification dictionary, it overrides any value assigned to the argument for the parameter in the Component’s constructor.
  • By direct assignment to the Component’s attribute for the parameter (see below).
  • In the runtime_params argument of a call to component’s execute method.

The specification of the initial value of a parameter can take any of the following forms:

  • Value – this must be a valid value for the parameter. It creates a default ParameterState, assigns the parameter’s default value as the ParameterState’s value, and assigns the parameter’s name as the name of the ParameterState.
  • ParameterState reference – this must refer to an existing ParameterState object; its name must be the name of a parameter of the owner or of the owner’s function, and its value must be a valid one for the parameter.

    Note

    This capability is provided for generality and potential future use, but its current use is not advised.

  • Modulatory specification – this can be an existing ControlSignal or ControlProjection, a LearningSignal or LearningProjection, a constructor or the class name for any of these, or the keywords CONTROL, CONTROL_PROJECTION, LEARNING, or LEARNING_PROJECTION. Any of these create a default ParameterState, assign the parameter’s default value as the ParameterState’s value, and assign the parameter’s name as the name of the ParameterState. They also create and/or assign the corresponding ModulatorySignal and ModulatoryProjection, and assign the ParameterState as the ModulatoryProjection’s receiver. If the ModulatorySignal and/or ModulatoryProjection already exist, their value(s) must be valid one(s) for the parameter. Note that only Control and Learning Modulatory components can be assigned to a ParameterState (Gating components cannot be used – they can only be assigned to InputStates and OutputStates).
  • 2-item tuple: (value, Modulatory specification) – this creates a default ParameterState, uses the value specification (1st item) as parameter’s value assignment, and assigns the parameter’s name as the name of the ParameterState. The Modulatory specification (2nd item) is used as the ParameterState’s modulatory assignment, and the ParameterState is assigned as the receiver for the corresponding ModulatoryProjection.

    Note

    Currently, the function of a Component, although it can be specified as a parameter value, cannot be assigned a ModulatorySignal or modified in the runtime_params argument of a call to a Mechanism’s execute method. This may change in the future.

The value specified for a parameter (either explicitly or by default) is assigned to an attribute of the Component or of the Component’s function to which the parameter belongs. The attribute has the same name as the parameter, and can be referenced using standard Python attribute (“dot”) notation; for example, the value of a parameter named param is assigned to an attribute named param that can be referenced as my_component.param). The parameter’s value is assigned as the default value for the ParameterState.

Note

If the value of a parameter is specified as NotImplemented, or any non-numeric value that is not one of those listed above, then no ParameterState is created and the parameter cannot be modified by a ModulatorySignal or in the runtime_params argument of a call to a Mechanism’s execute method.

Examples

In the following example, a Mechanism is created by specifying two of its parameters, as well as its function and two of that function’s parameters, each using a different specification format:

>>> import psyneulink as pnl
>>> my_mechanism = pnl.RecurrentTransferMechanism(
...                         size=5,
...                         noise=pnl.ControlSignal(),
...                         function=pnl.Logistic(
...                                         gain=(0.5, pnl.ControlSignal),
...                                         bias=(1.0, pnl.ControlSignal(modulation=pnl.ModulationParam.ADDITIVE))))

The first argument of the constructor for the Mechanism specifies its size parameter by directly assigning a value to it. The second specifies the noise parameter by assigning a default ControlSignal; this will use the default value of the noise attribute. The function argument is specified using the constructor for a Logistic function, that specifies two of its parameters. The gain parameter is specified using a tuple, the first item of which is the value to be assigned, and the second specifies a default ControlSignal. The bias parameter is also specified using a tuple, in this case with a constructor for the ControlSignal that specifies its modulation parameter.

In the following example, a MappingProjection is created, and its matrix parameter is assigned a random weight matrix (using a matrix keyword) and LearningSignal:

>>> my_input_mechanism = pnl.TransferMechanism()
>>> my_output_mechanism = pnl.TransferMechanism()
>>> my_mapping_projection = pnl.MappingProjection(sender=my_input_mechanism,
...                                               receiver=my_output_mechanism,
...                                               matrix=(pnl.RANDOM_CONNECTIVITY_MATRIX,
...                                                       pnl.LearningSignal))

Note

The matrix parameter belongs to the MappingProjection’s function; however, since it has only one standard function, its arguments are available in the constructor for the Projection (see Component_Specifying_Functions_and_Parameters for a more detailed explanation).

The example below shows how to specify the parameters in the first example using a parameter specification dictionary:

>>> my_mechanism = pnl.RecurrentTransferMechanism(
...                      noise=5,
...                      params={pnl.NOISE: pnl.CONTROL,
...                              pnl.FUNCTION: pnl.Logistic,
...                              pnl.FUNCTION_PARAMS:{
...                                     pnl.GAIN:(0.5,pnl.ControlSignal),
...                                     pnl.BIAS:(1.0,pnl.ControlSignal(modulation=pnl.ModulationParam.ADDITIVE))}})

There are several things to note here. First, the parameter specification dictionary must be assigned to the params argument of the constructor. Second, both methods for specifying a parameter – directly in an argument for the parameter, or in an entry of a parameter specification dictionary – can be used within the same constructor. If a particular parameter is specified in both ways (as is the case for noise in the example), the value in the parameter specification dictionary takes priority (i.e., it is the value that will be assigned to the parameter). If the parameter is specified in a parameter specification dictionary, the key for the parameter must be a string that is the same as the name of parameter (i.e., identical to how it appears as an arg in the constructor; as is shown for noise in the example), or using a keyword that resolves to such a string (as shown for NOISE in the example). Finally, the keyword FUNCTION_PARAMS can be used in a parameter specification dictionary to specify parameters of the Component’s function, as shown for the gain and bias parameters of the Logistic function in the example.

Structure

Every ParameterState is owned by a Mechanism or MappingProjection. It can receive one or more ControlProjections or LearningProjections, that are listed in its mod_afferents attribute. A ParameterState cannot receive PathwayProjections or GatingProjections. When the ParameterState is updated (i.e., its owner is executed), it uses the values of its ControlProjections and LearningProjections to determine whether and how to modify its parameter’s attribute value, which is then assigned as the ParameterState’s value (see Execution for addition details). ParameterStates have the following core attributes:

  • variable - the parameter’s attribute value; that is, the value assigned to the attribute for the parameter of the ParameterState’s owner; it can be thought of as the parameter’s “base” value. It is used by its function to determine the ParameterState’s value. It must match the format (the number and type of elements) of the parameter’s attribute value.
  • mod_afferents - lists the ModulatoryProjections received by the ParameterState. These specify either modify the ParameterState’s function, or directly assign the value of the ParameterState itself (see ModulatorySignals_Modulation).
  • function - takes the parameter’s attribute value as its input, modifies it under the influence of any Modulatory Projections it receives (listed in mod_afferents, and assigns the result as the ParameterState’s value which is used as the parameter’s “actual” value.
  • value - the result of function; used by the ParameterState’s owner as the value of the parameter for which the the ParameterState is responsible.

All of the configurable parameters of a Component – that is, for which it has ParameterStates – are listed in its user_params attribute, which is a read-only dictionary with an entry for each parameter. The parameters for a Component’s function are listed both in a FUNCTION_PARAMS entry of the user_params dictionary, and in their own function_params attribute, which is also a read-only dictionary (with an entry for each of its function’s parameters). The ParameterStates for a Mechanism or Projection are listed in its parameter_states attribute, which is also read-only.

An initial value can be assigned to a parameter in the corresponding argument of the constructor for the Component (see above. Parameter values can also be modified by a assigning a value to the corresponding attribute, or in groups using the Component’s assign_params method. The parameters of a Component’s function can be modified by assigning a value to the corresponding attribute of the Component’s function_object attribute (e.g., myMechanism.function_object.my_parameter) or in FUNCTION_PARAMS dict in a call to the Component’s assign_params method. See ParameterStates and Parameters for additional information.

Execution

A ParameterState cannot be executed directly. It is executed when the Component to which it belongs is executed. When this occurs, the ParameterState executes any Modulatory Projections it receives, the values of which modulate parameters of the ParameterState’s function. The ParameterState then calls its function and the result is assigned as its value. The ParameterState’s value is used as the value of the corresponding parameter by the Component, or by its own function.

Note

It is important to note the distinction between the function of a ParameterState, and the function of the Component to which it belongs. The former is used to determine the value of a parameter used by the latter (see figure, and Execution for additional details).

Class Reference

class psyneulink.components.states.parameterstate.ParameterState(owner, reference_value=None function=LinearCombination(operation=PRODUCT), variable=None, size=None, parameter_modulation_operation=Modulation.MULTIPLY, params=None, name=None, prefs=None)

Subclass of State that represents and possibly modifies the parameter of a Mechanism, Projection, or its Functions.

owner

Mechanism or MappingProjection – the Mechanism or MappingProjection to which the ParameterState belongs.

mod_afferents

Optional[List[Projection]] – a list of the ModulatoryProjection that project to the ParameterState (i.e., for which it is a receiver); these can be ControlProjection(s) and/or LearningProjection(s), but not GatingProjection. The value of each must match the format (number and types of elements) of the ParameterState’s variable.

variable

number, list or np.ndarray – the parameter’s attribute value — that is, the value of the attribute of the ParameterState’s owner or its function assigned to the parameter.

function

Function : default Linear – converts the parameter’s attribute value (same as the ParameterState’s variable) to the ParameterState’s value, under the influence of any ModulatoryProjections received by the ParameterState (and listed in its mod_afferents attribute. The result is assigned as the ParameterState’s value.

value

number, List[number] or np.ndarray – the result returned by the ParameterState’s function, and used by the ParameterState’s owner or its function as the value of the parameter for which the ParmeterState is responsible. Note that this is not necessarily the same as the parameter’s attribute value (that is, the value of the owner’s attribute for the parameter), since the ParameterState’s function may modify the latter under the influence of its mod_afferents.

name

str – the name of the ParameterState; same as the name of the attribute for the Parameter to which the ParameterState corresponds.

Note

Unlike other PsyNeuLink components, State names are “scoped” within a Mechanism, meaning that States with the same name are permitted in different Mechanisms.

prefs

PreferenceSet or specification dict – the PreferenceSet for the ParameterState; if it is not specified in the prefs argument of the constructor, a default is assigned using classPreferences defined in __init__.py (see PreferenceSet for details).