A Pathway is a sequence of Nodes and Projections. Generally, Pathways are assigned
to a Compositions, but a Pathway object can also be created on its and used as a template for specifying a Pathway for
a Composition, as described below (see Pathways for additional information about Pathways in
Compositions).
Creating a Pathway
Pathway objects are created in one of two ways, either using the constructor to create a template,
or automatically when a Pathway is assigned to a Composition.
Pathway as a Template
A Pathway created on its own, using its constructor, is a template, that can be used to specify a Pathway for one or more Compositions, as described below;
however, it cannot be executed on its own. When a Pathway object is used to assign a Pathway to a Composition,
its pathway attribute, and its name if that is not otherwise specified (see
below), are used as the specification to create a new Pathway that is assigned to the Composition,
and the template remains unassigned.
Assigning Pathways to a Composition
Pathways can be assigned to a Composition using the pathways argument of the Composition’s constructor, or one of
its Pathway addition methods. A Pathway object can be used, along with any
other form of Pathway specification for those arguments. However, the Pathway object itself
is not assigned to the Composition; rather, it serves as a template for a new Pathway object
that is automatically created and assigned to the Composition. The Composition’s Pathway addition methods return a Pathway object for each Pathway created and assigned to theComposition.
All of the Pathways assigned to a Composition are listed in its pathways attribute.
Pathway Name
If the name argument of the Pathway’s constructor is used to assign it a name, this is used as the name of the
Pathway created when it is assigned to a Composition in its constructor, or using its add_pathways method. This is also the case if one of the Composition’s other Pathway addition methods is used, as long as the name argument of those methods is not specified.
However, if the name argument is specified in those methods, or Pathway specification dictionary is used to specify the Pathway’s name, that takes precedence over, and replaces
one specified in the Pathway template'sname attribute.
Pathway Specification
A Pathway is specified as a list, each element of which is either a Node or set of Nodes,
possibly intercolated with specifications of Projections between them. The specification of each
is described in the two sections below.
Node Specifications
Nodes can be either a Mechanism, a Composition, or a tuple (Mechanism or Composition,
NodeRoles) that can be used to assign required_roles to the Nodes in the Composition (see
Nodes for additional details). The Node(s) specified in each entry of the list project to the
Node(s) specified in the next entry, with the exception of a ControlMechanism.
ControlMechanisms. Any ControlMechanisms specified in a Pathway are automatically added as Nodes of the Composition. If a ControlMechanism follows another Node that is not a ControlMechanism,
then a MappingProjection is created to it from that Node (as described below). However, no
MappingProjections are created from the ControlMechanism to any that follow it in the Pathway specification. This is
because the efferent Projections of a ControlMechanism can only be ModulatoryProjections (see `
<ControlMechanism_ControlSignals>` for specification), and not MappingProjections. Instead, if the ControlMechanism is
the first Node in the Pathway specification, the Node that follows it is treated as an INPUT Node of the Composition
(unless it receives a Projection from another Pathway); if it is the last Node in the Pathway specification, the Node
that precedes it is treated as an OUTPUT Node of the Composition (unless it sends a Projection to another Pathway);
otherwise, a MappingProjection is created from the primary OutputPort of the Node immediately
preceding the ControlMechanism to the primary InputPort of the Node immediately following it.
Use of sets. A set of Nodes can be used to specify multiple Nodes, all of which should receive Projections
from the same Node(s) in the preceding entry in the Pathway specification and send Projections to the same Node(s) in
the following entry (see below for additional details).
Note
Only a set can be used to specify multiple Nodes for a given entry in a Pathway; a list can not be used
for this purpose, as a list containing Nodes is always interpreted as a Pathway. If a list is included in a
Pathway specification, then it and all other entries are considered as separate, parallel Pathways (see
example vii in the figure below).
Projection Specifications
Where no Projections are specified between entries in the list, default Projections are created (using a
FULL_CONNECTIVITY_MATRIX, or the Pathway’s default_projection if specified)
from each Node in the first entry, as the sender(s), to each Node in the second, as receiver(s) (described further
below). Projections between Nodes in the two entries can also be specified explicitly, by
intercolating a Projection or set of Projections between the two entries in the list. If the sender and receiver are
both a single Mechanism, then a single MappingProjection can be specified between
them. The same applies if the sender is a Composition with a single OUTPUT Node and/or the
receiver is a Composition with a single INPUT Node. If either is a set of Nodes, or is a
nested Composition with more than one INPUT or OUTPUT
Node, respectively, then a collection of Projections can be specified between any or all pairs of the Nodes in the
set(s) and/or nested Composition(s), using either a set or list of Projections (order of specification does not matter
whether a set or a list is used). The collection can contain MappingProjections between specific
pairs of Nodes and/or a single default specification (either a matrix specification or a
MappingProjection without any sender or receiver
specified; see MappingProject MappingProjection_Matrix_Specification
).
Note
If a collection of Projection specifications includes a default matrix specification, then a list must be used
to specify the collection and not a set (since a matrix is unhashable and thus cannot be included in a set).
If a default Projection specification is included in the set, it is used to implement a Projection between any pair
of Nodes for which no MappingProjection is otherwise specified, whether within the collection or on its own; if no
Projections are specified for any individual pairs, a default Projection is created for every pairing of senders and
receivers. If a collection contains Projections for one or more pairs of Nodes, but does not include a default
projection specification, then no Projection is created between any of the other pairings.
If a pair of entries in a pathway has multiple sender and/or receiver Nodes specified (either in a set and/or belonging
to nested Composition, and either no Projection(s) or only a default Projection is intercollated
between them, then a default set of Projections is constructed (using the default Projection specification, if provided)
between each pair of sender and receiver Nodes in the set(s) or nested Composition(s), as follows:
One to one - if both the sender and receiver entries are Mechanisms, or if either is a Composition and the
sender has a single OUTPUT Node and the receiver has a single INPUT
Node, then a default MappingProjection is created from the primary OutputPort of the
sender (or of its sole OUTPUT Node, if the sender is a Composition) to the primary InputPort of the receiver (or of its sole of INPUT Node, if the receiver is
a Composition), and the Projection specification is intercolated between the two entries in the Pathway.
One to many - if the sender is either a Mechanism or a Composition with a single OUTPUT Node,
but the receiver is either a Composition with more than one INPUT Node or a set of Nodes, then
a MappingProjection is created from the primary OutputPort of the sender Mechanism (or of
its sole OUTPUT Node if the sender is a Composition) to the primary InputPort of each INPUT Node of the receiver Composition and/or Mechanism in the
receiver set, and a set containing the Projections is intercolated between the two entries in the Pathway.
Many to one - if the sender is a Composition with more than one OUTPUT Node or a set of
Nodes, and the receiver is either a Mechanism or a Composition with a single INPUTOUTPUT Node in the Composition or Mechanism in the set of sender(s), to the primary InputPort of the receiver Mechanism (or of its sole INPUT Node if the receiver is
a Composition), and a set containing the Projections is intercolated between the two entries in the Pathway.
Many to many - if both the sender and receiver entries contain multiple Nodes (i.e., are sets, and/or the
the sender is a Composition that has more than one INPUT Node and/or the receiver has more
than one OUTPUT Node), then a Projection is constructed for every pairing of Nodes in the
sender and receiver entries, using the primary OutputPort of each sender Node and the
primary InputPort of each receiver node.
Examples of Pathway specifications (including in the pathways argument of a Composition. i) Set
of Nodes: each is treated as a SINGLETON within a single Pathway.
ii) List of Nodes: forms a sequential Pathway. iii) Single Node followed by a set: one to many mapping.
iv) Set followed by a single Node: many to one mapping. v) Set followed by a set: many to many mapping.
vi) Set followed by a list: because there is a list in the specification ([C,D]) all other entries are
also treated as parallel Pathways (see note above), so A and B in the
set are SINGLETONs. vii) Set of Projections intercolated between two sets of Nodes:
since the set of Projections does not include any involving B or E nor a default Projection specification,
they are treated as SINGLETONs (compare with x). viii) Set followed by a Node and
then a set: many to one to many mapping. ix) Node followed by one that is a nested Composition then another Node: one to many to one mapping. x) Set followed by a list of Projections
then another set: since the list of Projections contains a default Projection specification (matrix)
Projections are created between all pairings of nodes in the sets that precede and follow the list (compare with
vii); note that the Projections must be specified in a list because the matrix is a list (or array), which
cannot be included in a set (see note above).
The full code for the examples above can be found in test_pathways_examples,
although some have been graphically rearranged for illustrative purposes.
Pathway Specification Formats
The following formats can be used to specify a Pathway in the pathway argument of the constructor for
the Pathway, the pathways argument of the constructor for a Composition, or the corresponding argument
of any of a Composition’s Pathway addition methods:
set: {Node, Node…} –
each item of the set must be a Node (i.e., Mechanism or Composition, or a
(Mechanism, NodeRoles) tuple); each Node is treated as a SINGLETON. Sets can also be used in a list specification (see above; and see
add_linear_processing_pathway for additional details).
2 or 3-item tuple: (Pathway, <learning_function>, <default_matrix_specification>) –
used to specify a learning Pathway and/or a matrix to use for any unspecified
Projections (overrides default matrix for MappingProjection) if a default projection is not otherwise specified
(see Pathway_Specification_Projections.The1stitemofthetuplemustbeoneoftheformsofPathwayspecificationdescribedabove.Theotheritemsmustbeasubclassof`LearningFunction and/or a matrix
specification.
Multiple Pathway Specifications
In addition to the forms of single Pathway specification above, where multiple Pathways
can be specified (e.g., the pathways argument of the constructor for a Composition or its add_pathways method), they can be specified in a list, in which each item of the list can be any of
the forms above, or one of the following:
dict: {name : Pathway) – in which name is a str and Pathway is a Pathway object or constuctor,
or one of the standard Pathway specifications listed above.
Note
If any of the following is used to specify the pathways argument:
then each such Node in the list is assigned as a SINGLETON Node in its own Pathway.
However, if the list contains only Nodes, then it is treated as a single Pathway (i.e., the list form of
Pathway specification described above. Thus:
pathway: NODE -> single pathway
pathway: [NODE] -> single pathway
pathway: [NODE, NODE…] -> single pathway
pathway: [NODE, () or {} or Pathway…] -> individual Pathways for each specification.
Structure
A Pathway has the following primary attributes:
pathway - if the Pathway was created on its own, this contains the specification provided in
the pathway arg of its constructor; that is, depending upon how it was specified, it may or may not contain
fully constructed Components. This is passed to the pathways argument of a Composition’s
constructor or one of its pathway addition methods when the Pathway is used
in the specification of any of these. In contrast, when a Pathway is created by a Composition (and assigned to its
pathways attribute), then the actual Mechanism(s) and/or Composition(s)
that comprise Nodes, and the Projection(s) between them, are listed in the
Pathway’s pathway attribute.
composition - contains the Composition that created the Pathway and to which it belongs,
or None if it is a template (i.e., was constructed on its own).
roles and Node attributes - if the Pathway was created by a Composition,
the roles attribute thisliststhe`PathwayRoles assigned to it by the Composition
that correspond to the NodeRoles<NodeRole> of its Components, and the Nodes with each of
those NodeRoles is assigned to a corresponding attribute on the Pathway. If the Pathway does not belong
to a Composition (i.e., it is a template), then these attributes return None.
learning_function - the LearningFunction assigned to the Pathway if it is a
learning Pathway that belongs to a Composition; otherwise it is None.
Execution
A Pathway cannot be executed on its own. Its Components are executed when the Composition to which it belongs is
executed, by default in the order in which they appear in the pathway attribute; however, this
can be modified by Conditions added to the Composition’s scheduler.
name (str : default see name) – specifies the name of the Pathway (see name for additional information).
pathway
if the Pathway is created on its own, this contains the specification provided to the pathway argument
of its constructor, and can take any of the forms permitted for Pathway specification;
if the Pathway is created by a Composition, this is a list of the Nodes and intercolated
Projections in the Pathway (see above for additional details).
list of PathwayRole(s) assigned to the Pathway, based on the NodeRole(s)
assigned to its Nodes in the composition to which it belongs.
Returns an empty list if belongs to a Composition but no PathwayRoles have been assigned,
and None if the Pathway is a tempalte (i.e., not assigned to a Composition).
matrix used for any unspecified Projections (overrides default matrix for MappingProjection)
if a default projection is not otherwise specified (see Projection Specifications;
see Specifying the Matrix Parameter for details of specification). A default_projection_matrix
is specified by including it in a tuple specification in the pathways argument of the Pathway’s
constructor (see 2 or 3-item tuple).
Type:
list, array, function, RandomMatrix or MATRIX_KEYWORD : default None
These are generated automatically and added to the Composition when the Pathway is assigned to it.
Returns an empty dict if it is not a learning Pathway, and None
if the Pathway is a tempalte (i.e., not assigned to a Composition).
Type:
dict or None
name
the name of the Pathway; if it is not specified in the name argument of the constructor, a default is
assigned by PathwayRegistry (see Naming for conventions used for default and duplicate names).
See note for additional information.
Type:
str
_assign_roles(composition)
Assign PathwayRoles to Pathway based NodeRoles assigned to its Nodes by the composition to which it belongs.
