EVCAuxiliary¶
Auxiliary functions for EVCControlMechanism.

class
psyneulink.library.subsystems.evc.evcauxiliary.
ValueFunction
(function=None)¶ Calculate the EVC for a given performance outcome and set of costs.
ValueFunction takes as its arguments an outcome (a value representing the performance of a System) and list of costs (each reflecting the
cost
of a ControlSignal of thecontroller System.controller
of that System), and returns an expected value of control (EVC) based on these (along with the outcome and aggregation of costs used to calculate the EVC).ValueFunction is the default for an EVCControlMechanism’s
value_function
attribute, and it is called byControlSignalGridSearch
(the EVCControlMechanism’s defaultfunction
).The ValueFunction’s default
function
calculates the EVC using the result of thefunction <ObjectiveMechanism.function
of the EVCControlMechanism’sobjective_mechanism
, and two auxiliary functions specified in corresponding attributes of the EVCControlMechanism:cost_function
andcombine_outcome_and_cost_function
. The calculation of the EVC provided by ValueFunction can be modified by customizing or replacing any of these functions, or by replacing the ValueFunction’sfunction
itself (in the EVCControlMechanism’svalue_function
attribute). Replacement functions must use the same format (number and type of items) for its arguments and return values (see note).
function
(controller, outcome, costs)¶ Calculate the EVC as follows:
 call the
cost_function
for the EVCControlMechanism specified in the controller argument, to combine the list of costs specified in the costs argument into a single cost value;  call the
combine_outcome_and_cost_function
for the EVCControlMechanism specified in the controller argument, to combine the value specified in the outcome argument with the value returned by thecost_function
;  return the results in a three item tuple: (EVC, outcome and cost).
Parameters:  controller (EVCControlMechanism) – the EVCControlMechanism for which the EVC is to be calculated; this is required so that the controller’s
cost_function
andcombine_outcome_and_cost_function
functions can be called.  outcome (value : default float) – should represent the outcome of performance of the System for which an
allocation_policy
is being evaluated.  costs (list or array of values : default 1d np.array of floats) – each item should be the
cost
of one of the controller’s ControlSignals.
Returns: (EVC, outcome, cost)
Return type: Tuple(float, float, float)
 call the


class
psyneulink.library.subsystems.evc.evcauxiliary.
ControlSignalGridSearch
(default_variable=None, params=None, function=None, owner=None, context=None)¶ Conduct an exhaustive search of allocation polices and return the one with the maximum EVC.
This is the default
function
for an EVCControlMechanism. It identifies theallocation_policy
with the maximum EVC by a conducting a grid search over every possibleallocation_policy
given theallocation_samples
specified for each of its ControlSignals (i.e., the Cartesian product of theallocation
values specified by theallocation_samples
attribute of each ControlSignal). The full set of allocation policies is stored in the EVCControlMechanism’scontrol_signal_search_space
attribute. The EVCControlMechanism’srun_simulation
method is used to simulate itssystem
under eachallocation_policy
incontrol_signal_search_space
, calculate the EVC for each of those policies, and return the policy with the greatest EVC. By default, only the maximum EVC is saved and returned. However, setting thesave_all_values_and_policies
attribute toTrue
saves each policy and its EVC for each simulation run (in the EVCControlMechanism’sEVC_policies
andEVC_values
attributes, respectively). The EVC is calculated for each policy by iterating over the following steps: Select an allocation_policy:
draw a successive item from
control_signal_search_space
in each iteration, and assign each of its values as theallocation
value for the corresponding ControlSignal for that simulation of thesystem
.
 Simulate performance:
execute the
system
under the selectedallocation_policy
using the EVCControlMechanism’srun_simulation
method, and thevalue
s of itsprediction_mechanisms
as the input to thesystem
; these use the history of previous trials to generate an average expected input for eachORIGIN
Mechanism of thesystem
.
 Calculate the EVC:
call the EVCControlMechanism’s
value_function
to calculate the EVC for the current iteration, using three values (see Function for additional details): the EVCControlMechanism’s
input
, which is the result of itsobjective_mechanism
’sfunction
) and provides an evaluation of the outcome of processing in thesystem
under the currentallocation_policy
;
 the result of the
cost
function, called by thevalue_function
, that returns the cost for theallocation_policy
based on the currentcost
associated with each of its ControlSignals;
 the result of the
combine
function, called by thevalue_function
, that returns the EVC by subtracting the cost from the outcome
 the EVCControlMechanism’s
 Save the values:
if the
save_all_values_and_policies
attribute isTrue
, save allocation policy in the EVCControlMechanism’sEVC_policies
attribute, and its value is saved in theEVC_values
attribute; otherwise, retain only maximum EVC value.
The ControlSignalGridSearch function returns the
allocation_policy
that yielded the maximum EVC. Its operation can be modified by customizing or replacing any or all of the functions referred to above (also see Function).
function
(controller=None, variable=None, runtime_params=None, params=None, context=None)¶ Grid search combinations of control_signals in specified allocation ranges to find one that maximizes EVC
 Called by ControlSignalGridSearch.
 Call System.execute for each
allocation_policy
incontrol_signal_search_space
.  Store an array of values for output_states in
monitored_output_states
 (i.e., the input_states in
input_states
) for eachallocation_policy
.
 Store an array of values for output_states in
 Call
_compute_EVC
for each allocation_policy to calculate the EVC, identify the maximum,  and assign to
EVC_max
.
 Call
 Set
EVC_max_policy
to theallocation_policy
(outputState.values) corresponding to EVC_max.  Set value for each control_signal (outputState.value) to the values in
EVC_max_policy
.  Return an allocation_policy.
Note: * runtime_params is used for self.__execute (that calculates the EVC for each call to System.execute);
 it is NOT used for System.execute – that uses the runtime_params provided for the Mechanisms in each
 Process.configuration
Return (2D np.array): value of outputState for each monitored state (in self.input_states) for EVC_max