Node

class caskade.Node(name: str | None = None, link: Node | tuple[Node] | None = None, description: str = '')

Bases: object

Base graph node class for caskade objects.

The Node object is the base class for all caskade objects. It is used to construct the directed acyclic graph (DAG). The primary function of the Node object is to manage the parent-child relationships between nodes in the graph. There is limited functionality for the Node object, though it implements the base versions of the active state and to / update_graph methods. The active state is used to communicate through the graph that the simulator is currently running. The to method is used to move and/or cast the values of the parameter. The update_graph method is used signal all parents that the graph below them has changed.

Examples

Example making some Node objects and then linking/unlinking them:

n1 = Node()
n2 = Node()
n1.link("subnode", n2) # link n2 as a child of n1, may use any str as the key
n1.unlink("subnode") # alternately n1.unlink(n2) to unlink by object

property active: bool

True if the node is currently in an active simulation run.

Type:

bool

add_memo(memo)

Add a memo string and propagate it to all children.

Parameters:

memo (str) – The memo message to add. Children in subgraphs receive the memo with the child name appended (memo|child_name).

append_state(saveto: str | File)

Append the current state to an existing HDF5 file.

The file must have been previously created by save_state with appendable=True. The graph structure in the file is verified before appending.

Parameters:

saveto (str or File) – Path to an HDF5 file ('.h5' or '.hdf5') or an open HDF5 File object.

Raises:

• GraphError – If the graph structure no longer matches the file.

• NotImplementedError – If the file path does not end with a supported extension.

property children: dict[str, Node]

Mapping of link keys to child nodes.

Type:

dict[str, Node]

graph_dict() → dict[str, dict]

Return a nested dictionary representation of the graph.

Each key is a string of the form "name|node_type" and the value is a dict containing the same structure for that node’s children.

Returns:

Nested dictionary mirroring the DAG hierarchy.

Return type:

dict[str, dict]

graph_print(dag: dict, depth: int = 0, indent: int = 4, result: str = '') → str

Recursively render a graph dictionary as an indented string.

Parameters:

• dag (dict[str, dict]) – A nested dictionary as returned by graph_dict.

• depth (int, optional) – Current indentation depth (used during recursion). Defaults to 0.

• indent (int, optional) – Number of spaces per indentation level. Defaults to 4.

• result (str, optional) – Accumulator string (used during recursion). Defaults to "".

Returns:

A human-readable, indented representation of the graph.

Return type:

str

graphviz(saveto: str | None = None) → graphviz.Digraph

Return a graphviz Digraph representing the DAG below this node.

Parameters:

saveto (str, optional) – If provided, save the rendered graph to this file path. The file extension determines the output format (e.g. '.pdf', '.png'). Defaults to None.

Returns:

The constructed directed-graph object.

Return type:

graphviz.Digraph

hierarchical_link(key: str, child: Node)

Link the current Node object to another Node object as a child in a hierarchical manner. See link for more detail on linking. A hierarchical link will allow batching internally to the simulator.

Parameters:

• key (str) – The key to link the child node with.

• child (Node) – The child Node object to link to.

Examples

parent = Node(name="parent")
child = Node(name="child")
parent.hierarchical_link("child", child)

link(key: str | tuple | Node, child: Node | tuple | None = None)

Link the current Node object to another Node object as a child.

Parameters:

• key ((Union[str, Node])) – The key to link the child node with. This will also become the attribute to access the child node. After linking you will have node.key == child

• child ((Optional[Node], optional)) – The child Node object to link to. Defaults to None in which case the key is used as the child and the child.name is used as the key.

Examples

Example making some Node objects and then linking/unlinking them, demonstrating multiple ways to link/unlink:

n1 = Node()
n2 = Node()

n1.link("subnode", n2)  # may use any str as the key
n1.unlink("subnode")

# Alternatively, link by object
n1.link(n2)
n1.unlink(n2)

load_state(loadfrom: str | File, index: int = -1, **kwargs)

Load node state (and children) from an HDF5 file.

Parameters:

• loadfrom (str or File) – Path to an HDF5 file ('.h5' or '.hdf5') or an open HDF5 File object.

• index (int, optional) – Sample index to load when the file was saved in appendable mode. Defaults to -1 (last sample).

• **kwargs – Additional keyword arguments forwarded to h5py.File (e.g. driver).

Raises:

• GraphError – If the graph structure no longer matches the file.

• NotImplementedError – If the file path does not end with a supported extension.

property memos: set[str]

Current set of memo strings held by this node.

Type:

set[str]

property name: str

The name of this node.

Type:

str

property online: bool

True if the node is online within a hierarchical sub-graph.

Type:

bool

property parents: set[Node]

Set of parent nodes that link to this node.

Type:

set[Node]

remove_memo(memo)

Remove a memo string and propagate removal to all children.

Parameters:

memo (str) – The memo message to remove. The same propagation rules as add_memo apply.

save_state(saveto: str | File, appendable: bool = False)

Save the state of the node and its children, currently only works for HDF5 file types (.h5 and .hdf5).

The “state” of a node is considered to be the value of its params, however it is also possible to save other attributes of the node by adding them to the Node.saveattrs set. Simply call Node.saveattrs.add(‘attribute’) and then Node.attribute will be saved if possible. The HDF5 file will be created with the same structure as the graph, even if there are multiple paths to the same node. For example if N1 has children N2 and N3, and both N2 and N3 have the child N4, the HDF5 file will reflect this. It will be possible to find the N4 params under both ‘N1/N2/N4’ and ‘N1/N3/N4’ if inspecting the HDF5 file manually. Specifically, if N4 has the param P1 then you could access its value like this:

If the save had been set as appendable, then the value will have an extra dimension for the number of samples, this will always be the first dimension. If appendable was false then the value will simply equal the param value.

Note

You need the optional h5py package installed to use this method.

Parameters:

• saveto ((Union[str, File])) – The file to save the state to. If a string, it should be the path to an HDF5 file (ending in ‘.h5’ or ‘.hdf5’). If a File object, it should be an open HDF5 file.

• appendable ((bool, optional)) – Whether to save the state in an appendable format. If True, the values will have an extra dimension for the number of samples. Defaults to False.

property subgraphs: set[Node]

Subset of children linked hierarchically.

Type:

set[Node]

to(device=None, dtype=None)

Moves and/or casts the values of the Node to a particular device and/or dtype.

Parameters:

• device ((optional)) – The device to move the values to. Defaults to None.

• dtype ((optional)) – The desired data type. Defaults to None.

topological_ordering() → tuple[Node]

Return a topological ordering of the graph below the current node.

Performs a recursive depth-first search with post-order traversal to resolve dependencies. The result starts with this node and proceeds to its descendants in dependency order.

Returns:

All nodes reachable from (and including) this node, ordered so that every parent appears before its children.

Return type:

tuple[Node]

unlink(key: str | Node | list | tuple | None = None)

Unlink one or more Node objects from this Node.

Parameters:

key ((str, Node, list, tuple, or None, optional)) – The key, Node object, or collection of keys/nodes to unlink. If a string, the child with that key is unlinked. If a Node object, the matching child is located and unlinked. If a list or tuple, each element is unlinked in turn. If None (the default), all children are unlinked.

Raises:

GraphError – If the graph is currently active.

update_graph()

Triggers a call to all parents that the graph below them has been updated. The base Node object does nothing with this information, but other node types may use this to update internal state.