PrincetonUniversity / PsyNeuLink / 9072871729

# Princeton University licenses this file to You under the Apache License, Version 2.0 (the "License");

# you may not use this file except in compliance with the License.  You may obtain a copy of the License at:

#     http://www.apache.org/licenses/LICENSE-2.0

# Unless required by applicable law or agreed to in writing, software distributed under the License is distributed

# on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.

# See the License for the specific language governing permissions and limitations under the License.

# ********************************************** Component  ************************************************************

Contents

--------

* `Component_Overview`

* `Component_Creation`

    * `Component_Deferred_Init`

* `Component_Structure`

    * `Component_Structural_Attributes`

        * `Variable <Component_Variable>`

        * `Function <Component_Function>`

        * `Value <Component_Value>`

        * `Log <Component_Log>`

        * `Name <Component_Name>`

        * `Preferences <Component_Prefs>`

    * `User_Modifiable_Parameters`

    COMMENT:

    * `Methods <Component_Methods>`

    COMMENT

* `Component_Execution`

    * `Component_Execution_Initialization`

    * `Component_Execution_Termination`

    * `Component_Execution_Count_and_Time`

* `Component_Class_Reference`

.. _Component_Overview:

Overview

--------

Component is the base class for all of the objects used to create `Compositions <Composition>` in PsyNeuLink.

It defines a common set of attributes possessed, and methods used by all Component objects.

.. _Component_Creation:

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 <Component_Methods>`) as part of the initialization procedure.  Every Component has a core set of

`configurable parameters <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 `User_Modifiable_Parameters`

and `Informational Attributes` below).

.. _Component_Deferred_Init:

*Deferred Initialization*

~~~~~~~~~~~~~~~~~~~~~~~~~

If information necessary to complete initialization is not specified in the constructor (e.g, the **owner** for a

`Port <Port_Base.owner>`, or the **sender** or **receiver** for a `Projection <Projection_Structure>`), then its

full initialization is deferred until its the information is available (e.g., the `Port <Port>` is assigned to a

`Mechanism <Mechanism>`, or a `Projection <Projection>` is assigned its `sender <Projection_Base.sender>` and `receiver

<Projection_Base.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 Port to a Mechanism) or to a Composition (e.g.,

a Projection to the `pathway <Process.pahtway>`) of a `Process`), as appropriate.

.. _Component_Structure:

Component Structure

-------------------

.. _Component_Structural_Attributes:

*Core Structural Attributes*

~~~~~~~~~~~~~~~~~~~~~~~~~~~~

Every Component has the following set of core structural attributes that can be specified in its constructor using the

arguments listed below. These attributes are not meant to be changed by the user once the component is constructed,

with the one exception of `prefs <Component_Prefs>`.

.. _Component_Type:

* **componentType** - species the type of Component.

.. _Component_Variable:

* **variable** - used as the input to its `function <Component_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 <Component.defaults>` (the value

  used when the Component is executed and no input is provided), and takes precedence over the specification of `size

  <Component_Size>`.

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

.. _Component_Size:

* **size** - the dimension of the `variable <Component.variable>` attribute.  The **size** argument of the

  constructor for a Component can be used as a convenient method for specifying the `variable <Component_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]].

  .. note::

     The size attribute serves a role similar to

     `shape in Numpy <https://numpy.org/doc/stable/reference/generated/numpy.shape.html>`_, with the difference that

     size permits the specification of `ragged arrays <https://en.wikipedia.org/wiki/Jagged_array>`_ -- that is, ones

     that have elements of varying lengths, such as [[1,2],[3,4,5]].

.. _Component_Function:

* **function** - determines the computation that a Component carries out. It is always a PsyNeuLink `Function

  <Function>` object (itself also a PsyNeuLink Component).

  .. note::

     The `function <Component.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 <Component.function>` (with a default set of parameters), that is used if it

  is not otherwise specified.  The `function <Component.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 <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 <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 <Function>` object (or the constructor for one) is

        used to specify the `function <Component.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 <Function>` can be used as templates for

        more than one Component, without being assigned simultaneously to multiple Components.

  A `function <Component.function>` can also be specified in an entry of a

  `parameter specification dictionary <ParameterPort_Specification>` 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)})

