pyactup 2.0__tar.gz → 2.2.3__tar.gz

{pyactup-2.0 → pyactup-2.2.3}/LICENSE

@@ -1,4 +1,4 @@
-Copyright (c) 2018-2022 Carnegie Mellon University
+Copyright (c) 2018-2024 Carnegie Mellon University
 
 Permission is hereby granted, free of charge, to any person obtaining a copy of this
 software and associated documentation files (the "Software"), to deal in the Software

{pyactup-2.0 → pyactup-2.2.3}/PKG-INFO

@@ -1,11 +1,10 @@
 Metadata-Version: 2.1
 Name: pyactup
-Version: 2.0
+Version: 2.2.3
 Summary: A lightweight Python implementation of a subset of the ACT-R cognitive architecture’s Declarative Memory
-Home-page: https://bitbucket.org/dfmorrison/pyactup/
+Home-page: https://dfmorrison.github.io/pyactup-documentation/
 Author: Don Morrison
 Author-email: dfm2@cmu.edu
-License: UNKNOWN
 Platform: any
 Classifier: Intended Audience :: Science/Research
 Classifier: License :: OSI Approved :: MIT License
@@ -25,20 +24,20 @@ ACT-R cognitive architecture’s Declarative Memory, suitable for
 incorporating into other Python models and applications. Its design
 is inspired by the ACT-UP cognitive modeling toolbox.
 
