# Component¶

## Overview¶

Component is the base class for all of the objects used to create Compositions in PsyNeuLink. It defines a common set of attributes possessed, and methods used by all Component objects.

## Creating a Component¶

A Component is never created by calling the constructor for the Component base class. However, its __init__() method is always called when a Component subclass is instantiated; that, in turn, calls a standard set of methods (listed below) as part of the initialization procedure. Every Component has a core set of configurable parameters that can be specified in the arguments of the constructor, as well as additional parameters and attributes that may be specific to particular Components, many of which can be modified by the user, and some of which provide useful information about the Component (see Parameters and Informational Attributes below).

### Deferred Initialization¶

If information necessary to complete initialization is not specified in the constructor (e.g, the owner for a State, or the sender or receiver for a Projection), then its full initialization is deferred until its the information is available (e.g., the State is assigned to a Mechanism, or a Projection is assigned its sender and receiver). This allows Components to be created before all of the information they require is available (e.g., at the beginning of a script). However, for the Component to be operational, its initialization must be completed by a call to it deferred_init method. This is usually done automatically when the Component is assigned to another Component to which it belongs (e.g., assigning a State to a Mechanism) or to a Composition (e.g., a Projection to the pathway) of a Process), as appropriate.

## Component Structure¶

### Core Structural Attributes¶

Every Component has the following set of core structural attributes. These attributes are not meant to be changed by the user once the component is constructed, with the one exception of prefs.

• variable - used as the input to its function. Specification of the default_variable argument in the constructor for a Component determines both its format (e.g., whether its value is numeric, its dimensionality and shape if it is an array, etc.) as well as its default value (the value used when the Component is executed and no input is provided), and takes precedence over the specification of size.

Note

Internally, the attribute variable is not directly used as input to functions, to allow for parallelization. The attribute is maintained as a way for the user to monitor variable along the execution chain. During parallelization however, the attribute may not accurately represent the most current value of variable being used, due to asynchrony inherent to parallelization.

• size - the dimension of the variable attribute. The size argument of the constructor for a Component can be used as a convenient method for specifying the variable, attribute in which case it will be assigned as an array of zeros of the specified size. For example, setting size = 3 is equivalent to setting variable = [0, 0, 0] and setting size = [4, 3] is equivalent to setting variable = [[0, 0, 0, 0], [0, 0, 0]].
• function - determines the computation that a Component carries out. It is always a PsyNeuLink Function object (itself a PsyNeuLink Component).

Note

The function of a Component can be assigned either a Function object or any other callable object in python. If the latter is assigned, it is “wrapped” in a UserDefinedFunction.

All Components have a default function (with a default set of parameters), that is used if it is not otherwise specified. The function can be specified in the function argument of the constructor for the Component, using one of the following:

• class - this must be a subclass of Function, as in the following example:

my_component = SomeComponent(function=SomeFunction)


This will create a default instance of the specified subclass, using default values for its parameters.

• Function - this can be either an existing Function object or the constructor for one, as in the following examples:

my_component = SomeComponent(function=SomeFunction)

or

some_function = SomeFunction(some_param=1)
my_component = SomeComponent(some_function)


The specified Function will be used as a template to create a new Function object that is assigned to the function attribute of the Component.

Note

In the current implementation of PsyNeuLink, if a Function object (or the constructor for one) is used to specify the function attribute of a Component, the Function object specified (or created) will only itself be assigned to the Component if it does not already belong to another Component. Otherwise, it is copied, and the copy is assigned to the Component. This is so that Functions can be used as templates for more than one Component, without being assigned simultaneously to multiple Components.

A function can also be specified in an entry of a parameter specification dictionary assigned to the params argument of the constructor for the Component, with the keyword FUNCTION as its key, and one of the specifications above as its value, as in the following example:

my_component = SomeComponent(params={FUNCTION:SomeFunction(some_param=1)})

• name - the name attribute contains the name assigned to the Component when it was created. If it was not specified, a default is assigned by the registry for subclass (see Registry for conventions used in assigning default names and handling of duplicate names).
• prefs - the prefs attribute contains the PreferenceSet assigned to the Component when it was created. If it was not specified, a default is assigned using classPreferences defined in __init__.py Each individual preference is accessible as an attribute of the Component, the name of which is the name of the preference (see PreferenceSet for details).

### Parameters¶

A Component defines its parameters in its parameters attribute, which contains a collection of Parameter objects, each of which stores a Parameter’s values, default values, and various properties of the parameter.

• function_params - the function_params attribute contains a dictionary of the parameters for the Component’s function and their values. Each entry is the name of a parameter, and its value is the value of that parameter. The dictionary uses a ReadOnlyDict (a PsyNeuLink-defined subclass of the Python class UserList). The value of an entry can be accessed in the standard manner (e.g., my_component.function_params[PARAMETER NAME]); as can its full list of its entries (e.g., my_component.function_params). However, because it is read-only, it cannot be used to make assignments. Rather, changes to the value of a function’s parameters must be made by assigning a value to the corresponding attribute of the Component’s function attribute (e.g., my_component.function.my_parameter), or in a FUNCTION_PARAMS dict using its assign_params method. The parameters for a function can be specified when the Component is created in one of the following ways:

• in the constructor for a Function – if that is used to specify the function argument, as in the following example:

