# ParameterState¶

## Overview¶

ParameterStates belong to either a Mechanism or a Projection. A ParameterState is created to represent each modulatable parameter of the Mechanism or a Projection, as well as those of the component’s function. A ParameterState provides the current value of the parameter it represents during any relevant computations, and serves as an interface for parameter modulation.

A ParameterState can receive one or more ControlProjections and/or LearningProjections that modify the value returned by the ParameterState according to the ParameterState’s function. The Projections received by a ParameterState are listed in its mod_afferents attribute.

When the Mechanism or Projection to which a ParameterState belongs executes, that component and its function use the ParameterState’s value – not the parameter attribute’s value – for any computation. A ParameterState’s corresponding attribute on the Mechanism, Projection, or Function to which it belongs (i.e. MyTransferMech.function.gain), stores the “base value” of that parameter. The base value of a parameter is the variable of the ParameterState’s function. The base value can be viewed or changed at any time through this attribute.

The ParameterState value is available on the ParameterState itself, as well as the mod_name attribute of the Mechanism or Projection to which it belongs (i.e. MyTransferMech.mod_gain would return the value of the “gain” ParameterState of the MyTransferMech mechanism.)

Note

Either of these options for looking up the value of the ParameterState will return the parameter state value that was used during the most recent execution. This means that if the value of MyTransferMech.function.gain (the base value) is updated after execution #1, the base value will change immediately, but the ParameterState value (and MyTransferMech.mod_gain) will not be computed again until execution #2.

As a result, if either MyTransferMech.mod_gain or MyTransferMech.parameter_states[“gain”].value is viewed in between execution #1 and execution #2, it will return the gain parameter state value that was used during execution 1.

## 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 Mechanisms 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 a Composition’s Run 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),


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,
...                                               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),


There are several things to note here.

First, the parameter specification dictionary must be assigned to the params argument of the constructor. Note that 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).

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).

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.

The example below shows how to access ParameterState values vs base values, and demonstrates their differences:

>>> my_transfer_mechanism = pnl.TransferMechanism(
...                      noise=5.0,
...                      function=pnl.Linear(slope=2.0))
>>> assert my_transfer_mechanism.noise == 5.0
>>> assert my_transfer_mechanism.mod_noise == [5.0]
>>> assert my_transfer_mechanism.function.slope == 2.0
>>> assert my_transfer_mechanism.mod_slope == [2.0]


Notice that the noise attribute, which stores the base value for the noise ParameterState of my_transfer_mechanism, is on my_transfer_mechanism, while the slope attribute, which stores the base value for the slope ParameterState of my_transfer_mechanism, is on my_transfer_mechanism’s function. However, mod_noise and mod_slope are both properties on my_transfer_mechanism.

>>> my_transfer_mechanism.noise = 4.0
>>> my_transfer_mechanism.function.slope = 1.0
>>> assert my_transfer_mechanism.noise == 4.0
>>> assert my_transfer_mechanism.mod_noise == [5.0]
>>> assert my_transfer_mechanism.function.slope == 1.0
>>> assert my_transfer_mechanism.mod_slope == [2.0]


When the base values of noise and slope are updated, we can inspect these attributes immediately and observe that they have changed. We do not observe a change in mod_noise or mod_slope because the ParameterState value will not update until the mechanism executes.

>>> my_transfer_mechanism.execute([10.0])
>>> assert my_transfer_mechanism.noise == 4.0
>>> assert my_transfer_mechanism.mod_noise == [4.0]
>>> assert my_transfer_mechanism.function.slope == 1.0
>>> assert my_transfer_mechanism.mod_slope == 1.0


Now that the mechanism has executed, we can see that each ParameterState evaluated its function with the base value, producing a modulated noise value of 4.0 and a modulated slope value of 1.0. These values were used by my_transfer_mechanism and its Linear function when the mechanism executed.

## 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:

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 attribute (e.g., myMechanism.function.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.core.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 Function.

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).