Utilities

Utilities that must be accessible to all PsyNeuLink modules, but are not PsyNeuLink-specific

That is:

do not require any information about PsyNeuLink objects are not constrained to be used by PsyNeuLink objects

********************************************* UTILITIES ********************************************************

CONTENTS

• deprecation_warning

TYPE CHECKING VALUE COMPARISON

Note

PsyNeuLink-specific typechecking functions are in the Component module

• parameter_spec

• optional_parameter_spec

• all_within_range

• `is_matrix

• is_matrix_spec

• is_numeric

• is_numeric_or_none

• is_iterable

• iscompatible

• is_value_spec

• is_unit_interval

• is_same_function_spec

• is_component

• is_comparison_operator

ENUM

• Autonumber

• Modulation

• get_modulationOperation_name

KVO

Note

This is for potential future use; not currently used by PsyNeuLink objects

• observe_value_at_keypath

MATHEMATICAL

• norm

• sinusoid

• scalar_distance

• powerset

• tensor_power

LIST MANAGEMENT

• insert_list

• convert_to_list

• flatten_list

• nesting_depth

OTHER

• get_args

• recursive_update

• multi_getattr

• np_array_less_that_2d

• convert_to_np_array

• type_match

• get_value_from_array

• is_matrix

• underscore_to_camelCase

• append_type_to_name

• ReadOnlyOrderedDict

• ContentAddressableList

• make_readonly_property

• get_class_attributes

• set_global_seed

private-members:

exclude-members:

parameter_spec,optional_parameter_spec,all_within_range,is_matrix, is_matrix_spec,iscompatible,is_value_spec, is_unit_interval, is_same_function_spec, is_component,is_comparison_operator,Modulation,get_modulationOperation_name, observe_value_at_keypath,insert_list,get_args,multi_getattr,type_match,append_type_to_name,make_readonly_property,get_class_attributes,get_global_seed,

class psyneulink.core.globals.utilities.ContentAddressableList(component_type, key=None, list=None)

Implements dict-like list, that can be keyed by a specified attribute of the Compoments in its entries. If called, returns list of items.

Instance is callable (with no arguments): returns list of its items.

The key with which it is created is also assigned as a property of the class, that returns a list with the keyed attribute of its entries. For example, the output_ports attribute of a Mechanism is a ContentAddressableList of the Mechanism’s OutputPorts, keyed by their names. Therefore, my_mech.output_ports.names returns the names of all of the Mechanism’s OutputPorts:

>>> import psyneulink as pnl
>>> print(pnl.DDM().output_ports.names)
['DECISION_VARIABLE', 'RESPONSE_TIME']

The keyed attribute can also be used to access an item of the list. For examples:

>>> print(pnl.DDM().output_ports['DECISION_VARIABLE'])
(OutputPort DECISION_VARIABLE)

Supports:

• getting and setting entries in the list using keys (string), in addition to numeric indices. the key to use is specified by the key arg of the constructor, and must be a string attribute; * for getting an entry:

  the key must match the keyed attribute of a Component in the list; otherwise an exception is raised;

  • for setting an entry:

    • the key must match the key of the component being assigned;

    • if there is already a component in the list the keyed vaue of which matches the key, it is replaced;

    • if there is no component in the list the keyed attribute of which matches the key, the component is appended to the list;

  • for getting lists of the names, values of the keyed attributes, and values of the value

    attributes of components in the list.

IMPLEMENTATION NOTE:

This class allows Components to be maintained in lists, while providing ordered storage and the convenience of access and assignment by name (e.g., akin to a dict). Lists are used (instead of a dict or OrderedDict) since:

• ordering is in many instances convenient, and in some critical (e.g., for consistent mapping from

  collections of ports to other variables, such as lists of their values);

• they are most commonly accessed either exhaustively (e.g., in looping through them during execution),

  or by key (e.g., to get the first, “primary” one), which makes the efficiencies of a dict for accessing by key/name less critical;

• the number of ports in a collection for a given Mechanism is likely to be small so that, even when

  accessed by key/name, the inefficiencies of searching a list are likely to be inconsequential.

Parameters:

• component_type (Class) – specifies the class of the items in the list.

• name (str : 'ContentAddressableList') – name to use for ContentAddressableList

• key (str : default name) – specifies the attribute of component_type used to key items in the list by content; component_type must have this attribute or, if it is not provided, an attribute with the name ‘name’.

• list (List : default None) – specifies a list used to initialize the list; all of the items must be of type component_type and have the key attribute.

component_type

the class of the items in the list.

Type:

Class

name

name if provided as arg, else name of of ContentAddressableList class

Type:

str

key

the attribute of component_type used to key items in the list by content;

Type:

str

data

the actual list of items.

Type:

List (property)

names

values of the name attribute of components in the list.

Type:

List (property)

key_values

values of the keyed attribute of each component in the list.

Type:

List (property)

values

values of the value attribute of components in the list.

Type:

List (property)

clear() → None -- remove all items from S

property names

Return list of values of the name attribute of components in the list. :returns: names – list of the values of the name attributes of components in the list. :rtype: list

property key_values

Return list of values of the keyed attribute of components in the list. :returns: key_values – list of the values of the keyed attributes of components in the list. :rtype: list

get_key_values(context=None)

Return list of values of the keyed parameter of components in the list. :returns: key_values – list of the values of the keyed

parameter of components in the list for context

Return type:

list

property values

Return list of values of components in the list. :returns: values – list of the values of the value attributes of components in the list. :rtype: list

get_values(context=None)

Return list of values of components in the list. :returns: values – list of the values of the value

parameter of components in the list for context

Return type:

list

property values_as_lists

Return list of values of components in the list, each converted to a list. :returns: values – list of list values of the value attributes of components in the list, :rtype: list

get_values_as_lists(context=None)

Return list of values of components in the list, each converted to a list. :returns: values – list of list values of the value attributes of components in the list, :rtype: list

psyneulink.core.globals.utilities.convert_to_np_array(value, dimension=None)

Converts value to np.ndarray if it is not already. Handles creation of “ragged” arrays (https://numpy.org/neps/nep-0034-infer-dtype-is-object.html)

Parameters:

• value – item to convert to np.ndarray

• dimension – 1, 2, None minimum dimension of np.ndarray to convert to

Returns:

np.ndarray

Return type:

value

psyneulink.core.globals.utilities.get_value_from_array(array)

Extract numeric value from array, preserving numeric type :param array: :return:

psyneulink.core.globals.utilities.is_iterable(x, exclude_str=False)

Parameters:

• x (Any)

• exclude_str (bool, optional) – if True, x of type str will return False. Defaults to False.

Return type:

bool

Returns:

• True - if **x* can be iterated on*

• False - otherwise

psyneulink.core.globals.utilities.powerset([1,2,3]) --> () (1,) (2,) (3,) (1,2) (1,3) (2,3) (1,2,3)

class psyneulink.core.globals.utilities.ReadOnlyOrderedDict(dict=None, name=None, **kwargs)

clear() → None.  Remove all items from D.

pop(k[, d]) → v, remove specified key and return the corresponding value.

If key is not found, d is returned if given, otherwise KeyError is raised.

popitem() → (k, v), remove and return some (key, value) pair

as a 2-tuple; but raise KeyError if D is empty.

keys() → a set-like object providing a view on D's keys

psyneulink.core.globals.utilities.tensor_power(items, levels=None, flat=False)

return tensor product for all members of powerset of items

levels specifies a range of set levels to return; 1=first order terms, 2=2nd order terms, etc. if None, all terms will be returned

if flat=False, returns list of 1d arrays with tensor product for each member of the powerset if flat=True, returns 1d array of values

psyneulink.core.globals.utilities.get_args(frame)

Gets dictionary of arguments and their values for a function Frame should be assigned as follows in the function itself: frame = inspect.currentframe()

psyneulink.core.globals.utilities.recursive_update(d, u, non_destructive=False)

Recursively update entries of dictionary d with dictionary u From: https://stackoverflow.com/questions/3232943/update-value-of-a-nested-dictionary-of-varying-depth

psyneulink.core.globals.utilities.set_global_seed(new_seed)

Set global randomization seed for all Components for which a local seed has not been specified.

Parameters:

new_seed (int) – new seed to use for randomization