Module: special_purpose

Special-purpose nodes.

This package contains nodes that support specialized workflows in NeuroPype that do not yet have their own package. Nodes with the generic (cycle) icon support internal operations of the NeuroPype engine and are not currently considered ready for general use.

DeclareGraphSignature

Declare arguments that can be passed into the graph, when the graph is called as a function.

The purpose of this node is to annotate a graph as a whole to have a specific call signature (e.g., defining positional and/or keyword-only arguments when the graph is called as a function, for example from Python). See documentation of the "signature" property for more details on the format. A graph may have at most one such node in it, and the node must be freestanding (i.e., not connected to anything).

Version 0.3.0

Ports/Properties

  • metadata
    User-definable meta-data associated with the node. Usually reserved for technical purposes.

    • verbose name: Metadata
    • default value: {}
    • port type: DictPort
    • value type: dict (can be None)

  • signature
    Argument signature of the overall graph. This is formatted the same way as signatures in graph-accepting ports. This is mostly used to annotate a graph with a positional argument list so as to make it callable with positional arguments, i.e., mygraph(arg1,arg2). As in normal graph signatures, this is specified as in (myargument1, myargument2), using whichever placeholder names you wish to bind in this fashion. You may optionally also speciff arguments that can be passed only by name, by listing these after a + symbol, as in: (myargument1, myargument2, +, mykeywordargument1, mykeywordargument2). However, note that the latter serves mostly a documentation purpose, since the user can always pass in unlisted keyword arguments, which inside the graph with be picked up by any free (i.e., not otherwise bound) Placeholder and ParameterPort names. Also note that the * and ~ symbols have no meaning in the context of the overall graph, but may be added to document the original signature that may have been used to define the graph.

    • verbose name: Signature
    • default value: (myargument1,myargument2)
    • port type: Port
    • value type: object (can be None)

  • set_breakpoint
    Set a breakpoint on this node. If this is enabled, your debugger (if one is attached) will trigger a breakpoint.

    • verbose name: Set Breakpoint (Debug Only)
    • default value: False
    • port type: BoolPort
    • value type: bool (can be None)

GraphCompile

Compile the given graph for more efficient processing.

