Quick Reference¶
Sections¶
Conventions¶
The following conventions are used for the names of PsyNeuLink objects and their documentation:
Class (type of object): names use CamelCase (with initial capitalization); the initial mention in a section of documentation is formatted as a link (in colored text) to the documentation for that class;
attribute
ormethod
of a Component or Composition: names use lower_case_and_underscore; appear in asmall box
in documentation;
argument of a method or function: names use lower_case_and_underscore; formatted in boldface in documentation.
KEYWORD: uses UPPER_CASE_AND_UNDERSCORE; italicized in documentation.
Examples:
Appear in boxed insets.
See Naming
for conventions for default and user-assigned names of instances.
Repository Organization¶
The PsyNeuLink “repo” is organized into two major sections:
Core¶
This contains the basic PsyNeuLink objects (described in the next section) that are used to build models and run simulations, and is divided into three subsections: Components (the basic building blocks of PsyNeuLink models), Compositions (objects used to combine Components into models), and Scheduling (used to control execution of the Components within a Composition).
Library¶
This contains extensions based on the Core objects (under Compositions and Components), and PsyNeuLink implementations of published models (under Models). The Library is meant to be extended, and used both to compare different models that address similar neural mechanisms and/or psychological functions, and to integrate these into higher level models of system-level function.
PsyNeuLink Objects¶
Overview¶
The two primary types of objects in PsyNeuLink are Components (basic building blocks) and Compositions (combinations of Components that implement a model). There are four primary types of Components:
Functions are the basic units of computation in PsyNeuLink – every other type of Component in PsyNeuLink
has at least one Function, and sometimes more. They “package” an executable method that is assigned to a Component’s
function
attribute, and used to carry out the computation for which the Component is
responsible.
Mechanisms are the basic units of processing in a PsyNeuLink model. They have one or more Functions that
perform their characteristic operations.
Ports represent the input(s) and output(s) of a Mechanism, and the parameters of its Function(s). Ports
have Functions themselves, that determine the value of the Port, and that can be used to modulate that value for
learning, control and/or gating.
Projections are used to connect Mechanisms and/or nested Compositions, transmit information between them,
and to modulate the value of their Ports.
Mechanisms and Projections are combined to make up a Composition. A Composition can also contain nested
Compositions, that receive and/or send Projections to Mechanisms and/or other nested Compositions. The outermost
Composition constitutes a model, that can be executed using its run
method.
The sections that follow provide a description of the Component types, Composition, and other basic objects in PsyNeuLink.
Components¶
Components are objects that perform a specific function. Every Component has the following core attributes:
function
- performs the core computation of the Component (belongs to a PsyNeuLink Function assigned to the Component’sfunction
attribute);parameter(s) - determine how a Component’s
function
operates;name
- string label that uniquely identifies the Component.
The four types of Components in PsyNeuLink – Functions, Mechanisms, Projections, and Ports – are described below:
- Functions
A Function is the most fundamental unit of computation in PsyNeuLink. Every Component has a Function object, that wraps a callable object (usually an executable function) together with attributes for its parameters. This allows parameters to be maintained from one call of a function to the next, for those parameters to be subject to modulation by ModulatoryProjections (see below), and for Functions to be swapped out for one another or replaced with customized ones. PsyNeuLink provides a library of standard Functions (e.g. for linear, non-linear, and matrix transformations, integration, and comparison), as well as a standard Application Programmers Interface (API) or creating new Functions that can be used to “wrap” any callable object that can be written in or called from Python.
- Mechanisms
A Mechanism takes one or more inputs received from its afferent Projections, uses its
function
to combine and/or transform these in some way, and makes the output available to other Components. There are two primary types of Mechanisms in PsyNeuLink: ProcessingMechanisms and ModulatoryMechanisms:- ProcessingMechanism
Aggregates the inputs it receives from its afferent Projections, transforms them in some way, and provides the result as output to its efferent Projections. Subtypes implement various types of opearations, such as intergration and comparison.
- ModulatoryMechanism
Uses the input it receives from other Mechanisms to modify the parameters of one or more other PsyNeuLink Components. There are two primary types:
- ControlMechanism
Modifies the parameters, inputs and/or outputs of other Mechanisms. Subtypes are specialized for operations such as optimization (e.g., OptimizationControlMechanism) or gating (Gating Mechanism).
- LearningMechanism
Modifies the matrix of a MappingProjection. Subtypes are specialized for autoassociative (e.g., Hebbian) learning, and various supervised learning algorithms (e.g., reinforcement and backprogation).
- Projections
A Projection takes the output of a Mechanism, and transforms it as necessary to provide it as the input to another Component. There are two types of Projections, that correspond to the two types of Mechanisms:
- PathwayProjection
Used in conjunction with ProcessingMechanisms to convey information along a processing pathway. There is currently one on type of PathwayProjection:
MappingProjection Takes the value of the OutputPort of one Mechanism, and converts it as necessary to provide it as the variable for the InputPort of another Mechanism.
- ModulatoryProjection
Used in conjunction with ModulatoryMechanisms to regulate the functioning of one or more other Components. Takes the output of a ModulatoryMechanism and uses it to modify the input, parameters, and/or output of another Component. There are two primary types of ModulatoryProjections, corresponding to the two types of ModulatoryMechanisms (see figure):
- ControlProjection
Takes a ControlSignal from a ControlMechanism and uses it to modify the input, parameter and/or output of a ProcessingMechanism. A GatingProjection is a subtype,that is specialized for modulating the input or output of a Mechanism.
- LearningProjection
Takes a LearningSignal from a LearningMechanism and uses it to modify the matrix of a MappingProjection.
- Ports
A Port is a Component that belongs to a Mechanism or a Projection. For Mechanisms, it is used to represent it input(s), the parameter(s) of its function, or its output(s) (see figure). For Projections, it is used to represent the the parameter(s) of its function. There are three types of Ports, one for each type of information, as described below. A Port can receive and/or send PathwayProjections and/or ModulatoryProjections, depending on its type (see figure).
- InputPort
Represents a set of inputs to a Mechanism. Receives one or more afferent PathwayProjections to a Mechanism, combines them using its
function
, and assigns the result (itsvalue
)as an item of the Mechanism’svariable
. It can also receive one or more ControlProjections or GatingProjections, that modify the parameter(s) of the Port’s function, and thereby the Port’svalue
.
- ParameterPort
Represents a parameter of the
function
of a Mechanism or Projection. Takes the assigned value of the parameter as thevariable
for the Port’sfunction
, and assigns the result as the value of the parameter used by the Mechanism’sfunction
when the Componet executes. It can also receive one or more ControlProjections that modify parameter(s) of the Port’sfunction
of the Mechanism or Projection.
- OutputPort
Represents an output of a Mechanism. Takes an item of the Mechanism’s
value
as thevariable
for the Port’sfunction
, assigns the result as the Port’svalue
, and provides that to one or more efferent PathwayProjections. It can also receive one or more ControlProjections or GatingProjections, that modify parameter(s) of the Port’s function, and thereby the Port’svalue
.
Compositions¶
A Composition is made up of one more Mechanisms and/or nested Compositions, connected by Projections. A Composition
is created by first calling its constructor and then using its add methods to add Components.
Every Composition has a graph
attribute, in which each Mechanism or nested Composition is a
node and each Projection is a directed edge. The graph defines the default flow of computation (from each node to
the ones to which it projects)when it is executed using its run
method, that may be modified by
Conditions assigned to the Composition’s scheduler
(see
below. The graph can be displayed using the Composition’s show_graph
method, an example of which is shown in the following figure:
Scheduling¶
PsyNeuLink Mechanisms can be executed on their own. However, usually they are executed as part of a Composition to
which they belong, when that is executed using its run
method. When a Composition is run
, its Components are executed under the control of its scheduler
. This
is a Scheduler, that executes the Composition iteratively in rounds of execution referred to as a PASS
, in which
each node (Mechanism and/or nested Composition) in the Composition’s graph
is given an
opportunity to execute. By default, each node executes exactly once per PASS
, in the order determined by the edges
(Projections) between them. However, the Scheduler can be used to specify one or more Conditions for each node that determine whether it executes in a given PASS
. This can be
used to determine when a node begins and/or ends executing, how many times it executes or the frequency with
which it executes relative to other nodes, and any other dependency that can be expressed in terms of the
attributes of other Components in PsyNeuLink. Using a Scheduler and a combination of pre-specified and custom Conditions, any pattern of execution can be configured
that is logically possible.
A Composition continues to execute PASS
es until its TRIAL
termination Condition is met, which constitutes a TRIAL
of executions. This is associated with a
single input to the Composition. Multiple TRIAL
s (corresponding to a sequences of inputs) can be executed using a
Composition’s run
method.
Logging¶
PsyNeuLink supports logging of any attribute of any Component or Composition under various specified
conditions. Logs are dictionaries, with an entry for each Component being logged. The key for each entry is
the name of the Component, and the value is a record of the Component’s value
recorded under the
conditions specified by its logPref
attribute, specified as a LogLevel
; each record is a
tuple, the first item of which is a time stamp (the TIME_STEP
of the RUN
), the second a string indicating the
context in which the value was recorded, and the third the value
itself.
Graphic Display¶
At the moment, PsyNeuLink has limited support for graphic displays: the graph of a Composition can be displayed
using its show_graph
method. This can be used to display just the processing components
(i.e., ProcessingMechanisms and MappingProjections), or to include
learning and/or control components. A future release will include
a more complete and interacdtive graphical user interface.
Preferences¶
PsyNeuLink supports a hierarchical system of Preferences for all Components and Compositions. Every object has its own set of preferences, as does every class of object. Any preference for an object can be assigned its own value, or the default value for any of its parent classes for that preference (e.g., an instance of a DDM can be assigned its own preference for reporting, or use the default value for ProcessingMechanisms, Mechanisms, or Components. There are preferences for reporting (i.e., which results of processing are printed to the console during execution), logging, levels of warnings, and validation (useful for debugging, but suppressible for efficiency of execution).