my_component = SomeComponent(function=SomeFunction(some_param=1, some_param=2)

• in an argument of the Component’s constructor – if all of the allowable functions for a Component’s function share some or all of their parameters in common, the shared paramters may appear as arguments in the constructor of the Component itself, which can be used to set their values.

• in an entry of a parameter specification dictionary assigned to the params argument of the constructor for the Component. The entry must use the keyword FUNCTION_PARAMS as its key, and its value must be a dictionary containing the parameters and their values. The key for each entry in the FUNCTION_PARAMS dictionary must be the name of a parameter, and its value the parameter’s value, as in the example below:

my_component = SomeComponent(function=SomeFunction
params={FUNCTION_PARAMS:{SOME_PARAM=1, SOME_OTHER_PARAM=2}})


The parameters of functions for some Components may allow other forms of specification (see Specifying Parameters for details concerning different ways in which the value of a parameter can be specified).

### Informational Attributes¶

In addition to its user-modifiable parameters, a Component has attributes that provide information about its contents and/or state, but do not directly affect its operation. Every Component has the following two informational attributes:

• current_execution_count – maintains a record of the number of times a Component has executed; it excludes the executions carried out during initialization and validation, but includes all other executions, whether they are of the Component on its own are as part of a Composition (e.g., Process or System). The value can be changed “manually” or programmatically by assigning an integer value directly to the attribute.

### Component Methods¶

• assign_params - assign the value of one or more parameters of a Component. Each parameter is specified as an entry in a parameter specification dictionary in the request_set argument; parameters for the Component’s function are specified as entries in a FUNCTION_PARAMS dict within request_set dict.
• reset_params - reset the value of all user_params to a set of default values as specified in its mode argument, using a value of ResetMode.

## Execution¶

Calls the execute method of the subclass that, in turn, calls its function.

## Class Reference¶

class psyneulink.core.components.component.Component(default_variable, param_defaults, size=NotImplemented, function=None, name=None, prefs=None)

Base class for Component.

Note

Component is an abstract class and should NEVER be instantiated by a direct call to its constructor. It should be instantiated using the constructor for a subclass.

variable

2d np.array – see variable

size

int or array of ints – see size

function

Function, function or method – see function

function_params

Dict[param_name: param_value] – see function_params

user_params

Dict[param_name: param_value] – see user_params

value

2d np.array – see value

log

Log – see log

current_execution_count

int – see current_execution_count

current_execution_time

tuple(Time.RUN, Time.TRIAL, Time.PASS, Time.TIME_STEP) – see current_execution_time

reinitialize_when
name

str – see name

prefs

PreferenceSet – see prefs

parameters

see parameters

defaults

an object that provides access to the default values of a Component's parameters

assign_params(request_set=None, context=None)

Validates specified params, adds them TO paramInstanceDefaults, and instantiates any if necessary

Call _instantiate_defaults with context = COMMAND_LINE, and “validated_set” as target_set. Update paramInstanceDefaults with validated_set so that any instantiations (below) are done in proper context. Instantiate any items in request set that require it (i.e., function or states).

current_execution_count

Maintains a simple count of executions over the life of the Component, Incremented in the Component’s execute method by call to self._increment_execution_count

function_parameters

The parameters object of this object’s function

log_values(entries)

Specifies items to be logged; ; these must be be loggable_items of the Component’s log. This is a convenience method that calls the log_values method of the Component’s log.

loggable_items

Diciontary of items that can be logged in the Component’s log and their current ContextFlags. This is a convenience method that calls the loggable_items property of the Component’s log.

logged_items

Dictionary of all items that have entries in the log, and their currently assigned ContextFlagss This is a convenience method that calls the logged_items property of the Component’s log.

most_recent_execution_context

used to set a default behavior for attributes that correspond to parameters

reinitialize(*args, execution_context=None)

If the component’s execute method involves execution of an IntegratorFunction Function, this method effectively begins the function’s accumulation over again at the specified value, and may update related values on the component, depending on the component type.

reset_params(mode=<ResetMode.INSTANCE_TO_CLASS: 1>)

Reset current and/or instance defaults

If called with:
• CURRENT_TO_INSTANCE_DEFAULTS all current param settings are set to instance defaults
• INSTANCE_TO_CLASS all instance defaults are set to class defaults
• ALL_TO_CLASS_DEFAULTS all current and instance param settings are set to class defaults
Parameters: mode – (ResetMode) - determines which params are reset
set_log_conditions(items log_condition=EXECUTION)

Specifies items to be logged; these must be be loggable_items of the Component’s log. This is a convenience method that calls the set_log_conditions method of the Component’s log.

stateful_parameters

A list of all of this object’s parameters whose values may change during runtime

class psyneulink.core.components.component.DefaultsFlexibility

Denotes how rigid an assignment to a default is. That is, how much, if at all it can be modified to suit the purpose of a method/owner/etc.

e.g. when assigning a Function to a Mechanism:

pnl.TransferMechanism(default_variable=[0, 0], function=pnl.Linear())

the Linear function is assigned a default variable ([0]) based on it’s ClassDefault, which conflicts with the default variable specified by its future owner ([0, 0]). Since the default for Linear was not explicitly stated, we allow the TransferMechanism to reassign the Linear’s default variable as needed (FLEXIBLE)

FLEXIBLE

can be modified in any way

RIGID

cannot be modifed in any way

INCREASE_DIMENSION

can be wrapped in a single extra dimension

class psyneulink.core.components.component.ResetMode

ResetModes used for reset_params:

CURRENT_TO_INSTANCE_DEFAULTS
• resets all paramsCurrent values to paramInstanceDefaults values.
INSTANCE_TO_CLASS
• resets all paramInstanceDefaults values to paramClassDefaults values.
ALL_TO_CLASS_DEFAULTS
• resets all paramsCurrent and paramInstanceDefaults values to paramClassDefafults values