refactor/emcomposition_softmax_after_dot

[jdcpni]

• emcomposition.py
  - move softmax operation to after combining weighted dot products
  - update use_gating_for_weighting and softmax CONTROL option to work with refactoring
  - validate that use_gating_for_weighting is False when learn_field_weights is True
  - docstring mods

[github-actions]

This PR causes the following changes to the html docs (ubuntu-latest-3.11):

diff -r docs-base/EMComposition.html docs-head/EMComposition.html
302,309c302,309
< on the relative similarity of the keys to the entries in memory, computed as the dot product of each key and the
< values in the corresponding field for each entry in memory.  These dot products are then softmaxed, and those
< softmax distributions are weighted by the corresponding <a class="reference internal" href="#psyneulink.library.compositions.emcomposition.EMComposition.field_weights" title="psyneulink.library.compositions.emcomposition.EMComposition.field_weights"><code class="xref any py py-attr docutils literal notranslate"><span class="pre">field_weights</span></code></a> for each field
< and then combined, to produce a single softmax distribution over the entries in memory. That is then used to generate
< a weighted average of the retrieved values across all fields, which is returned as the <code class="xref any docutils literal notranslate"><span class="pre">result</span></code>
< of the EMComposition’s <a class="reference internal" href="Composition.html#composition-execution"><span class="std std-ref">execution</span></a> (an EMComposition can also be configured to return the
< entry with the highest dot product weighted by field, however then it is not compatible with learning;
< see <a class="reference internal" href="#emcomposition-softmax-choice"><span class="std std-ref">softmax_choice</span></a>).</p>
---
> on the relative similarity of the keys to the entries in memory, computed as the distance of each key and the
> values in the corresponding field for each entry in memory. By default, normalized dot products (comparable to cosine
> similarity) are used to compute the similarity of each query to each key in memory. These distances are then
> weighted by the corresponding <a class="reference internal" href="#psyneulink.library.compositions.emcomposition.EMComposition.field_weights" title="psyneulink.library.compositions.emcomposition.EMComposition.field_weights"><code class="xref any py py-attr docutils literal notranslate"><span class="pre">field_weights</span></code></a> for each field (if specified) and then
> summed, and the sum is softmaxed to produce a softmax distribution over the entries in memory. That is then used to
> generate a softmax-weighted average of the retrieved values across all fields, which is returned as the <code class="xref any docutils literal notranslate"><span class="pre">result</span></code> of the EMComposition’s <a class="reference internal" href="Composition.html#composition-execution"><span class="std std-ref">execution</span></a> (an EMComposition can also be
> configured to return the entry with the lowest distance weighted by field, however then it is not compatible
> with learning; see <a class="reference internal" href="#emcomposition-softmax-choice"><span class="std std-ref">softmax_choice</span></a>).</p>
395,396c395,396
< here there can be one or more keys and any number of values;  if all fields are keys, this implements a full form of
< content-addressable memory. If <strong>learn_field_weight</strong> is True (and <a class="reference internal" href="#psyneulink.library.compositions.emcomposition.EMComposition.enable_learning" title="psyneulink.library.compositions.emcomposition.EMComposition.enable_learning"><code class="xref any py py-attr docutils literal notranslate"><span class="pre">enable_learning</span></code></a>
---
> here there can be one or more keys and any number of values; if all fields are keys, this implements a full form of
> content-addressable memory. If <strong>learn_field_weights</strong> is True (and <a class="reference internal" href="#psyneulink.library.compositions.emcomposition.EMComposition.enable_learning" title="psyneulink.library.compositions.emcomposition.EMComposition.enable_learning"><code class="xref any py py-attr docutils literal notranslate"><span class="pre">enable_learning</span></code></a>
399c399
< scalar values rather than vecdtors); if <strong>learn_field_weight</strong> is False, then the field_weights are fixed.
---
> scalar values rather than vecdtors); if <strong>learn_field_weights</strong> is False, then the field_weights are fixed.
417,418c417,418
< <ul id="emcomposition-normalize-field-weights">
< <li><dl>
---
> <ul class="simple" id="emcomposition-normalize-field-weights">
> <li><dl class="simple">
424,431d423
< <div class="admonition warning">
< <p class="admonition-title">Warning</p>
< <p>If <strong>normalize_field_weights</strong> is False and <strong>enable_learning</strong> is True, a warning is issued indicating that
< this may produce an error if the <code class="xref any docutils literal notranslate"><span class="pre">loss_spec</span></code> for the EMComposition (or an
< <a class="reference internal" href="AutodiffComposition.html"><span class="doc">AutodiffComposition</span></a> that contains it) requires all values to be between 0 and 1, and calling the
< EMComposition’s <a class="reference internal" href="Composition.html#psyneulink.core.compositions.composition.Composition.learn" title="psyneulink.core.compositions.composition.Composition.learn"><code class="xref any py py-meth docutils literal notranslate"><span class="pre">learn</span></code></a> method will generate an error if the loss_spec is specified is
< one known to be incompatible (e.g., <code class="xref any docutils literal notranslate"><span class="pre">BINARY_CROSS_ENTROPY</span></code>).</p>
< </div>
454,456c446,447
< <p>While this is computationally more efficient, it can affect the outcome of the <a class="reference internal" href="#emcomposition-processing"><span class="std std-ref">matching process</span></a>, since computing the normalized dot product of a single vector comprised of the
< concatentated inputs is not identical to computing the normalized dot product of each field independently and
< then combining the results.</p>
---
> <p>While this is computationally more efficient, it can affect the outcome of the <a class="reference internal" href="#emcomposition-processing"><span class="std std-ref">matching process</span></a>, since computing the distance of a single vector comprised of the concatentated
> inputs is not identical to computing the distance of each field independently and then combining the results.</p>
481,482c472,473
< <li><p><strong>softmax_gain</strong> : specifies the gain (inverse temperature) used for softmax normalizing the dot products of
< queries and keys in memory (see <a class="reference internal" href="#emcomposition-execution"><span class="std std-ref">Execution</span></a> below).  The following options can be used:</p>
---
> <li><p><strong>softmax_gain</strong> : specifies the gain (inverse temperature) used for softmax normalizing the combined distances
> used for retrieval (see <a class="reference internal" href="#emcomposition-execution"><span class="std std-ref">Execution</span></a> below).  The following options can be used:</p>
485c476
< <a class="reference internal" href="#psyneulink.library.compositions.emcomposition.EMComposition.softmax_nodes" title="psyneulink.library.compositions.emcomposition.EMComposition.softmax_nodes"><code class="xref any py py-attr docutils literal notranslate"><span class="pre">softmax_nodes</span></code></a>.</p></li>
---
> <a class="reference internal" href="#psyneulink.library.compositions.emcomposition.EMComposition.softmax_node" title="psyneulink.library.compositions.emcomposition.EMComposition.softmax_node"><code class="xref any py py-attr docutils literal notranslate"><span class="pre">softmax_node</span></code></a>.</p></li>
487c478
< the <a class="reference internal" href="#psyneulink.library.compositions.emcomposition.EMComposition.softmax_gain" title="psyneulink.library.compositions.emcomposition.EMComposition.softmax_gain"><code class="xref any py py-attr docutils literal notranslate"><span class="pre">softmax_gain</span></code></a> based on the entropy of the dot products, in order to preserve
---
> the <a class="reference internal" href="#psyneulink.library.compositions.emcomposition.EMComposition.softmax_gain" title="psyneulink.library.compositions.emcomposition.EMComposition.softmax_gain"><code class="xref any py py-attr docutils literal notranslate"><span class="pre">softmax_gain</span></code></a> based on the entropy of the distances, in order to preserve
490c481
< <li><p><em>CONTROL</em>: a <a class="reference internal" href="ControlMechanism.html"><span class="doc">ControlMechanism</span></a> is created, and its <a class="reference internal" href="ControlSignal.html"><span class="doc">ControlSignal</span></a> is used to modulate the <a class="reference internal" href="#psyneulink.library.compositions.emcomposition.EMComposition.softmax_gain" title="psyneulink.library.compositions.emcomposition.EMComposition.softmax_gain"><code class="xref any py py-attr docutils literal notranslate"><span class="pre">softmax_gain</span></code></a> parameter of the <a class="reference internal" href="TransferFunctions.html#psyneulink.core.components.functions.transferfunctions.SoftMax" title="psyneulink.core.components.functions.transferfunctions.SoftMax"><code class="xref any py py-class docutils literal notranslate"><span class="pre">SoftMax</span></code></a> function of the EMComposition’s <a class="reference internal" href="#psyneulink.library.compositions.emcomposition.EMComposition.softmax_nodes" title="psyneulink.library.compositions.emcomposition.EMComposition.softmax_nodes"><code class="xref any py py-attr docutils literal notranslate"><span class="pre">softmax_nodes</span></code></a>.</p></li>
---
> <li><p><em>CONTROL</em>: a <a class="reference internal" href="ControlMechanism.html"><span class="doc">ControlMechanism</span></a> is created, and its <a class="reference internal" href="ControlSignal.html"><span class="doc">ControlSignal</span></a> is used to modulate the <a class="reference internal" href="#psyneulink.library.compositions.emcomposition.EMComposition.softmax_gain" title="psyneulink.library.compositions.emcomposition.EMComposition.softmax_gain"><code class="xref any py py-attr docutils literal notranslate"><span class="pre">softmax_gain</span></code></a> parameter of the <a class="reference internal" href="TransferFunctions.html#psyneulink.core.components.functions.transferfunctions.SoftMax" title="psyneulink.core.components.functions.transferfunctions.SoftMax"><code class="xref any py py-class docutils literal notranslate"><span class="pre">SoftMax</span></code></a> function of the EMComposition’s <a class="reference internal" href="#psyneulink.library.compositions.emcomposition.EMComposition.softmax_node" title="psyneulink.library.compositions.emcomposition.EMComposition.softmax_node"><code class="xref any py py-attr docutils literal notranslate"><span class="pre">softmax_node</span></code></a>.</p></li>
497c488
< then any values below the specified threshold are set to 0 before the dot products are softmaxed
---
> then any values below the specified threshold are set to 0 before the distances are softmaxed
501c492
< <li><p><strong>softmax_choice</strong> : specifies how the <a class="reference internal" href="TransferFunctions.html#psyneulink.core.components.functions.transferfunctions.SoftMax" title="psyneulink.core.components.functions.transferfunctions.SoftMax"><code class="xref any py py-class docutils literal notranslate"><span class="pre">SoftMax</span></code></a> Function of each of the EMComposition’s <a class="reference internal" href="#psyneulink.library.compositions.emcomposition.EMComposition.softmax_nodes" title="psyneulink.library.compositions.emcomposition.EMComposition.softmax_nodes"><code class="xref any py py-attr docutils literal notranslate"><span class="pre">softmax_nodes</span></code></a> is used, with the dot products of queries and keys, to generate a retrieved item;
---
> <li><p><strong>softmax_choice</strong> : specifies how the <a class="reference internal" href="TransferFunctions.html#psyneulink.core.components.functions.transferfunctions.SoftMax" title="psyneulink.core.components.functions.transferfunctions.SoftMax"><code class="xref any py py-class docutils literal notranslate"><span class="pre">SoftMax</span></code></a> Function of the EMComposition’s <a class="reference internal" href="#psyneulink.library.compositions.emcomposition.EMComposition.softmax_node" title="psyneulink.library.compositions.emcomposition.EMComposition.softmax_node"><code class="xref any py py-attr docutils literal notranslate"><span class="pre">softmax_node</span></code></a> is used, with the combined distances, to generate a retrieved item;
504,506c495,497
< <li><p><em>WEIGHTED_AVG</em> (default): softmax-weighted average of entries, based on their dot products with the key(s).</p></li>
< <li><p><em>ARG_MAX</em>: entry with the largest dot product (one with lowest index in <a class="reference internal" href="#psyneulink.library.compositions.emcomposition.EMComposition.memory" title="psyneulink.library.compositions.emcomposition.EMComposition.memory"><code class="xref any py py-attr docutils literal notranslate"><span class="pre">memory</span></code></a>)               if there are identical ones).</p></li>
< <li><p><em>PROBABISTIC</em>: probabilistically chosen entry based on softmax-transformed distribution of dot products.</p></li>
---
> <li><p><em>WEIGHTED_AVG</em> (default): softmax-weighted average based on combined distances of queries and keys in memory.</p></li>
> <li><p><em>ARG_MAX</em>: entry with the smallest distance (one with lowest index in <a class="reference internal" href="#psyneulink.library.compositions.emcomposition.EMComposition.memory" title="psyneulink.library.compositions.emcomposition.EMComposition.memory"><code class="xref any py py-attr docutils literal notranslate"><span class="pre">memory</span></code></a>)               if there are identical ones).</p></li>
> <li><p><em>PROBABISTIC</em>: probabilistically chosen entry based on softmax-transformed distribution of combined distance.</p></li>
543c534
< <dt><strong>learn_field_weight</strong><span class="classifier">specifies whether <a class="reference internal" href="#psyneulink.library.compositions.emcomposition.EMComposition.field_weights" title="psyneulink.library.compositions.emcomposition.EMComposition.field_weights"><code class="xref any py py-attr docutils literal notranslate"><span class="pre">field_weights</span></code></a> are modifiable during</span></dt><dd><p>learning (see <a class="reference internal" href="#psyneulink.library.compositions.emcomposition.EMComposition.field_weights" title="psyneulink.library.compositions.emcomposition.EMComposition.field_weights"><code class="xref any py py-attr docutils literal notranslate"><span class="pre">field_weights</span></code></a> and <a class="reference internal" href="#emcomposition-learning"><span class="std std-ref">Learning</span></a> for additional
---
> <dt><strong>learn_field_weights</strong><span class="classifier">specifies whether <a class="reference internal" href="#psyneulink.library.compositions.emcomposition.EMComposition.field_weights" title="psyneulink.library.compositions.emcomposition.EMComposition.field_weights"><code class="xref any py py-attr docutils literal notranslate"><span class="pre">field_weights</span></code></a> are modifiable during</span></dt><dd><p>learning (see <a class="reference internal" href="#psyneulink.library.compositions.emcomposition.EMComposition.field_weights" title="psyneulink.library.compositions.emcomposition.EMComposition.field_weights"><code class="xref any py py-attr docutils literal notranslate"><span class="pre">field_weights</span></code></a> and <a class="reference internal" href="#emcomposition-learning"><span class="std std-ref">Learning</span></a> for additional
545c536,537
< also be True, or it must be a list with at least one True entry.</p>
---
> also be True, or it must be a list with at least one True entry.  If <strong>learn_field_weights</strong> is True,
> <strong>use_gating_for_weighting</strong> must be False (see <a class="reference internal" href="#emcomposition-gating-for-weighting"><span class="std std-ref">note</span></a>).</p>
550c542
< <strong>learn_field_weight</strong> is True; see <a class="reference internal" href="#emcomposition-learning"><span class="std 
...

See CI logs for the full diff.

[github-actions]

This PR causes the following changes to the html docs (ubuntu-latest-3.11):

diff -r docs-base/EMComposition.html docs-head/EMComposition.html
302,309c302,309
< on the relative similarity of the keys to the entries in memory, computed as the dot product of each key and the
< values in the corresponding field for each entry in memory.  These dot products are then softmaxed, and those
< softmax distributions are weighted by the corresponding <a class="reference internal" href="#psyneulink.library.compositions.emcomposition.EMComposition.field_weights" title="psyneulink.library.compositions.emcomposition.EMComposition.field_weights"><code class="xref any py py-attr docutils literal notranslate"><span class="pre">field_weights</span></code></a> for each field
< and then combined, to produce a single softmax distribution over the entries in memory. That is then used to generate
< a weighted average of the retrieved values across all fields, which is returned as the <code class="xref any docutils literal notranslate"><span class="pre">result</span></code>
< of the EMComposition’s <a class="reference internal" href="Composition.html#composition-execution"><span class="std std-ref">execution</span></a> (an EMComposition can also be configured to return the
< entry with the highest dot product weighted by field, however then it is not compatible with learning;
< see <a class="reference internal" href="#emcomposition-softmax-choice"><span class="std std-ref">softmax_choice</span></a>).</p>
---
> on the relative similarity of the keys to the entries in memory, computed as the distance of each key and the
> values in the corresponding field for each entry in memory. By default, normalized dot products (comparable to cosine
> similarity) are used to compute the similarity of each query to each key in memory. These distances are then
> weighted by the corresponding <a class="reference internal" href="#psyneulink.library.compositions.emcomposition.EMComposition.field_weights" title="psyneulink.library.compositions.emcomposition.EMComposition.field_weights"><code class="xref any py py-attr docutils literal notranslate"><span class="pre">field_weights</span></code></a> for each field (if specified) and then
> summed, and the sum is softmaxed to produce a softmax distribution over the entries in memory. That is then used to
> generate a softmax-weighted average of the retrieved values across all fields, which is returned as the <code class="xref any docutils literal notranslate"><span class="pre">result</span></code> of the EMComposition’s <a class="reference internal" href="Composition.html#composition-execution"><span class="std std-ref">execution</span></a> (an EMComposition can also be
> configured to return the entry with the lowest distance weighted by field, however then it is not compatible
> with learning; see <a class="reference internal" href="#emcomposition-softmax-choice"><span class="std std-ref">softmax_choice</span></a>).</p>
395,396c395,396
< here there can be one or more keys and any number of values;  if all fields are keys, this implements a full form of
< content-addressable memory. If <strong>learn_field_weight</strong> is True (and <a class="reference internal" href="#psyneulink.library.compositions.emcomposition.EMComposition.enable_learning" title="psyneulink.library.compositions.emcomposition.EMComposition.enable_learning"><code class="xref any py py-attr docutils literal notranslate"><span class="pre">enable_learning</span></code></a>
---
> here there can be one or more keys and any number of values; if all fields are keys, this implements a full form of
> content-addressable memory. If <strong>learn_field_weights</strong> is True (and <a class="reference internal" href="#psyneulink.library.compositions.emcomposition.EMComposition.enable_learning" title="psyneulink.library.compositions.emcomposition.EMComposition.enable_learning"><code class="xref any py py-attr docutils literal notranslate"><span class="pre">enable_learning</span></code></a>
399c399
< scalar values rather than vecdtors); if <strong>learn_field_weight</strong> is False, then the field_weights are fixed.
---
> scalar values rather than vecdtors); if <strong>learn_field_weights</strong> is False, then the field_weights are fixed.
417,418c417,418
< <ul id="emcomposition-normalize-field-weights">
< <li><dl>
---
> <ul class="simple" id="emcomposition-normalize-field-weights">
> <li><dl class="simple">
424,431d423
< <div class="admonition warning">
< <p class="admonition-title">Warning</p>
< <p>If <strong>normalize_field_weights</strong> is False and <strong>enable_learning</strong> is True, a warning is issued indicating that
< this may produce an error if the <code class="xref any docutils literal notranslate"><span class="pre">loss_spec</span></code> for the EMComposition (or an
< <a class="reference internal" href="AutodiffComposition.html"><span class="doc">AutodiffComposition</span></a> that contains it) requires all values to be between 0 and 1, and calling the
< EMComposition’s <a class="reference internal" href="Composition.html#psyneulink.core.compositions.composition.Composition.learn" title="psyneulink.core.compositions.composition.Composition.learn"><code class="xref any py py-meth docutils literal notranslate"><span class="pre">learn</span></code></a> method will generate an error if the loss_spec is specified is
< one known to be incompatible (e.g., <code class="xref any docutils literal notranslate"><span class="pre">BINARY_CROSS_ENTROPY</span></code>).</p>
< </div>
454,456c446,447
< <p>While this is computationally more efficient, it can affect the outcome of the <a class="reference internal" href="#emcomposition-processing"><span class="std std-ref">matching process</span></a>, since computing the normalized dot product of a single vector comprised of the
< concatentated inputs is not identical to computing the normalized dot product of each field independently and
< then combining the results.</p>
---
> <p>While this is computationally more efficient, it can affect the outcome of the <a class="reference internal" href="#emcomposition-processing"><span class="std std-ref">matching process</span></a>, since computing the distance of a single vector comprised of the concatentated
> inputs is not identical to computing the distance of each field independently and then combining the results.</p>
481,482c472,473
< <li><p><strong>softmax_gain</strong> : specifies the gain (inverse temperature) used for softmax normalizing the dot products of
< queries and keys in memory (see <a class="reference internal" href="#emcomposition-execution"><span class="std std-ref">Execution</span></a> below).  The following options can be used:</p>
---
> <li><p><strong>softmax_gain</strong> : specifies the gain (inverse temperature) used for softmax normalizing the combined distances
> used for retrieval (see <a class="reference internal" href="#emcomposition-execution"><span class="std std-ref">Execution</span></a> below).  The following options can be used:</p>
485c476
< <a class="reference internal" href="#psyneulink.library.compositions.emcomposition.EMComposition.softmax_nodes" title="psyneulink.library.compositions.emcomposition.EMComposition.softmax_nodes"><code class="xref any py py-attr docutils literal notranslate"><span class="pre">softmax_nodes</span></code></a>.</p></li>
---
> <a class="reference internal" href="#psyneulink.library.compositions.emcomposition.EMComposition.softmax_node" title="psyneulink.library.compositions.emcomposition.EMComposition.softmax_node"><code class="xref any py py-attr docutils literal notranslate"><span class="pre">softmax_node</span></code></a>.</p></li>
487c478
< the <a class="reference internal" href="#psyneulink.library.compositions.emcomposition.EMComposition.softmax_gain" title="psyneulink.library.compositions.emcomposition.EMComposition.softmax_gain"><code class="xref any py py-attr docutils literal notranslate"><span class="pre">softmax_gain</span></code></a> based on the entropy of the dot products, in order to preserve
---
> the <a class="reference internal" href="#psyneulink.library.compositions.emcomposition.EMComposition.softmax_gain" title="psyneulink.library.compositions.emcomposition.EMComposition.softmax_gain"><code class="xref any py py-attr docutils literal notranslate"><span class="pre">softmax_gain</span></code></a> based on the entropy of the distances, in order to preserve
490c481
< <li><p><em>CONTROL</em>: a <a class="reference internal" href="ControlMechanism.html"><span class="doc">ControlMechanism</span></a> is created, and its <a class="reference internal" href="ControlSignal.html"><span class="doc">ControlSignal</span></a> is used to modulate the <a class="reference internal" href="#psyneulink.library.compositions.emcomposition.EMComposition.softmax_gain" title="psyneulink.library.compositions.emcomposition.EMComposition.softmax_gain"><code class="xref any py py-attr docutils literal notranslate"><span class="pre">softmax_gain</span></code></a> parameter of the <a class="reference internal" href="TransferFunctions.html#psyneulink.core.components.functions.transferfunctions.SoftMax" title="psyneulink.core.components.functions.transferfunctions.SoftMax"><code class="xref any py py-class docutils literal notranslate"><span class="pre">SoftMax</span></code></a> function of the EMComposition’s <a class="reference internal" href="#psyneulink.library.compositions.emcomposition.EMComposition.softmax_nodes" title="psyneulink.library.compositions.emcomposition.EMComposition.softmax_nodes"><code class="xref any py py-attr docutils literal notranslate"><span class="pre">softmax_nodes</span></code></a>.</p></li>
---
> <li><p><em>CONTROL</em>: a <a class="reference internal" href="ControlMechanism.html"><span class="doc">ControlMechanism</span></a> is created, and its <a class="reference internal" href="ControlSignal.html"><span class="doc">ControlSignal</span></a> is used to modulate the <a class="reference internal" href="#psyneulink.library.compositions.emcomposition.EMComposition.softmax_gain" title="psyneulink.library.compositions.emcomposition.EMComposition.softmax_gain"><code class="xref any py py-attr docutils literal notranslate"><span class="pre">softmax_gain</span></code></a> parameter of the <a class="reference internal" href="TransferFunctions.html#psyneulink.core.components.functions.transferfunctions.SoftMax" title="psyneulink.core.components.functions.transferfunctions.SoftMax"><code class="xref any py py-class docutils literal notranslate"><span class="pre">SoftMax</span></code></a> function of the EMComposition’s <a class="reference internal" href="#psyneulink.library.compositions.emcomposition.EMComposition.softmax_node" title="psyneulink.library.compositions.emcomposition.EMComposition.softmax_node"><code class="xref any py py-attr docutils literal notranslate"><span class="pre">softmax_node</span></code></a>.</p></li>
497c488
< then any values below the specified threshold are set to 0 before the dot products are softmaxed
---
> then any values below the specified threshold are set to 0 before the distances are softmaxed
501c492
< <li><p><strong>softmax_choice</strong> : specifies how the <a class="reference internal" href="TransferFunctions.html#psyneulink.core.components.functions.transferfunctions.SoftMax" title="psyneulink.core.components.functions.transferfunctions.SoftMax"><code class="xref any py py-class docutils literal notranslate"><span class="pre">SoftMax</span></code></a> Function of each of the EMComposition’s <a class="reference internal" href="#psyneulink.library.compositions.emcomposition.EMComposition.softmax_nodes" title="psyneulink.library.compositions.emcomposition.EMComposition.softmax_nodes"><code class="xref any py py-attr docutils literal notranslate"><span class="pre">softmax_nodes</span></code></a> is used, with the dot products of queries and keys, to generate a retrieved item;
---
> <li><p><strong>softmax_choice</strong> : specifies how the <a class="reference internal" href="TransferFunctions.html#psyneulink.core.components.functions.transferfunctions.SoftMax" title="psyneulink.core.components.functions.transferfunctions.SoftMax"><code class="xref any py py-class docutils literal notranslate"><span class="pre">SoftMax</span></code></a> Function of the EMComposition’s <a class="reference internal" href="#psyneulink.library.compositions.emcomposition.EMComposition.softmax_node" title="psyneulink.library.compositions.emcomposition.EMComposition.softmax_node"><code class="xref any py py-attr docutils literal notranslate"><span class="pre">softmax_node</span></code></a> is used, with the combined distances, to generate a retrieved item;
504,506c495,497
< <li><p><em>WEIGHTED_AVG</em> (default): softmax-weighted average of entries, based on their dot products with the key(s).</p></li>
< <li><p><em>ARG_MAX</em>: entry with the largest dot product (one with lowest index in <a class="reference internal" href="#psyneulink.library.compositions.emcomposition.EMComposition.memory" title="psyneulink.library.compositions.emcomposition.EMComposition.memory"><code class="xref any py py-attr docutils literal notranslate"><span class="pre">memory</span></code></a>)               if there are identical ones).</p></li>
< <li><p><em>PROBABISTIC</em>: probabilistically chosen entry based on softmax-transformed distribution of dot products.</p></li>
---
> <li><p><em>WEIGHTED_AVG</em> (default): softmax-weighted average based on combined distances of queries and keys in memory.</p></li>
> <li><p><em>ARG_MAX</em>: entry with the smallest distance (one with lowest index in <a class="reference internal" href="#psyneulink.library.compositions.emcomposition.EMComposition.memory" title="psyneulink.library.compositions.emcomposition.EMComposition.memory"><code class="xref any py py-attr docutils literal notranslate"><span class="pre">memory</span></code></a>)               if there are identical ones).</p></li>
> <li><p><em>PROBABISTIC</em>: probabilistically chosen entry based on softmax-transformed distribution of combined distance.</p></li>
543c534
< <dt><strong>learn_field_weight</strong><span class="classifier">specifies whether <a class="reference internal" href="#psyneulink.library.compositions.emcomposition.EMComposition.field_weights" title="psyneulink.library.compositions.emcomposition.EMComposition.field_weights"><code class="xref any py py-attr docutils literal notranslate"><span class="pre">field_weights</span></code></a> are modifiable during</span></dt><dd><p>learning (see <a class="reference internal" href="#psyneulink.library.compositions.emcomposition.EMComposition.field_weights" title="psyneulink.library.compositions.emcomposition.EMComposition.field_weights"><code class="xref any py py-attr docutils literal notranslate"><span class="pre">field_weights</span></code></a> and <a class="reference internal" href="#emcomposition-learning"><span class="std std-ref">Learning</span></a> for additional
---
> <dt><strong>learn_field_weights</strong><span class="classifier">specifies whether <a class="reference internal" href="#psyneulink.library.compositions.emcomposition.EMComposition.field_weights" title="psyneulink.library.compositions.emcomposition.EMComposition.field_weights"><code class="xref any py py-attr docutils literal notranslate"><span class="pre">field_weights</span></code></a> are modifiable during</span></dt><dd><p>learning (see <a class="reference internal" href="#psyneulink.library.compositions.emcomposition.EMComposition.field_weights" title="psyneulink.library.compositions.emcomposition.EMComposition.field_weights"><code class="xref any py py-attr docutils literal notranslate"><span class="pre">field_weights</span></code></a> and <a class="reference internal" href="#emcomposition-learning"><span class="std std-ref">Learning</span></a> for additional
545c536,537
< also be True, or it must be a list with at least one True entry.</p>
---
> also be True, or it must be a list with at least one True entry.  If <strong>learn_field_weights</strong> is True,
> <strong>use_gating_for_weighting</strong> must be False (see <a class="reference internal" href="#emcomposition-gating-for-weighting"><span class="std std-ref">note</span></a>).</p>
550c542
< <strong>learn_field_weight</strong> is True; see <a class="reference internal" href="#emcomposition-learning"><span class="std 
...

See CI logs for the full diff.

[coveralls]

coverage: 83.739% (+0.03%) from 83.71%
when pulling 8c1bc8e on refactor/emcomposition_softmax_after_dot
into b9eb21f on devel.