Tests/control/warnings

[jdcpni]

test_control.py:

• add test_warning_for_add_controller_twice()
• add test_warning_for_controller_assigned_to_another_comp()
• add test_warning_for_replacement_of_controller

docs: misc edits to docstrings

[github-actions]

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

diff -r docs-base/AutodiffComposition.html docs-head/AutodiffComposition.html
206,208c206,214
<   <section id="module-psyneulink.library.compositions.autodiffcomposition">
< <span id="autodiffcomposition"></span><h1>AutodiffComposition<a class="headerlink" href="#module-psyneulink.library.compositions.autodiffcomposition" title="Permalink to this headline">¶</a></h1>
< <section id="contents">
---
>   <section id="autodiffcomposition">
> <h1>AutodiffComposition<a class="headerlink" href="#autodiffcomposition" title="Permalink to this headline">¶</a></h1>
> <div class="related docutils container">
> <p><em>Related</em></p>
> <ul class="simple">
> <li><p><a class="reference internal" href="Composition.html#composition-learning"><span class="std std-ref">Learning in a Composition</span></a></p></li>
> </ul>
> </div>
> <span class="target" id="module-psyneulink.library.compositions.autodiffcomposition"></span><section id="contents">
diff -r docs-base/Composition.html docs-head/Composition.html
221c221
< <ul>
---
> <ul class="current">
222a223
> <li class="toctree-l1 current"><a class="reference internal" href="CompositionInterfaceMechanism.html">CompositionInterfaceMechanism</a></li>
698c699
< graph.  Subsets of Nodes connected by Projections are often defined as a <a class="reference internal" href="Pathway.html"><span class="doc">Pathway</span></a> as decribed under
---
> graph.  Subsets of Nodes connected by Projections can be defined as a <a class="reference internal" href="Pathway.html"><span class="doc">Pathway</span></a> as decribed under
707c708,709
< connect a Node with itself.  Projections can also connect the Node(s) of a Composition to one(s) <a class="reference internal" href="#composition-nested"><span class="std std-ref">nested within it</span></a>.  In general, these are to the <a class="reference internal" href="#psyneulink.core.compositions.composition.NodeRole.INPUT" title="psyneulink.core.compositions.composition.NodeRole.INPUT"><code class="xref any py py-attr docutils literal notranslate"><span class="pre">INPUT</span></code></a> Nodes and from the <a class="reference internal" href="#psyneulink.core.compositions.composition.NodeRole.OUTPUT" title="psyneulink.core.compositions.composition.NodeRole.OUTPUT"><code class="xref any py py-attr docutils literal notranslate"><span class="pre">OUTPUT</span></code></a> Nodes of a <a class="reference internal" href="#composition-nested"><span class="std std-ref">nested Composition</span></a>, but if the Composition’s <a class="reference internal" href="#psyneulink.core.compositions.composition.Composition.allow_probes" title="psyneulink.core.compositions.composition.Composition.allow_probes"><code class="xref any py py-attr docutils literal notranslate"><span class="pre">allow_probes</span></code></a> attribute is not False, then Projections can be received from any Nodes within a nested
---
> connect a Node with itself.  Projections can also connect the Node(s) of a Composition to one(s) <a class="reference internal" href="#composition-nested"><span class="std std-ref">nested within
> it</span></a>.  In general, these are to the <a class="reference internal" href="#psyneulink.core.compositions.composition.NodeRole.INPUT" title="psyneulink.core.compositions.composition.NodeRole.INPUT"><code class="xref any py py-attr docutils literal notranslate"><span class="pre">INPUT</span></code></a> Nodes and from the <a class="reference internal" href="#psyneulink.core.compositions.composition.NodeRole.OUTPUT" title="psyneulink.core.compositions.composition.NodeRole.OUTPUT"><code class="xref any py py-attr docutils literal notranslate"><span class="pre">OUTPUT</span></code></a> Nodes of a <a class="reference internal" href="#composition-nested"><span class="std std-ref">nested Composition</span></a>, but if the Composition’s <a class="reference internal" href="#psyneulink.core.compositions.composition.Composition.allow_probes" title="psyneulink.core.compositions.composition.Composition.allow_probes"><code class="xref any py py-attr docutils literal notranslate"><span class="pre">allow_probes</span></code></a> attribute is not False, then Projections can be received from any Nodes within a nested
709a712,726
> <p>Projections can be specified between <a class="reference internal" href="Mechanism.html"><span class="doc">Mechanisms</span></a> before they are added to a Composition.  If both
> Mechanisms are later added to the same Composition, and the Projection between them is legal for the Composition,
> then the Projection between them is added to it and is used during its <a class="reference internal" href="#composition-execution"><span class="std std-ref">execution</span></a>.
> However, if the Projection is not legal for the Composition (e.g., the Mechanisms are not assigned as <a class="reference internal" href="#psyneulink.core.compositions.composition.NodeRole.INTERNAL" title="psyneulink.core.compositions.composition.NodeRole.INTERNAL"><code class="xref any py py-attr docutils literal notranslate"><span class="pre">INTERNAL</span></code></a> <a class="reference internal" href="#composition-nodes"><span class="std std-ref">Nodes</span></a> of two different <a class="reference internal" href="#composition-nested"><span class="std std-ref">nested Compositions</span></a>),
> the Projection will still be associated with the two Mechanisms (i.e., listed in their <a class="reference internal" href="Mechanism.html#id14" title="psyneulink.core.components.mechanisms.mechanism.Mechanism_Base.afferents"><code class="xref any py py-attr docutils literal notranslate"><span class="pre">afferents</span></code></a> and <a class="reference internal" href="Mechanism.html#id15" title="psyneulink.core.components.mechanisms.mechanism.Mechanism_Base.efferents"><code class="xref any py py-attr docutils literal notranslate"><span class="pre">efferents</span></code></a> attributes, respectively), but it is not
> added to the Composition and not used during its execution.</p>
> <blockquote>
> <div><div class="admonition hint">
> <p class="admonition-title">Hint</p>
> <p>Projections that are associated with the <a class="reference internal" href="#composition-nodes"><span class="std std-ref">Nodes</span></a> of a Composition but are not in the
> Composition itself (and, accordingly, <em>not</em> listed it is <a class="reference internal" href="#psyneulink.core.compositions.composition.Composition.projections" title="psyneulink.core.compositions.composition.Composition.projections"><code class="xref any py py-attr docutils literal notranslate"><span class="pre">projections</span></code></a> attribute)
> can still be visualized using the Composition’s <a class="reference internal" href="Visualization.html#psyneulink.core.compositions.showgraph.ShowGraph.show_graph" title="psyneulink.core.compositions.showgraph.ShowGraph.show_graph"><code class="xref any py py-meth docutils literal notranslate"><span class="pre">show_graph</span></code></a> method, by specifying its
> <strong>show_projections_not_in_composition</strong> argument as True; Projections not in the Composition appear in red.</p>
> </div>
> </div></blockquote>
diff -r docs-base/CompositionFunctionApproximator.html docs-head/CompositionFunctionApproximator.html
214a215,216
> <div class="line-block">
> <div class="line"><br /></div>
215a218,220
> </div>
> <div class="related docutils container">
> <p><em>Related</em></p>
216a222,225
> <ul>
> <li class="toctree-l1"><a class="reference internal" href="OptimizationControlMechanism.html">OptimizationControlMechanism</a></li>
> </ul>
> </div>
diff -r docs-base/CompositionInterfaceMechanism.html docs-head/CompositionInterfaceMechanism.html
200,202c200,211
<   <section id="module-psyneulink.core.components.mechanisms.processing.compositioninterfacemechanism">
< <span id="compositioninterfacemechanism"></span><h1>CompositionInterfaceMechanism<a class="headerlink" href="#module-psyneulink.core.components.mechanisms.processing.compositioninterfacemechanism" title="Permalink to this headline">¶</a></h1>
< <section id="contents">
---
>   <section id="compositioninterfacemechanism">
> <h1>CompositionInterfaceMechanism<a class="headerlink" href="#compositioninterfacemechanism" title="Permalink to this headline">¶</a></h1>
> <div class="related docutils container">
> <p><em>Related</em></p>
> <div class="toctree-wrapper compound">
> <ul class="current">
> <li class="toctree-l1"><a class="reference internal" href="Mechanism.html">Mechanism</a></li>
> <li class="toctree-l1 current"><a class="reference internal" href="Composition.html">Composition</a></li>
> </ul>
> </div>
> </div>
> <span class="target" id="module-psyneulink.core.components.mechanisms.processing.compositioninterfacemechanism"></span><section id="contents">
diff -r docs-base/InputPort.html docs-head/InputPort.html
474,476c474,475
< <a class="reference internal" href="Composition.html#composition-nodes"><span class="std std-ref">Nodes</span></a> of a <a class="reference internal" href="Composition.html#composition-nested"><span class="std std-ref">nested</span></a> can be specified for shadowing, unless the
< <a class="reference internal" href="Composition.html#psyneulink.core.compositions.composition.Composition.allow_probes" title="psyneulink.core.compositions.composition.Composition.allow_probes"><code class="xref any py py-attr docutils literal notranslate"><span class="pre">allow_probes</span></code></a> attribute of the <a class="reference internal" href="Composition.html"><span class="doc">Composition</span></a> is set to True.  Note also that any
< Node that shadows an <a class="reference internal" href="Composition.html#psyneulink.core.compositions.composition.NodeRole.INPUT" title="psyneulink.core.compositions.composition.NodeRole.INPUT"><code class="xref any py py-attr docutils literal notranslate"><span class="pre">INPUT</span></code></a> <a class="reference internal" href="Composition.html#composition-nodes"><span class="std std-ref">Node</span></a> of the Composition to which it
---
> <a class="reference internal" href="Composition.html#composition-nodes"><span class="std std-ref">Nodes</span></a> of a <a class="reference internal" href="Composition.html#composition-nested"><span class="std std-ref">nested</span></a> can be specified for shadowing.  Note also that
> any Node that shadows an <a class="reference internal" href="Composition.html#psyneulink.core.compositions.composition.NodeRole.INPUT" title="psyneulink.core.compositions.composition.NodeRole.INPUT"><code class="xref any py py-attr docutils literal notranslate"><span class="pre">INPUT</span></code></a> <a class="reference internal" href="Composition.html#composition-nodes"><span class="std std-ref">Node</span></a> of the Composition to which it
482,485c481,485
< not an <a class="reference internal" href="Composition.html#psyneulink.core.compositions.composition.NodeRole.INPUT" title="psyneulink.core.compositions.composition.NodeRole.INPUT"><code class="xref any py py-attr docutils literal notranslate"><span class="pre">INPUT</span></code></a> <a class="reference internal" href="Composition.html#composition-nodes"><span class="std std-ref">Node</span></a> of that Composition, this can be accomplished as
< follows: 1) add a Mechanism to the nested Composition with an InputPort that shadows the one to be
< shadowed; 2) specify <a class="reference internal" href="Composition.html#psyneulink.core.compositions.composition.NodeRole.INPUT" title="psyneulink.core.compositions.composition.NodeRole.INPUT"><code class="xref any py py-attr docutils literal notranslate"><span class="pre">OUTPUT</span></code></a> as a <code class="xref any docutils literal notranslate"><span class="pre">required_role</span></code>
< for that Mechanism;  3) use that Mechanism as the <a class="reference internal" href="#inputport-specification"><span class="std std-ref">InputPort specification</span></a>
---
> not an <a class="reference internal" href="Composition.html#psyneulink.core.compositions.composition.NodeRole.INPUT" title="psyneulink.core.compositions.composition.NodeRole.INPUT"><code class="xref any py py-attr docutils literal notranslate"><span class="pre">INPUT</span></code></a> <a class="reference internal" href="Composition.html#composition-nodes"><span class="std std-ref">Node</span></a> of that Composition, this can be accomplished in
> one of two ways:  1) by assigning it <a class="reference internal" href="Composition.html#psyneulink.core.compositions.composition.NodeRole.INPUT" title="psyneulink.core.compositions.composition.NodeRole.INPUT"><code class="xref any py py-attr docutils literal notranslate"><span class="pre">INPUT</span></code></a> as a <a class="reference internal" href="Composition.html#composition-node-role-assignment"><span class="std std-ref">required NodeRole</span></a> where it is added to the nested Composition; and/or 2) by doing the
> following: a) add a Mechanism to the nested Composition with an InputPort that shadows the one to be
> shadowed; b) specify <a class="reference internal" href="Composition.html#psyneulink.core.compositions.composition.NodeRole.INPUT" title="psyneulink.core.compositions.composition.NodeRole.INPUT"><code class="xref any py py-attr docutils literal notranslate"><span class="pre">OUTPUT</span></code></a> as a <code class="xref any docutils literal notranslate"><span class="pre">required_role</span></code>
> for that Mechanism;  c) use that Mechanism as the <a class="reference internal" href="#inputport-specification"><span class="std std-ref">InputPort specification</span></a>
diff -r docs-base/Library.html docs-head/Library.html
267a268
> <li class="toctree-l3"><a class="reference internal" href="OptimizationControlMechanism.html">OptimizationControlMechanism</a></li>
270c271,272
< <li class="toctree-l2"><a class="reference internal" href="ParameterEstimationComposition.html">ParameterEstimationComposition</a><ul class="simple">
---
> <li class="toctree-l2"><a class="reference internal" href="ParameterEstimationComposition.html">ParameterEstimationComposition</a><ul>
> <li class="toctree-l3"><a class="reference internal" href="OptimizationControlMechanism.html">OptimizationControlMechanism</a></li>
diff -r docs-base/OptimizationControlMechanism.html docs-head/OptimizationControlMechanism.html
35c35,37
<     <link rel="search" title="Search" href="search.html" /> 
---
>     <link rel="search" title="Search" href="search.html" />
>     <link rel="next" title="ParameterEstimationComposition" href="ParameterEstimationComposition.html" />
>     <link rel="prev" title="RegressionCFA" href="RegressionCFA.html" /> 
129c131
<               <ul>
---
>               <ul class="current">
134c136
< <li class="toctree-l1"><a class="reference internal" href="Library.html">Library</a></li>
---
> <li class="toctree-l1 current"><a class="reference internal" href="Library.html">Library</a></li>
176a179,184
>           <li><a href="Library.html">Library</a> &gt;</li>
>         
>           <li><a href="Compositions.html">Compositions</a> &gt;</li>
>         
>           <li><a href="CompositionFunctionApproximator.html">CompositionFunctionApproximator</a> &gt;</li>
>         
460a469,484
> <div class="admonition note">
> <p class="admonition-title">Note</p>
> <p>Only the <a class="reference internal" href="Composition.html#psyneulink.core.compositions.composition.NodeRole.INPUT" title="psyneulink.core.compositions.composition.NodeRole.INPUT"><code class="xref any py py-attr docutils literal notranslate"><span class="pre">INPUT</span></code></a> <code class="xref any docutils literal notranslate"><span class="pre">Nodes</span></code> of a <a class="reference internal" href="Composition.html#composition-nested"><span class="std std-ref">nested Composition</span></a>
> can shadowed.  Therefore, if the Composition that an OptimizationControlMechanism controls contains any
> nested Compositions, only its <a class="reference internal" href="Composition.html#psyneulink.core.compositions.composition.NodeRole.INPUT" title="psyneulink.core.compositions.composition.NodeRole.INPUT"><code class="xref any py py-attr docutils literal notranslate"><span class="pre">INPUT</span></code></a> Nodes can be specified for shadowing in the
> <strong>state_features</strong> argument of the OptimizationControlMechani
...

See CI logs for the full diff.

[coveralls]

Coverage increased (+0.04%) to 84.332% when pulling 735ceec on tests/control/warnings into cb18e77 on devel.