Skip to content

Commit

Permalink
Docs/comp ctlmech ocm pec (#2187)
Browse files Browse the repository at this point in the history 
* • component.py
  docstring mod to **size**

* • parameterestimationcomposition.py: docstring edits

* • composition.py: docstring edits

* -

* -

* -
  • Loading branch information
@jdcpni
jdcpni authored Nov 8, 2021
1 parent c1927fb commit 3813c13
Show file tree
Hide file tree
Showing 2 changed files with 56 additions and 36 deletions.
87 changes: 53 additions & 34 deletions psyneulink/core/compositions/composition.py
View file
Original file line number Diff line number Diff line change
Expand Up @@ -480,16 +480,22 @@
~~~~~~~~~~~~~~~~~~~~~~

The `controller <Composition.controller>` is executed only if the Composition's `enable_controller
<Composition.enable_controller>` attribute is True. This generally done automatically when the `controller
<Composition.controller>` is `assigned <Composition_Controller_Assignment>`. If enabled, the `controller
<Composition.controller>` is generally executed either before or after all of the other Components in the Composition
have been executed within a given `TimeScale <TimeScale>`, as determined by the Composition's
`controller_time_scale` and `controller_mode <Composition.controller_mode>` attributes. The Composition's
`controller_condition <Composition.controller_condition>` attribute can be used to further customize when it is
executed. All three of these attributes can be specified in corresponding arguments of the
Composition's constructor, or programmatically after it is constructed by assigning the desired value to the
corresponding attribute.

<Composition.enable_controller>` attribute is True. This is generally done automatically when the controller is
is `assigned <Composition_Controller_Assignment>`. If `enabled <Composition.enable_controller>`, the controller is
executed either before or after all of the other Components in the Composition have been executed at a given
`TimeScale`, and if its specified `Condition <Composition.controller_condition>` has been met, as determined by the
Composition's `controller_mode <Composition.controller_mode>`, `controller_time_scale
<Composition.controller_time_scale>` and `controller_condition <Composition.controller_condition>` attributes. By
default, a controller is enabled, and executes after the rest of the Composition (`controller_mode
<Composition.controller_mode>`\\= *AFTER*) at the end of every trial (`controller_time_scale
<Composition.controller_time_scale>`\\= `TimeScale.TRIAL` and `controller_condition <Composition.controller_condition>`
= `Always()`). However, `controller_mode <Composition.controller_mode>` can be used to specify execution of the
controller before the Composition; `controller_time_scale <Composition.controller_time_scale>` can be used to specify
execution at a particular `TimeScale` (that is at the beginning or end of every `TIME_STEP <TimeScale.TIME_STEP>`,
`PASS <TimeScale._PASS>, or `RUN <TimeScale.RUN>`); and `controller_condition <Composition.controller_condition>` can
be used to specify a particular `Condition` that must be satisified for the controller to execute. Arguments for all
three of these attributes can be specified in the Composition's constructor, or programmatically after it is
constructed by assigning the desired value to the corresponding attribute.

.. _Composition_Learning:

Expand Down Expand Up @@ -1215,7 +1221,7 @@ def input_function(env, result):
- *value* - (<parameter value>, `Condition`), <parameter value>, or subdictionary (see below) `Condition`
specifies when the value is applied; otherwise, its previously assigned value or `default
<Parameter_Defaults>` is used; if the parameter values appears alone in a tuple or outside of one,
then the Condtion `Always` is applied.
then the Condition `Always()` is applied.

See `Runtime Parameter Specification Dictionary <Mechanism_Runtime_Param_Specification>` for additional details.

Expand Down Expand Up @@ -2104,7 +2110,7 @@ def input_function(env, result):
*Runtime Parameters*
~~~~~~~~~~~~~~~~~~~~

If a runtime parameter is meant to be used throughout the `Run`, then the `Condition` may be omitted and the `Always`
If a runtime parameter is meant to be used throughout the `Run`, then the `Condition` may be omitted and the `Always()`
`Condition` will be assigned by default:

>>> import psyneulink as pnl
Expand Down Expand Up @@ -2938,7 +2944,8 @@ class Composition(Composition_Base, metaclass=ComponentsMeta):
controller=None, \
enable_controller=None, \
controller_mode=AFTER, \
controller_condition=Always, \
controller_time_scale=TRIAL \
controller_condition=Always(), \
retain_old_simulation_data=None, \
show_graph_attributes=None, \
name=None, \
Expand Down Expand Up @@ -2967,33 +2974,37 @@ class Composition(Composition_Base, metaclass=ComponentsMeta):
`learning mode <Composition.learn>`.