.. _Component_Value:

* **value** - the `value <Component.value>` attribute generally contains the result (return value) of the Component's

  `function <Component.function>` after the function is called, though some Components may override this to return

  other values.

      .. technical_note::

         In general, Components that have an execute() method may use this to assign the `value` of the Component

         (e.g., `Mechanism_Base`; see `OptimizationControlMechanism` and `LCControlMechanism` for examples).

..

.. _Component_Log:

* **log** - the `log <Component.log>` attribute contains the Component's `Log`, that can be used to record its `value

  <Component.value>`, as well as that of Components that belong to it, during initialization, validation, execution

  and learning.  It also has four convenience methods -- `loggable_items <Log.loggable_items>`, `set_log_conditions

  <Log.set_log_conditions>`, `log_values <Log.log_values>` and `logged_items <Log.logged_items>` -- that provide

  access to the corresponding methods of its Log, used to identify, configure and track items for logging.

..

.. _Component_Name:

* **name** - the `name <Component.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 <Registry>` for subclass (see `Registry_Naming` for

  conventions used in assigning default names and handling of duplicate names).

..

.. _Component_Prefs:

* **prefs** - the `prefs <Component.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

  COMMENT:

  THIS SEEMS TO BE INCORRECT:

  ``__init__.py``

  COMMENT

  `BasePreferences`

  Each individual preference is accessible as an attribute of the Component, the name of which is the name of the

  preference (see `Preferences` for details).

.. _User_Modifiable_Parameters:

*Parameters*

~~~~~~~~~~~~

.. _Component_Parameters:

A Component defines its `parameters <Parameters>` in its *parameters* attribute, which contains a collection of

`Parameter` objects, each of which stores a Parameter's values, `default values <Component.defaults>`, and various

`properties <Parameter_Attributes_Table>` of the parameter.

* `Parameters <Component.Parameters>` - a `Parameters class <Parameters>` defining parameters and their default values

   that are used for all Components, unless overridden.

   All of the parameters listed in the *parameters* class can be modified by the user (as described above).  Some

   can also be modified by `ControlSignals <ControlSignal>` when a `Composition executes <Composition_Execution>`.

   In general, only parameters that take numerical values and/or do not affect the structure, mode of operation,

   or format of the values associated with a Component can be subject to modulation.  For example, for a

   `TransferMechanism`, `clip <TransferMechanism.clip>`, `initial_value <TransferMechanism.initial_value>`,

   `integrator_mode <TransferMechanism.integrator_mode>`, `input_ports <Mechanism_Base.input_ports>`,

   `output_ports`, and `function <Mechanism_Base.function>`, are all listed in parameters, and are user-modifiable,

   but are not subject to modulation; whereas `noise <TransferMechanism.noise>` and `integration_rate

   <TransferMechanism.integration_rate>` can all be subject to modulation. Parameters that are subject to modulation

   have the `modulable <Parameter.modulable>` attribute set to True and are associated with a `ParameterPort` to which

   the ControlSignals can project (by way of a `ControlProjection`).

  COMMENT:

      FIX: ADD DISCUSSION ABOUT HOW TO ASSIGN DEFAULTS HERE 5/8/20

  COMMENT

.. _Component_Function_Params:

* **initial_shared_parameters** - the `initial_shared_parameters <Component.function>` attribute contains a

  dictionary of any parameters for the Component's functions or attributes, to be used to

  instantiate the corresponding object.  Each entry is the name of a parameter, and its value is the value of that parameter.

  The parameters for a function can be specified when the Component is created in one of the following ways:

      * in an argument of the **Component's constructor** -- if all of the allowable functions for a Component's

        `function <Component.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 <ParameterPort_Specification>` 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

  `ParameterPort_Specification` for details concerning different ways in which the value of a

  parameter can be specified).

