Preferences

[DOCUMENTATION COMING…]

class psyneulink.globals.preferences.ComponentPreferenceSet(owner=None, prefs=None, level=<PreferenceLevel.SYSTEM: 5>, name=None, context=None, **kargs)

Implement and manage PreferenceSets for Component class hierarchy

Description:
Implement the following preferences:
  • verbose (bool): enables/disables reporting of (non-exception) warnings and system function
  • paramValidation (bool): enables/disables run-time validation of the execute method of a Function object
  • reportOutput (bool): enables/disables reporting of execution of execute method
  • log (bool): sets LogCondition for a given Component
  • functionRunTimeParams (Modulation): uses run-time params to modulate execute method params
Implement the following preference levels:
  • SYSTEM: System level default settings (Function.classPreferences)
  • CATEGORY: category-level default settings:
    Mechanism.classPreferences State.classPreferences Projection.classPreferences Function.classPreferences
  • TYPE: type-level default settings (if one exists for the category, else category-level settings are used):
    MechanismTypes:
    ControlMechanism.classPreferences ProcessingMechanism.classPreferences
    State types:
    InputState.classPreferences ParameterState.classPreferences OutputState.classPreferences
    Projection types:
    ControlProjection.classPreferences MappingProjection.classPreferences
  • SUBTYPE: subtype-level default settings (if one exists for the type, else type-level settings are used):
    ControlMechanism subtypes:
    DefaultControlMechanism.classPreferences EVCControlMechanism.classPreferences
    ProcessingMechanism subtypes:
    DDM.classPreferences Linear.classPreferences SigmoidLayer.classPreferences IntegratorMechanism.classPreferences
  • INSTANCE: returns the setting specified in the PreferenceSetEntry of the specified object itself
Initialization arguments:
  • owner (Function object): object to which the PreferenceSet belongs; (default: DefaultProcessingMechanism)
    Note: this is used to get appropriate default preferences (from class) for instantiation;

    however, since a PreferenceSet can be assigned to multiple objects, when accessing the preference the owner is set dynamically, to insure context-relevant PreferenceLevels for returning the setting

  • prefs (dict): a specification dict, each entry of which must have a:
    key that is a keypath (kp<*>) corresponding to an attribute of the PreferenceSet, from the following set:
    • kwPreferenceSetName: specifies the name of the PreferenceSet
    • kpVerbosePref: print non-exception-related information during execution
    • kpParamValidationPref: validate parameters during execution
    • kpReportOutputPref: report object’s ouptut during execution
    • kpLogPref: record attribute data for the object during execution
    • kpRuntimeParamModulationPref: modulate parameters using runtime specification (in pathway)
    • kpRuntimeParamStickAssignmentPref: assignments remain in effect until replaced

    value that is either a PreferenceSet, valid setting for the preference, or a PreferenceLevel; defaults

  • level (PreferenceLevel): ??

  • name (str): name of PreferenceSet

  • context (value): must be self (to call super’s abstract class: PreferenceSet)

  • **kargs (dict): dictionary of arguments, that takes precedence over the individual args above

Class attributes:
  • defaultPreferencesDict (PreferenceSet): SystemDefaultPreferences
  • baseClass (class): Function
Class methods:

Note: * All of the setters below use PreferenceSet.set_preference, which validates any preference info passed to it,

and can take a PreferenceEntry, setting, or PreferenceLevel
  • verbosePref():
    returns setting for verbosePref preference at level specified in verbosePref PreferenceEntry of
    owner’s PreferenceSet
  • verbosePref(setting=<value>):
    assigns the value of the setting arg to the verbosePref of the owner’s PreferenceSet
  • paramValidationPref():
    returns setting for paramValidationPref preference at level specified in paramValidationPref PreferenceEntry of owner’s PreferenceSet
  • paramValidationPref(setting=<value>):
    assigns the value of the setting arg to the paramValidationPref of the owner’s PreferenceSet
  • reportOutputPref():
    returns setting for reportOutputPref preference at level specified in reportOutputPref PreferenceEntry of owner’s Preference object
  • reportOutputPref(setting=<value>):
    assigns the value of the setting arg to the reportOutputPref of the owner’s PreferenceSet
  • logPref():
    returns setting for log preference at level specified in log PreferenceEntry of owner’s Preference object
  • logPref(setting=<value>):
    assigns the value of the setting arg to the logPref of the owner’s PreferenceSet
    and, if it contains log entries, it adds them to the owner’s log
  • runtimeParamModulationPref():
    returns setting for runtimeParamModulation preference at level specified in
    runtimeParamModulation PreferenceEntry of owner’s Preference object
  • runtimeParamModulationPref(setting=<value>):
    assigns the value of the setting arg to the runtimeParamModulationPref of the owner’s Preference object
  • runtimeParamStickyAssignmentPref():
    returns setting for runtimeParamStickyAssignment preference at level specified in
    runtimeParamStickyAssignment PreferenceEntry of owner’s Preference object
  • runtimeParamStickyAssignmentPref(setting=<value>):
    assigns value of the setting arg to the runtimeParamStickyAssignmentPref of the owner’s Preference object
