diff --git a/psyneulink/core/compositions/composition.py b/psyneulink/core/compositions/composition.py index 3e923bc6450..f8a455014f5 100644 --- a/psyneulink/core/compositions/composition.py +++ b/psyneulink/core/compositions/composition.py @@ -480,16 +480,22 @@ ~~~~~~~~~~~~~~~~~~~~~~ The `controller ` is executed only if the Composition's `enable_controller -` attribute is True. This generally done automatically when the `controller -` is `assigned `. If enabled, the `controller -` is generally executed either before or after all of the other Components in the Composition -have been executed within a given `TimeScale `, as determined by the Composition's -`controller_time_scale` and `controller_mode ` attributes. The Composition's -`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. - +` attribute is True. This is generally done automatically when the controller is +is `assigned `. If `enabled `, 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 ` has been met, as determined by the +Composition's `controller_mode `, `controller_time_scale +` and `controller_condition ` attributes. By +default, a controller is enabled, and executes after the rest of the Composition (`controller_mode +`\\= *AFTER*) at the end of every trial (`controller_time_scale +`\\= `TimeScale.TRIAL` and `controller_condition ` += `Always()`). However, `controller_mode ` can be used to specify execution of the +controller before the 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 `, +`PASS , or `RUN `); and `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: @@ -1215,7 +1221,7 @@ def input_function(env, result): - *value* - (, `Condition`), , or subdictionary (see below) `Condition` specifies when the value is applied; otherwise, its previously assigned value or `default ` 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 ` for additional details. @@ -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 @@ -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, \ @@ -2967,23 +2974,27 @@ class Composition(Composition_Base, metaclass=ComponentsMeta): `learning mode `. controller : `OptimizationControlMechanism` : default None - specifies the `OptimizationControlMechanism` to use as the Composition's `controller - ` (see `Composition_Controller` for details). + specifies the `OptimizationControlMechanism` to use as the `Composition's controller + `. enable_controller: bool : default None specifies whether the Composition's `controller ` is executed when the - Composition is executed. Set to True by default if **controller** specified; if set to False, - the `controller ` is ignored when the Composition is executed. + Composition is run. Set to True by default if **controller** specified (see `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 ` 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 ` 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 ` is executed, either before or + after the Composition is run as specified by **controller_mode** (see `controller_time_scale + ` for additional details). - controller_condition: Condition : default Always - specifies when the Composition's `controller ` is executed in a trial. + controller_condition: Condition : default Always() + specifies a specific `Condition` for whether the Composition's `controller ` is + executed in a trial (see `controller_condition ` for additional details). retain_old_simulation_data : bool : default False specifies whether or not to retain Parameter values generated during `simulations @@ -2991,9 +3002,9 @@ class Composition(Composition_Base, metaclass=ComponentsMeta): ` for additional details). show_graph_attributes : dict : None - specifies state_features of how the Composition is displayed when its `show_graph ` method - is called or **animate** is specified in a call to its `run ` method (see `ShowGraph` for - list of attributes and their values). + specifies state_features of how the Composition is displayed when its `show_graph ` + method is called or **animate** is specified in a call to its `run ` method (see `ShowGraph` + for list of attributes and their values). name : str : default see `name ` specifies the name of the Composition. @@ -3131,18 +3142,25 @@ class Composition(Composition_Base, metaclass=ComponentsMeta): (see `Composition_Controller` for details). enable_controller : bool - determines whether the Composition's `controller ` is executed in each trial - (see controller_mode ` for timing of execution). Set to True by default - if `controller ` is specified. Setting it to False suppresses exectuion of the - `controller `. + determines whether the Composition's `controller ` is executed when the Composition + is run. Set to True by default if `controller ` is specified. Setting it to False + suppresses exectuion of the `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 ` is executed before or after the rest of the + `Composition` when it is run, at the `TimeScale` determined by `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 ` is executed, either before or + after the Composition as determined by `controller_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 ` 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, @@ -7472,7 +7490,8 @@ def evaluate( ` attempts to use the entire input set provided to the `run ` method of the `Composition` as input for the call to `run `. If it is not, the `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 ` 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. diff --git a/psyneulink/core/compositions/parameterestimationcomposition.py b/psyneulink/core/compositions/parameterestimationcomposition.py index 06a50d2e1b0..ade8eebb820 100644 --- a/psyneulink/core/compositions/parameterestimationcomposition.py +++ b/psyneulink/core/compositions/parameterestimationcomposition.py @@ -367,10 +367,11 @@ class ParameterEstimationComposition(Composition): OptimizationControlMechanism's `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 ` 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 ` 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 ` method. The latter determines how many full fits of the `model ` are carried out (that is, how many times the ParameterEstimationComposition *itself* is run), whereas **num_trials_per_estimate** determines how many