9808675981

Committed 05 Jul 2024 12:57PM UTC coverage: 83.985% (-0.003%) from 83.988%

Build # 9808675981

Build Type

push

github

Committed by

web-flow

Commit Message

llvm: Tweaks to structure layout and codestyle (#2994)

Make MT state size 8B aligned.
Make Philox state size 8B aligned.
Use derived types in operations where the expected type is known.
Codestyle.

Run Details

11586 of 14853 branches covered (78.0%)

Branch coverage included in aggregate %.

73 of 73 new or added lines in 5 files covered. (100.0%)

2 existing lines in 2 files now uncovered.

31746 of 36742 relevant lines covered (86.4%)

0.86 hits per line

Source File
Press 'n' to go to next uncovered line, 'b' for previous

83.2

/psyneulink/library/components/projections/pathway/autoassociativeprojection.py

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


# *******************************************  AutoAssociativeProjection ***********************************************

"""

Contents
--------

  * `AutoAssociative_Overview`
  * `AutoAssociative_Creation`
  * `AutoAssociative_Structure`
      - `AutoAssociative_Configurable_Attributes`
  * `AutoAssociative_Execution`
  * `AutoAssociative_Class_Reference`


.. _AutoAssociative_Overview:

Overview
--------

An AutoAssociativeProjection is a subclass of `MappingProjection` that acts as the recurrent projection for a
`RecurrentTransferMechanism`. The primary difference between an AutoAssociativeProjection and a basic MappingProjection
is that an AutoAssociativeProjection uses the `auto <RecurrentTransferMechanism.auto>` and
`hetero <RecurrentTransferMechanism.hetero>` parameters *on the RecurrentTransferMechanism* to help update its matrix:
this allows for a `ControlMechanism <ControlMechanism>` to control the `auto <RecurrentTransferMechanism.auto>` and
`hetero <RecurrentTransferMechanism.hetero>` parameters and thereby control the matrix.

AutoAssociativeProjection represents connections between nodes in a single-layer recurrent network. It multiplies
the output of the `RecurrentTransferMechanism` by a matrix, then presents the product as input to the
`RecurrentTransferMechanism`.



.. _AutoAssociative_Creation:

Creating an AutoAssociativeProjection
-------------------------------------

An AutoAssociativeProjection is created automatically by a RecurrentTransferMechanism (or its subclasses), and is
stored as the `recurrent_projection <RecurrentTransferMechanism.recurrent_projection>` parameter of the
RecurrentTransferMechanism. It is not recommended to create an AutoAssociativeProjection on its own, because during
execution an AutoAssociativeProjection references parameters owned by its RecurrentTransferMechanism (see
`Execution <AutoAssociative_Execution>` below).

.. _AutoAssociative_Structure:

Auto Associative Structure
--------------------------

In structure, the AutoAssociativeProjection is almost identical to a MappingProjection: the only additional attributes
are `auto <AutoAssociativeProjection.auto>` and `hetero <AutoAssociativeProjection.hetero>`.

.. _AutoAssociative_Configurable_Attributes:

*Configurable Attributes*
~~~~~~~~~~~~~~~~~~~~~~~~~

Due to its specialized nature, most parameters of the AutoAssociativeProjection are not configurable: the `variable` is
determined by the format of the output of the RecurrentTransferMechanism, the `function` is always LinearMatrix, and so
on. The only configurable parameter is the matrix, configured through the **matrix**, **auto**, and/or **hetero**
arguments for a RecurrentTransferMechanism:

.. _AutoAssociative_Matrix:

* **matrix** - multiplied by the input to the AutoAssociativeProjection in order to produce the output. Specification of
  the **matrix**, **auto**, and/or **hetero** arguments determines the values of the matrix; **auto** determines the
  diagonal entries (representing the strength of the connection from each node to itself) and **hetero** determines
  the off-diagonal entries (representing connections between nodes).

.. _AutoAssociative_Execution:

Execution
---------

An AutoAssociativeProjection uses its `matrix <AutoAssociativeProjection.matrix>` parameter to transform the value of
its `sender <AutoAssociativeProjection.sender>`, and provide the result as input for its
`receiver <AutoAssociativeProjection.receiver>`, the primary InputPort of the RecurrentTransferMechanism.

.. note::
     During execution the AutoAssociativeProjection updates its `matrix <AutoAssociativeProjection.matrix> parameter
     based on the `auto <RecurrentTransferMechanism.auto>` and `hetero <RecurrentTransferMechanism.hetero>` parameters
     *on the `RecurrentTransferMechanism`*. (The `auto <AutoAssociativeProjection.auto>` and
     `hetero <AutoAssociativeProjection.hetero>` parameters of the AutoAssociativeProjection simply refer to their
     counterparts on the RecurrentTransferMechanism as well.) The reason for putting the `auto
     <RecurrentTransferMechanism.auto>` and `hetero <RecurrentTransferMechanism.hetero>` parameters on the
     RecurrentTransferMechanism is that this allows them to be modified by a `ControlMechanism <ControlMechanism>`.

.. _AutoAssociative_Class_Reference:

Class Reference
---------------

"""
import numpy as np
from beartype import beartype

from psyneulink._typing import Optional

from psyneulink.core.components.component import parameter_keywords
from psyneulink.core.components.functions.nonstateful.transferfunctions import LinearMatrix
from psyneulink.core.components.functions.function import get_matrix
from psyneulink.core.components.projections.pathway.mappingprojection import MappingError, MappingProjection
from psyneulink.core.components.projections.projection import projection_keywords
from psyneulink.core.components.shellclasses import Mechanism
from psyneulink.core.components.ports.outputport import OutputPort
from psyneulink.core.globals.keywords import AUTO_ASSOCIATIVE_PROJECTION, DEFAULT_MATRIX, HOLLOW_MATRIX, FUNCTION, OWNER_MECH
from psyneulink.core.globals.parameters import SharedParameter, Parameter, check_user_specified
from psyneulink.core.globals.preferences.basepreferenceset import ValidPrefSet
from psyneulink.core.globals.preferences.preferenceset import PreferenceLevel
from psyneulink.core.globals.utilities import is_numeric_scalar

__all__ = [
    'AutoAssociativeError', 'AutoAssociativeProjection', 'get_auto_matrix', 'get_hetero_matrix',
]

parameter_keywords.update({AUTO_ASSOCIATIVE_PROJECTION})
projection_keywords.update({AUTO_ASSOCIATIVE_PROJECTION})


class AutoAssociativeError(MappingError):
    pass


class AutoAssociativeProjection(MappingProjection):
    """
    AutoAssociativeProjection(
        )

    Subclass of `MappingProjection` that is self-recurrent on a `RecurrentTransferMechanism`.
    See `MappingProjection <MappingProjection_Class_Reference>` and `Projection <Projection_Class_Reference>`
    for additional arguments and attributes.

    COMMENT:
        JDC [IN GENERAL WE HAVE TRIED TO DISCOURAGE SUCH DEPENDENCIES;  BETTER TO HAVE IT ACCEPT ARGUMENTS THAT
        RecurrentTransferMechanism (or Composition) PROVIDES THAN ASSUME THEY ARE ON ANOTHER OBJECT THAT CREATED
        THIS ONE]
    Note: The reason **auto** and **hetero** are not arguments to the constructor of the AutoAssociativeProjection is
    because it is only ever created by a RecurrentTransferMechanism: by the time the AutoAssociativeProjection is
    created, the **auto** and **hetero** arguments are already incorporated into the **matrix** argument.

    COMMENT

    Arguments
    ---------

    sender : OutputPort or Mechanism : default None
        specifies the source of the Projection's input; must be (or belong to) the same Mechanism as **receiver**,
        and the length of its `value <OutputPort.value>` must match that of the `variable <InputPort.variable>` of
        the **receiver**.

    receiver: InputPort or Mechanism : default None
        specifies the destination of the Projection's output; must be (or belong to) the same Mechanism as **sender**,
        and the length of its `variable <InputPort.variable>` must match the `value <OutputPort.value>` of **sender**.

    matrix : list, np.ndarray, function or keyword : default DEFAULT_MATRIX
        specifies the matrix used by `function <Projection_Base.function>` (default: `LinearCombination`) to
        transform the `value <Projection_Base.value>` of the `sender <MappingProjection.sender>` into a value
        provided to the `variable <InputPort.variable>` of the `receiver <MappingProjection.receiver>` `InputPort`;
        must be a square matrix (i.e., have the same number of rows and columns).

    Attributes
    ----------

    sender : OutputPort
        the `OutputPort` of the `Mechanism <Mechanism>` that is the source of the Projection's input; in the case of
        an AutoAssociativeProjection, it is an OutputPort of the same Mechanism to which the `receiver
        <AutoAssociativeProjection.receiver>` belongs.

    receiver: InputPort
        the `InputPort` of the `Mechanism <Mechanism>` that is the destination of the Projection's output; in the case
        of an AutoAssociativeProjection, it is an InputPort of the same Mechanism to which the `sender
        <AutoAssociativeProjection.sender>` belongs.

    matrix : 2d np.ndarray
        square matrix used by `function <AutoAssociativeProjection.function>` to transform input from the `sender
        <MappingProjection.sender>` to the value provided to the `receiver <AutoAssociativeProjection.receiver>`;
        in the case of an AutoAssociativeProjection.

    """

    componentType = AUTO_ASSOCIATIVE_PROJECTION
    className = componentType
    suffix = " " + className

    class Parameters(MappingProjection.Parameters):
        """
            Attributes
            ----------

                variable
                    see `variable <AutoAssociativeProjection.variable>`

                    :default value: numpy.array([[0]])
                    :type: ``numpy.ndarray``
                    :read only: True

                auto
                    see `auto <AutoAssociativeProjection.auto>`

                    :default value: 1
                    :type: ``int``

                function
                    see `function <AutoAssociativeProjection.function>`

                    :default value: `LinearMatrix`
                    :type: `Function`

                hetero
                    see `hetero <AutoAssociativeProjection.hetero>`

                    :default value: 0
                    :type: ``int``

                matrix
                    see `matrix <AutoAssociativeProjection.matrix>`

                    :default value: `AUTO_ASSIGN_MATRIX`
                    :type: ``str``
        """
        variable = Parameter(np.array([[0]]), read_only=True, pnl_internal=True, constructor_argument='default_variable')
        # function is always LinearMatrix that requires 1D input
        function = Parameter(LinearMatrix, stateful=False, loggable=False)

        auto = SharedParameter(1, attribute_name=OWNER_MECH)
        hetero = SharedParameter(0, attribute_name=OWNER_MECH)
        matrix = SharedParameter(DEFAULT_MATRIX, attribute_name=OWNER_MECH)

    classPreferenceLevel = PreferenceLevel.TYPE

    @check_user_specified
    @beartype
    def __init__(self,
                 owner=None,
                 sender=None,
                 receiver=None,
                 matrix=None,
                 function=None,
                 params=None,
                 name=None,
                 prefs:  Optional[ValidPrefSet] = None,
                 **kwargs
                 ):

        if owner is not None:
            if not isinstance(owner, Mechanism):
                raise AutoAssociativeError('Owner of AutoAssociative Mechanism must either be None or a Mechanism')
            if sender is None:
                sender = owner
            if receiver is None:
                receiver = owner

        super().__init__(sender=sender,
                         receiver=receiver,
                         matrix=matrix,
                         function=function,
                         params=params,
                         name=name,
                         prefs=prefs,
                         **kwargs)

    # temporary override to make sure matrix/auto/hetero parameters
    # get passed properly. should be replaced with a better organization
    # of auto/hetero, in which the base parameters are stored either on
    # AutoAssociativeProjection or on LinearMatrix itself
    def _instantiate_parameter_classes(self, context):
        if FUNCTION not in self.initial_shared_parameters:
            try:
                self.initial_shared_parameters[FUNCTION] = {
                    'matrix': self.initial_shared_parameters[OWNER_MECH]['matrix']
                }
            except KeyError:
                pass

        super()._instantiate_parameter_classes(context)

    # COMMENTED OUT BY KAM 1/9/2018 -- this method is not currently used; should be moved to Recurrent Transfer Mech
    #     if it is used in the future

    # def _update_auto_and_hetero(self, owner_mech=None, runtime_params=None, time_scale=TimeScale.TRIAL, context=None):
    #     if owner_mech is None:
    #         if isinstance(self.sender, OutputPort):
    #             owner_mech = self.sender.owner
    #         elif isinstance(self.sender, Mechanism):
    #             owner_mech = self.sender
    #         else:
    #             raise AutoAssociativeError("The sender of the {} \'{}\' must be a Mechanism or OutputPort: currently"
    #                                        " the sender is {}".
    #                                        format(self.__class__.__name__, self.name, self.sender))
    #     if AUTO in owner_mech._parameter_ports and HETERO in owner_mech._parameter_ports:
    #         owner_mech._parameter_ports[AUTO].update(context=context, params=runtime_params, time_scale=time_scale)
    #         owner_mech._parameter_ports[HETERO].update(context=context, params=runtime_params, time_scale=time_scale)
    #

    # END OF COMMENTED OUT BY KAM 1/9/2018

    # NOTE 7/25/17 CW: Originally, this override was written because if the user set the 'auto' parameter on the
        # recurrent mechanism, the ParameterPort wouldn't update until after the mechanism executed: since the system
        # first runs the projection, then runs the mechanism, the projection initially uses the 'old' value. However,
        # this is commented out because this may in fact be the desired behavior.
        # Two possible solutions: allow control to be done on projections, or build a more general way to allow
        # projections to read parameters from mechanisms.
    # def _update_parameter_ports(self, runtime_params=None, context=None):
    #     """Update this projection's owner mechanism's `auto` and `hetero` parameter ports as well! The owner mechanism
    #     should be a RecurrentTransferMechanism, which DOES NOT update its own `auto` and `hetero` parameter ports during
    #     its _update_parameter_ports function (so that the ParameterPort is not redundantly updated).
    #     Thus, if you want to have an AutoAssociativeProjection on a mechanism that's not a RecurrentTransferMechanism,
    #     your mechanism must similarly exclude `auto` and `hetero` from updating.
    #     """
    #     super()._update_parameter_ports(runtime_params, context)
    #
    #     if isinstance(self.sender, OutputPort):
    #         owner_mech = self.sender.owner
    #     elif isinstance(self.sender, Mechanism):
    #         owner_mech = self.sender
    #     else:
    #         raise AutoAssociativeError("The sender of the {} \'{}\' must be a Mechanism or OutputPort: currently the"
    #                                    " sender is {}".
    #                                    format(self.__class__.__name__, self.name, self.sender))
    #
    #     if AUTO in owner_mech._parameter_ports and HETERO in owner_mech._parameter_ports:
    #         owner_mech._parameter_ports[AUTO].update(context=context, params=runtime_params)
    #         owner_mech._parameter_ports[HETERO].update(context=context, params=runtime_params)
    #     else:
    #         raise AutoAssociativeError("Auto or Hetero ParameterPort not found in {0} \"{1}\"; here are names of the "
    #                                    "current ParameterPorts for {1}: {2}".format(owner_mech.__class__.__name__,
    #                                    owner_mech.name, owner_mech._parameter_ports.key_values))

    @property
    def owner_mech(self):
        if isinstance(self.sender, OutputPort):
            return self.sender.owner
        elif isinstance(self.sender, Mechanism):
            return self.sender
        else:
            raise AutoAssociativeError(
                "The sender of the {} \'{}\' must be a Mechanism or OutputPort: currently the sender is {}".format(
                    self.__class__.__name__, self.name, self.sender
                )
            )

    @property
    def matrix(self):
        owner_mech = self.owner_mech
        if hasattr(owner_mech, "matrix"):
            return owner_mech.matrix
        return super(AutoAssociativeProjection, self.__class__).matrix.fget(self)

    @matrix.setter
    def matrix(self, setting):
        owner_mech = self.owner_mech
        if hasattr(owner_mech, "matrix"):
            owner_mech.matrix = setting
        else:
            super(AutoAssociativeProjection, self.__class__).matrix.fset(self, setting)


# a helper function that takes a specification of `hetero` and returns a hollow matrix with the right values
def get_hetero_matrix(raw_hetero, size):
    if is_numeric_scalar(raw_hetero):
        return get_matrix(HOLLOW_MATRIX, size, size) * raw_hetero
    elif ((isinstance(raw_hetero, np.ndarray) and raw_hetero.ndim == 1) or
              (isinstance(raw_hetero, list) and np.array(raw_hetero).ndim == 1)):
        if len(raw_hetero) != 1:
            return None
        return get_matrix(HOLLOW_MATRIX, size, size) * raw_hetero[0]
    elif (isinstance(raw_hetero, np.matrix) or
              (isinstance(raw_hetero, np.ndarray) and raw_hetero.ndim == 2) or
              (isinstance(raw_hetero, list) and np.array(raw_hetero).ndim == 2)):
        np.fill_diagonal(raw_hetero, 0)
        return np.array(raw_hetero)
    else:
        return None


# similar to get_hetero_matrix() above
def get_auto_matrix(raw_auto, size):
    if is_numeric_scalar(raw_auto):
        return np.diag(np.full(size, raw_auto, dtype=float))
    elif ((isinstance(raw_auto, np.ndarray) and raw_auto.ndim == 1) or
              (isinstance(raw_auto, list) and np.array(raw_auto).ndim == 1)):
        if len(raw_auto) == 1:
            return np.diag(np.full(size, raw_auto[0], dtype=float))
        else:
            if len(raw_auto) != size:
                return None
            return np.diag(raw_auto)
    elif (isinstance(raw_auto, np.matrix) or
              (isinstance(raw_auto, np.ndarray) and raw_auto.ndim == 2) or
              (isinstance(raw_auto, list) and np.array(raw_auto).ndim == 2)):
        # we COULD add a validation here to ensure raw_auto is diagonal, but it would slow stuff down.
        return np.array(raw_auto)
    else:
        return None

1	# Princeton University licenses this file to You under the Apache License, Version 2.0 (the "License");
2	# you may not use this file except in compliance with the License. You may obtain a copy of the License at:
3	# http://www.apache.org/licenses/LICENSE-2.0
4	# Unless required by applicable law or agreed to in writing, software distributed under the License is distributed
5	# on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
6	# See the License for the specific language governing permissions and limitations under the License.
7
8
9	# ***************************************** AutoAssociativeProjection *********************************************
10
11	"""
12
13	Contents
14	--------
15
16	* `AutoAssociative_Overview`
17	* `AutoAssociative_Creation`
18	* `AutoAssociative_Structure`
19	- `AutoAssociative_Configurable_Attributes`
20	* `AutoAssociative_Execution`
21	* `AutoAssociative_Class_Reference`
22
23
24	.. _AutoAssociative_Overview:
25
26	Overview
27	--------
28
29	An AutoAssociativeProjection is a subclass of `MappingProjection` that acts as the recurrent projection for a
30	`RecurrentTransferMechanism`. The primary difference between an AutoAssociativeProjection and a basic MappingProjection
31	is that an AutoAssociativeProjection uses the `auto <RecurrentTransferMechanism.auto>` and
32	`hetero <RecurrentTransferMechanism.hetero>` parameters on the RecurrentTransferMechanism to help update its matrix:
33	this allows for a `ControlMechanism <ControlMechanism>` to control the `auto <RecurrentTransferMechanism.auto>` and
34	`hetero <RecurrentTransferMechanism.hetero>` parameters and thereby control the matrix.
35
36	AutoAssociativeProjection represents connections between nodes in a single-layer recurrent network. It multiplies
37	the output of the `RecurrentTransferMechanism` by a matrix, then presents the product as input to the
38	`RecurrentTransferMechanism`.
39
40
41
42	.. _AutoAssociative_Creation:
43
44	Creating an AutoAssociativeProjection
45	-------------------------------------
46
47	An AutoAssociativeProjection is created automatically by a RecurrentTransferMechanism (or its subclasses), and is
48	stored as the `recurrent_projection <RecurrentTransferMechanism.recurrent_projection>` parameter of the
49	RecurrentTransferMechanism. It is not recommended to create an AutoAssociativeProjection on its own, because during
50	execution an AutoAssociativeProjection references parameters owned by its RecurrentTransferMechanism (see
51	`Execution <AutoAssociative_Execution>` below).
52
53	.. _AutoAssociative_Structure:
54
55	Auto Associative Structure
56	--------------------------
57
58	In structure, the AutoAssociativeProjection is almost identical to a MappingProjection: the only additional attributes
59	are `auto <AutoAssociativeProjection.auto>` and `hetero <AutoAssociativeProjection.hetero>`.
60
61	.. _AutoAssociative_Configurable_Attributes:
62
63	Configurable Attributes
64	~~~~~~~~~~~~~~~~~~~~~~~~~
65
66	Due to its specialized nature, most parameters of the AutoAssociativeProjection are not configurable: the `variable` is
67	determined by the format of the output of the RecurrentTransferMechanism, the `function` is always LinearMatrix, and so
68	on. The only configurable parameter is the matrix, configured through the matrix, auto, and/or hetero
69	arguments for a RecurrentTransferMechanism:
70
71	.. _AutoAssociative_Matrix:
72
73	* matrix - multiplied by the input to the AutoAssociativeProjection in order to produce the output. Specification of
74	the matrix, auto, and/or hetero arguments determines the values of the matrix; auto determines the
75	diagonal entries (representing the strength of the connection from each node to itself) and hetero determines
76	the off-diagonal entries (representing connections between nodes).
77
78	.. _AutoAssociative_Execution:
79
80	Execution
81	---------
82
83	An AutoAssociativeProjection uses its `matrix <AutoAssociativeProjection.matrix>` parameter to transform the value of
84	its `sender <AutoAssociativeProjection.sender>`, and provide the result as input for its
85	`receiver <AutoAssociativeProjection.receiver>`, the primary InputPort of the RecurrentTransferMechanism.
86
87	.. note::
88	During execution the AutoAssociativeProjection updates its `matrix <AutoAssociativeProjection.matrix> parameter
89	based on the `auto <RecurrentTransferMechanism.auto>` and `hetero <RecurrentTransferMechanism.hetero>` parameters
90	on the `RecurrentTransferMechanism`. (The `auto <AutoAssociativeProjection.auto>` and
91	`hetero <AutoAssociativeProjection.hetero>` parameters of the AutoAssociativeProjection simply refer to their
92	counterparts on the RecurrentTransferMechanism as well.) The reason for putting the `auto
93	<RecurrentTransferMechanism.auto>` and `hetero <RecurrentTransferMechanism.hetero>` parameters on the
94	RecurrentTransferMechanism is that this allows them to be modified by a `ControlMechanism <ControlMechanism>`.
95
96	.. _AutoAssociative_Class_Reference:
97
98	Class Reference
99	---------------
100
101	"""
102	import numpy as np	1✔
103	from beartype import beartype	1✔
104
105	from psyneulink._typing import Optional	1✔
106
107	from psyneulink.core.components.component import parameter_keywords	1✔
108	from psyneulink.core.components.functions.nonstateful.transferfunctions import LinearMatrix	1✔
109	from psyneulink.core.components.functions.function import get_matrix	1✔
110	from psyneulink.core.components.projections.pathway.mappingprojection import MappingError, MappingProjection	1✔
111	from psyneulink.core.components.projections.projection import projection_keywords	1✔
112	from psyneulink.core.components.shellclasses import Mechanism	1✔
113	from psyneulink.core.components.ports.outputport import OutputPort	1✔
114	from psyneulink.core.globals.keywords import AUTO_ASSOCIATIVE_PROJECTION, DEFAULT_MATRIX, HOLLOW_MATRIX, FUNCTION, OWNER_MECH	1✔
115	from psyneulink.core.globals.parameters import SharedParameter, Parameter, check_user_specified	1✔
116	from psyneulink.core.globals.preferences.basepreferenceset import ValidPrefSet	1✔
117	from psyneulink.core.globals.preferences.preferenceset import PreferenceLevel	1✔
118	from psyneulink.core.globals.utilities import is_numeric_scalar	1✔
119
120	__all__ = [	1✔
121	'AutoAssociativeError', 'AutoAssociativeProjection', 'get_auto_matrix', 'get_hetero_matrix',
122	]
123
124	parameter_keywords.update({AUTO_ASSOCIATIVE_PROJECTION})	1✔
125	projection_keywords.update({AUTO_ASSOCIATIVE_PROJECTION})	1✔
126
127
128	class AutoAssociativeError(MappingError):	1✔
129	pass	1✔
130
131
132	class AutoAssociativeProjection(MappingProjection):	1✔
133	"""
134	AutoAssociativeProjection(
135	)
136
137	Subclass of `MappingProjection` that is self-recurrent on a `RecurrentTransferMechanism`.
138	See `MappingProjection <MappingProjection_Class_Reference>` and `Projection <Projection_Class_Reference>`
139	for additional arguments and attributes.
140
141	COMMENT:
142	JDC [IN GENERAL WE HAVE TRIED TO DISCOURAGE SUCH DEPENDENCIES; BETTER TO HAVE IT ACCEPT ARGUMENTS THAT
143	RecurrentTransferMechanism (or Composition) PROVIDES THAN ASSUME THEY ARE ON ANOTHER OBJECT THAT CREATED
144	THIS ONE]
145	Note: The reason auto and hetero are not arguments to the constructor of the AutoAssociativeProjection is
146	because it is only ever created by a RecurrentTransferMechanism: by the time the AutoAssociativeProjection is
147	created, the auto and hetero arguments are already incorporated into the matrix argument.
148
149	COMMENT
150
151	Arguments
152	---------
153
154	sender : OutputPort or Mechanism : default None
155	specifies the source of the Projection's input; must be (or belong to) the same Mechanism as receiver,
156	and the length of its `value <OutputPort.value>` must match that of the `variable <InputPort.variable>` of
157	the receiver.
158
159	receiver: InputPort or Mechanism : default None
160	specifies the destination of the Projection's output; must be (or belong to) the same Mechanism as sender,
161	and the length of its `variable <InputPort.variable>` must match the `value <OutputPort.value>` of sender.
162
163	matrix : list, np.ndarray, function or keyword : default DEFAULT_MATRIX
164	specifies the matrix used by `function <Projection_Base.function>` (default: `LinearCombination`) to
165	transform the `value <Projection_Base.value>` of the `sender <MappingProjection.sender>` into a value
166	provided to the `variable <InputPort.variable>` of the `receiver <MappingProjection.receiver>` `InputPort`;
167	must be a square matrix (i.e., have the same number of rows and columns).
168
169	Attributes
170	----------
171
172	sender : OutputPort
173	the `OutputPort` of the `Mechanism <Mechanism>` that is the source of the Projection's input; in the case of
174	an AutoAssociativeProjection, it is an OutputPort of the same Mechanism to which the `receiver
175	<AutoAssociativeProjection.receiver>` belongs.
176
177	receiver: InputPort
178	the `InputPort` of the `Mechanism <Mechanism>` that is the destination of the Projection's output; in the case
179	of an AutoAssociativeProjection, it is an InputPort of the same Mechanism to which the `sender
180	<AutoAssociativeProjection.sender>` belongs.
181
182	matrix : 2d np.ndarray
183	square matrix used by `function <AutoAssociativeProjection.function>` to transform input from the `sender
184	<MappingProjection.sender>` to the value provided to the `receiver <AutoAssociativeProjection.receiver>`;
185	in the case of an AutoAssociativeProjection.
186
187	"""
188
189	componentType = AUTO_ASSOCIATIVE_PROJECTION	1✔
190	className = componentType	1✔
191	suffix = " " + className	1✔
192
193	class Parameters(MappingProjection.Parameters):	1✔
194	"""
195	Attributes
196	----------
197
198	variable
199	see `variable <AutoAssociativeProjection.variable>`
200
201	:default value: numpy.array([[0]])
202	:type: ``numpy.ndarray``
203	:read only: True
204
205	auto
206	see `auto <AutoAssociativeProjection.auto>`
207
208	:default value: 1
209	:type: ``int``
210
211	function
212	see `function <AutoAssociativeProjection.function>`
213
214	:default value: `LinearMatrix`
215	:type: `Function`
216
217	hetero
218	see `hetero <AutoAssociativeProjection.hetero>`
219
220	:default value: 0
221	:type: ``int``
222
223	matrix
224	see `matrix <AutoAssociativeProjection.matrix>`
225
226	:default value: `AUTO_ASSIGN_MATRIX`
227	:type: ``str``
228	"""
229	variable = Parameter(np.array([[0]]), read_only=True, pnl_internal=True, constructor_argument='default_variable')	1✔
230	# function is always LinearMatrix that requires 1D input
231	function = Parameter(LinearMatrix, stateful=False, loggable=False)	1✔
232
233	auto = SharedParameter(1, attribute_name=OWNER_MECH)	1✔
234	hetero = SharedParameter(0, attribute_name=OWNER_MECH)	1✔
235	matrix = SharedParameter(DEFAULT_MATRIX, attribute_name=OWNER_MECH)	1✔
236
237	classPreferenceLevel = PreferenceLevel.TYPE	1✔
238
239	@check_user_specified	1✔
240	@beartype	1✔
241	def __init__(self,	1✔
242	owner=None,
243	sender=None,
244	receiver=None,
245	matrix=None,
246	function=None,
247	params=None,
248	name=None,
249	prefs: Optional[ValidPrefSet] = None,
250	**kwargs
251	):
252
253	if owner is not None:	1!
254	if not isinstance(owner, Mechanism):	1✔
255	raise AutoAssociativeError('Owner of AutoAssociative Mechanism must either be None or a Mechanism')
256	if sender is None:	1✔
257	sender = owner	1✔
258	if receiver is None:	1✔
259	receiver = owner	1✔
260
261	super().__init__(sender=sender,	1✔
262	receiver=receiver,
263	matrix=matrix,
264	function=function,
265	params=params,
266	name=name,
267	prefs=prefs,
268	**kwargs)
269
270	# temporary override to make sure matrix/auto/hetero parameters
271	# get passed properly. should be replaced with a better organization
272	# of auto/hetero, in which the base parameters are stored either on
273	# AutoAssociativeProjection or on LinearMatrix itself
274	def _instantiate_parameter_classes(self, context):	1✔
275	if FUNCTION not in self.initial_shared_parameters:	1!
276	try:	1✔
277	self.initial_shared_parameters[FUNCTION] = {	1✔
278	'matrix': self.initial_shared_parameters[OWNER_MECH]['matrix']
279	}
280	except KeyError:	×
281	pass	×
282
283	super()._instantiate_parameter_classes(context)	1✔
284
285	# COMMENTED OUT BY KAM 1/9/2018 -- this method is not currently used; should be moved to Recurrent Transfer Mech
286	# if it is used in the future
287
288	# def _update_auto_and_hetero(self, owner_mech=None, runtime_params=None, time_scale=TimeScale.TRIAL, context=None):
289	# if owner_mech is None:
290	# if isinstance(self.sender, OutputPort):
291	# owner_mech = self.sender.owner
292	# elif isinstance(self.sender, Mechanism):
293	# owner_mech = self.sender
294	# else:
295	# raise AutoAssociativeError("The sender of the {} \'{}\' must be a Mechanism or OutputPort: currently"
296	# " the sender is {}".
297	# format(self.__class__.__name__, self.name, self.sender))
298	# if AUTO in owner_mech._parameter_ports and HETERO in owner_mech._parameter_ports:
299	# owner_mech._parameter_ports[AUTO].update(context=context, params=runtime_params, time_scale=time_scale)
300	# owner_mech._parameter_ports[HETERO].update(context=context, params=runtime_params, time_scale=time_scale)
301	#
302
303	# END OF COMMENTED OUT BY KAM 1/9/2018
304
305	# NOTE 7/25/17 CW: Originally, this override was written because if the user set the 'auto' parameter on the
306	# recurrent mechanism, the ParameterPort wouldn't update until after the mechanism executed: since the system
307	# first runs the projection, then runs the mechanism, the projection initially uses the 'old' value. However,
308	# this is commented out because this may in fact be the desired behavior.
309	# Two possible solutions: allow control to be done on projections, or build a more general way to allow
310	# projections to read parameters from mechanisms.
311	# def _update_parameter_ports(self, runtime_params=None, context=None):
312	# """Update this projection's owner mechanism's `auto` and `hetero` parameter ports as well! The owner mechanism
313	# should be a RecurrentTransferMechanism, which DOES NOT update its own `auto` and `hetero` parameter ports during
314	# its _update_parameter_ports function (so that the ParameterPort is not redundantly updated).
315	# Thus, if you want to have an AutoAssociativeProjection on a mechanism that's not a RecurrentTransferMechanism,
316	# your mechanism must similarly exclude `auto` and `hetero` from updating.
317	# """
318	# super()._update_parameter_ports(runtime_params, context)
319	#
320	# if isinstance(self.sender, OutputPort):
321	# owner_mech = self.sender.owner
322	# elif isinstance(self.sender, Mechanism):
323	# owner_mech = self.sender
324	# else:
325	# raise AutoAssociativeError("The sender of the {} \'{}\' must be a Mechanism or OutputPort: currently the"
326	# " sender is {}".
327	# format(self.__class__.__name__, self.name, self.sender))
328	#
329	# if AUTO in owner_mech._parameter_ports and HETERO in owner_mech._parameter_ports:
330	# owner_mech._parameter_ports[AUTO].update(context=context, params=runtime_params)
331	# owner_mech._parameter_ports[HETERO].update(context=context, params=runtime_params)
332	# else:
333	# raise AutoAssociativeError("Auto or Hetero ParameterPort not found in {0} \"{1}\"; here are names of the "
334	# "current ParameterPorts for {1}: {2}".format(owner_mech.__class__.__name__,
335	# owner_mech.name, owner_mech._parameter_ports.key_values))
336
337	@property	1✔
338	def owner_mech(self):	1✔
339	if isinstance(self.sender, OutputPort):	1!
340	return self.sender.owner	1✔
341	elif isinstance(self.sender, Mechanism):	×
342	return self.sender	×
343	else:
344	raise AutoAssociativeError(
345	"The sender of the {} \'{}\' must be a Mechanism or OutputPort: currently the sender is {}".format(
346	self.__class__.__name__, self.name, self.sender
347	)
348	)
349
350	@property	1✔
351	def matrix(self):	1✔
352	owner_mech = self.owner_mech	1✔
353	if hasattr(owner_mech, "matrix"):	1!
354	return owner_mech.matrix	1✔
355	return super(AutoAssociativeProjection, self.__class__).matrix.fget(self)	×
356
357	@matrix.setter	1✔
358	def matrix(self, setting):	1✔
359	owner_mech = self.owner_mech	1✔
360	if hasattr(owner_mech, "matrix"):	1!
361	owner_mech.matrix = setting	1✔
362	else:
363	super(AutoAssociativeProjection, self.__class__).matrix.fset(self, setting)	×
364
365
366	# a helper function that takes a specification of `hetero` and returns a hollow matrix with the right values
367	def get_hetero_matrix(raw_hetero, size):	1✔
368	if is_numeric_scalar(raw_hetero):	1✔
369	return get_matrix(HOLLOW_MATRIX, size, size) * raw_hetero	1✔
370	elif ((isinstance(raw_hetero, np.ndarray) and raw_hetero.ndim == 1) or	1!
371	(isinstance(raw_hetero, list) and np.array(raw_hetero).ndim == 1)):
372	if len(raw_hetero) != 1:	×
373	return None	×
374	return get_matrix(HOLLOW_MATRIX, size, size) * raw_hetero[0]	×
375	elif (isinstance(raw_hetero, np.matrix) or	1✔
376	(isinstance(raw_hetero, np.ndarray) and raw_hetero.ndim == 2) or
377	(isinstance(raw_hetero, list) and np.array(raw_hetero).ndim == 2)):
378	np.fill_diagonal(raw_hetero, 0)	1✔
379	return np.array(raw_hetero)	1✔
380	else:
381	return None	1✔
382
383
384	# similar to get_hetero_matrix() above
385	def get_auto_matrix(raw_auto, size):	1✔
386	if is_numeric_scalar(raw_auto):	1✔
387	return np.diag(np.full(size, raw_auto, dtype=float))	1✔
388	elif ((isinstance(raw_auto, np.ndarray) and raw_auto.ndim == 1) or	1✔
389	(isinstance(raw_auto, list) and np.array(raw_auto).ndim == 1)):
390	if len(raw_auto) == 1:	1✔
391	return np.diag(np.full(size, raw_auto[0], dtype=float))	1✔
392	else:
393	if len(raw_auto) != size:	1!
UNCOV 394	return None	×
395	return np.diag(raw_auto)	1✔
396	elif (isinstance(raw_auto, np.matrix) or	1!
397	(isinstance(raw_auto, np.ndarray) and raw_auto.ndim == 2) or
398	(isinstance(raw_auto, list) and np.array(raw_auto).ndim == 2)):
399	# we COULD add a validation here to ensure raw_auto is diagonal, but it would slow stuff down.
400	return np.array(raw_auto)	×
401	else:
402	return None	1✔

PrincetonUniversity / PsyNeuLink / 9808675981

Source File Press 'n' to go to next uncovered line, 'b' for previous

Source File
Press 'n' to go to next uncovered line, 'b' for previous