10242756048

Committed 05 Aug 2024 04:45AM UTC coverage: 83.773% (+0.04%) from 83.734%

Build # 10242756048

Build Type

push

github

Committed by

web-flow

Commit Message

llvm: Use numpy ndpointer for fixed size arguments of compiled functions (#3027)

Construct numpy dtypes from LLVM IR.
Convert ctype structures to type records.
Use numpy ndpointer [0] to check fixed sized arguments to compiled functions.

[0] https://numpy.org/doc/stable/reference/routines.ctypeslib.html#numpy.ctypeslib.ndpointer

Run Details

11682 of 15043 branches covered (77.66%)

Branch coverage included in aggregate %.

135 of 143 new or added lines in 5 files covered. (94.41%)

5 existing lines in 2 files now uncovered.

32010 of 37112 relevant lines covered (86.25%)

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 / 10242756048

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