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, a ‘name’ attribute.
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 :type array: :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