Array Tree

A generic hierarchical tree data structure backed by NumPy structured arrays, with typed node payloads.

ArrayTree stores tree topology (parent, child, and sibling pointers) in a compact NumPy structured array for cache-friendly memory layout and efficient bulk operations. Payloads are stored separately in a typed list, so the tree works with any Python object — strings, dicts, dataclasses, or the included DataNode container for data + metadata.

Designed for CAE (Computer-Aided Engineering) workflows where trees represent assembly structures, material hierarchies, and analysis results with thousands of nodes carrying large numerical arrays.

Key features

• Generic — ArrayTree[T] accepts any payload type
• NumPy-backed topology — structured array with uint32 IDs, ~29 bytes per node
• Soft deletion — O(1) delete, explicit repack() for compaction
• Lazy loading — LazyDataNode loads array data on demand, releases to free memory
• Frozen mode — prevent mutations after construction
• Zero hard dependencies beyond NumPy

Installation

pip install vcti-array-tree>=1.4.0

In pyproject.toml dependencies

dependencies = [
    "vcti-array-tree>=1.4.0",
]

Quick Start

from vcti.arraytree import ArrayTree, DataNode

# Create a tree with any payload type
tree: ArrayTree[str] = ArrayTree()

# Add nodes (root is always id=0)
models = tree.add_node(0, data="models")
results = tree.add_node(0, data="results")
stress = tree.add_node(results, data="stress")

# Navigate
children = tree.get_children_ids(0)        # [1, 2]
parent = tree.get_parent_id(stress)         # 2 (results)
all_nodes = tree.iter_nodes(0)              # [1, 2, 3] depth-first

# Access and update payloads
tree.get_node(stress)                       # "stress"
tree.set_node(stress, "von_mises_stress")   # update payload

# Ancestry and depth
tree.get_ancestor_ids(stress)               # [2, 0] (results, root)
tree.get_depth(stress)                      # 2

# Soft-delete and repack
tree.delete_node(models)
mapping = tree.repack()                     # compacts, remaps IDs

# Freeze for read-only access
tree.freeze()

With DataNode payloads

import numpy as np
from vcti.arraytree import ArrayTree, DataNode

tree: ArrayTree[DataNode] = ArrayTree()

tree.add_node(0, DataNode(
    data=np.array([1.0, 2.0, 3.0]),
    attributes={'units': 'mm', 'name': 'displacement'},
))

tree.add_node(0, DataNode(
    attributes={'type': 'group', 'solver': 'NASTRAN'},
))

Error handling

from vcti.arraytree import ArrayTree

tree: ArrayTree[str] = ArrayTree()
node = tree.add_node(0, "data")

# KeyError — node doesn't exist
try:
    tree.get_node(999)
except KeyError:
    pass

# ValueError — node is deleted
tree.delete_node(node)
try:
    tree.get_node(node)
except ValueError:
    pass

# RuntimeError — tree is frozen
tree.freeze()
try:
    tree.add_node(0, "blocked")
except RuntimeError:
    pass

Core API

ArrayTree[T]

DataNode

Simple container for tree node payloads:

LazyDataNode

DataNode subclass with on-demand loading for large arrays:

from vcti.arraytree import ArrayTree, LazyDataNode

tree: ArrayTree[LazyDataNode] = ArrayTree()

node = LazyDataNode(
    loader=lambda: load_stress_data(path, offset),
    attributes={'units': 'MPa', 'name': 'stress'},
)
nid = tree.add_node(0, node)

# Attributes always available
tree.get_node(nid).attributes       # {'units': 'MPa', 'name': 'stress'}

# Array loaded on demand
tree.get_node(nid).is_loaded        # False
tree.get_node(nid).load()           # calls loader, caches result
tree.get_node(nid).is_loaded        # True
tree.get_node(nid).release()        # frees array, can reload later

Configuration

The ID dtype and sentinel value are configurable per tree:

import numpy as np
from vcti.arraytree import ArrayTree

tree = ArrayTree(id_dtype=np.uint64)          # 64-bit node IDs
tree.id_dtype                                  # dtype('uint64')
tree.invalid_id                                # 18446744073709551615
tree.tree_dtype                                # structured dtype for topology

The make_tree_dtype(id_dtype) helper builds the structured dtype for external consumers (e.g., file loaders building topology arrays).

Exceptions

Dependencies

• numpy (>=1.24)