mbdlyb.formalisms.tensornet.base

Tensor Network base classes for node and network representation.

This module provides the core classes for building and managing tensor networks using the quimb library as the backend. It includes node classes with conditional probability table (CPT) support, influence factors, and automatic parent splitting for handling complex relationships.

Classes:: TNDependency: Represents a dependency relationship between tensor network nodes. TNInfluence: Represents an influence factor in a tensor network. TNElement: Abstract base class for elements in a tensor network. TensorNode: A probabilistic variable node in a tensor network. TensorAutoSplitNode: A specialized node with automatic parent splitting. TensorNet: The main tensor network container and manager.

Attributes

MAX_PARENTS

Classes

`TNDependency`	Represents a dependency relationship in a tensor network.
`TNElement`	Abstract base class for tensor network elements.
`TNInfluence`	Represents an influence factor in a tensor network.
`TensorAutoSplitNode`	A tensor network node with automatic parent splitting capability.
`TensorNet`	A tensor network container and reasoning structure.
`TensorNode`	A probabilistic node in a tensor network.

Module Contents

class mbdlyb.formalisms.tensornet.base.TNDependency(source: MBDNode, target: MBDNode, net: MBDNet | None = None)

Bases: mbdlyb.MBDDependency

Represents a dependency relationship in a tensor network.

This class encapsulates a dependency between two nodes in a tensor network, where one node (parent) influences the conditional probability of another node (child).

class mbdlyb.formalisms.tensornet.base.TNElement(name: str, net: MBDNet | None = None)

Bases: mbdlyb.MBDElement

Abstract base class for tensor network elements.

Defines the interface for creating tensor network nodes and connections within a quimb TensorNetwork structure.

abstractmethod create_tn_connections(tn: quimb.tensor.TensorNetwork)

Create connections in the tensor network.

Establishes the edges and tensor relationships between nodes.

Parameters:: tn – The quimb TensorNetwork to add connections to.
Raises:: NotImplementedError – This method must be implemented by subclasses.

abstractmethod create_tn_nodes(tn: quimb.tensor.TensorNetwork)

Create nodes in the tensor network.

Parameters:: tn – The quimb TensorNetwork to add nodes to.
Raises:: NotImplementedError – This method must be implemented by subclasses.

class mbdlyb.formalisms.tensornet.base.TNInfluence(*nodes: TensorNode, array: numpy.ndarray, net: TensorNet | None = None)

Bases: mbdlyb.MBDInfluence

Represents an influence factor in a tensor network.

Encapsulates a tensor (multi-dimensional array) that represents the influence or interaction between multiple nodes in the tensor network.

Variables:

array – The numpy array containing the tensor data.
nodes – The set of nodes involved in this influence.

create_tn_connections(tn: quimb.tensor.TensorNetwork)

Add this influence tensor to the tensor network.

Parameters:: tn – The quimb TensorNetwork to add this influence to.

array: numpy.ndarray

class mbdlyb.formalisms.tensornet.base.TensorAutoSplitNode(name: str, net: MBDNet | None = None)

Bases: TensorNode

A tensor network node with automatic parent splitting capability.

When a node has too many parents (exceeding MAX_PARENTS), this class automatically splits the parents into groups and creates intermediate tensors to handle the large parent set while maintaining probability correctness.

Variables:

_split_preserve_classes – List of node classes whose parents should not be split.
_parent_split – Mapping of split node FQNs to their parent lists, or None if no split.

create_tn_nodes(tn: quimb.tensor.TensorNetwork)

Create this node with automatic parent splitting in the tensor network.

If the number of parents exceeds MAX_PARENTS, creates intermediate split tensors to handle the large parent set. Otherwise, delegates to parent class.

Parameters:: tn – The quimb TensorNetwork to add this node to.

class mbdlyb.formalisms.tensornet.base.TensorNet(name: str, net: MBDNet | None = None)

Bases: TNElement, mbdlyb.MBDNet

A tensor network container and reasoning structure.

Manages a collection of tensor network nodes, influences, and their relationships, providing methods to convert the abstract representation into a quimb TensorNetwork for inference and analysis.

Variables:

elements – Dictionary mapping element names to TNElement instances.
influences – List of TNInfluence instances in this network.

create_tn_connections(tn: quimb.tensor.TensorNetwork)

Create all connections in the tensor network.

Iterates through all TNElement instances and establishes their connections in the quimb TensorNetwork structure.

Parameters:: tn – The quimb TensorNetwork to add connections to.

create_tn_nodes(tn: quimb.tensor.TensorNetwork)

Add all nodes and influences to the tensor network.

Iterates through all TNElement instances and TNInfluence instances and adds them to the quimb TensorNetwork structure.

Parameters:: tn – The quimb TensorNetwork to add nodes and influences to.

get_tn_influences() → list[TNInfluence]

Get all tensor influence factors in this network.

Returns:: A list of all TNInfluence instances in this network.

get_tn_nodes() → list[TNElement]

Get all tensor network elements.

Returns:: A list of all TNElement instances in this network.

to_tn() → quimb.tensor.TensorNetwork

Convert this abstract network to a quimb TensorNetwork.

Creates a complete tensor network with all nodes and influences, ready for contraction and inference operations.

Returns:: The quimb TensorNetwork instance.

elements: dict[str, TNElement]

class mbdlyb.formalisms.tensornet.base.TensorNode[T](name: str, net: MBDNet | None = None)

Bases: TNElement, mbdlyb.MBDInfluenceableNode[T], mbdlyb.formalisms.CPTEnabledNode[T]

A probabilistic node in a tensor network.

Represents a random variable with discrete states that contributes a tensor (conditional probability table) to the overall tensor network structure.

Variables:: _PARENT_RELATION_TYPE – The type of dependency used in this network.

Type Parameters:: T: The type of states this node can take.

create_tn_connections(tn: quimb.tensor.TensorNetwork)

Create connections in the tensor network.

This method is a placeholder for future connection operations. Currently, connections are handled by quimb’s native tensor network edge management.

Parameters:: tn – The quimb TensorNetwork.

create_tn_nodes(tn: quimb.tensor.TensorNetwork)

Create this node as a tensor in the tensor network.

Adds this node’s conditional probability table as a tensor to the tensor network structure, with indices representing parent and node states.

Parameters:: tn – The quimb TensorNetwork to add this node to.

mbdlyb.formalisms.tensornet.base.MAX_PARENTS = 10