← control_flow package

FoldCollect

A variant of the Fold loop node that additionally collects a secondary output of the loop body in each iteration and stacks them into an array or Packet.

See the documentation for the Fold loop for a basic introduction. Unlike Fold, the loop body must return a two-element list: the first is the updated state (which is the only output in case of the plain Fold loop), and the second is the value to collect. The result of the Fold Collect loop is then all the values that were emitted in this way stacked along a new leading axis. The value can be a number, array or data of type block, chunk, or packet, where again the stacking is always along a new leading axis. In the latter cases, if there was a unique leading axis in the loop input, that axis is preserved and will become (again) the leading axis in the output, otherwise the leading axis will be a plain untyped axis (type Axis). The loop body is also allowed to emit a nesting of lists or dictionaries of stackable data as the emitted value, and the loop output will respect the same data structure but contain stacked data in the respective places. More Info... Version 1.0.0

Ports/Properties

body

Reducer function (loop body).

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

body__signature

Names of arguments accepted by the loop body. Since a fold loop, in contrast to a for each loop, carries over state from one iteration to the next, your loop body must accept at least two arguments: the previous iteration's state (or initial value), which must always be the first argument listed here, and the current item from the iterable being looped over. If you wish to loop over multiple iterables (e.g., lists/arrays/iterators) simultaneously (which all must have the same length), you can list additional items here, using any name of your choosing. Your loop body must then have one Placeholder node for each of the loop variables listed here, with its slotname set to the respective name (i.e., state, item1, item2, ...), although you can also choose any other names here. Then, anything downstream of (i.e., depending on the value of) those Placeholders will collectively constitute your loop body. In contrast to the simple Fold Loop, which only returns the final state, the Fold Collect loop is expected to return a two-element list: the first is the updated state (which can be any data type or structure of your choosing), and the second is the value to collect. Therefore, the final node of the loop body is usually a CreateList node with two inputs wired into it. The final output node of your loop body is then wired into the "body" input port of the loop node. In graphical UIs, the edge will be drawn in dotted style to indicate that the preceding graph itself is given to the loop node as the loop body (which will then execute it zero or more times), which is in contrast to a regular (solid) edge that indices normal data flow wherein first the preceding node runs, and then its output is passed to the subsequent node. The loop node itself has two main outputs: one is the final state received from the loop body on the last iteration (in the final output port), and the other is the collected values, which is either an array or packet stacked along a new leading axis, or a list (depending on the "collect" setting).

• verbose name: Body [State, Item]
• default value: (state,item)
• port type: Port
• value type: object (can be None)

iterable1

Iterable 1 to iterate over.

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

iterable2

Iterable 2 to iterate over.

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

iterable3

Iterable 3 to iterate over.

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

iterable4

Iterable 4 to iterate over.

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

iterable5

Iterable 5 to iterate over.

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

iterableN

Additional iterables.. .

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

iterable

Alias for the iterable1 port.

• verbose name: Iterable
• default value: None
• port type: AliasPort
• value type: object (can be None)

collected

Collected results in stacked form.

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

final

Final state after last operation.

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

initial

Initial value for the state. It is recommended that this has the same structure (e.g., dictionary fields) as what is returned by the loop body. For compiled loops, this is required.

• verbose name: Initial
• default value: None
• port type: Port
• value type: object (can be None)

collect

Form into which results are collected. Note: when the loop operates in reverse mode, the collected items will be automatically reversed (again) as well, so as to be in the order of the original iterable. If set to list, the outputs of the loop body are returned as a list. If set to stacked, the outputs are stacked along a new first axis. In this case, if the input data was packets, and the first axes being iterated over were the same in all chunks, then the first axis of the output will be the same as in the input (otherwise a generic axis is used).

• verbose name: Collect
• default value: stacked
• 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)

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)

reverse

If True, process the iterables in reverse order. The output will then be the state after having processed the leftmost element of the iterables.

• verbose name: Process In Reverse Order
• default value: False
• port type: BoolPort
• value type: bool (can be None)

log_errors

If True, log exceptions occurring in the loop body.

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

compile

Whether and how to compile the loop body for more efficient execution. Auto will compile the loop only if it occurs in a context where compilation is necessary, for example inside a model passed to nodes such as DeepLearning, ConvexModel, or one of the Inference nodes. The 'jax' option will generally attempt to compile the loop to run on the jax backend; this comes with a series of limitations -- all nodes in the body have to work with jax data types (numeric values only) and operations, and break/continue nodes cannot be used. 'Off' is the appropriate setting for anything except for the most performance-critical computations consisting of mainly math operations, possibly with some data reformatting. Off can also be useful in a situation where the loop occurs in a compiled context, but the iterable is a static constant (e.g., fixed list) and relatively short; in this case, the loop will be completely unrolled, which can be more efficient than actually looping.

• verbose name: Compile
• default value: auto
• port type: EnumPort
• value type: str (can be None)

unroll

Optionally the unrolling factor for this loop, if compiling. Typically this is a small power of two such as 4 or 8. This is mainly an efficiency improvement for extremely tight loops that perform very cheap math operations.

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