controller : `OptimizationControlMechanism` : default None
specifies the `OptimizationControlMechanism` to use as the Composition's `controller
<Composition.controller>` (see `Composition_Controller` for details).
specifies the `OptimizationControlMechanism` to use as the `Composition's controller
<Composition_Controller>`.

enable_controller: bool : default None
specifies whether the Composition's `controller <Composition.controller>` is executed when the
Composition is executed. Set to True by default if **controller** specified; if set to False,
the `controller <Composition.controller>` is ignored when the Composition is executed.
Composition is run. Set to True by default if **controller** specified (see `enable_controller
<Composition.enable_controller>` for additional details).

controller_mode: enum.Enum[BEFORE|AFTER] : default AFTER
specifies whether the controller is executed before or after the rest of the Composition
in each run, trial, pass, or time step. Must be either the keyword *BEFORE* or *AFTER*.
specifies whether the `controller <Composition.controller>` is executed before or after the rest of the
Composition when it is run, at the `TimeScale` specified by **controller_time_scale**). Must be either the
keyword *BEFORE* or *AFTER* (see `controller_mode <Compositon.controller_mode>` for additional details).

controller_time_scale: TimeScale[TIME_STEP, PASS, TRIAL, RUN] : default TRIAL
specifies with what frequency the the controller should be executed.
specifies the frequency at which the `controller <Composition.controller>` is executed, either before or
after the Composition is run as specified by **controller_mode** (see `controller_time_scale
<Composition.controller_time_scale>` for additional details).

controller_condition: Condition : default Always
specifies when the Composition's `controller <Composition.controller>` is executed in a trial.
controller_condition: Condition : default Always()
specifies a specific `Condition` for whether the Composition's `controller <Composition.controller>` is
executed in a trial (see `controller_condition <Compositon.controller_condition>` for additional details).

retain_old_simulation_data : bool : default False
specifies whether or not to retain Parameter values generated during `simulations
<OptimizationControlMechanism_Execution>` of the Composition (see `retain_old_simulation_data
<Composition.retain_old_simulation_data>` for additional details).

show_graph_attributes : dict : None
specifies state_features of how the Composition is displayed when its `show_graph <ShowGraph.show_graph>` method
is called or **animate** is specified in a call to its `run <Composition.run>` method (see `ShowGraph` for
list of attributes and their values).
specifies state_features of how the Composition is displayed when its `show_graph <ShowGraph.show_graph>`
method is called or **animate** is specified in a call to its `run <Composition.run>` method (see `ShowGraph`
for list of attributes and their values).

name : str : default see `name <Composition.name>`
specifies the name of the Composition.
Expand Down Expand Up @@ -3131,18 +3142,25 @@ class Composition(Composition_Base, metaclass=ComponentsMeta):
(see `Composition_Controller` for details).

enable_controller : bool
determines whether the Composition's `controller <Composition.controller>` is executed in each trial
(see controller_mode <Composition.controller_mode>` for timing of execution). Set to True by default
if `controller <Composition.controller>` is specified. Setting it to False suppresses exectuion of the
`controller <Composition.controller>`.
determines whether the Composition's `controller <Composition.controller>` is executed when the Composition
is run. Set to True by default if `controller <Composition.controller>` is specified. Setting it to False
suppresses exectuion of the `controller <Composition.controller>` (see `Composition_Controller_Execution`
for additional details, including timing of execution).

controller_mode : BEFORE or AFTER
determines whether the controller is executed before or after the rest of the `Composition`
is executed on each trial.
determines whether the `controller <Composition.controller>` is executed before or after the rest of the
`Composition` when it is run, at the `TimeScale` determined by `controller_time_scale
<Composition.controller_time_scale>` (see `Composition_Controller_Execution` for additional details).

controller_time_scale: TimeScale[TIME_STEP, PASS, TRIAL, RUN] : default TRIAL
deterines the frequency at which the `controller <Composition.controller>` is executed, either before or
after the Composition as determined by `controller_mode <cComposition.ontroller_mode>` (see
`Composition_Controller_Execution` for additional details).

controller_condition : Condition
specifies whether the controller is executed in a given trial. The default is `Always`, which
executes the controller on every trial.
determines whether the `controller <Composition.controller>` is executed in a given trial. The
default is `Always()`, which executes the controller on every trial (see `Composition_Controller_Execution`
for additional details).

default_execution_id
if no *context* is specified in a call to run, this *context* is used; by default,
Expand Down Expand Up @@ -7472,7 +7490,8 @@ def evaluate(
<Composition.controller>` attempts to use the entire input set provided to the `run <Composition.run>`
method of the `Composition` as input for the call to `run <Composition.run>`. If it is not, the `controller
<Composition.controller>` uses the inputs slated for its next or previous execution, depending on whether the
`controller_mode` of the `Composition` is set to `before` or `after`, respectively.
`controller_mode <Composition.controller_mode>` of the `Composition` is set to `before` or `after`,
respectively.

.. note::
Block simulation can not be used if the Composition's stimuli were specified as a generator.
Expand Down
5 changes: 3 additions & 2 deletions psyneulink/core/compositions/parameterestimationcomposition.py
View file
Original file line number Diff line number Diff line change
Expand Up @@ -367,10 +367,11 @@ class ParameterEstimationComposition(Composition):
OptimizationControlMechanism's `evaluate_agent_rep <OptimizationControlMechanism.evaluate_agent_rep>` method.
If it is None (the default), then either the number of **inputs** or the value specified for **num_trials** in
the ParameterEstimationComposition's `run <ParameterEstimationComposition.run>` method used to determine the
number of trials executed (see `Composition_Execution_Num_Trials` for additional information).
number of trials executed (see `number of trials <Composition_Execution_Num_Trials>` for additional
information).
.. _note::
Note that **num_trials_per_estimate** is distinct from the **num_trials** argument of the
The **num_trials_per_estimate** is distinct from the **num_trials** argument of the
ParameterEstimationComposition's `run <Composition.run>` method. The latter determines how many full fits
of the `model <ParameterEstimationComposition.model>` are carried out (that is, how many times the
ParameterEstimationComposition *itself* is run), whereas **num_trials_per_estimate** determines how many
Expand Down

0 comments on commit 3813c13

Please sign in to comment.