docs/composition_randomization

[jdcpni]

No description provided.

[github-actions]

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

diff -r docs-base/AutoAssociativeLearningMechanism.html docs-head/AutoAssociativeLearningMechanism.html
331c331
< <dd class="field-odd"><p>ContentAddressableList[<a class="reference internal" href="OutputPort.html#psyneulink.core.components.ports.outputport.OutputPort" title="psyneulink.core.components.ports.outputport.OutputPort">OutputPort</a>]</p>
---
> <dd class="field-odd"><p><a class="reference internal" href="Utilities.html#psyneulink.core.globals.utilities.ContentAddressableList" title="psyneulink.core.globals.utilities.ContentAddressableList">ContentAddressableList</a>[<a class="reference internal" href="OutputPort.html#psyneulink.core.components.ports.outputport.OutputPort" title="psyneulink.core.components.ports.outputport.OutputPort">OutputPort</a>]</p>
450c450
< <dd class="field-odd"><p>ContentAddressableList[<a class="reference internal" href="OutputPort.html#psyneulink.core.components.ports.outputport.OutputPort" title="psyneulink.core.components.ports.outputport.OutputPort">OutputPort</a>]</p>
---
> <dd class="field-odd"><p><a class="reference internal" href="Utilities.html#psyneulink.core.globals.utilities.ContentAddressableList" title="psyneulink.core.globals.utilities.ContentAddressableList">ContentAddressableList</a>[<a class="reference internal" href="OutputPort.html#psyneulink.core.components.ports.outputport.OutputPort" title="psyneulink.core.components.ports.outputport.OutputPort">OutputPort</a>]</p>
diff -r docs-base/ComparatorMechanism.html docs-head/ComparatorMechanism.html
366c366
< <dd class="field-odd"><p>ContentAddressableList[<a class="reference internal" href="InputPort.html#psyneulink.core.components.ports.inputport.InputPort" title="psyneulink.core.components.ports.inputport.InputPort">InputPort</a>, <a class="reference internal" href="InputPort.html#psyneulink.core.components.ports.inputport.InputPort" title="psyneulink.core.components.ports.inputport.InputPort">InputPort</a>]</p>
---
> <dd class="field-odd"><p><a class="reference internal" href="Utilities.html#psyneulink.core.globals.utilities.ContentAddressableList" title="psyneulink.core.globals.utilities.ContentAddressableList">ContentAddressableList</a>[<a class="reference internal" href="InputPort.html#psyneulink.core.components.ports.inputport.InputPort" title="psyneulink.core.components.ports.inputport.InputPort">InputPort</a>, <a class="reference internal" href="InputPort.html#psyneulink.core.components.ports.inputport.InputPort" title="psyneulink.core.components.ports.inputport.InputPort">InputPort</a>]</p>
403c403
< <dd class="field-odd"><p>ContentAddressableList[<a class="reference internal" href="OutputPort.html#psyneulink.core.components.ports.outputport.OutputPort" title="psyneulink.core.components.ports.outputport.OutputPort">OutputPort</a>]</p>
---
> <dd class="field-odd"><p><a class="reference internal" href="Utilities.html#psyneulink.core.globals.utilities.ContentAddressableList" title="psyneulink.core.globals.utilities.ContentAddressableList">ContentAddressableList</a>[<a class="reference internal" href="OutputPort.html#psyneulink.core.components.ports.outputport.OutputPort" title="psyneulink.core.components.ports.outputport.OutputPort">OutputPort</a>]</p>
diff -r docs-base/Component.html docs-head/Component.html
522c522
< <li><p><strong>execute_until_finished</strong> – determines whether the Component executes until its <a class="reference internal" href="DDM.html#psyneulink.library.components.mechanisms.processing.integrator.ddm.DDM.is_finished" title="psyneulink.library.components.mechanisms.processing.integrator.ddm.DDM.is_finished"><code class="xref any py py-meth docutils literal notranslate"><span class="pre">is_finished</span></code></a> method returns True.
---
> <li><p><strong>execute_until_finished</strong> – determines whether the Component executes until its <a class="reference internal" href="#psyneulink.core.components.component.Component.is_finished" title="psyneulink.core.components.component.Component.is_finished"><code class="xref any py py-meth docutils literal notranslate"><span class="pre">is_finished</span></code></a> method returns True.
524,525c524,525
< irrespective of its <a class="reference internal" href="DDM.html#psyneulink.library.components.mechanisms.processing.integrator.ddm.DDM.is_finished" title="psyneulink.library.components.mechanisms.processing.integrator.ddm.DDM.is_finished"><code class="xref any py py-meth docutils literal notranslate"><span class="pre">is_finished</span></code></a> method;  if it is True then, depending on how its class implements and handles its
< <a class="reference internal" href="DDM.html#psyneulink.library.components.mechanisms.processing.integrator.ddm.DDM.is_finished" title="psyneulink.library.components.mechanisms.processing.integrator.ddm.DDM.is_finished"><code class="xref any py py-meth docutils literal notranslate"><span class="pre">is_finished</span></code></a> method, the Component may execute more than once per call to its <a class="reference internal" href="#psyneulink.core.components.component.Component.execute" title="psyneulink.core.components.component.Component.execute"><code class="xref any py py-meth docutils literal notranslate"><span class="pre">execute</span></code></a> method.</p></li>
---
> irrespective of its <a class="reference internal" href="#psyneulink.core.components.component.Component.is_finished" title="psyneulink.core.components.component.Component.is_finished"><code class="xref any py py-meth docutils literal notranslate"><span class="pre">is_finished</span></code></a> method;  if it is True then, depending on how its class implements and handles its
> <a class="reference internal" href="#psyneulink.core.components.component.Component.is_finished" title="psyneulink.core.components.component.Component.is_finished"><code class="xref any py py-meth docutils literal notranslate"><span class="pre">is_finished</span></code></a> method, the Component may execute more than once per call to its <a class="reference internal" href="#psyneulink.core.components.component.Component.execute" title="psyneulink.core.components.component.Component.execute"><code class="xref any py py-meth docutils literal notranslate"><span class="pre">execute</span></code></a> method.</p></li>
530c530
< <a class="reference internal" href="#psyneulink.core.components.component.Component.execute" title="psyneulink.core.components.component.Component.execute"><code class="xref any py py-meth docutils literal notranslate"><span class="pre">execute</span></code></a> method, or extend over several calls.  It is set to 0 each time <a class="reference internal" href="DDM.html#psyneulink.library.components.mechanisms.processing.integrator.ddm.DDM.is_finished" title="psyneulink.library.components.mechanisms.processing.integrator.ddm.DDM.is_finished"><code class="xref any py py-meth docutils literal notranslate"><span class="pre">is_finished</span></code></a> evaluates
---
> <a class="reference internal" href="#psyneulink.core.components.component.Component.execute" title="psyneulink.core.components.component.Component.execute"><code class="xref any py py-meth docutils literal notranslate"><span class="pre">execute</span></code></a> method, or extend over several calls.  It is set to 0 each time <a class="reference internal" href="#psyneulink.core.components.component.Component.is_finished" title="psyneulink.core.components.component.Component.is_finished"><code class="xref any py py-meth docutils literal notranslate"><span class="pre">is_finished</span></code></a> evaluates
1275c1275
< <dd class="field-odd"><p>ContentAddressableList</p>
---
> <dd class="field-odd"><p><a class="reference internal" href="Utilities.html#psyneulink.core.globals.utilities.ContentAddressableList" title="psyneulink.core.globals.utilities.ContentAddressableList">ContentAddressableList</a></p>
1296c1296
< <dd class="field-odd"><p>ContentAddressableList</p>
---
> <dd class="field-odd"><p><a class="reference internal" href="Utilities.html#psyneulink.core.globals.utilities.ContentAddressableList" title="psyneulink.core.globals.utilities.ContentAddressableList">ContentAddressableList</a></p>
diff -r docs-base/Composition.html docs-head/Composition.html
345a346
> <li><p><a class="reference internal" href="#composition-randomization"><span class="std std-ref">Randomization</span></a></p></li>
1349a1351
> <li><p><a class="reference internal" href="#composition-randomization"><span class="std std-ref">Randomization</span></a></p></li>
1638a1641
> <li><p><a class="reference internal" href="#composition-randomization"><span class="std std-ref">Randomization</span></a></p></li>
1932a1936,1964
> <section id="randomization">
> <span id="composition-randomization"></span><h4><em>Randomization</em><a class="headerlink" href="#randomization" title="Permalink to this headline">¶</a></h4>
> <p>Each PsyNeuLink Component that relies on randomization uses a private instance of a <a class="reference external" href="https://en.wikipedia.org/wiki/Pseudorandom_number_generator#:~:text=A%20pseudorandom%20number%20generator%20(PRNG,of%20sequences%20of%20random%20numbers">pseudorandom number generator</a> (PRNG). This makes random sequences within each Component independent of
> one another, and independent of any random number generation used in the script from which PsyNeuLink is run and/or any
> imported modules in that script. Each PsyNeuLink Component that relies on randomization has its won <code class="xref any docutils literal notranslate"><span class="pre">seed</span></code> <a class="reference internal" href="Parameters.html#psyneulink.core.globals.parameters.Parameter" title="psyneulink.core.globals.parameters.Parameter"><code class="xref any py py-class docutils literal notranslate"><span class="pre">Parameter</span></code></a>
> that can be used to explicitly seed its PRNG (see <a class="reference internal" href="#composition-local-random-seed"><span class="std std-ref">below</span></a>).  If no seed is specified for
> a Component, it gets its seed from the PsyNeuLink <a class="reference internal" href="#composition-global-random-seed"><span class="std std-ref">global seed</span></a>. Because PsyNeuLink
> handles randomization internally in this way, the behavior of a Composition is reproducible, and is isolated from any
> calls to python and/or numpy random modules from the script in which the Composition is run, and/or any imported
> modules. Below are details about setting PsyNeuLink global and local seeds.</p>
> <div class="technical-note docutils container">
> <p>To avoid interfering with the internal handling of randomization, <code class="xref any docutils literal notranslate"><span class="pre">np.random</span></code> and python <code class="xref any docutils literal notranslate"><span class="pre">random</span></code> should <em>NOT</em>
> be called inside PsyNeulink code itself.  Rather, a Component’s <a class="reference internal" href="IntegratorFunctions.html#psyneulink.core.components.functions.stateful.integratorfunctions.DriftDiffusionIntegrator.random_state" title="psyneulink.core.components.functions.stateful.integratorfunctions.DriftDiffusionIntegrator.random_state"><code class="xref any py py-attr docutils literal notranslate"><span class="pre">random_state</span></code></a> <a class="reference internal" href="Parameters.html#psyneulink.core.globals.parameters.Parameter" title="psyneulink.core.globals.parameters.Parameter"><code class="xref any py py-class docutils literal notranslate"><span class="pre">Parameter</span></code></a> should be used, which
> provides a <a class="reference external" href="https://numpy.org/doc/2.2/reference/random/legacy.html">numpy.random.RandomState</a> object that is
> initialized with the seed assigned to the Component; that can then be used to call the desired numpy function
> (e.g., <code class="docutils literal notranslate"><span class="pre">&lt;component&gt;.random_state.normal()</span></code> or <code class="docutils literal notranslate"><span class="pre">&lt;component&gt;.random_state.uniform()</span></code>) to get a random value.</p>
> </div>
> <div class="technical-note docutils container">
> <p>PsyNeuLink uses the <a class="reference external" href="https://en.wikipedia.org/wiki/Mersenne_Twister">Mersenne Twister</a> algorithm
> for its pseudorandom number generator (PRNG), which is the default PRNG for numpy.</p>
> </div>
> <p id="composition-global-random-seed"><strong>Global random seed.</strong> Calling <a class="reference internal" href="Utilities.html#psyneulink.core.globals.utilities.set_global_seed" title="psyneulink.core.globals.utilities.set_global_seed"><code class="xref any py py-func docutils literal notranslate"><span class="pre">set_global_seed()</span></code></a> sets the seed for all Components for which a <a class="reference internal" href="#composition-local-random-seed"><span class="std std-ref">local seed</span></a> has not been specified. This can be used to ensure that, each time the Composition
> is constructed and executed, its Components are assigned the same sequence of random numbers, and therefore any
> results affected by randomization will be the exact same across executions. The call to <a class="reference internal" href="Utilities.html#psyneulink.core.globals.utilities.set_global_seed" title="psyneulink.core.globals.utilities.set_global_seed"><code class="xref any py py-func docutils literal notranslate"><span class="pre">set_global_seed()</span></code></a> must be
> made before construction of a Composition to ensure consistency of randomization.</p>
> <p id="composition-local-random-seed"><strong>Local random seeds.</strong> Individual Components that use random values can be assigned their own seed, by specifying
> it in the <strong>random_seed</strong> argument of the Component’s constructor, or by assigning a value to its <code class="xref any docutils literal notranslate"><span class="pre">seed</span></code> <a class="reference internal" href="Parameters.html#psyneulink.core.globals.parameters.Parameter" title="psyneulink.core.globals.parameters.Parameter"><code class="xref any py py-class docutils literal notranslate"><span class="pre">Parameter</span></code></a>.
> Components assigned their own seed will not be affected by any calls to the <a class="reference internal" href="Utilities.html#psyneulink.core.globals.utilities.set_global_seed" title="psyneulink.core.globals.utilities.set_global_seed"><code class="xref any py py-func docutils literal notranslate"><span class="pre">set_global_seed</span></code></a> function.</p>
> </section>
5973a6006
> <li><a class="reference internal" href="#randomization"><em>Randomization</em></a></li>
diff -r docs-base/Condition.html docs-head/Condition.html
463c463
< satisfied when the <a class="reference internal" href="DDM.html#psyneulink.library.components.mechanisms.processing.integrator.ddm.DDM.is_finished" title="psyneulink.library.components.mechanisms.processing.integrator.ddm.DDM.is_finished"><code class="xref any py py-meth docutils literal notranslate"><span class="pre">is_finished</span></code></a> method of the specified node,       given <a class="reference internal" href="Context.html#psyneulink.core.globals.context.Context.execution_id" title="psyneulink.core.globals.context.Context.execution_id"><code class="xref any py py-attr docutils literal notranslate"><span class="pre">execution_id</span></code></a> returns <code class="xref any docutils literal notranslate"><span class="pre">True</span></code>.</p></li>
---
> satisfied when the <a class="reference internal" href="Component.html#psyneulink.core.components.component.Component.is_finished" title="psyneulink.core.components.component.Component.is_finished"><code class="xref any py py-meth docutils literal notranslate"><span class="pre">is_finished</span></code></a> method of the specified node,       given <a class="reference internal" href="Context.html#psyneulink.core.globals.context.Context.execution_id" title="psyneulink.core.globals.context.Context.execution_id"><code class="xref any py py-attr docutils literal notranslate"><span class="pre">execution_id</span></code></a> returns <code class="xref any docutils literal notranslate"><span class="pre">True</span></code>.</p></li>
465c465
< satisfied when the <a class="reference internal"
...

See CI logs for the full diff.