vtkmodules.numpy_interface.vtk_soa_array#

VTKSOAArray — numpy-compatible mixin for vtkSOADataArrayTemplate.

This module provides the VTKSOAArray mixin class and registers overrides for all vtkSOADataArrayTemplate instantiations so that SOA arrays coming from VTK automatically have numpy-compatible operations. Per-component buffers are exposed as zero-copy numpy arrays; when a contiguous AOS array is needed, the wrapper materialises one on the fly via numpy.column_stack.

Module Contents#

Classes#

VTKSOAArray

A numpy-compatible view of VTK’s structure-of-arrays data arrays.

Functions#

_to_ndarray

Materialise a VTKSOAArray to ndarray via __array__().

_soa_to_ndarray_arg

Convert VTKSOAArray to ndarray, recursing into lists/tuples.

_soa_as_ndarray

Convert VTKSOAArray to ndarray; pass anything else through.

_soa_sum

_soa_mean

_soa_min

_soa_max

_soa_std

_soa_var

_soa_any

_soa_all

_soa_prod

_soa_argmin

_soa_argmax

_soa_cumsum

_soa_cumprod

_soa_concatenate

_soa_clip

_soa_sort

_soa_where

_soa_isin

_soa_round

_soa_dot

_register_soa_overrides

Register VTKSOAArray mixin as override for all SOA template types.

Data#

_UNINITIALIZED

API#

vtkmodules.numpy_interface.vtk_soa_array._UNINITIALIZED#

‘object(…)’

vtkmodules.numpy_interface.vtk_soa_array._to_ndarray(x)#

Materialise a VTKSOAArray to ndarray via __array__().

Calls __array__() directly for VTKSOAArray to ensure per-component column_stack materialisation.

vtkmodules.numpy_interface.vtk_soa_array._soa_to_ndarray_arg(arg)#

Convert VTKSOAArray to ndarray, recursing into lists/tuples.

vtkmodules.numpy_interface.vtk_soa_array._soa_as_ndarray(x)#

Convert VTKSOAArray to ndarray; pass anything else through.

class vtkmodules.numpy_interface.vtk_soa_array.VTKSOAArray(*args, **kwargs)#

Bases: vtkmodules.numpy_interface._vtk_array_mixin.VTKDataArrayMixin

A numpy-compatible view of VTK’s structure-of-arrays data arrays.

VTK’s SOA (structure-of-arrays) layout stores each component in a separate contiguous buffer. This mixin exposes those per-component buffers as zero-copy numpy arrays and performs element-wise operations per-component, avoiding the overhead of converting to AOS layout.

This mixin is automatically applied to all vtkSOADataArrayTemplate instantiations. Any SOA array that crosses from C++ to Python is already a VTKSOAArray instance.

Properties

shape : tuple of int (ntuples,) for 1-component, (ntuples, ncomps) otherwise. dtype : numpy.dtype The element data type. components : list of numpy.ndarray Per-component zero-copy numpy array views. dataset : vtkDataSet or None The owning VTK dataset, when the array is attached to one. association : int or None The attribute association (POINT, CELL, etc.).

Per-Component Operations

Arithmetic, comparisons, and ufuncs operate on each component buffer independently, preserving the SOA layout in the result. This avoids the memory overhead and cache penalty of interleaving components into AOS form::

arr = soa_filter.GetOutput().GetPointData().GetArray(0)
scaled = arr * 2.0          # per-component multiply, stays SOA
diff = arr1 - arr2          # per-component subtract

When an operation cannot be decomposed per-component (e.g. cross-component reductions with axis=1), the mixin materialises a contiguous AOS copy via numpy.column_stack.

Memory Safety

The mixin observes BufferChangedEvent from VTK. If any component buffer is reallocated, the cached views are automatically invalidated.

NumPy Integration

  • numpy.asarray(arr) materialises an AOS copy via column_stack.

  • Reductions (sum, mean, min, max, std, var) operate per-component without materialisation when possible.

  • numpy.concatenate, numpy.where, numpy.clip, etc. have SOA-aware overrides.

  • The __buffer__ override (PEP 688) prevents GetVoidPointer from destructively converting SOA storage to AOS.

Examples

Arrays from VTK are already the right type::

arr = soa_output.point_data["velocity"]
print(arr.components)      # [x_array, y_array, z_array]
print(np.sum(arr, axis=0)) # per-component sum, no AOS copy

Create from numpy::

from vtkmodules.util.numpy_support import numpy_to_vtk_soa
soa = numpy_to_vtk_soa([x, y, z], name="coords")

See Also

VTKAOSArray : Mixin for array-of-structures VTK arrays.

Initialization

_init_from_data(data)#

