vcti-fieldset 1.0.0

Named array container with lazy expression evaluation, scoped metadata, and pluggable key mapping

Field Set

Named array container with lazy expression evaluation, scoped metadata, and pluggable key mapping.

Installation

pip install vcti-fieldset>=1.0.0

For pandas DataFrame support:

pip install vcti-fieldset[dataframe]>=1.0.0

In pyproject.toml dependencies

dependencies = [
    "vcti-fieldset>=1.0.0",
]

# or, with DataFrame support:
dependencies = [
    "vcti-fieldset[dataframe]>=1.0.0",
]

---

Quick Start

import numpy as np
from vcti.fieldset import FieldSet

# Create from named arrays
fs = FieldSet(
    stress=np.array([100.0, 200.0, 150.0]),
    displacement=np.array([0.1, 0.2, 0.15]),
)

# Add computed expressions (lazy — evaluated on access)
fs.add_expression("strain = stress / 200000")
fs.get_values("strain")  # array([0.0005, 0.001, 0.00075])

# Metadata — user attributes and system settings
fs.set_property("units", "MPa", field="stress")
fs.set_property("units", "mm", field="displacement")

# Components for multi-dimensional fields
fs = FieldSet(velocity=np.array([[1, 2, 3], [4, 5, 6]]))
fs.set_components("velocity", ["x", "y", "z"])

# Generate pandas DataFrame with MultiIndex columns
df = fs.create_dataframe()

---

Core API

FieldSet

Method	Description
add_data(*args, **kwargs)	Add structured or named arrays (atomic)
get_values(name) / fs[name]	Get field array or evaluate expression
add_expression(expr)	Register lazy expression (e.g., "c = a + b")
materialize(name)	Convert expression to permanent field
remove_field(name)	Remove a stored field
remove_expression(name)	Remove a registered expression
list_fields()	List all fields and expressions
load_from_npz(path)	Load arrays from .npz file
set_property(name, value, field)	Set user attribute or system setting
get_property(name, field, default)	Get metadata value
set_components(field, components)	Set component names for a field
get_components(field)	Get component names
create_dataframe(fields)	Generate pandas DataFrame (requires [dataframe])
shape	(rows, total_fields) tuple
name in fs	Check if field or expression exists
for name in fs	Iterate over field and expression names
copy.copy(fs) / copy.deepcopy(fs)	Shallow / deep copy

Metadata

Pluggable key-value storage with hierarchical key resolution:

Class	Key format	Use case
DefaultKeyMapper	a.b.c (separator-joined)	Simple paths
ScopedKeyMapper	system.col.setting / user.col.attr	System + user scopes
ConfigKeyMapper	col.setting	System-only config

---

Dependencies

• numpy (>=1.24)
• numexpr (>=2.8)
• vcti-cache (>=1.0.0) — ObjectCache for expression results

Optional

• pandas (>=2.0) — required for create_dataframe(), install via vcti-fieldset[dataframe]