This is a graph transformation node that can be used to compile a graph into a more efficient to run (but less inspectable) representation. The resulting graph can then be wired into a node that will run the graphs, e.g., the Call node. Note that only a modest subset of nodes can be used in compilable graphs; this includes most of the nodes with a backend option (e.g., elementwise math, most purely mathematical operations like ConcatInputs, ArrayReshape, MatrixMultiplication, the Loss nodes, but not including most stateful nodes even if they have a backend option, like, e.g., IncrementalWhitening). Also supported are stateless deep learning nodes like NetInitialize and NetApply and optimizer step nodes (e.g., StepInit and StepApply). Future releases will support greater subsets of graph operations. If you find that your code appears to run slower with the compile node enabled, chances are that it is recompiling your code each time it is run; the most common causes of this are that a) either some input arguments that are marked as "static" are varying between calls, or - more likely - if you are passing Packets into the graph, that any axes or props of the packet are changing between calls (these also count as static). The most common culprit here is the instance axis (if present) or time axis (otherwise), and the simplest fix is to reset that axis to a dummy instance (or time) axis before passing it into the compiled portion of the graph. Or b) your graph itself changes between calls, which is most likely due to some node properties varying, which can be caused by wires that feed variable data into the graph from its upstream (left-hand) side. A more rare cause is that the previous execution modified the graph in some way, e.g., updating the state of some nodes; this can be determined by inspecting (e.g., printing) the graph and looking for node properties that are changing between calls. However, note that then you should also get errors about "unexpected" or "leaked" tracers (from the jit backend), and if you are not seeing those, this is not the first thing to suspect (although it is still a possibility). This node will implicily configure any upstream nodes (those wired into this node's graph port) that support multiple backends to default to the selected compiler backend when being compiled.

Version 0.8.0

Ports/Properties

  • metadata
    User-definable meta-data associated with the node. Usually reserved for technical purposes.

    • verbose name: Metadata
    • default value: {}
    • port type: DictPort
    • value type: dict (can be None)

  • graph
    Graph to compile.

    • verbose name: Graph
    • default value: None
    • port type: GraphPort
    • value type: Graph

  • graph__signature
    Optional list of input argument names to the graph being compiled. Similarly to the loop body of a loop node, the graph being compiled is a function of one or more arguments, whose names are listed here. The graph must then contain, for each listed arguments name, one Placeholder node with its slotname matching that name. The graph is then all nodes that are downstream reachable from those placeholders. The final node of the graph is then wired into the graph port of the CompileGraph node. In graphical UIs this edge will show as dotted to indicate that this is not normal forward data flow but a subgraph (i.e., the graph being compiled) is being passed to the Compile Graph node for compilation. The output of this node is then the compiled graph, which can be wired into, for example, the Call node in order to invoke it with some positional arguments.

    • verbose name: Graph [Signature]
    • default value: (inputs)~>()
    • port type: Port
    • value type: object (can be None)

  • annotations
    Additional annotations to supply per argument.

    • verbose name: Annotations
    • default value: {}
    • port type: DictPort
    • value type: dict (can be None)

  • backend
    Optional compiler backend to use. Keep defaults to the current context and/or global setting, which defaults to not compiling unless it was specifically enabled by the user -- it can, for example, be overridden for a part of a graph using the WithBackend node. The jax backend uses the JIT (Just-in-time) compiler from the jax library, which works in conjunction with numeric operations using the jax backend. Numpy is an alias for not compiling the graph and using plain numpy operations.

    • verbose name: Backend
    • default value: keep
    • port type: EnumPort
    • value type: str (can be None)

  • disabled
    Enable/disable compilation. This can be used to bypass compilation for debugging purposes, regardless of the current backend setting.

    • verbose name: Disabled
    • default value: False
    • port type: BoolPort
    • value type: bool (can be None)

  • static
    List of argument names (if any) that are compiled-in "static" constants as opposed to dynamic parameters. Static parameters require a recomilation whenever they change, but there is no restriction on their contents and they can be used to optimize the compiled code. Dynamic parameters instead have to be arrays or data structures containing arrays for the current backend (e.g., values that were created by a node with a backend option set to "jax", or values that were moved to jax either explicitly using MoveToBackend or possibly implicitly by a node that this node is directly or indirectly wired into). Note that not every backend may recognize this option and may treat all arguments as dynamic.

    • verbose name: Static
    • default value: []
    • port type: ListPort
    • value type: list (can be None)

  • automove_data
    Automatically move data to the chosen backend. This adds a slight performance overhead if the data is already on the desired backend and is only included for convenience.

    • verbose name: Automove Data
    • default value: True
    • port type: BoolPort
    • value type: bool (can be None)

  • detect_changes
    How often to check for changes in the graph. The eager mode checks for changes before every run, which is safest during interactive editing of the graph being compiled, but this adds considerable overhead. The lax mode checks for changes only occasionally (every few calls), and logs a warning when a change is detected, and recompiles the graph then. It will run with the old graph until the change is detected. The never mode never checks for changes, and only compiles the graph at the beginning; this is useful for production runs where the graph being compiled is no longer modified. Note that downstream graph edits can be made freely in any mode as they do not affect the compiled portion of the graph. Note that, for this to work, you need to enable the stateful option on any Call nodes that are used to invoke the compiled graph (otherwise the compile node will not have its state persisted across calls).

    • verbose name: Detect Changes
    • default value: eager
    • port type: EnumPort
    • value type: str (can be None)

  • sanity_checks
    Optionally perform sanity checks on the graph.

    • verbose name: Sanity Checks
    • default value: False
    • port type: BoolPort
    • value type: bool (can be None)

  • set_breakpoint
    Set a breakpoint on this node. If this is enabled, your debugger (if one is attached) will trigger a breakpoint.

    • verbose name: Set Breakpoint (Debug Only)
    • default value: False
    • port type: BoolPort
    • value type: bool (can be None)

GraphTemplate

Create a new graph by merging one or more disconnected sets of nodes that are taken verbatim (i.e

., unevaluated and therefore statically defined) from the node's (verbatim0-9) inputs. The resulting graph may optionally contain named Template Slot nodes, each of which is substituted by a runtime-computed subgraph provided via the node's (substitution0-4) inputs. The names of the substitutions are specified via the node's (name0-4) inputs (these names pair with the slotnames of the template slots). This implements a generic graph template engine that's analogous to the quasiquote mechanism in some programming languages (for code expressions) or the template mechanism in some markup languages (for documents). Nodes within the substitution subgraphs can connect to the ambient graph into which they are inserted, which is specified using the numbered input and output ports on the template slot nodes, which define the wiring into the ambient graph. This works in conjunction with a special type of numbered slot node that may occur inside the subgraphs (InputSlot and OutputSlot), which define the wiring from nodes within the subgraph to the numbered input and output ports of the Template Slot node. When the final graph is composed, all these slot nodes disappear, and all that remains of them are the edges between the newly inserted and ambient subgraphs. See also documentation for the slot nodes (Template Slot, Input Slot, Output Slot) for additional details.

More Info...

Version 1.0.0

Ports/Properties

  • metadata
    User-definable meta-data associated with the node. Usually reserved for technical purposes.

    • verbose name: Metadata
    • default value: {}
    • port type: DictPort
    • value type: dict (can be None)

  • graph
    New graph.

    • verbose name: Graph
    • default value: None
    • port type: GraphPort
    • value type: Graph

  • graph__signature
    Signature for the "graph" input. This represents the signature for the subgraph that is wired into the "graph" port. This is formatted as in (a,b,c) where a,b,c are names of placeholders that are expected in the subgraph that goes out of the "graph" port. Alternatively, it can also be provided in data structure form as a list of lists, as in: [['a','b','c']].

    • verbose name: Graph [Signature]
    • default value: ()
    • port type: Port
    • value type: object (can be None)

  • verbatim0
    Verbatim nodes 0.

    • verbose name: Verbatim0
    • default value: None
    • port type: GraphPort
    • value type: Graph

  • verbatim1
    Verbatim nodes 1.

    • verbose name: Verbatim1
    • default value: None
    • port type: GraphPort
    • value type: Graph

  • verbatim2
    Verbatim nodes 2.

    • verbose name: Verbatim2
    • default value: None
    • port type: GraphPort
    • value type: Graph

  • verbatim3
    Verbatim nodes 3.

    • verbose name: Verbatim3
    • default value: None
    • port type: GraphPort
    • value type: Graph

  • verbatim4
    Verbatim nodes 4.

    • verbose name: Verbatim4
    • default value: None
    • port type: GraphPort
    • value type: Graph

  • verbatim5
    Verbatim nodes 5.

    • verbose name: Verbatim5
    • default value: None
    • port type: GraphPort
    • value type: Graph

  • verbatim6
    Verbatim nodes 6.

    • verbose name: Verbatim6
    • default value: None
    • port type: GraphPort
    • value type: Graph

  • verbatim7
    Verbatim nodes 7.

    • verbose name: Verbatim7
    • default value: None
    • port type: GraphPort
    • value type: Graph

  • verbatim8
    Verbatim nodes 8.

    • verbose name: Verbatim8
    • default value: None
    • port type: GraphPort
    • value type: Graph

  • verbatim9
    Verbatim nodes 9.

    • verbose name: Verbatim9
    • default value: None
    • port type: GraphPort
    • value type: Graph

  • substitution0
    Graph for template slot 0.

    • verbose name: Substitution0
    • default value: None
    • port type: DataPort
    • value type: Graph (can be None)
    • data direction: IN

  • substitution1
    Graph for template slot 1.

    • verbose name: Substitution1
    • default value: None
    • port type: DataPort
    • value type: Graph (can be None)
    • data direction: IN

  • substitution2
    Graph for template slot 2.

    • verbose name: Substitution2
    • default value: None
    • port type: DataPort
    • value type: Graph (can be None)
    • data direction: IN

  • substitution3
    Graph for template slot 3.

    • verbose name: Substitution3
    • default value: None
    • port type: DataPort
    • value type: Graph (can be None)
    • data direction: IN

  • substitution4
    Graph for template slot 4.

    • verbose name: Substitution4
    • default value: None
    • port type: DataPort
    • value type: Graph (can be None)
    • data direction: IN

  • substitutionN
    Graphs for additional template slots.

    • verbose name: Substitutionn
    • default value: None
    • port type: DataPort
    • value type: list (can be None)
    • data direction: IN

  • name0
    Template slot name 0. If the graph contains named Template Slot nodes, this is the name of the first such placeholder, which will then be substituted by the graph for template slot 0.

    • verbose name: Name0
    • default value: None
    • port type: StringPort
    • value type: str (can be None)

  • name1
    Template slot name 1. See name0 for more info.

    • verbose name: Name1
    • default value: None
    • port type: StringPort
    • value type: str (can be None)

  • name2
    Template slot name 2. See name0 for more info.

    • verbose name: Name2
    • default value: None
    • port type: StringPort
    • value type: str (can be None)

  • name3
    Template slot name 3. See name0 for more info.

    • verbose name: Name3
    • default value: None
    • port type: StringPort
    • value type: str (can be None)

  • name4
    Template slot name 4. See name0 for more info.

    • verbose name: Name4
    • default value: None
    • port type: StringPort
    • value type: str (can be None)

  • nameN
    Additional template slot names. See name0 for more info.

    • verbose name: Namen
    • default value: []
    • port type: ListPort
    • value type: list (can be None)

  • strict
    Enforce strict template matching. This enforces among others that the input/output edges of a template node have corresponding input/output slots in the substitution graph, and vice versa, and that the numbering of these slots is consecutive.

    • verbose name: Strict
    • default value: True
    • port type: BoolPort
    • value type: bool (can be None)

  • verbose
    Enable verbose output.

    • verbose name: Verbose
    • default value: False
    • port type: BoolPort
    • value type: bool (can be None)

  • desc
    Description values for the graph. This is an optional dictionary of name/value pairs used to create a description. Note that the only available fields are those of the NeuroPype Description class (name, description, version, status, license, url, id, and keywords). Keywords, if given as a string, is formatted as a comma-separated list.

    • verbose name: Description
    • default value: {}
    • port type: DictPort
    • value type: dict (can be None)

  • set_breakpoint
    Set a breakpoint on this node. If this is enabled, your debugger (if one is attached) will trigger a breakpoint.

    • verbose name: Set Breakpoint (Debug Only)
    • default value: False
    • port type: BoolPort
    • value type: bool (can be None)

InputSlot

A placeholder node in a subgraph that will be merged into an ambient graph.

The node represents the place where a numbered input comes into the graph from the ambient graph, and is used to designate edges from the ambient graph to specific nodes in the subgraph. See Output Slot (Graph Template) node for more comprehensive usage documentation.

Version 1.0.0

Ports/Properties

  • metadata
    User-definable meta-data associated with the node. Usually reserved for technical purposes.

    • verbose name: Metadata
    • default value: {}
    • port type: DictPort
    • value type: dict (can be None)

  • data
    Incoming data.

    • verbose name: Data
    • default value: None
    • port type: DataPort
    • value type: object (can be None)
    • data direction: OUT

  • number
    Number of the input slot. In places where there can be multiple such nodes, this one indicates the node's place in the ordering.

    • verbose name: Number
    • default value: 0
    • port type: IntPort
    • value type: int (can be None)

  • usage
    Usage of the input slot. At this time there's only one usage, but this field is reserved for potential future use cases.

    • verbose name: Usage (Reserved)
    • default value: graph template
    • port type: EnumPort
    • value type: str (can be None)

  • set_breakpoint
    Set a breakpoint on this node. If this is enabled, your debugger (if one is attached) will trigger a breakpoint.

    • verbose name: Set Breakpoint (Debug Only)
    • default value: False
    • port type: BoolPort
    • value type: bool (can be None)

OutputSlot

A placeholder node in a subgraph that will be merged into an ambient graph.

The node represents the place where a numbered output goes from the subgraph out to the ambient graph, and is used to designate edges from specific nodes of he subgraph graph to specific destinations in the ambient graph. Two scenarios in which this node can occur are: 1) when creating a graph using the Create Graph (Graph Template) node. In this context the overall template is a static literal graph which may have slots for subgraphs that are computed at runtime; these slots are indicated with Template Slot nodes in the graph, and they are to be substituted by the computed subgraphs. In order to determine precisely how the subgraph should connect with the ambient graph (from what nodes and ports the edges go out, and what nodes/ports those edges go to), the template placeholder can have one or more numberd out-edges that can go anywhere in the ambient graph. When the template placeholder is replaced by the computed graph, it is still necessary to indiate from what nodes/ports inside that graph these out-edges emanate. This is done by placing a numbered Next Node Placeholder node in the computed graph (the number pairs with the number of the out-edge of the template placeholder). Once inserted, the Output Slot node disappears, but the edge going to it continues on to the destination node/edge of the out-edge of the template placeholder. 2) when using the graph_mode() context manager in a Python script to create graphs using a define-by-run approach. In this context, any node invocation (e.g., MyNode(...)() will create a a graph that has a Output Slot node in it that indicates the connection point for the next node in the graph. When the result of MyNode(...)() is then passed to another node invocation (e.g., MyOtherNode()(...)), the Output Slot node is replaced by that other node, and the result is a two-node graph. This process can be repeated to create larger graphs (generally tree-shaped, although additional edges can be inserted explicitly to it). See also the Input Slot node for a corresponding node for designating inbound edges of the subgraph.

Version 1.0.0

Ports/Properties

  • metadata
    User-definable meta-data associated with the node. Usually reserved for technical purposes.

    • verbose name: Metadata
    • default value: {}
    • port type: DictPort
    • value type: dict (can be None)

  • data
    Outgoing data.

    • verbose name: Data
    • default value: None
    • port type: DataPort
    • value type: object (can be None)
    • data direction: IN

  • number
    Number of the output slot. In places where there can be multiple such nodes, this one indicates the node's place in the ordering.

    • verbose name: Number
    • default value: 0
    • port type: IntPort
    • value type: int (can be None)

  • usage
    Usage of the output slot. Slots can be used in two scenarios: for use with Create Graph (Graph Template) nodes, or for internal use by with the Python-side graph_mode() context manager. The latter is used for creating graphs using a define-by-run approach, where the graph is created on the fly as the nodes are executed in Python code. Do not manually set this to "python graph mode".

    • verbose name: Usage (Reserved)
    • default value: graph template
    • port type: EnumPort
    • value type: str (can be None)

  • set_breakpoint
    Set a breakpoint on this node. If this is enabled, your debugger (if one is attached) will trigger a breakpoint.

    • verbose name: Set Breakpoint (Debug Only)
    • default value: False
    • port type: BoolPort
    • value type: bool (can be None)

TemplateSlot

Declare a named template placeholder in a verbatim graph template.

When a graph is created using the Create Graph (Graph Template) node, the statically defined graph template can contain one or more Template Slot nodes. These placeholders stand for dynamically (runtime-) computed subgraphs that are provided to the Graph Template node as additional inputs, and which are substituted for the placeholders. The Template Slot node supports multiple numbered input and output ports that can be wired to destinations in the ambient template graph. These edges become coincident with edges going to any numbered "Output Slot" or "Input Slot" nodes that occur inside the computed subgraph when the subgraph is merged into the template graph. Both the Template Slot and the Input/Output Slot nodes disappear from the resulting graph in the process. A simple analogy for what this node represents is found in 'string interpolation' (or string template substitution). In string interpolation, a statically defined verbatim (quoted) template string, such as "Hello, my name is {name}." is combined with a named string value (e.g., name = "John"), which is usually computed at runtime (e.g., depending on user input), to compose a final string, here "Hello, my name is John." In the world of graphs, the template string is a statically defined, unevaluated (i.e, verbatim or "quoted") graph, the {name} placeholder is a node inside that graph of the form Template Slot whose slotname has been set to "name", and the string "John" is a graph that is computed at runtime. The operator that composes the pieces into a final string is the Create Graph (Graph Template) node. When the template is composed into a final graph, the placeholder node disappears and will be replaced by the computed graph that was bound to it. However, the final graph would only be useful if it was possible to express that there should be edges from specific nodes (and ports) inside the computed graph going to specific nodes (and ports) in the ambient template graph. There are two sides to this specification -- the Template Slot node has a set of predefined numberd output ports (out0..N), from which edges can be drawn to destinations inside the ambient graph. In the computed graph on the other hand, there may be one or more numbered nodes of type Output Slot to which edges can be drawn from within the computed graph. When the graphs are combined, both the Template Slot and the Output Slot nodes go away, but the edges to the latter continue on into the ambient graph and end on the destinations that were indicated by the former template placeholder's numbered output port edges. The same happens with Input Slot nodes in the computed subgraph vs in-edges to the Template Slot node's numbered input ports.

More Info...

Version 1.0.0

Ports/Properties

  • metadata
    User-definable meta-data associated with the node. Usually reserved for technical purposes.

    • verbose name: Metadata
    • default value: {}
    • port type: DictPort
    • value type: dict (can be None)

  • in0
    Incoming connection 0.

    • verbose name: In0
    • default value: None
    • port type: DataPort
    • value type: object (can be None)
    • data direction: IN

  • in1
    Incoming connection 1.

    • verbose name: In1
    • default value: None
    • port type: DataPort
    • value type: object (can be None)
    • data direction: IN

  • in2
    Incoming connection 2.

    • verbose name: In2
    • default value: None
    • port type: DataPort
    • value type: object (can be None)
    • data direction: IN

  • in3
    Incoming connection 3.

    • verbose name: In3
    • default value: None
    • port type: DataPort
    • value type: object (can be None)
    • data direction: IN

  • in4
    Incoming connection 4.

    • verbose name: In4
    • default value: None
    • port type: DataPort
    • value type: object (can be None)
    • data direction: IN

  • in5
    Incoming connection 5.

    • verbose name: In5
    • default value: None
    • port type: DataPort
    • value type: object (can be None)
    • data direction: IN

  • in6
    Incoming connection 6.

    • verbose name: In6
    • default value: None
    • port type: DataPort
    • value type: object (can be None)
    • data direction: IN

  • in7
    Incoming connection 7.

    • verbose name: In7
    • default value: None
    • port type: DataPort
    • value type: object (can be None)
    • data direction: IN

  • in8
    Incoming connection 8.

    • verbose name: In8
    • default value: None
    • port type: DataPort
    • value type: object (can be None)
    • data direction: IN

  • in9
    Incoming connection 9.

    • verbose name: In9
    • default value: None
    • port type: DataPort
    • value type: object (can be None)
    • data direction: IN

  • out0
    Outgoing connection 0.

    • verbose name: Out0
    • default value: None
    • port type: DataPort
    • value type: object (can be None)
    • data direction: OUT

  • out1
    Outgoing connection 1.

    • verbose name: Out1
    • default value: None
    • port type: DataPort
    • value type: object (can be None)
    • data direction: OUT

  • out2
    Outgoing connection 2.

    • verbose name: Out2
    • default value: None
    • port type: DataPort
    • value type: object (can be None)
    • data direction: OUT

  • out3
    Outgoing connection 3.

    • verbose name: Out3
    • default value: None
    • port type: DataPort
    • value type: object (can be None)
    • data direction: OUT

  • out4
    Outgoing connection 4.

    • verbose name: Out4
    • default value: None
    • port type: DataPort
    • value type: object (can be None)
    • data direction: OUT

  • out5
    Outgoing connection 5.

    • verbose name: Out5
    • default value: None
    • port type: DataPort
    • value type: object (can be None)
    • data direction: OUT

  • out6
    Outgoing connection 6.

    • verbose name: Out6
    • default value: None
    • port type: DataPort
    • value type: object (can be None)
    • data direction: OUT

  • out7
    Outgoing connection 7.

    • verbose name: Out7
    • default value: None
    • port type: DataPort
    • value type: object (can be None)
    • data direction: OUT

  • out8
    Outgoing connection 8.

    • verbose name: Out8
    • default value: None
    • port type: DataPort
    • value type: object (can be None)
    • data direction: OUT

  • out9
    Outgoing connection 9.

    • verbose name: Out9
    • default value: None
    • port type: DataPort
    • value type: object (can be None)
    • data direction: OUT

  • slotname
    Name of the placeholder slot. This needs to be matched to the name of a computed substitution graph in the GraphTemplate (Create Graph) node.

    • verbose name: Name
    • default value: graph1
    • port type: StringPort
    • value type: str

  • set_breakpoint
    Set a breakpoint on this node. If this is enabled, your debugger (if one is attached) will trigger a breakpoint.

    • verbose name: Set Breakpoint (Debug Only)
    • default value: False
    • port type: BoolPort
    • value type: bool (can be None)