Multi Valued Array

Variable-length array for multivalued mappings — CSR-like storage with domain-codomain operations, reverse, cascade, and filtering.

Installation

pip install vcti-multi-valued-array>=1.6.0

In pyproject.toml dependencies

dependencies = [
    "vcti-multi-valued-array>=1.6.0",
]

Quick Start

import numpy as np
from vcti.multivalued import MultiValuedArray, reverse, cascade

# Create: element 0 has values [10, 20], element 1 has [30], element 2 has [40, 50, 60]
mva = MultiValuedArray(counts=np.array([2, 1, 3]), values=np.array([10, 20, 30, 40, 50, 60]))

mva.counts()          # array([2, 1, 3])
mva.offsets()         # array([0, 2, 3, 6])
mva.values()          # array([10, 20, 30, 40, 50, 60])
mva.value_indices()   # array([0, 0, 1, 2, 2, 2])  — which element each value belongs to

# With domain and codomain metadata
faces = np.array([(1, 1), (2, 2)], dtype=[('id', 'u4'), ('type', 'u4')])
vertices = np.array([(1, 0., 0.), (2, 2., 0.), (3, 3., 1.), (4, 2., 2.), (5, 0., 2.)],
                     dtype=[('id', 'u4'), ('x', 'f4'), ('y', 'f4')])

connectivity = MultiValuedArray(
    counts=np.array([4, 3], dtype=np.uint32),
    values=np.array([0, 1, 3, 4, 1, 2, 3], dtype=np.uint32),
    domain=faces,
    codomain=vertices,
)

# Reverse: for each vertex, which faces contain it
node_faces = reverse(connectivity)

Core API

MultiValuedArray

Operations

Dependencies

• numpy (>=1.24)
• numba (>=0.59) — JIT compilation for performance-critical loops
• vcti-nputils (>=1.0.0) — position_array, as_ndarray