Populate this array from an iterable of per-component iterables.

Each element of data becomes one component. All components must have the same length. Data is converted to match this array’s VTK data type.

_copy_metadata_to(target)#

Copy dataset/association metadata to target array.

SetArray(comp, array, size, *args, **kwargs)#

Override to prevent garbage collection of numpy arrays passed in.

property _component_arrays#
_init_components()#

Extract per-component numpy arrays from VTK buffers.

_setup_observer()#

Set up BufferChangedEvent observer for memory safety.

property _num_tuples#
property _num_components#
property _dtype#
property dtype#
property components#

Return the list of per-component zero-copy numpy arrays.

to_numpy()#

Return tuple of per-component numpy arrays (zero-copy).

static _from_components(components, dtype=None)#

Build a VTKSOAArray from a list of numpy arrays with VTK backing.

For bool components, the backing VTK array is vtkSOADataArrayTemplate<char> (int8) since bool and char are binary compatible (both 1 byte).

__array__(dtype=None, copy=None)#
__buffer__(flags)#

Override C-level buffer protocol for SOA arrays.

Materialises an AOS copy via __array__ so that callers expecting a contiguous buffer get correct results without altering the underlying SOA storage.

__array_ufunc__(ufunc, method, *inputs, **kwargs)#
__array_function__(func, types, args, kwargs)#
__getitem__(index)#
__setitem__(index, value)#
__neg__()#
__abs__()#
_per_component(other)#

Decompose other into per-component operands, or return None.

_binop(other, op)#
_rbinop(other, op)#
__add__(other)#
__radd__(other)#
__sub__(other)#
__rsub__(other)#
__mul__(other)#
__rmul__(other)#
__truediv__(other)#
__rtruediv__(other)#
__floordiv__(other)#
__rfloordiv__(other)#
__pow__(other)#
__rpow__(other)#
__mod__(other)#
__rmod__(other)#
__lt__(other)#
__le__(other)#
__eq__(other)#
__ne__(other)#
__ge__(other)#
__gt__(other)#
__iter__()#
astype(dtype)#
__repr__()#
__str__()#
property T#
property nbytes#
copy(order='C')#
clip(a_min=None, a_max=None, **kwargs)#
round(decimals=0, **kwargs)#
sort(axis=0, **kwargs)#

Sort per-component (axis=0) or materialise for other axes.

vtkmodules.numpy_interface.vtk_soa_array._soa_sum(a, axis=None, **kwargs)#
vtkmodules.numpy_interface.vtk_soa_array._soa_mean(a, axis=None, **kwargs)#
vtkmodules.numpy_interface.vtk_soa_array._soa_min(a, axis=None, **kwargs)#
vtkmodules.numpy_interface.vtk_soa_array._soa_max(a, axis=None, **kwargs)#
vtkmodules.numpy_interface.vtk_soa_array._soa_std(a, axis=None, **kwargs)#
vtkmodules.numpy_interface.vtk_soa_array._soa_var(a, axis=None, **kwargs)#
vtkmodules.numpy_interface.vtk_soa_array._soa_any(a, axis=None, **kwargs)#
vtkmodules.numpy_interface.vtk_soa_array._soa_all(a, axis=None, **kwargs)#
vtkmodules.numpy_interface.vtk_soa_array._soa_prod(a, axis=None, **kwargs)#
vtkmodules.numpy_interface.vtk_soa_array._soa_argmin(a, axis=None, **kwargs)#
vtkmodules.numpy_interface.vtk_soa_array._soa_argmax(a, axis=None, **kwargs)#
vtkmodules.numpy_interface.vtk_soa_array._soa_cumsum(a, axis=None, **kwargs)#
vtkmodules.numpy_interface.vtk_soa_array._soa_cumprod(a, axis=None, **kwargs)#
vtkmodules.numpy_interface.vtk_soa_array._soa_concatenate(arrays, axis=0, **kwargs)#
vtkmodules.numpy_interface.vtk_soa_array._soa_clip(a, a_min=None, a_max=None, **kwargs)#
vtkmodules.numpy_interface.vtk_soa_array._soa_sort(a, axis=0, **kwargs)#
vtkmodules.numpy_interface.vtk_soa_array._soa_where(condition, x=None, y=None)#
vtkmodules.numpy_interface.vtk_soa_array._soa_isin(element, test_elements, **kwargs)#
vtkmodules.numpy_interface.vtk_soa_array._soa_round(a, decimals=0, out=None)#
vtkmodules.numpy_interface.vtk_soa_array._soa_dot(a, b)#
vtkmodules.numpy_interface.vtk_soa_array._register_soa_overrides()#

Register VTKSOAArray mixin as override for all SOA template types.