logPref

Return setting of owner’s logPref at level specified in its PreferenceEntry.level :param level: :return:

paramValidationPref

Return setting of owner’s param_validationPref at level specified in its PreferenceEntry.level :param level: :return:

reportOutputPref

Return setting of owner’s reportOutputPref at level specified in its PreferenceEntry.level :param level: :return:

runtimeParamModulationPref

Returns owner’s runtimeParamModulationPref :return:

runtimeParamStickyAssignmentPref

Returns owner’s runtimeParamStickyAssignmentPref :return:

verbosePref

Return setting of owner’s verbosePref at level specified in its PreferenceEntry.level :param level: :return:

class psyneulink.globals.preferences.MechanismPreferenceSet(owner=None, reportOutput_pref=PreferenceEntry(setting=False, level=<PreferenceLevel.INSTANCE: 1>), runtimeParamModulation_pref=PreferenceEntry(setting=<function Modulation.<lambda>>, level=<PreferenceLevel.INSTANCE: 1>), log_pref=PreferenceEntry(setting=False, level=<PreferenceLevel.INSTANCE: 1>), verbose_pref=PreferenceEntry(setting=False, level=<PreferenceLevel.INSTANCE: 1>), param_validation_pref=PreferenceEntry(setting=False, level=<PreferenceLevel.INSTANCE: 1>), level=<PreferenceLevel.SYSTEM: 5>, name=None, **kargs)

Extends ComponentPreferenceSet to include Mechanism-specific preferences

Description:
Implements the following preference:
  • runtimeParamModulation (bool): uses specification of run-time params to update execute method params
Class methods:
  • runtimeParamModulationPref():
    returns setting for runtimeParamModulation preference at level specified in runtimeParamModulation PreferenceEntry of owner’s Preference object
  • runtimeParamModulationPref(setting=<value>):
    assigns the value of the setting item in the runtimeParamModulationPref PreferenceEntry of the owner’s Preference object
  • runtimeParamModulationPrefLevel()
    returns level in the runtimeParamModulationPref PreferenceEntry of the owner’s Preference object
  • runtimeParamModulationPrefLevel(level=<PreferenceLevel>):
    assigns the value of the level item in the runtimeParamModulationPref PreferenceEntry of the owner’s Preference object
  • runtimeParamModulationPrefEntry():
    assigns PreferenceEntry to runtimeParamModulationPref attribute of the owner’s Preference object
  • runtimeParamModulationPrefEntry(entry=<PreferenceEntry>):
    returns PreferenceEntry for the runtimeParamModulationPref attribute of the owner’s Preference object
  • RuntimeParamStickyAssignmentPref():
    returns setting for runtimeParamStickyAssignment preference at level specified in runtimeParamStickyAssignment PreferenceEntry of owner’s Preference object
  • RuntimeParamStickyAssignmentPref(setting=<value>):
    assigns the value of the setting item in the RuntimeParamStickyAssignmentPref PreferenceEntry of the owner’s Preference object
  • RuntimeParamStickyAssignmentPrefLevel()
    returns level in the RuntimeParamStickyAssignmentPref PreferenceEntry of the owner’s Preference object
  • RuntimeParamStickyAssignmentPrefLevel(level=<PreferenceLevel>):
    assigns the value of the level item in the RuntimeParamStickyAssignmentPref PreferenceEntry of the owner’s Preference object
  • RuntimeParamStickyAssignmentPrefEntry():
    assigns PreferenceEntry to RuntimeParamStickyAssignmentPref attribute of the owner’s Preference object
  • RuntimeParamStickyAssignmentPrefEntry(entry=<PreferenceEntry>):
    returns PreferenceEntry for the RuntimeParamStickyAssignmentPref attribute of the owner’s Preference object
runtimeParamModulationPref

Returns setting of owner’s runtimeParamModulation pref at level specified in its PreferenceEntry.level :param level: :return:

runtimeParamModulationPrefEntry