COMMENT:

    FIX: STATEMENT ABOVE ABOUT MODIFYING EXECUTION COUNT VIOLATES THIS DEFINITION, AS PROBABLY DO OTHER ATTRIBUTES

      * parameters are things that govern the operation of the Mechanism (including its function) and/or can be

        modified/modulated

      * attributes include parameters, but also read-only attributes that reflect but do not determine the operation

        (e.g., EXECUTION_COUNT)

COMMENT

.. _Component_Stateful_Parameters:

* **stateful_parameters** - a list containing all of the Component's `stateful parameters <Parameter_Statefulness>`.

  COMMENT:

     DESCRIPTION HERE

  COMMENT

COMMENT:

.. _Component_Methods:

*Component Methods*

~~~~~~~~~~~~~~~~~~~

   FOR DEVELOPERS:

    There are two sets of methods that belong to every Component: one set that is called when it is initialized; and

    another set that can be called to perform various operations common to all Components.  Each of these is described

    briefly below.  All of these methods can be overridden by subclasses to implement customized operations, however

    it is strongly recommended that the method be called on super() at some point, so that the standard operations are

    carried out.  Whether customization operations should be performed before or after the call to super is discussed in

    the descriptions below where relevant.

    .. _Component_Initialization_Methods:

    Initialization Methods

    ^^^^^^^^^^^^^^^^^^^^^^

    These methods can be overridden by the subclass to customize the initialization process, but should always call the

    corresponding method of the Component base class (using ``super``) to insure full initialization.  There are two

    categories of initializion methods:  validation and instantiation.

    .. _Component_Validation_Methods:

    * **Validation methods** perform a strictly *syntactic* check, to determine if a value being validated conforms

    to the format expected for it by the Component (i.e., the type of the value and, if it is iterable, the type its

    elements and/or its length).  The value itself is not checked in any other way (e.g., whether it equals a particular

    value or falls in a specified range).  If the validation fails, and exception is raised.  Validation methods never

    make changes the actual value of an attribute, but they may change its format (e.g., from a list to an ndarray) to

    comply with requirements of the Component.

      * `_validate_variable <Component._validate_variable>` validates the value provided to the keyword:`variable`

        argument in the constructor for the Component.  If it is overridden, customized validation should generally

        performed *prior* to the call to super(), to allow final processing by the Component base class.

      * `_validate_params <Component._validate_params>` validates the value of any parameters specified in the

        constructor for the Component (whether they are made directly in the argument for a parameter, or in a

        `parameter specification dictionary <ParameterPort_Specification>`.  If it is overridden by a subclass,

        customized validation should generally be performed *after* the call to super().

    * **Instantiation methods** create, assign, and/or perform *semantic* checks on the values of Component attributes.

      Semantic checks may include value and/or range checks, as well as checks of formatting and/or value

      compatibility with other attributes of the Component and/or the attributes of other Components (for example, the

      _instantiate_function method checks that the input of the Component's `function <Comonent.function>` is compatible

      with its `variable <Component.variable>`).

      * `_handle_size <Component._handle_size>` converts the `variable <Component.variable>` and `size <Component.size>`

        arguments to the correct dimensions (for `Mechanism <Mechanism>`, this is a 2D array and 1D

        array, respectively). If **variable** is not passed as an argument, this method attempts to infer `variable

        <Component.variable>` from the **size** argument, and vice versa if the **size** argument is missing.

        The _handle_size method then checks that the **size** and **variable** arguments are compatible.

      * `_instantiate_defaults <Component._instantiate_defaults>` first calls the validation methods, and then

        assigns the default values for all of the attributes of the instance of the Component being created.

        _instantiate_attributes_before_function

        _instantiate_function

        _instantiate_attributes_after_function

    .. _Component_Callable_Methods:

    Callable Methods

    ^^^^^^^^^^^^^^^^

    initialize

COMMENT

.. _Component_Assign_Params:

* **reset_params** - reset the value of all parameters to a set of default values as specified in its **mode**

  argument, using a value of `ResetMode <Component_ResetMode>`.

.. _Component_Execution:

Execution

---------

A Component is executed when its `execute <Component.execute>` method is called, which in turn calls its `function

<Component_Function>`.

.. _Component_Lazy_Updating:

*Lazy Updating*

~~~~~~~~~~~~~~~

In general, only `Compositions <Composition>` are executed from the command line (i.e., from the console or in a

script).  `Mechanisms <Mechanism>` can also be executed, although this is usually just for the purposes of demonstration

or debugging, and `Functions <Function>` can only be executed if they are standalone (that is, they do not belong to

another Component).  All other Components are executed only a Component that depends on them to do so.  This can be

one to which a Components belongs (such as the Mechanism to which a `Port` belongs) or that otherwise requires it to

execute (for example, a updating a `Port` requires its `afferent Projections <Port_Projections>` to `execute

<Port_Execution>`).  This is referred to as "lazy updating", since it means that most Components don't execute unless

and until they are required to do so.  While this reduces unecessary computation, it can sometimes be confusing. For

example, when `learning <Composition_Learning>` occurs in a Composition, the modification to the `matrix

<MappingProjection.matrix>` parameter of a `MappingProjection` that occurs on a given `TRIAL <TimeScale.TRIAL>`

does not acutally appear in its `value <ParameterPort>` until the next `TRIAL <TimeScale.TRIAL>`, since it requires

that the ParameterPort for the `matrix <MappingProjection.matrix>` be executed, which does not occur until the next

time the MappingProjection is executed (i.e., in the next `TRIAL <TimeScale.TRIAL>`).  Therefore, in tracking the

`value <Component.value>` of Components during execution, it is important to carefully consider the state of

execution of the Components to which they belong or on which they depend for execution.

The following attributes and methods control and provide information about the execution of a Component:

.. _Component_Execution_Initialization:

*Initialization*

~~~~~~~~~~~~~~~~

.. _Component_Reset_Stateful_Function_When:

* **reset_stateful_function_when** -- a `Condition` that determines when the Component's `reset <Component.reset>`

  method is called.  The `reset <Component.reset>` method and `reset_stateful_function_when

  <Component.reset_stateful_function_when>` attribute only exist for Mechanisms that have `stateful

  <Parameter.stateful>` `Parameters`, or that have a `function <Mechanism_Base.function>` with `stateful

  <Parameter.stateful>` Parameters.  When the `reset <Component.reset>` method is called, this is done without any

  arguments, so that the relevant `initializer <IntegratorFunction.initializer>` attributes (or their equivalents

  -- initialization attributes vary among functions) are used for reinitialization.

  COMMENT:

      WHAT ABOUT initializer ATTRIBUTE FOR NON-INTEGRATOR FUNCTIONS, AND FOR STATEFUL PARAMETERS ON MECHANISMS?

      WHY IS THIS ATTRIBUTE ON COMPONENT RATHER THAN MECHANISM?

  COMMENT

  .. note::

     `Mechanisms <Mechanism>` are the only type of Component that reset when the `reset_stateful_function_when

     <Component.reset_stateful_function_when>` `Condition` is satisfied. Other Component types do not reset,

     although `Composition` has a `reset <Composition.reset>` method that can be used to reset all of its eligible

     Mechanisms (see `Composition_Reset`)

.. _Component_Execution_Termination:

*Termination*

~~~~~~~~~~~~~

.. _Component_Is_Finished:

* **is_finished()** -- method that determines whether execution of the Component is complete for a `TRIAL

  <TimeScale.TRIAL>`;  it is only used if `execute_until_finished <Component_Execute_Until_Finished>` is True.

.. _Component_Execute_Until_Finished:

* **execute_until_finished** -- determines whether the Component executes until its `is_finished` method returns True.

  If it is False, then the Component executes only once per call to its `execute <Component.execute>` method,

  irrespective of its `is_finished` method;  if it is True then, depending on how its class implements and handles its

  `is_finished` method, the Component may execute more than once per call to its `execute <Component.execute>` method.

.. _Component_Num_Executions_Before_Finished:

* **num_executions_before_finished** -- contains the number of times the Component has executed prior to finishing

  (and since it last finished);  depending upon the class, these may all be within a single call to the Component's

  `execute <Component.execute>` method, or extend over several calls.  It is set to 0 each time `is_finished` evaluates

  to True. Note that this is distinct from the `execution_count <Component_Execution_Count>` and `num_executions

  <Component_Num_Executions>` attributes.

.. _Component_Max_Executions_Before_Finished:

* **max_executions_before_finished** -- determines the maximum number of executions allowed before finishing

  (i.e., the maximum allowable value of `num_executions_before_finished <Component.num_executions_before_finished>`).

  If it is exceeded, a warning message is generated.  Note that this only pertains to `num_executions_before_finished

  <Component_Num_Executions_Before_Finished>`, and not its `execution_count <Component_Execution_Count>`, which can be

  unlimited.

.. _Component_Execution_Count_and_Time:

*Count and Time*

~~~~~~~~~~~~~~~~

.. _Component_Execution_Count:

* **execution_count** -- maintains a record of the number of times a Component has executed since it was constructed,

  *excluding*  executions carried out during initialization and validation, but including all others whether they are

  of the Component on its own are as part of a `Composition`, and irrespective of the `context <Context>` in which

  they are occur. The value can be changed "manually" or programmatically by assigning an integer

  value directly to the attribute.  Note that this is the distinct from the `num_executions <Component_Num_Executions>`

  and `num_executions_before_finished <Component_Num_Executions_Before_Finished>` attributes.

.. _Component_Num_Executions:

* **num_executions** -- maintains a record, in a `Time` object, of the number of times a Component has executed in a

  particular `context <Context>` and at different `TimeScales <TimeScale>`. The value cannot be changed. Note that this

  is the distinct from the `execution_count <Component_Execution_Count>` and `num_executions_before_finished

  <Component_Num_Executions_Before_Finished>` attributes.

.. _Component_Current_Execution_Time:

* **current_execution_time** -- maintains the `Time` of the last execution of the Component in the context of the

  `Composition`'s current `scheduler <Composition.scheduler`, and is stored as a `time

  <Context.time>` tuple of values indicating the `TimeScale.TRIAL`,  `TimeScale.PASS`, and `TimeScale.TIME_STEP` of the

  last execution.

.. _Component_Class_Reference:

Class Reference

---------------

COMMENT:

This module defines the Component abstract class

It also contains:

- arg_name definitions for primary Component categories:

    Process

    Mechanism

        types:

            DDM

            [PDP]

    Projection

        types:

            MappingProjection

            ControlProjection

            LearningProjection

    Function

COMMENT

"""

    Context, ContextError, ContextFlags, INITIALIZATION_STATUS_FLAGS, _get_time, handle_external_context

    CONTEXT, CONTROL_PROJECTION, DEFERRED_INITIALIZATION, EXECUTE_UNTIL_FINISHED, \

    FUNCTION, FUNCTION_PARAMS, INIT_FULL_EXECUTE_METHOD, INPUT_PORTS, \

    LEARNING, LEARNING_PROJECTION, MATRIX, MAX_EXECUTIONS_BEFORE_FINISHED, \

    MODEL_SPEC_ID_PSYNEULINK, MODEL_SPEC_ID_METADATA, \

    MODEL_SPEC_ID_INPUT_PORTS, MODEL_SPEC_ID_OUTPUT_PORTS, \

    MODEL_SPEC_ID_MDF_VARIABLE, \

    MODULATORY_SPEC_KEYWORDS, NAME, OUTPUT_PORTS, OWNER, PARAMS, PREFS_ARG, \

    RESET_STATEFUL_FUNCTION_WHEN, SIZE, VALUE, VARIABLE, SHARED_COMPONENT_TYPES

    Defaults, SharedParameter, Parameter, ParameterAlias, ParameterError, ParametersBase, check_user_specified, copy_parameter_value, is_array_like

    PreferenceLevel, PreferenceSet, _assign_prefs

    ContentAddressableList, convert_all_elements_to_np_array, convert_to_np_array, get_deepcopy_with_shared, \

    is_instance_or_subclass, is_matrix, iscompatible, kwCompatibilityLength, \

    get_all_explicit_arguments, is_numeric, call_with_pruned_args, safe_equals, safe_len, parse_valid_identifier, try_extract_0d_array_item, contains_type

    'Component', 'COMPONENT_BASE_CLASS', 'component_keywords', 'ComponentError', 'ComponentLog',

    'DefaultsFlexibility', 'DeferredInitRegistry', 'parameter_keywords', 'ResetMode',

]

    """

    .. _Component_ResetMode:

    ResetModes used for **reset_params**:

    .. _CURRENT_TO_INSTANCE_DEFAULTS:

    *CURRENT_TO_INSTANCE_DEFAULTS*

      • resets all current values to instance default values.

    .. _INSTANCE_TO_CLASS:

    *INSTANCE_TO_CLASS*

      • resets all instance default values to class default values.

    .. _ALL_TO_CLASS_DEFAULTS:

    *ALL_TO_CLASS_DEFAULTS*

      • resets all current values and instance default values to \

      class default values

    """

    """

        Denotes how rigid an assignment to a default is. That is, how much it can be modified, if at all,

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

    Attributes

    ----------

    FLEXIBLE

        can be modified in any way.

    RIGID

        cannot be modifed in any way.

    INCREASE_DIMENSION

        can be wrapped in a single extra dimension.

    """

# suppress_validation_preference_set = BasePreferenceSet(prefs = {

#     PARAM_VALIDATION_PREF: PreferenceEntry(False,PreferenceLevel.INSTANCE),

#     VERBOSE_PREF: PreferenceEntry(False,PreferenceLevel.INSTANCE),

#     REPORT_OUTPUT_PREF: PreferenceEntry(True,PreferenceLevel.INSTANCE)})

        else:

            # _get does handle stateful case, but checking here avoids

            # extra overhead for most_recent_context and external get.

            # external get is being used so that dot-notation returns a

            # copy of stored numpy arrays. dot-notation is also often

            # used internally for non-stateful parameters, like

            # function, input_ports, output_ports, etc.

            else:

                'Setting parameter values directly using dot notation'

                ' may be removed in a future release. It is replaced with,'

                f' for example, <object>.{param.name}.base = {value}',

                FutureWarning,

            )

                raise ParameterError(

                    f"Parameter '{p.name}' is read-only. Set at your own risk."

                    f' Use .parameters.{p.name}.set with override=True to force set.'

                ) from None

    """

    Assign has_initializers status to Component and any of its owners up the hierarchy.

    """

        # only update owner's attribute if setting to True, because there may be

        # other children that have initializers

            # no owner

# *****************************************   COMPONENT CLASS  ********************************************************

    # consider removing this for explicitness

    # but can be useful for simplicity

    """

    Component(                 \

        default_variable=None, \

        size=None,             \

        params=None,           \

        name=None,             \

        prefs=None,            \

        context=None           \

    )

    Base class for Component.

    The arguments below are ones that can be used in the constructor for any Component subclass.

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

    COMMENT:

    FOR API DOCUMENTATION:

        The Component itself can be called without any arguments (in which case it uses its instance defaults) or

            one or more variables (as defined by the subclass) followed by an optional params dictionary

        The variable(s) can be a function reference, in which case the function is called to resolve the value;

            however:  it must be "wrapped" as an item in a list, so that it is not called before being passed

                      it must of course return a variable of the type expected for the variable

        The size argument is an int or array of ints, which specify the size of variable and set variable to be array(s)

            of zeros.

        The default variableList is a list of default values, one for each of the variables defined in the child class

        The params argument is a dictionary; the key for each entry is the parameter name, associated with its value.

            + Component subclasses can define the param FUNCTION:<method or Function class>

        The instance defaults can be assigned at initialization or using the _instantiate_defaults class method;

            - if instance defaults are not assigned on initialization, the corresponding class defaults are assigned

        Each Component child class must initialize itself by calling super(childComponentName).__init__()

            with a default value for its variable, and optionally an instance default paramList.

        A subclass MUST either:

            - implement a <class>.function method OR

            - specify a default Function

            - this is checked in Component._instantiate_function()

            - if params[FUNCTION] is NOT specified, it is assigned to self.function (so that it can be referenced)

            - if params[FUNCTION] IS specified, it assigns it's value to self.function (superceding existing value):

                self.function is aliased to it (in Component._instantiate_function):

                    if FUNCTION is found on initialization:

                        if it is a reference to an instantiated function, self.function is pointed to it

                        if it is a class reference to a function:

                            it is instantiated using self.defaults.variable and FUNCTION_PARAMS (if they are there too)

                            this works, since _validate_params is always called after _validate_variable

                            so self.defaults.variable can be used to initialize function

                            to the method referenced by self.defaults.function

                    if self.function is found, an exception is raised

        NOTES:

            * In the current implementation, validation is:

              - top-level only (items in lists, tuples and dictionaries are not checked, nor are nested items)

              - for type only (it is oblivious to content)

              - forgiving (e.g., no distinction is made among numberical types)

            * However, more restrictive validation (e.g., recurisve, range checking, etc.) can be achieved

                by overriding the class _validate_variable and _validate_params methods

    COMMENT

    Arguments

    ---------

    default_variable : scalar, list or array : default [[0]]

        specifies template for the input to the Component's `function <Component.function>`, and the value used as the

        input to the Component if none is provided on execution (see `Component_Variable` for additional information).

    size : int, list or np.ndarray of ints : default None

        specifies default_variable as array(s) of zeros if **default_variable** is not passed as an argument;

        if **default_variable** is specified, it takes precedence over the specification of **size** (see

        `size <Component_Size>` for additonal details).

    COMMENT:

    param_defaults :   :  default None,

    COMMENT

    params : Dict[param keyword: param value] : default None

        a `parameter dictionary <ParameterPort_Specification>` that can be used to specify the parameters for

        the Component and/or a custom function and its parameters. Values specified for parameters in the dictionary

        override any assigned to those parameters in arguments of the constructor.

    name : str : for default see `name <Component_Name>`

        a string used for the name of the Component;  default is assigned by relevant `Registry` for Component

        (see `Registry_Naming` for conventions used for default and duplicate names).

    prefs : PreferenceSet or specification dict : default Component.classPreferences

        specifies the `PreferenceSet` for the Component (see `prefs <Component_Base.prefs>` for details).

    context : Context : default None

        specifies `context <Context>` in which Component is being initialized or executed.

    Attributes

    ----------

    variable : 2d np.array

        see `variable <Component_Variable>`

    size : int or array of ints

        see `size <Component_Size>`

    function : Function, function or method

        see `function <Component_Function>`

    value : 2d np.array

        see `value <Component_Value>`

    log : Log

        see `log <Component_Log>`

    execution_count : int

        see `execution_count <Component_Execution_Count>`

    num_executions : Time

        see `num_executions <_Component_Num_Executions>`

    current_execution_time : tuple(`Time.RUN`, `Time.TRIAL`, `Time.PASS`, `Time.TIME_STEP`)

        see `current_execution_time <Component_Current_Execution_Time>`

    execute_until_finished : bool

        see `execute_until_finished <Component_Execute_Until_Finished>`

    num_executions_before_finished : int

        see `num_executions_before_finished <Component_Num_Executions_Before_Finished>`

    max_executions_before_finished : bool

        see `max_executions_before_finished <Component_Max_Executions_Before_Finished>`

    stateful_parameters : list

        see `stateful_parameters <Component_Stateful_Parameters>`

    reset_stateful_function_when : `Condition`

        see `reset_stateful_function_when <Component_reset_stateful_function_when>`

    name : str

        see `name <Component_Name>`

    prefs : PreferenceSet

        see `prefs <Component_Prefs>`

    parameters :  Parameters

        see `parameters <Component_Parameters>` and `Parameters` for additional information.

    defaults : Defaults

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