Hypercausal Graph

Hypercausal Graph#

Hypercausal Graphs#

Directed acyclic graph (DAG) abstraction for deterministic evaluation of hypercausal nodes.

This module defines: - Edge: a directed connection between nodes. - HCGraph: a lightweight executor for hypercausal DAGs and chains.

class qmlhc.hc.graph.Edge(src, dst)[source]#

Bases: object

Directed edge connecting two nodes.

Parameters:

  • src (str) – Source node name.

  • dst (str) – Destination node name.

dst: str#
src: str#
class qmlhc.hc.graph.HCGraph(nodes, edges)[source]#

Bases: object

Directed acyclic graph (DAG) of hypercausal nodes with deterministic topological evaluation.

Nodes are executed respecting causal order. Missing explicit inputs are automatically derived from the mean of parent states.

Examples

>>> dag = HCGraph.chain(["A", "B", "C"], [nodeA, nodeB, nodeC])
>>> s_map, s_hat_map, info_map = dag.step({"A": x_t})
__init__(nodes, edges)[source]#

Initialize a hypercausal DAG.

Parameters:

  • nodes (Mapping[str, HypercausalNode]) – Dictionary mapping node names to HypercausalNode instances.

  • edges (Iterable[Edge]) – Directed edges connecting nodes.

Raises:

  • ValueError – If no nodes are provided or if a cycle/self-loop is detected.

  • KeyError – If an edge references an unknown node.

classmethod chain(names, nodes)[source]#

Build a linear chain of nodes n0 -> n1 -> ... -> n_{L-1}.

Parameters:

  • names (list[str]) – Node names (must be unique).

  • nodes (list[HypercausalNode]) – Node instances corresponding to names.

Returns:

Constructed linear chain graph.

Return type:

HCGraph

Raises:

ValueError – If names and nodes have different lengths.

step(x_map, s_tm1_map=None, branches=2)[source]#

Process one time step across the DAG.

Parameters:

  • x_map (Mapping[str, TensorLike]) – Per-node current inputs.

  • s_tm1_map (Mapping[str, TensorLike] or None, optional) – Optional mapping of previous states per node, by default None.

  • branches (int, optional) – Number of candidate future branches (K), by default 2.

Returns:

(s_map, s_hat_map, info_map) where: - s_map : dict[str, Array] Per-node current state S_t. - s_hat_map : dict[str, Array] Per-node projected future state Ŝ_{t+1}. - info_map : dict[str, Mapping[str, Any]] Auxiliary per-node diagnostics.

Return type:

tuple

Raises:

KeyError – If a root node has no explicit input and no parent.

Contents