Returns owner’s runtimeParamModulation PreferenceEntry tuple (setting, level) :return:

runtimeParamModulationPrefLevel

Returns level for owner’s runtimeParamModulation pref :return:

runtimeParamStickyAssignmentPref

Returns setting of owner’s runtimeParamStickyAssignment pref at level specified in its PreferenceEntry.level :param level: :return:

runtimeParamStickyAssignmentPrefEntry

Returns owner’s runtimeParamStickyAssignment PreferenceEntry tuple (setting, level) :return:

runtimeParamStickyAssignmentPrefLevel

Returns level for owner’s runtimeParamStickyAssignment pref :return:

class psyneulink.globals.preferences.PreferenceEntry(setting, level)
level

Alias for field number 1

setting

Alias for field number 0

class psyneulink.globals.preferences.PreferenceLevel

An enumeration.

class psyneulink.globals.preferences.PreferenceSet(owner, level=<PreferenceLevel.SYSTEM: 5>, prefs=None, name=None, context=None)

Abstract class for PreferenceSets that stores preferences and provides access to level-specific settings

Description:

Each PreferenceSet object stores a set of preferences in its corresponding attributes Every class in the Component hierarchy is assigned a PreferenceLevel:

  • System: reserved for the Component class
  • Category: primary function subclasses (e.g., Process, Mechanism, State, Projection, Function)
  • Type: Category subclasses (e.g., MappingProjection and ControlProjection subclasses of Projection, Function subclasses)
  • Instance: an instance of an object of any class
Each class level in a hierarchy should be assigned a PreferenceSet object as a class attribute,
that specifies default settings at that class-level for objects in that class and its subclasses
Each attribute of a PreferenceSet object is a PreferenceEntry (setting, level) tuple for a preference:
  • setting (value):
    specifies the setting of the preference for the class or object to which the PreferenceSet belongs
  • level (PreferenceLevel):
    there are four levels used to specify default settings at four levels of the class hierarchy,
    SYSTEM, CATEGORY, TYPE, and INSTANCE
    specifying a given level in PreferenceEntry will cause the value assigned at that level
    to be returned when a request is made for the value of the setting for that preference
PreferenceSets are instantiated using a specification dict; for each entry:

the key must be a keyPath for a preference attribute (kpReportOutput, kpLog, kpVerbose, kpParamValidation) the value must be either:

a PreferenceEntry, or a value that is valid for the setting of the corresponding attribute, or a PreferenceLevel
PreferenceSet attributes MUST have “_pref” as a substring in their attribute name,
as this is used by the PreferenceSet.show() method (and possibly others in the future) to identify PreferenceSet preference attributes
Any preference attributes defined by a subclass (in its defaultPreferencesDict - see below), but not specified
in the dict of the prefs arg, will be assigned a default PreferenceEntry from defaultPreferencesDict dict
PreferenceSet.logPref settings must be assigned a value from a LogEntry class:
  • Globals.Log defines a LogEntry class that can be used

  • classes can define their own LogEntry class; however:

    every definition of LogEntry must include all of the attributes of Globals.Log.LogEntry those attributes must have a value identical to the one in Globals.Log.LogEntry,

    with the exception of ALL and DEFAULTS (which can vary for different versions of LogEntry)

    assignments from a LogEntry class other than the one in Globals.Log

    MUST be from one declared in the same module as the object that owns the PreferenceSet

SUBCLASSES of PreferenceSet: Every subclass of PreferenceSet must define a class attribute called defaultPreferencesDict:

  • this must be a dict, with an entry for each preference attribute used by subclass; each entry must have:
    a key that is the name of the instance variable for the corresponding preference attribute a value that is a PreferenceEntry specifying the default setting and level for that preference
  • this will be used if no prefs arg is provided to PreferenceSet.__init__, or if any preferences are missing
Every subclass of PreferenceSet must define a class attribute called baseClass:
  • this must be a class, that is at the base of the hierarchy for which the PreferenceSet will be used
  • this is used to validate PreferenceSet assignments to other classes and objects in the class hierarchy and when searching the hierarchy in get_pref_setting_for_level
[TBI: Deprecated PreferenceSet subclasses; not useful, too complicated; only implemented MechanismPreferenceSet
Subclasses of PreferenceSet can be created to define preferences specific to subclasses of Function
  • subclasses of PreferenceSet inherit all the preference attributes above it in the hierarchy
  • however, the level assigned in a PreferenceEntry cannot exceed the level in the PreferenceSet hiearchy
    at which the preference is defined; this is checked and, if the level being assigned is too high, a warning message is generated (irrespective of any verbose preferences), and the highest level allowable (i.e., the one at which the preference is defined) is used instead]
