NPZ Tree Exporter

NPZ exporter plugin for vcti-tree-exporter: writes a vcti tree to a single .npz archive.

NpzExporter serializes any vcti-tree tree whose node payloads are vcti-datanode DataNodes to one NumPy .npz archive, and ships a get_exporter_descriptor() factory so a consumer registers it in a catalog and resolves it by id ("npz") or by attribute lookup.

NPZ preserves array dtype and shape natively, so it suits complete numeric simulation data — the heavy arrays JSON and CSV handle poorly.

Tree → NPZ mapping

The archive is self-contained:

• each data leaf's array is stored under a path key built from node names, e.g. model/materials/material_0, so the flat NPZ namespace still reads as the tree (duplicate paths are de-collided with a ~N suffix);
• the hierarchy, each node's attributes, and the array key of every data node are stored as one JSON manifest under the reserved key __manifest__.

import numpy as np, json
archive = np.load("model.npz")
manifest = json.loads(str(archive["__manifest__"]))   # the tree structure + attributes
array = archive["model/materials/material_0"]          # a leaf's array, native dtype

A node may carry both an array and children. Attribute values are JSON-encoded into the manifest (bytes decoded, numpy scalars/arrays converted) with a str() fallback. The export is one-way — there is no matching importer.

Usage

from pathlib import Path
from vcti.tree.exporter.core import build_registry, get_exporter
from vcti.tree.exporter.npz import get_exporter_descriptor

registry = build_registry([get_exporter_descriptor()])   # plus any other format plugins
get_exporter(registry, "npz").export(tree, Path("model.npz"), overwrite=True)

Or use the exporter directly:

from vcti.tree.exporter.npz import NpzExporter
NpzExporter().export(tree, Path("model.npz"))

Dependencies

• vcti-tree-exporter — the Exporter protocol and the ExporterDescriptor catalog.
• vcti-tree / vcti-datanode — the tree and payload types.
• numpy — the .npz backend.