Struct SiteIndexNetwork 

pub struct SiteIndexNetwork<NodeName, I>
where
    NodeName: Clone + Hash + Eq + Send + Sync + Debug,
    I: IndexLike,
{ /* private fields */ }

Site Index Network (inspired by ITensorNetworks.jl’s IndsNetwork)

Represents the index structure of a tensor network:

• Topology: Graph structure via NodeNameNetwork
• Site space: Physical indices at each node via HashMap

This structure enables:

• Comparing topologies and site spaces independently of tensor data
• Extracting index information without accessing tensor values
• Validating network structure consistency

Type Parameters

• NodeName: Node name type (must be Clone, Hash, Eq, Send, Sync, Debug)
• I: Index type (must implement IndexLike)

Examples

use std::collections::HashSet;
use tensor4all_core::index::{DynId, Index, TagSet};
use tensor4all_treetn::SiteIndexNetwork;

let mut net = SiteIndexNetwork::<String, Index<DynId, TagSet>>::new();
let idx_a = Index::new_dyn(2);
let idx_b = Index::new_dyn(3);

net.add_node("A".to_string(), HashSet::from([idx_a])).unwrap();
net.add_node("B".to_string(), HashSet::from([idx_b])).unwrap();
net.add_edge(&"A".to_string(), &"B".to_string()).unwrap();

assert_eq!(net.node_count(), 2);
assert_eq!(net.edge_count(), 1);

Implementations

impl<NodeName, I> SiteIndexNetwork<NodeName, I>

where NodeName: Clone + Hash + Eq + Send + Sync + Debug, I: IndexLike,

pub fn new() -> Self

Create a new empty SiteIndexNetwork.

pub fn with_capacity(nodes: usize, edges: usize) -> Self

Create a new SiteIndexNetwork with initial capacity.

pub fn add_node( &mut self, node_name: NodeName, site_space: impl Into<HashSet<I>>, ) -> Result<NodeIndex, String>

Add a node with site space (physical indices).

Arguments

• node_name - The name of the node
• site_space - The physical indices at this node (order doesn’t matter)

Returns an error if the node already exists.

pub fn has_node(&self, node_name: &NodeName) -> bool

Check if a node exists.

pub fn rename_node( &mut self, old_name: &NodeName, new_name: NodeName, ) -> Result<(), String>

Rename an existing node and preserve its site-space metadata.

pub fn site_space(&self, node_name: &NodeName) -> Option<&HashSet<I>>

Get the site space (physical indices) for a node.

pub fn site_space_mut( &mut self, node_name: &NodeName, ) -> Option<&mut HashSet<I>>

Get a mutable reference to the site space for a node.

Warning: Direct modification of site space via this method does NOT update the reverse lookup (index_to_node). Use add_site_index(), remove_site_index(), or replace_site_index() for modifications that maintain consistency.

pub fn find_node_by_index(&self, index: &I) -> Option<&NodeName>

Find the node containing a given site index.

Arguments

• index - The index to look up

Returns

The node name containing this index, or None if not found.

pub fn find_node_by_index_id(&self, id: &I::Id) -> Option<&NodeName>

Find the node containing an index by ID.

pub fn contains_index(&self, index: &I) -> bool

Check if a site index is registered.

pub fn add_site_index( &mut self, node_name: &NodeName, index: I, ) -> Result<(), String>

Add a site index to a node’s site space.

Updates both the site space and the reverse lookup.

pub fn remove_site_index( &mut self, node_name: &NodeName, index: &I, ) -> Result<bool, String>

Remove a site index from a node’s site space.

Updates both the site space and the reverse lookup.

pub fn replace_site_index( &mut self, node_name: &NodeName, old_index: &I, new_index: I, ) -> Result<(), String>

Replace a site index in a node’s site space.

Updates both the site space and the reverse lookup.

pub fn set_site_space( &mut self, node_name: &NodeName, new_indices: HashSet<I>, ) -> Result<(), String>

Replace all site indices for a node with a new set.

Updates both the site space and the reverse lookup. This is an atomic operation that removes all old indices and adds all new ones.

pub fn site_space_by_index(&self, node: NodeIndex) -> Option<&HashSet<I>>

Get the site space by NodeIndex.

pub fn add_edge( &mut self, n1: &NodeName, n2: &NodeName, ) -> Result<EdgeIndex, String>

Add an edge between two nodes.

Returns an error if either node doesn’t exist.

pub fn node_index(&self, node_name: &NodeName) -> Option<NodeIndex>

Get the NodeIndex for a node name.

pub fn node_name(&self, node: NodeIndex) -> Option<&NodeName>

Get the node name for a NodeIndex.

pub fn node_names(&self) -> Vec<&NodeName>

Get all node names.

pub fn node_count(&self) -> usize

Get the number of nodes.

pub fn edge_count(&self) -> usize

Get the number of edges.

pub fn topology(&self) -> &NodeNameNetwork<NodeName>

Get a reference to the underlying topology (NodeNameNetwork).

pub fn edges(&self) -> impl Iterator<Item = (NodeName, NodeName)> + '_

Get all edges as pairs of node names.

Returns an iterator of (NodeName, NodeName) pairs.

pub fn neighbors( &self, node_name: &NodeName, ) -> impl Iterator<Item = NodeName> + '_

Get all neighbors of a node.

Returns an iterator of neighbor node names.

pub fn graph(&self) -> &StableGraph<(), (), Undirected>

Get a reference to the internal graph.

pub fn graph_mut(&mut self) -> &mut StableGraph<(), (), Undirected>

Get a mutable reference to the internal graph.

Warning: Directly modifying the internal graph can break consistency.

pub fn share_equivalent_site_index_network(&self, other: &Self) -> bool

Check if two SiteIndexNetworks share equivalent site index structure.

Two networks are equivalent if:

• Same topology (nodes and edges)
• Same site space for each node

This is used to verify that two TreeTNs can be added or contracted.

pub fn post_order_dfs(&self, root: &NodeName) -> Option<Vec<NodeName>>

Perform a post-order DFS traversal starting from the given root node.

pub fn post_order_dfs_by_index(&self, root: NodeIndex) -> Vec<NodeIndex>

Perform a post-order DFS traversal starting from the given root NodeIndex.

pub fn path_between( &self, from: NodeIndex, to: NodeIndex, ) -> Option<Vec<NodeIndex>>

Find the shortest path between two nodes.

pub fn steiner_tree_nodes( &self, terminals: &HashSet<NodeIndex>, ) -> HashSet<NodeIndex>

Compute the Steiner tree nodes spanning a set of terminal nodes.

Delegates to NodeNameNetwork::steiner_tree_nodes.

Examples

use std::collections::HashSet;
use tensor4all_core::DynIndex;
use tensor4all_treetn::SiteIndexNetwork;

let mut net: SiteIndexNetwork<String, DynIndex> = SiteIndexNetwork::new();
let a = net.add_node("A".to_string(), HashSet::<DynIndex>::new()).unwrap();
let b = net.add_node("B".to_string(), HashSet::<DynIndex>::new()).unwrap();
let c = net.add_node("C".to_string(), HashSet::<DynIndex>::new()).unwrap();
net.add_edge(&"A".to_string(), &"B".to_string()).unwrap();
net.add_edge(&"B".to_string(), &"C".to_string()).unwrap();

let steiner = net.steiner_tree_nodes(&[a, c].into_iter().collect::<HashSet<_>>());
assert_eq!(steiner, [a, b, c].into_iter().collect());

pub fn is_connected_subset(&self, nodes: &HashSet<NodeIndex>) -> bool

Check if a subset of nodes forms a connected subgraph.

pub fn edges_to_canonicalize( &self, current_region: Option<&HashSet<NodeIndex>>, target: NodeIndex, ) -> CanonicalizeEdges

Compute edges to canonicalize from current state to target.

pub fn edges_to_canonicalize_by_names( &self, target: &NodeName, ) -> Option<Vec<(NodeName, NodeName)>>

Compute edges to canonicalize from leaves to target, returning node names.

This is similar to edges_to_canonicalize(None, target) but returns (from_name, to_name) pairs instead of (NodeIndex, NodeIndex).

See NodeNameNetwork::edges_to_canonicalize_by_names for details.

pub fn edges_to_canonicalize_to_region( &self, target_region: &HashSet<NodeIndex>, ) -> CanonicalizeEdges

Compute edges to canonicalize from leaves towards a connected region (multiple centers).

See NodeNameNetwork::edges_to_canonicalize_to_region for details.

pub fn edges_to_canonicalize_to_region_by_names( &self, target_region: &HashSet<NodeName>, ) -> Option<Vec<(NodeName, NodeName)>>

Compute edges to canonicalize towards a region, returning node names.

See NodeNameNetwork::edges_to_canonicalize_to_region_by_names for details.

pub fn apply_operator_topology(&self, operator: &Self) -> Result<Self, String>

Check if an operator can act on this state (as a ket).

Returns Ok(result_network) if the operator can act on self, where result_network is the SiteIndexNetwork of the output state.

For an operator to act on a state:

• They must have the same topology (same nodes and edges)
• The operator must have indices that can contract with the state’s site indices

Arguments

• operator - The operator’s SiteIndexNetwork

Returns

• Ok(SiteIndexNetwork) - The resulting state’s site index network after the operator acts
• Err(String) - Error message if the operator cannot act on this state

Note

This is a simplified version that assumes the operator’s output indices have the same structure as the input (i.e., the result has the same site index structure as the original state). For more complex operators with different input/output dimensions, a more sophisticated approach would be needed.

pub fn compatible_site_dimensions(&self, other: &Self) -> bool

Check if this network has compatible site dimensions with another.

Two networks have compatible site dimensions if:

• Same topology (nodes and edges)
• Each node has the same number of site indices
• Site index dimensions match (after sorting, order doesn’t matter)

This is useful for checking if two states can be added or if a state matches the expected output of an operator.

Trait Implementations

impl<NodeName, I> Clone for SiteIndexNetwork<NodeName, I>

where NodeName: Clone + Hash + Eq + Send + Sync + Debug + Clone, I: IndexLike + Clone, I::Id: Clone,

fn clone(&self) -> SiteIndexNetwork<NodeName, I>

Returns a duplicate of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl<NodeName, I> Debug for SiteIndexNetwork<NodeName, I>

where NodeName: Clone + Hash + Eq + Send + Sync + Debug + Debug, I: IndexLike + Debug, I::Id: Debug,

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl<NodeName, I> Default for SiteIndexNetwork<NodeName, I>

where NodeName: Clone + Hash + Eq + Send + Sync + Debug, I: IndexLike,

fn default() -> Self

Returns the “default value” for a type.

impl<NodeName, I> NetworkTopology<NodeName> for SiteIndexNetwork<NodeName, I>

where NodeName: Clone + Hash + Eq + Send + Sync + Debug, I: IndexLike,

Implement NetworkTopology for SiteIndexNetwork.

This enables direct use of SiteIndexNetwork for cache invalidation and environment computation without needing adapter types like StaticTopology.

type Neighbors<'a> = Box<dyn Iterator<Item = NodeName> + 'a> where Self: 'a, NodeName: 'a

Iterator over neighbors of a node.

fn neighbors(&self, node: &NodeName) -> Self::Neighbors<'_>

Get neighbors of a node.