Preference attributes added to a subclass of PreferenceSet MUST have “_pref” as a substring in their name,
as this is used by the PreferenceSet.show() method (and possibly others in the future) to identify PreferenceSet preference attributes
Initialization arguments:
  • owner (Function object):

    used on instantiation to determine the level of the default preferences; assigned dynamically (by the baseClass) on access to a preference;

    this is because a PreferenceSet can be assigned to multiple objects, so current owner should be used to determine context-appropriate PreferenceLevel for returning setting

  • level (PreferenceLevel): level for which to report setting (default: PreferenceLevel.SYSTEM)

  • prefs (dict): see above for keys and entries

  • name (str): name of PreferenceSet (default: <subclass.__name__>

  • context (class): must be a subclass of PreferenceSet; otherwise, an exception is raised

Note: * instantiation always returns a complete PreferenceSet (as defined by the subclass)

Class attributes:
  • prefsList (list): list of preference attribute names in PreferenceSet (== PreferenceSet.__dict__.keys();
Class methods:
  • add_preference(pref_attrib=<str>, pref_spec=<value>, default_pref=<PreferenceEntry>):

    create preference attribute for PreferenceSet and assign pref_spec as its value

  • get_pref_setting_for_level(pref_ivar_name=<str>, level=<PreferenceLevel>):

    return setting for specified preference at level specified if level is omitted, return setting for level specified in instance’s PreferenceEntry

  • show():
    generate table showing all preference attributes for the PreferenceSet, their base and current and values,

    and their PreferenceLevel assignment

  • set_preference(candidate_info=<PreferenceEntry, setting or PreferenceLevel>,

    default_entry=<PreferenceEntry>, setting_types=<[types]> pref_ivar_name=<str>):

    set specified value of PreferenceEntry attribute (entire PreferenceEntry. setting or level)

  • validate_setting(candidate_setting=<value>, reference_setting=<value>, pref_ivar_name=<str>)

    validate value of setting for pref_ivar_name attribute of PreferenceSet

  • validate_log(candidate_log_item=<LogEntry.<value>>, pref_set=<PreferenceSet>)

    validate that value of kplogPref (_log_pref_) is from conforming and appropriate LogEntry class

Instance attributes:
None
Instance methods:
None
get_pref_setting_for_level(pref_ivar_name, requested_level=None)

Return the setting of a preference for a specified preference level, and any error messages generated

Arguments: - pref_ivar_name (str): name of ivar for preference attribute for which to return the setting; - requested_level (PreferenceLevel): preference level for which the setting should be returned

Returns: - PreferenceEntry.setting, str:

set_preference(candidate_info, pref_ivar_name, default_entry=None)

Validate and assign PreferenceSet, setting, or level to a PreferenceSet preference attribute

Validate candidate candidate_info and, if OK, assign to pref_ivar_name attribute; candidate_info can be a:
  • PreferenceEntry; validate both the setting and PreferenceLevel items
  • setting; validate against current value retrieved from pref_ivar_name
  • PreferenceLevel; type-check
If default_entry is provided, it must be a PreferenceEntry;
use it to validate candidate_info, and fill any invalid or missing values;
If default_entry is not provided, there must be a current entry for PreferenceSet;
otherwise an exception will be raised
Return a PreferenceEntry containing the validated information;
  • this is NOT necessarily the full current PreferenceEntry for the pref;
  • it contains only the information passed in candidate_info (e.g., setting or PreferenceLevel could be None)
  • it is provided simply as parse of candidate_info for the convenience of the caller (e.g., logPref.setter)
Note: pref_ivar_name MUST include the underscore prefix (e.g., _log_pref), else a recursive loop will ensue
(wherein the setter calls set_preference, which calls the setter for the pref, etc).
Parameters:
  • candidate_info – (PreferenceEntry, value, or PreferenceLevel)
  • pref_ivar_name – (str)
  • reference_value – ([types])
Return assignment:
 

(PreferenceEntry)

show(type=None)

Print preferences for PreferenceSet

Returns:
validate_log(candidate_log_item, pref_set)

Validate value of log setting and that it is from the LogEntry class associated with the owner of the preference

Parameters:
  • candidate_log_item
  • pref_set
Returns:

validate_setting(candidate_setting, reference_setting, pref_ivar_name)

Validate candidate_setting by checking against reference_setting and, if a log_entry, its type

Parameters:
  • candidate_setting
  • reference_setting
Returns: