Quantum Model Abstractions

Hypercausal Model Composition

High-level orchestration of hypercausal nodes in single-node or chained setups.

This module defines the HCModel class, which manages the execution of one or multiple hypercausal nodes across steps or temporal sequences. Each node follows the hypercausal contract: given an input x_t and optional previous state s_{t-1}, it returns the current state s_t, a projected future state ŝ_{t+1}, and auxiliary information.

class qmlhc.core.model.HCModel(nodes, config=None)

Bases: object

Composes one or more hypercausal nodes into an executable model.

Provides both single-step and multi-step execution methods that support: - Sequential chaining of multiple nodes (forward_chain) - Temporal sequence processing (predict_sequence)

__init__(nodes, config=None)

Initialize an HCModel with a sequence of hypercausal nodes.

Parameters:

• nodes (Sequence[HypercausalNode]) – Ordered list of hypercausal nodes to be executed.

• config (ModelConfig or None, optional) – Model configuration. If None, uses default settings.

Raises:

ValueError – If no nodes are provided.

forward(x_t, s_tm1=None, branches=None)

Execute only the first node.

Parameters:

• x_t (TensorLike) – Current input vector at time t.

• s_tm1 (TensorLike or None, optional) – Previous state (t−1), by default None.

• branches (int or None, optional) – Number of future branches (K). Uses default_branches if None.

Returns:

(s_t, ŝ_{t+1}, info) s_t : Array Current state. ŝ_{t+1} : Array Projected next-state prediction. info : dict Additional node diagnostics.

Return type:

tuple

forward_chain(x_t, s_tm1=None, branches=None)

Execute all nodes sequentially in a forward chain.

Each node receives the output s_t of the previous node as its next input x_t. The previous state reference (s_tm1) is passed to the first node only; subsequent nodes use the previous node’s state for consistency.

Parameters:

• x_t (TensorLike) – Current input vector at time t.

• s_tm1 (TensorLike or None, optional) – Previous state (t-1), by default None.

• branches (int or None, optional) – Number of future branches (K). Uses default_branches if None.

Returns:

(s_t, ŝ_{t+1}, infos) s_t : Array Final state after the last node. ŝ_{t+1} : Array Projected next-state prediction from the last node. infos : list[dict] Per-node diagnostic information.

Return type:

tuple

predict_sequence(x_seq, s0=None, branches=None, use_chain=False)

Process an entire temporal sequence of inputs.

If use_chain is False, applies only the first node across all steps. If True, applies the full multi-node chain at each time step.

Parameters:

• x_seq (Sequence[TensorLike]) – Input sequence (T × D).

• s0 (TensorLike or None, optional) – Initial state, by default None.

• branches (int or None, optional) – Number of future branches (K). Uses default_branches if None.

• use_chain (bool, optional) – Whether to execute all nodes sequentially per time step, by default False.

Returns:

(states, futures, infos) states : list[Array] Sequence of current states. futures : list[Array] Sequence of projected next states. infos : list[Any] Per-step diagnostic information.

Return type:

tuple

class qmlhc.core.model.ModelConfig(default_branches=2)

Bases: object

Static configuration defining model execution semantics.

Parameters:

default_branches (int, optional) – Number of candidate future branches (K) used by default when no explicit value is provided, by default 2.

default_branches: int = 2