-There is [online documentation of PyACTUp](http://halle.psy.cmu.edu/pyactup/),
-and the [sources](https://bitbucket.org/dfmorrison/pyactup/) are on Bitbucket.
+There is [online documentation of PyACTUp](http://koalemos.psy.cmu.edu/pyactup/),
+and the [sources](https://github.com/dfmorrison/pyactup/) are on GitHub.
 
-The latest version of PyACTUp can be download and install from PyPi with  ``pip``:
+The latest version of PyACTUp can be download and installed from PyPi with pip:
 
-  .. parsed-literal:: pip install pyactup
+    pip install pyactup
 
-Use of a virtual environment for Python, such as ``venv`` or Anaconda is recommended.
+Use of a virtual environment for Python, such as venv or Anaconda is recommended.
 
 PyACTUp requires Python version 3.8 or later.
 
 PyACTUp is released under the following MIT style license:
 
-Copyright (c) 2018-2022 Carnegie Mellon University
+Copyright (c) 2018-2024 Carnegie Mellon University
 
 Permission is hereby granted, free of charge, to any person obtaining a copy of this
 software and associated documentation files (the "Software"), to deal in the Software
@@ -56,5 +55,3 @@ PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIG
 HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF
 CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE
 OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
-
-

{pyactup-2.0 → pyactup-2.2.3}/README.md

@@ -3,20 +3,20 @@ ACT-R cognitive architecture’s Declarative Memory, suitable for
 incorporating into other Python models and applications. Its design
 is inspired by the ACT-UP cognitive modeling toolbox.
 
-There is [online documentation of PyACTUp](http://halle.psy.cmu.edu/pyactup/),
-and the [sources](https://bitbucket.org/dfmorrison/pyactup/) are on Bitbucket.
+There is [online documentation of PyACTUp](http://koalemos.psy.cmu.edu/pyactup/),
+and the [sources](https://github.com/dfmorrison/pyactup/) are on GitHub.
 
-The latest version of PyACTUp can be download and install from PyPi with  ``pip``:
+The latest version of PyACTUp can be download and installed from PyPi with pip:
 
-  .. parsed-literal:: pip install pyactup
+    pip install pyactup
 
-Use of a virtual environment for Python, such as ``venv`` or Anaconda is recommended.
+Use of a virtual environment for Python, such as venv or Anaconda is recommended.
 
 PyACTUp requires Python version 3.8 or later.
 
 PyACTUp is released under the following MIT style license:
 
-Copyright (c) 2018-2022 Carnegie Mellon University
+Copyright (c) 2018-2024 Carnegie Mellon University
 
 Permission is hereby granted, free of charge, to any person obtaining a copy of this
 software and associated documentation files (the "Software"), to deal in the Software

{pyactup-2.0 → pyactup-2.2.3}/pyactup.egg-info/PKG-INFO

@@ -1,11 +1,10 @@
 Metadata-Version: 2.1
 Name: pyactup
-Version: 2.0
+Version: 2.2.3
 Summary: A lightweight Python implementation of a subset of the ACT-R cognitive architecture’s Declarative Memory
-Home-page: https://bitbucket.org/dfmorrison/pyactup/
+Home-page: https://dfmorrison.github.io/pyactup-documentation/
 Author: Don Morrison
 Author-email: dfm2@cmu.edu
-License: UNKNOWN
 Platform: any
 Classifier: Intended Audience :: Science/Research
 Classifier: License :: OSI Approved :: MIT License
@@ -25,20 +24,20 @@ ACT-R cognitive architecture’s Declarative Memory, suitable for
 incorporating into other Python models and applications. Its design
 is inspired by the ACT-UP cognitive modeling toolbox.
 
-There is [online documentation of PyACTUp](http://halle.psy.cmu.edu/pyactup/),
-and the [sources](https://bitbucket.org/dfmorrison/pyactup/) are on Bitbucket.
+There is [online documentation of PyACTUp](http://koalemos.psy.cmu.edu/pyactup/),
+and the [sources](https://github.com/dfmorrison/pyactup/) are on GitHub.
 
-The latest version of PyACTUp can be download and install from PyPi with  ``pip``:
+The latest version of PyACTUp can be download and installed from PyPi with pip:
 
-  .. parsed-literal:: pip install pyactup
+    pip install pyactup
 
-Use of a virtual environment for Python, such as ``venv`` or Anaconda is recommended.
+Use of a virtual environment for Python, such as venv or Anaconda is recommended.
 
 PyACTUp requires Python version 3.8 or later.
 
 PyACTUp is released under the following MIT style license:
 
-Copyright (c) 2018-2022 Carnegie Mellon University
+Copyright (c) 2018-2024 Carnegie Mellon University
 
 Permission is hereby granted, free of charge, to any person obtaining a copy of this
 software and associated documentation files (the "Software"), to deal in the Software
@@ -56,5 +55,3 @@ PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIG
 HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF
 CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE
 OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
-
-

{pyactup-2.0 → pyactup-2.2.3}/pyactup.egg-info/requires.txt

@@ -1,3 +1,4 @@
 numpy
-prettytable
 pylru
+prettytable
+packaging

{pyactup-2.0 → pyactup-2.2.3}/pyactup.py

@@ -1,4 +1,4 @@
-# Copyright (c) 2018-2022 Carnegie Mellon University
+# Copyright (c) 2018-2024 Carnegie Mellon University
 #
 # Permission is hereby granted, free of charge, to any person obtaining a copy of this
 # software and associated documentation files (the "Software"), to deal in the Software
@@ -37,7 +37,7 @@ may be strictly algorithmic, may interact with human subjects, or may be embedde
 sites.
 """
 
-__version__ = "2.0"
+__version__ = "2.2.3"
 
 if "dev" in __version__:
     print("PyACTUp version", __version__)
@@ -47,9 +47,9 @@ import csv
 import io
 import math
 import numpy as np
-import numpy.ma as ma
 import operator
 import random
+import re
 import sys
 
 from dataclasses import dataclass, field
@@ -61,7 +61,8 @@ from prettytable import PrettyTable
 from pylru import lrucache
 from warnings import warn
 
-__all__ = ["Memory"]
+__all__ = ["__version__", "Memory"]
+
 
 DEFAULT_NOISE = 0.25
 DEFAULT_DECAY = 0.5
@@ -91,7 +92,7 @@ class Memory(dict):
     saved to and restored from persistent storage, so long as any similarity functions it
     contains are defined at the top level of a module using ``def``. Note that attempts to
     pickle a Memory object containing a similarity function defined as a lambda function,
-    or as an inner function, will cause a :exc:`Exception` to be raised. And note further
+    or as an inner function, will cause an :exc:`Exception` to be raised. And note further
     that pickle only includes the function name in the pickled object, not its definition.
     Also, if the contents of a ``Memory`` object are sufficiently complicated it may be
     necessary to raise Python's recursion limit with
@@ -99,18 +100,18 @@ class Memory(dict):
 
     A common use case for PyACTUp involves all of the chunks in a ``Memory`` having the
     same attributes, and some of those attributes are always used, by matching exactly,
-    not partially, some of those attributes. The ``index``keyword argument declares that
+    not partially, some of those attributes. The ``index`` keyword argument declares that
     such a set of attributes is present, and can result in significant performance
     improvements for models with a *very* large number of chunks. The value of this
     keyword argument should be a list of attribute names. As a convenience, if none of the
-    attribute names contains commas or spaces, a string maybe used instead of a list, the
+    attribute names contain commas or spaces, a string maybe used instead of a list, the
     attribute names being separated by spaces or commas; either spaces or commas must be
     used, not a mixture. For example, both ``index="decision utility"`` and
     ``index="decision,utiliy"`` are equivalent to ``index=["decision", "utility"]``. A
     list of he attributes in a :class:`Memory`'s *index* can be retrieved with the
     :attr:`index` property. If the ``Memory`` is empty, containing no chunks, the *index*
     can be modified by setting that property, but otherwise the *index* cannot be changed
-    after the ``Memory`` was created. `All chunks in a ``Memory`` with an *index* must
+    after the ``Memory`` was created. All chunks in a ``Memory`` with an *index* must
     contain values for all the attributes listed in the *index*; if any are omitted in the
     argument to :meth:`learn` they will be automatically added with a value of ``None``.
 
@@ -134,12 +135,14 @@ class Memory(dict):
         self._fixed_noise_time = None
         self._temperature_param = 1 # will be reset below, but is needed for noise assignment
         self._noise = None
+        self._noise_distribution = None
         self._decay = None
         self._optimized_learning = None
         self._use_actr_similarity = False
         self._minimum_similarity = 0
         self._maximum_similarity = 1
         self._similarities = defaultdict(Similarity)
+        self._extra_activation = None
         self.noise = noise
         self.decay = decay
         if temperature is None and not self._validate_temperature(None, noise):
@@ -168,11 +171,19 @@ class Memory(dict):
         """Deletes this :class:`Memory`'s chunks and resets its time to zero.
         If *preserve_prepopulated* is ``False`` it deletes all chunks; if it is ``True``
         it deletes all chunk references later than time zero, completely deleting those
-        chunks that were created at a time other than zero. If *index* is supplied it
+        chunks that were created at a time greater than zero. If *index* is supplied it
         sets the :class:`Memory`'s index to that value.
         """
+        if preserve_prepopulated and self._optimized_learning is not None:
+            preserve_prepopulated = False
+            warn("The preserve_prepopulated argument to reset() cannot be used when "
+                 "optimized_learning is on, and is being ignored")
         if preserve_prepopulated:
-            preserved = {k: v for k, v in self.items() if v._creation == 0}
+            preserved = {k: c for k, c in self.items() if c._creation <= 0}
+            for c in preserved.values():
+                c._references = np.array([r for r in c._references[:c._reference_count]
+                                          if r <= 0])
+                c._reference_count = len(c._references)
         self.clear()
         self._slot_name_index.clear()
         self._index.clear()
@@ -182,11 +193,12 @@ class Memory(dict):
         if index is not None:
             self.index = index
         if preserve_prepopulated:
-            for k, v in preserved.items():
-                v._references = np.empty(1, dtype=np.int32) if self._optimized_learning else np.array([0])
-                v._reference_count = 1
-                self[k] = v
-                self._slot_name_index[frozenset(v.keys())].append(v)
+            for k, c in preserved.items():
+                self[k] = c
+                self._slot_name_index[frozenset(c.keys())].append(c)
+                if  self._indexed_attributes:
+                    self._index[Memory._signature(c, "learn", self._indexed_attributes)
+                                ].append(c)
 
     @property
     @contextmanager
@@ -201,8 +213,8 @@ class Memory(dict):
             practical.
 
         >>> m = Memory()
-        >>> m.learn(color="red")
-        True
+        >>> m.learn({"color": "red"})
+        <Chunk 0000 {'color': 'red'} 1>
         >>> m.advance()
         1
         >>> m.activation_history = []
@@ -266,13 +278,13 @@ class Memory(dict):
 
     @property
     def index(self):
-        """A list of the attribute names in this ``Memory``'s index.
+        """A tuple of the attribute names in this ``Memory``'s index.
         If this :class:`Memory` is empty, containing no chunks, this can also be set,
         using the same syntax as in the :class:`Memory` constructor. However, if
         this ``Memory`` contains chunks an attempt to set the ``index`` will raise
         a :exc:`RuntimeError`.
         """
-        return sorted(self._indexed_attributes)
+        return tuple(sorted(self._indexed_attributes))
 
     @index.setter
     def index(self, value):
@@ -284,18 +296,33 @@ class Memory(dict):
         assert not self._index and not self._slot_name_index
         self._indexed_attributes = indexed_attributes
 
+    @staticmethod
+    def is_real(x, name, non_negative=True, positive=False, none_allowed=True):
+        if none_allowed and x is None:
+            return
+        if (x is True or x is False
+            or (positive and x <= 0)
+            or (non_negative and x < 0)):
+            if positive:
+                mod = " positive"
+            elif non_negative:
+                mod = " non-negative"
+            else:
+                mod = ""
+            raise ValueError(f"The {name}, {x}, must be{' None or' if none_allowed else ''} a{mod} real number")
+
     @property
     def time(self):
         """This ``Memory``'s current time.
         Time in PyACTUp is a dimensionless quantity, the interpretation of which is at the
-        discretion of the modeler.
+        discretion of the modeler. Attempting to set the ``time`` to anything but a real
+        number raises a :exc:`ValueError`.
         """
         return self._time
 
     @time.setter
     def time(self, value):
-        if not isinstance(value, Real):
-            raise ValueError(f"Time {value} is not a real number")
+        Memory.is_real(value, "time", False, False, False)
         self._time = value
         if value != self._time:
             self._clear_fixed_noise()
@@ -308,9 +335,10 @@ class Memory(dict):
             While *amount* can be negative, this is rarely appropriate. Backward time can
             easily result in biologically implausible models, and attempts to perform
             retrievals or similar operations at times preceding those at which relevant
-            chunks were created will result in infinite or complex valued base-level
-            activations and raise an :exc:`Exception`.
+            chunks were created or reinforced will result in infinite or complex valued
+            base-level activations and raise an :exc:`Exception`.
         """
+        Memory.is_real(amount, "time increment", False)
         if amount is not None:
             self.time += amount
         return self._time
@@ -328,20 +356,13 @@ class Memory(dict):
             chunks created or reinforced in the future results in failures of attempts to
             retrieve them.
 
-        >>> m = Memory(temperature=1, noise=0)
-        >>> m.learn(size=1)
-        Traceback (most recent call last):
-          File "<stdin>", line 1, in <module>
-        TypeError: learn() got an unexpected keyword argument 'size'
-        >>>
-        >>>
         >>> m = Memory(temperature=1, noise=0)
         >>> m.learn({"size": 1})
-        True
+        <Chunk 0000 {'size': 1} 1>
         >>> m.advance(10)
         10
         >>> m.learn({"size": 10})
-        True
+        <Chunk 0001 {'size': 10} 1>
         >>> m.advance()
         11
         >>> m.blend("size")
@@ -377,8 +398,9 @@ class Memory(dict):
 
     @noise.setter
     def noise(self, value):
-        if value < 0:
-            raise ValueError(f"The noise, {value}, must not be negative")
+        Memory.is_real(value, "noise")
+        if value is None:
+            value = 0
         if self._temperature_param is None:
             t = Memory._validate_temperature(None, value)
             if not t:
@@ -387,38 +409,65 @@ class Memory(dict):
             else:
                 self._temperature = t
         if value != self._noise:
-            self._noise = value
+            self._noise = float(value)
             self._clear_fixed_noise()
 
+    @property
+    def noise_distribution(self):
+        """ Provide an alternative distribution from which noise is sampled.
+        If ``None`` the default logistic distribution is used. Otherwise the value of this
+        attribute should be a callable that takes no arguments and returns a real number.
+        It will be called once each time activation noise is required and the value,
+        scaled as usual by the :attr:`noise` parameter, will be used as the activation
+        noise. A :exc:`ValueError` is raised if an attempt is made to set this attribute
+        to anything other than a callable or ``None``.
+
+        .. warning::
+            It is rarely appropriate to use ``noise_distribution``. The default logistic
+            distribution is almost always a more appropriate choice. The ability to change
+            the distribution is provided only for esoteric purposes, and care should be
+            exercised lest biologically implausible models result.
+        """
+        return self._noise_distribution
+
+    @noise_distribution.setter
+    def noise_distribution(self, value):
+        if value is None or callable(value):
+            self._noise_distribution = value
+        else:
+            raise ValueError(f"The provided noise_distribution, {value}, is neither Callable nor None")
+
     @property
     def decay(self):
         """Controls the rate at which activation for chunks in memory decay with the passage of time.
         Time in PyACTUp is dimensionless.
         The :attr:`decay` is typically between about 0.1 and 2.0.
-        The default value is 0.5. If zero memory does not decay.
+        The default value is 0.5. If set to zero then memory does not decay.
         If set to ``None`` no base-level activation is computed or used; note that this is
         significantly different than setting it to zero which causes base-level activation
         to still be computed and used, but with no decay.
         Attempting to set it to a negative number raises a :exc:`ValueError`.
-        It must be less one 1 if this memory's :attr:`optimized_learning` parameter is set.
+        If this memory's :attr:`optimized_learning` parameter is true, then :attr:`decay`
+        must be less than one.
         """
         return self._decay
 
     @decay.setter
     def decay(self, value):
+        Memory.is_real(value, "decay")
         if value is not None:
-            if value < 0:
-                raise ValueError(f"The decay, {value}, must not be negative")
             if value >= 1 and self._optimized_learning is not None:
                 raise ValueError(f"The decay, {value}, must be less than one if optimized_learning is used")
-        self._decay = value
+            self._decay = float(value)
+        else:
+            self._decay = None
 
     @property
     def temperature(self):
         """The temperature parameter used for blending values.
         If ``None``, the default, the square root of 2 times the value of
         :attr:`noise` will be used. If the temperature is too close to zero, which
-        can also happen if it is ``None`` and the :attr:`noise` is too low, or negative, a
+        can also happen if it is ``None`` and the :attr:`noise` is too low, a
         :exc:`ValueError` is raised.
         """
         return self._temperature_param
@@ -430,6 +479,7 @@ class Memory(dict):
         if value is None or value is False:
             value = None
         else:
+            Memory.is_real(value, "temperature", True, True)
             value = float(value)
         t = Memory._validate_temperature(value, self._noise)
         if not t:
@@ -469,7 +519,8 @@ class Memory(dict):
 
     @threshold.setter
     def threshold(self, value):
-        if value is None or value is False:
+        Memory.is_real(value, "threshold", False)
+        if value is None:
             self._threshold = None
         else:
             self._threshold = float(value)
@@ -484,25 +535,26 @@ class Memory(dict):
         from the activation.
 
         Attributes for which no similarity function has been defined are always compared
-        exactly, and chunks not matching on this attributes are not included at all in the
-        corresponding partial retrievals or blending operations.
+        exactly, and chunks not matching on these attributes are not included at all in
+        the corresponding partial retrievals or blending operations.
 
         While for the likelihoods of retrieval the values of :attr:`time` are normally
         scale free, not depending upon the magnitudes of :attr:`time`, but rather the
         ratios of various times, the :attr:`mismatch` is sensitive to the actual
         magnitude. Suitable care should be exercised when adjusting it.
 
-        Attempting to set this parameter to a value other than ``None`` or a real number
-        raises a :exc:`ValueError`.
+        Attempting to set this parameter to a value other than ``None`` or a non-negative
+        real number raises a :exc:`ValueError`.
         """
         return self._mismatch
 
     @mismatch.setter
     def mismatch(self, value):
-        if value is None or value is False:
+        if value is False:
+            value = None
+        Memory.is_real(value, "mismatch")
+        if value is None:
             self._mismatch = None
-        elif value < 0:
-            raise ValueError(f"The mismatch penalty, {value}, must not be negative")
         else:
             self._mismatch = float(value)
 
@@ -585,6 +637,49 @@ class Memory(dict):
             self._maximum_similarity =  1
         self._use_actr_similarity = bool(value)
 
+    @property
+    def extra_activation(self):
+        """A tuple of callables that are called to add additional terms to the activations of chunks.
+
+        For advanced purposes it is sometimes useful to add additional terms to chunks'
+        activation computations, for example for implementing a constant base level
+        offset for one or more chunks, or for implementing spreading activation.
+        This property can be set to None (or another falsey value) meaning no such
+        additional activation is added to any chunks; this is the default. Otherwise it
+        should be set to an iterable of callables, each of which should take a single
+        argument, a chunk, and returns a real number. For convenience it may also be set
+        to a single callable, which is equivalent to setting it to a tuple of length one
+        containing that callable.
+
+        Attempting to set a value that is not a callable, an iterable of callables or
+        falsey raises an :exc:`RuntimeError` will be raised when it is used in computing
+        activations.
+
+        .. warning::
+            The use of extra_activation requires care lest biologically implausible models
+            result. In addition to the ease with which artificial adjustments to the
+            activations can be made with this method, the appropriate magnitudes of
+            activation values depend upon the units in which time is measured.
+        """
+        return self._extra_activation
+
+    @extra_activation.setter
+    def extra_activation(self, value):
+        if not value:
+            self._extra_activation = None
+        elif callable(value):
+            self._extra_activation = (value,)
+        else:
+            try:
+                value = tuple(value)
+                for v in value:
+                    if not callable(v):
+                        raise ValueError()
+            except:
+                raise ValueError(
+                    f"The extra_activation must be either a callable or an iterable of callables ({value})")
+            self._extra_activation = value
+
     @property
     def activation_history(self):
         """A :class:`MutableSequence`, typically a :class:`list`, into which details of the computations underlying PyACTUp operation are appended.
@@ -595,7 +690,7 @@ class Memory(dict):
         As a convenience setting :attr:`activation_history` to ``True`` assigns a fresh,
         empty list as its value.
 
-        If PyACTUp is being using in a loop, the details collected will likely become
+        If PyACTUp is being used in a loop, the details collected will likely become
         voluminous. It is usually best to clear them frequently, such as on each
         iteration.
 
@@ -604,18 +699,19 @@ class Memory(dict):
 
         >>> m = Memory()
         >>> m.learn({"color": "red", "size": 3})
-        True
+        <Chunk 0005 {'color': 'red', 'size': 3} 1>
         >>> m.advance()
         1
         >>> m.learn({"color": "red", "size": 5})
-        True
+        <Chunk 0006 {'color': 'red', 'size': 5} 1>
         >>> m.advance()
         2
         >>> m.activation_history = []
         >>> m.blend("size", {"color": "red"})
         4.810539051819914
         >>> pprint(m.activation_history, sort_dicts=False)
-        [{'name': '0005',
+        [{'time': 2,
+          'name': '0005',
           'creation_time': 0,
           'attributes': (('color', 'red'), ('size', 3)),
           'reference_count': 1,
@@ -624,7 +720,8 @@ class Memory(dict):
           'activation_noise': -0.032318983984613185,
           'activation': -0.3788925742645858,
           'retrieval_probability': 0.09473047409004302},
-         {'name': '0006',
+         {'time': 2,
+          'name': '0006',
           'creation_time': 1,
           'attributes': (('color', 'red'), ('size', 5)),
           'reference_count': 1,
@@ -633,7 +730,6 @@ class Memory(dict):
           'activation_noise': 0.4191470689622754,
           'activation': 0.4191470689622754,
           'retrieval_probability': 0.905269525909957}]
-
         """
         return self._activation_history
 
@@ -679,7 +775,7 @@ class Memory(dict):
                      "chunk contents": dict(k).__repr__()[1:-1],
                      "chunk created at": c._creation,
                      "chunk reference count": c._reference_count,
-                     "chunk references": Memory._elide_long_list(c._references)}
+                     "chunk references": Memory._elide_long_list(c._references[:c._reference_count])}
                     for k, c in self.items()]
             if pretty:
                 tab = PrettyTable()
@@ -716,10 +812,10 @@ class Memory(dict):
         Note that after learning one or more chunks, before :meth:`retrieve`,
         :meth:`blend` or similar methods can be called :meth:`advance` must be called,
         lest the chunk(s) learned have infinite activation.
-        Because it is so common to call :meth:`advance` immediately after :meth"`learn`
+        Because it is so common to call :meth:`advance` immediately after :meth:`learn`
         as a convenience if *advance* is not None just before :meth:`learn` returns
-        :meth:`advance` with *advance* as its argument, without an argument if *advance*
-        is ``True``.
+        it calls :meth:`advance` with *advance* as its argument, or without any argument
+        if *advance* is ``True``.
 
         Raises a :exc:`TypeError` if an attempt is made to learn an attribute value that
         is not :class:`Hashable`. Raises a :exc:`ValueError` if no *slots* are provided,
@@ -727,16 +823,16 @@ class Memory(dict):
 
         >>> m = Memory()
         >>> m.learn({"color":"red", "size":4})
-        True
+        <Chunk 0000 {'color': 'red', 'size': 4} 1>
         >>> m.advance()
         1
         >>> m.learn({"color":"blue", "size":4}, advance=1)
+        <Chunk 0001 {'color': 'blue', 'size': 4} 1>
+        >>> m.learn({"color":"red", "size":4}) is None
         True
-        >>> m.learn({"color":"red", "size":4})
-        False
         >>> m.advance()
         3
-        >>> m.retrieve({"color": "red"})
+        >>>
         <Chunk 0000 {'color': 'red', 'size': 4} 2>
         """
         slots = self._ensure_slots(slots, True)
@@ -767,10 +863,7 @@ class Memory(dict):
         if thing is None:
             return []
         if isinstance(thing, str):
-            if "," in thing:
-                names = [s.strip() for s in thing.split(",")]
-            else:
-                names = thing.split()
+            names = re.split(r"\s*(?:,|\s)\s*", thing.strip())
         else:
             names = list(thing)
         s = set()
@@ -779,7 +872,7 @@ class Memory(dict):
             if n in s:
                 raise ValueError(f"Duplicate attribute name {n}")
             s.add(n)
-        return names
+        return tuple(names)
 
     def _ensure_slots(self, slots, learn=False):
         slots = dict(slots)
@@ -862,7 +955,7 @@ class Memory(dict):
             slot_names = set(slot_names)
             slot_names.add(extra)
         partial_slots = []
-        if partial and self._mismatch:
+        if partial and self._mismatch is not None:
             exact_slots =[]
             for n, v in conditions.items():
                 if s := self._similarities.get(n):
@@ -906,9 +999,9 @@ class Memory(dict):
                                   - self._decay * np.log(ages))
                     else:
                         result = np.empty(nchunks)
-                        counts = ma.masked_all(nchunks)
-                        ages = ma.masked_all(nchunks)
-                        middles = ma.masked_all(nchunks)
+                        counts = np.ma.masked_all(nchunks)
+                        ages = np.ma.masked_all(nchunks)
+                        middles = np.ma.masked_all(nchunks)
                         for c, i in zip(chunks, count()):
                             if c._reference_count <= self._optimized_learning:
                                 result[i] = np.sum((self._time - c._references[0:c._reference_count])
@@ -935,14 +1028,20 @@ class Memory(dict):
                 if self._activation_history is not None:
                     initial_history_length = len(self._activation_history)
                     for c, r in zip(chunks, result):
-                        self._activation_history.append({"name": c._name,
+                        self._activation_history.append({"time": self.time,
+                                                         "name": c._name,
                                                          "creation_time": c._creation,
                                                          "attributes": tuple(c.items()),
                                                          "reference_count": c.reference_count,
                                                          "references": c.references,
                                                          "base_level_activation": r})
                 if self._noise:
-                    noise = self._rng.logistic(scale=self._noise, size=nchunks)
+                    if self._noise_distribution is not None:
+                        noise = self._noise * np.array([self._noise_distribution()
+                                                        for i in range(nchunks)],
+                                                       dtype=np.float64)
+                    else:
+                        noise = self._rng.logistic(scale=self._noise, size=nchunks)
                     if self._fixed_noise is not None:
                         if self._fixed_noise_time != self._time:
                             self._clear_fixed_noise()
@@ -962,11 +1061,28 @@ class Memory(dict):
                     penalties = np.empty((nchunks, len(partial_slots)))
                     for c, row in zip(chunks, count()):
                         penalties[row] = [s._similarity(c[n], v) for n, v, s in partial_slots]
+                    if self._activation_history is not None:
+                        offset = 0 if self.use_actr_similarity else 1
+                        for i, pens in zip(count(initial_history_length), penalties):
+                            similarities = {ps[0]: p + offset
+                                            for ps, p in zip(partial_slots, pens)}
+                            self._activation_history[i]["similarities"] = similarities
                     penalties = np.sum(penalties, 1) * self._mismatch
                     result += penalties
                     if self._activation_history is not None:
                         for i, p in zip(count(initial_history_length), penalties):
                             self._activation_history[i]["mismatch"] = p
+                if self._extra_activation is not None:
+                    extra_activations = np.empty((nchunks))
+                    try:
+                        for c, row in zip(chunks, count()):
+                            extra_activations[row] = sum(f(c) for f in self._extra_activation)
+                    except:
+                        raise RuntimeError("Error attempting to compute extra activation values")
+                    result += extra_activations
+                    if self._activation_history is not None:
+                        for i, ea in zip(count(initial_history_length), extra_activations):
+                            self._activation_history[i]["extra_activation"] = ea
                 if self._activation_history is not None:
                     for i, r in zip(count(initial_history_length), result):
                         self._activation_history[i]["activation"] = r
@@ -974,9 +1090,9 @@ class Memory(dict):
                             self._activation_history[i]["meets_threshold"] = (r >= self._threshold)
                 raw_activations_count = len(result)
                 if self._threshold is not None:
-                    m = ma.masked_less(result, self._threshold)
-                    if ma.is_masked(m):
-                        chunks = ma.array(chunks, mask=ma.getmask(m)).compressed()
+                    m = np.ma.masked_less(result, self._threshold)
+                    if np.ma.is_masked(m):
+                        chunks = np.ma.array(chunks, mask=np.ma.getmask(m)).compressed()
                         result = m.compressed()
             except FloatingPointError as e:
                 raise RuntimeError(f"Error when computing activations, perhaps a chunk's "
@@ -991,7 +1107,7 @@ class Memory(dict):
         If there is no such matching chunk returns ``None``.
         Normally only retrieves chunks exactly matching the *slots*; if *partial* is
         ``True`` it also retrieves those only approximately matching, using similarity
-        (see :meth:`similarity`) and :attr:`mismatch` to determine closeness
+        (see :meth:`similarity`) and the value of :attr:`mismatch` to determine closeness
         of match.
 
         If *rehearse* is supplied and true it also reinforces this chunk at the current
@@ -1005,11 +1121,11 @@ class Memory(dict):
 
         >>> m = Memory()
         >>> m.learn({"widget":"thromdibulator", "color":"red", "size":2})
-        True
+        <Chunk 0000 {'widget': 'thromdibulator', 'color': 'red', 'size': 2} 1>
         >>> m.advance()
         1
         >>> m.learn({"widget":"snackleizer", "color":"blue", "size":1})
-        True
+        <Chunk 0001 {'widget': 'snackleizer', 'color': 'blue', 'size': 1} 1>
         >>> m.advance()
         2
         >>> m.retrieve({"color":"blue"})["widget"]
@@ -1034,60 +1150,123 @@ class Memory(dict):
             self._cite(result)
         return result
 
-    def _blend(self, outcome_attribute, slots):
+    def _blend(self, outcome_attribute, slots, instance_salience, feature_salience):
         Memory._ensure_slot_name(outcome_attribute)
         activations, chunks, raw = self._activations(self._ensure_slots(slots),
                                                      extra=outcome_attribute)
         if chunks is None:
-            return None, None
+            return None, None, None, None
         with np.errstate(divide="raise", over="raise", under="ignore", invalid="raise"):
             wp = np.exp(activations / self._temperature)
             wp /= np.sum(wp)
-            if self._activation_history is not None:
-                h = self._activation_history
-                # this i malarkey is in case one or more candidates didn't clear the threshold
-                i = len(h) - raw
-                for p, c in zip(wp, chunks):
-                    while h[i]["name"] != c._name:
-                        i += 1
-                        assert i < len(h)
-                    h[i]["retrieval_probability"] = p
-        return wp, chunks
-
-    def blend(self, outcome_attribute, slots={}):
+        if self._activation_history is not None:
+            h = self._activation_history
+            # this i malarkey is in case one or more candidates didn't clear the threshold
+            i = len(h) - raw
+            for p, c in zip(wp, chunks):
+                while h[i]["name"] != c._name:
+                    i += 1
+                    assert i < len(h)
+                h[i]["retrieval_probability"] = p
+        def normalize(v):
+            v = np.array(v)
+            norm = np.linalg.norm(v)
+            return v / norm if norm > 0 else v
+        isal = None
+        if instance_salience:
+            vals = np.array([c[outcome_attribute] for c in chunks])
+            isal = normalize(wp * (vals - np.sum(wp * vals)) / self._temperature)
+        fsal = None
+        if feature_salience and self._mismatch is not None:
+            pslots = [a for a in slots if self._similarities.get(a)]
+            if self._mismatch != 0:
+                def slot_salience(attr, attrval):
+                    deriv = self._similarities[attr]._derivative
+                    weight = self._similarities[attr]._weight
+                    if not deriv:
+                        raise RuntimeError(f"No derivative defined for {attr} similarities")
+                    dvals = np.array([weight * deriv(c[attr], attrval) for c in chunks])
+                    dsum = np.sum(wp * dvals)
+                    return np.sum(wp * (dvals - dsum) * np.array([c[outcome_attribute]
+                                                                  for c in chunks]))
+                # Doing the division up front could make for loss of precision
+                # but this is unlikely to matter in any realistic use case.
+                coef = self._mismatch / self._temperature
+                fsal = [coef * slot_salience(a, slots[a]) for a in pslots]
+            else:
+                fsal = [0] * len(pslots)
+            fsal = dict(zip(pslots, normalize(fsal)))
+        return wp, chunks, isal, fsal
+
+    def blend(self, outcome_attribute, slots={}, instance_salience=False, feature_salience=False):
         """Returns a blended value for the given attribute of those chunks matching *slots*, and which contain *outcome_attribute*, and have activations greater than or equal to this Memory's threshold, if any.
         Returns ``None`` if there are no matching chunks that contain
         *outcome_attribute*. If any matching chunk has a value of *outcome_attribute*
         that is not a real number an :exc:`Exception` is raised.
 
+        If neither ``instance_salience`` nor ``feature_salience`` is true, the sole return
+        value is the blended value; otherwise a tuple of three values is returned. The
+        first the blended value. If ``instance_salience`` is true the second is a dict
+        mapping a descriptions of the slot values of each of the matched chunks that
+        contributed to the blended value to the normalized instance salience value, a real
+        number between -1 and 1, inclusive; otherwise the second value is ``None``. The
+        slot representation of slot values in this dict is a tuple of tuples, the inner
+        tuples being the slot name and value.
+
+        If ``feature_salience`` is true the third value is a dict mapping slot names,
+        corresponding to those slots that were partially matched in this blending
+        operation, to their normalized feature salience values, a real number between -1
+        and 1, inclusive; otherwise the third value is ``None``. To compute feature
+        salience a derivative of the similarity function must have been specified for
+        every partially match slot using :meth:`similarity`; if any are missing a
+        :exc:`RuntimeError`` is raised.
+
         >>> m = Memory()
         >>> m.learn({"color":"red", "size":2})
-        True
+        <Chunk 0000 {'color': 'red', 'size': 2} 1>
         >>> m.advance()
         1
         >>> m.learn({"color":"blue", "size":30})
-        True
+        <Chunk 0001 {'color': 'blue', 'size': 30} 1>
         >>> m.advance()
         2
         >>> m.learn({"color":"red", "size":1})
-        True
+        <Chunk 0002 {'color': 'red', 'size': 1} 1>
         >>> m.advance()
         3
         >>> m.blend("size", {"color":"red"})
-        1.221272238515685
+        1.3660254037844388
+        >>> m.blend("size", {"color":"red"}, instance_salience=True)
+        (1.3660254037844388,
+         {(('color', 'red'), ('size', 2)): 0.7071067811865472,
+          (('color', 'red'), ('size', 1)): -0.7071067811865478},
+         None)
+
         """
-        probs, chunks = self._blend(outcome_attribute, slots)
-        if chunks is None:
-            return None
-        with np.errstate(divide="raise", over="raise", under="ignore", invalid="raise"):
-            try:
-                return np.average(np.array([c[outcome_attribute] for c in chunks],
-                                           dtype=np.float64),
-                                  weights=probs)
-            except Exception as e:
-                raise RuntimeError(f"Error computing blended value, is perhaps the value "
-                                   f"of the {outcome_attribute} slotis  not numeric in "
-                                   f"one of the matching chunks? ({e})")
+        probs, chunks, isal, fsal = self._blend(outcome_attribute, slots,
+                                                instance_salience, feature_salience)
+        if chunks is not None:
+            with np.errstate(divide="raise", over="raise", under="ignore", invalid="raise"):
+                try:
+                    result = np.average(np.array([c[outcome_attribute] for c in chunks],
+                                                 dtype=np.float64),
+                                        weights=probs)
+                except Exception as e:
+                    raise RuntimeError(f"Error computing blended value, is perhaps the value "
+                                       f"of the {outcome_attribute} slotis not numeric in "
+                                       f"one of the matching chunks? ({e})")
+        else:
+            result = None
+        if not instance_salience and not feature_salience:
+            return result
+        if instance_salience:
+            if isal is not None:
+                isal = {tuple(c.items()): s for c, s in zip(chunks, isal)}
+            else:
+                isal = {}
+        if feature_salience and fsal is None:
+            fsal = {}
+        return result, isal, fsal
 
     def best_blend(self, outcome_attribute, iterable, select_attribute=None, minimize=False):
         """Returns two values (as a 2-tuple), describing the extreme blended value of the *outcome_attribute* over the values provided by *iterable*.
@@ -1101,7 +1280,8 @@ class Memory(dict):
         none of the values from *iterable* result in blended values of *outcome_attribute*
         then both return values are ``None``.
 
-        This operation is particularly useful for building Instance Based Learning models.
+        This operation is particularly useful for building `Instance Based Learning models
+        <https://www.sciencedirect.com/science/article/abs/pii/S0364021303000314>`_.
 
         For the common case where *iterable* iterates over only the values of a single
         slot the *select_attribute* parameter may be used to simplify the iteration. If
@@ -1112,25 +1292,25 @@ class Memory(dict):
 
         >>> m = Memory()
         >>> m.learn({"color":"red", "utility":1})
-        True
+        <Chunk 0000 {'color': 'red', 'utility': 1} 1>
         >>> m.advance()
         1
         >>> m.learn({"color":"blue", "utility":2})
-        True
+        <Chunk 0001 {'color': 'blue', 'utility': 2} 1>
         >>> m.advance()
         2
         >>> m.learn({"color":"red", "utility":1.8})
-        True
+        <Chunk 0002 {'color': 'red', 'utility': 1.8} 1>
         >>> m.advance()
         3
         >>> m.learn({"color":"blue", "utility":0.9})
-        True
+        <Chunk 0003 {'color': 'blue', 'utility': 0.9} 1>
         >>> m.advance()
         4
         >>> m.best_blend("utility", ({"color": c} for c in ("red", "blue")))
         ({'color': 'blue'}, 1.5149259914576285)
         >>> m.learn({"color":"blue", "utility":-1})
-        True
+        <Chunk 0004 {'color': 'blue', 'utility': -1} 1>
         >>> m.advance()
         5
         >>> m.best_blend("utility", ("red", "blue"), "color")
@@ -1170,25 +1350,24 @@ class Memory(dict):
 
         >>> m = Memory()
         >>> m.learn({"kind": "tilset", "age": "old"})
-        True
+        <Chunk 0000 {'kind': 'tilset', 'age': 'old'} 1>
         >>> m.advance()
         1
         >>> m.learn({"kind": "limburger", "age": "old"})
-        True
+        <Chunk 0001 {'kind': 'limburger', 'age': 'old'} 1>
         >>> m.advance()
         2
         >>> m.learn({"kind": "tilset", "age": "old"})
-        False
         >>> m.advance()
         3
         >>> m.learn({"kind": "tilset", "age": "new"})
-        True
+        <Chunk 0002 {'kind': 'tilset', 'age': 'new'} 1>
         >>> m.advance()
         4
         >>> m.discrete_blend("kind", {"age": "old"})
         ('tilset', {'tilset': 0.9540373563209859, 'limburger': 0.04596264367901423})
         """
-        probs, chunks = self._blend(outcome_attribute, slots)
+        probs, chunks, isal, fsal = self._blend(outcome_attribute, slots, False, False)
         if not chunks:
             return None, None
         candidates = defaultdict(list)
@@ -1207,7 +1386,7 @@ class Memory(dict):
         return (random.choice(best),
                 dict(sorted(candidates.items(), key=lambda x: x[1], reverse=True)))
 
-    def similarity(self, attributes, function=None, weight=None):
+    def similarity(self, attributes, function=None, weight=None, derivative=None):
         """Assigns a similarity function and/or corresponding weight to be used when comparing attribute values with the given *attributes*.
         The *attributes* should be an :class:`Iterable` of strings, attribute names.
         The *function* should take two arguments, and return a real number between 0 and 1,
@@ -1220,15 +1399,26 @@ class Memory(dict):
         will, in most cases, be meaningless if they are.
         If ``True`` is supplied as the *function* a default similarity function is used
         that returns one if its two arguments are ``==`` and zero otherwise.
-        If only one of *function* or *weight* is supplied, it is changed without
-        changing the other; the initial defaults are ``Treu`` for *function* and ``1``
-        for *weight*.
-        If neither *function* nor *weight* is supplied both are removed, and these
-        *attributes* will no longer have an associated similarity computation, and will
-        be matched only exactly.
+
+        If *derivative* is supplied it should be a callable, the first partial derivative
+        of the similarity function with respect to its first argument, and will be used
+        if the feature saliences are requested in :meth:`blend`. The *derivative* must
+        be defined for all values that may occur for the relevant slots. It is common
+        that the strict mathematical derivative may not exists for one or a small number
+        of possibly values, most commonly when the similarly involves the absolute value
+        of the difference between the two arguments of the similarly function. Even in
+        these cases the argument to :meth:`similarity` should return a value; often zero
+        is a good choice in these cases.
+
+        If only one or two of *function*, *weight* and *derivatve* are supplied, they
+        changed without changing those not supplied; the initial defaults are ``True`` for
+        *function*, ``1`` for *weight*, and ``None`` for *derivative*. If none
+        of*function*, *weight* nor *derivative* are supplied all are removed, and these
+        *attributes* will no longer have an associated similarity computation, and will be
+        matched only exactly.
 
         As a convenience, if none of the attribute names contains commas or spaces, a
-        string maybe used instead of a list as the first argument to ``similarity``, the
+        string may be used instead of a list as the first argument to ``similarity``, the
         attribute names being separated by spaces or commas; either spaces or commas must
         be used, not a mixture. For example, both ``"decision utility"`` and
         ``"decision,utiliy"`` are equivalent to ``["decision", "utility"]``.
@@ -1247,14 +1437,15 @@ class Memory(dict):
         ...         return f(y, x)
         ...     return 1 - (y - x) / y
         >>> similarity(["length", "width"], f, weight=2)
-
         """
         if function is not None and not (callable(function) or function is True):
             raise ValueError(f"Function {function} is neither callable nor True")
+        if derivative is not None and not callable(derivative):
+            raise(ValueError(f"Derivative {derivative} is not callable"))
         if weight is not None and weight <= 0:
             raise ValueError(f"Similarity weight, {weight}, is not a positive number")
         for a in Memory._ensure_slot_names(attributes):
-            if function is None and weight is None:
+            if function is None and weight is None and derivative is None:
                 if a in self._similarities:
                     del self._similarities[a]
             else:
@@ -1262,12 +1453,19 @@ class Memory(dict):
                 sim._memory = self
                 if function is not None and function != sim._function:
                     sim._function = function
+                if derivative is not None and function != sim._derivative:
+                    sim._derivative = derivative
                 if weight is not None and weight != sim._weight:
                     sim._weight = weight
                 sim._cache.clear()
 
 
 class Chunk(dict):
+    """A learned item.
+
+    A chunk acts much like a dictionary, and its slots can be retrieved with the usual
+    `[]` notation, or with `.get()`.
+    """
 
     __slots__ = ["_name", "_memory", "_creation", "_references", "_reference_count" ]
 
@@ -1289,6 +1487,11 @@ class Chunk(dict):
     def __str__(self):
         return f"Chunk-{self._name}"
 
+    @property
+    def memory(self):
+        """The :class:`Memory` object that contains this chunk."""
+        return self._memory
+
     @property
     def reference_count(self):
         """A non-negative integer, the number of times that this :class:`Chunk` has been reinforced.
@@ -1297,26 +1500,28 @@ class Chunk(dict):
 
     @property
     def references(self):
-        """A list of real numbers, the times at which that this :class:`Chunk` has been reinforced.
+        """A tuple of real numbers, the times at which that this :class:`Chunk` has been reinforced.
         If :attr:`optimized_learning` is being used this may be just the most recent
         reinforcements, or an empty list, depending upon the value of
-        :attr:`optimized_learning`
+        :attr:`optimized_learning`.
         """
-        return list(self._references[:(self._reference_count
-                                       if self._memory._optimized_learning is None
-                                       else min(self._reference_count,
-                                                self._memory._optimized_learning))])
+        return tuple(self._references[:(self._reference_count
+                                        if self._memory._optimized_learning is None
+                                        else min(self._reference_count,
+                                                 self._memory._optimized_learning))])
 
 
 @dataclass
 class Similarity:
     _memory: Memory = None
     _function: callable = True
+    _derivative: callable = None
     _weight: float = 1.0
     _cache: lrucache = field(default_factory=lambda: lrucache(SIMILARITY_CACHE_SIZE))
 
     def _similarity(self, x, y):
-        # returns a non-positive number that has already been weighted on a per slot basis
+        # returns the mismatch penalty, a non-positive number that has already been
+        # weighted on a per slot basis
         if x == y:
             return 0
         if self._function is True:

{pyactup-2.0 → pyactup-2.2.3}/setup.py

@@ -1,4 +1,4 @@
-# Copyright 2018-2022 Carnegie Mellon University
+# Copyright 2018-2024 Carnegie Mellon University
 
 from setuptools import setup
 from pyactup import __version__
@@ -10,7 +10,7 @@ setup(name="pyactup",
       description="A lightweight Python implementation of a subset of the ACT-R cognitive architecture’s Declarative Memory",
       author="Don Morrison",
       author_email="dfm2@cmu.edu",
-      url="https://bitbucket.org/dfmorrison/pyactup/",
+      url="https://dfmorrison.github.io/pyactup-documentation/",
       platforms=["any"],
       long_description=DESCRIPTION,
       long_description_content_type="text/markdown",
@@ -18,7 +18,8 @@ setup(name="pyactup",
       install_requires=[
           "numpy",
           "pylru",
-          "prettytable"],
+          "prettytable",
+          "packaging"],
       tests_require=["pytest"],
       python_requires=">=3.8",
       classifiers=["Intended Audience :: Science/Research",