Source code for tecio._reader

"""Shared, format-independent base classes for Tecplot readers.

Every format's reader (SZL, PLT, DAT) exposes the same interface: :class:`TecplotReader`
(the open file/dataset), :class:`TecplotZoneReader` (one zone, split into
:class:`TecplotOrderedZoneReader`, :class:`TecplotFEZoneReader`,
:class:`TecplotFEMixedZoneReader`, and :class:`TecplotPolyZoneReader` since the
topologies don't share properties like dimensions or connectivity),
:class:`TecplotVariableReader` (one variable within a zone, not split by value location
or zone topology, neither changes which properties exist, only the shape
``get_values()`` returns, which the method already computes from
``zone_type``/``value_location``), and :class:`TecplotAuxDataReader` (a read-only
auxiliary-data mapping). This module defines that interface once so the three formats
can no longer drift apart, and so downstream code (the ParaView plugin, in particular)
can be written against ``TecplotZoneReader``/``TecplotVariableReader`` instead of
``Any``.

Design notes:
    * Instances are immutable: attribute assignment raises :exc:`AttributeError`.
      Internal caches for lazily loaded data (a zone's variable list, node map, and
      aux data) are populated through ``object.__setattr__``, bypassing the
      blocked ``__setattr__`` on purpose, the same trick :mod:`~tecio._meta`
      already uses via ``frozen=True`` dataclasses, applied by hand here because
      these classes also need lazy loading, which a plain frozen dataclass can't
      combine with ``__slots__``.
    * :class:`TecplotZoneReader` and its subclasses split fields into two groups.
      Small, cheap scalar metadata (title, zone type, dimensions or node/element
      counts, solution time, strand ID) is resolved once at construction and
      frozen, since even a per-value C call is cheap and doing it once beats
      re-querying on every access. Data that can be large (the variable list, an
      FE node map that may hold millions of entries) or that a caller may never
      touch (aux data) stays lazily loaded on first access, exactly matching each
      format's existing behaviour.
    * Unlike :mod:`~tecio._meta`, this module imports :mod:`~tecio._constants`
      at runtime rather than only under ``TYPE_CHECKING``. ``_meta`` only ever
      needs the enums as type annotations (erased at runtime by ``from __future__
      import annotations``); ``nodes_per_cell`` below needs the actual
      ``ZoneType`` members to key a lookup table, so a runtime import is
      unavoidable. ``_constants`` is a dependency-free leaf module (no C library,
      no other ``tecio`` submodule), so this introduces no cycle regardless.
"""

from __future__ import annotations

import hashlib
from abc import ABC, abstractmethod
from collections.abc import ItemsView, Iterator, KeysView, Mapping, ValuesView
from typing import Any, Final, Literal, TypeAlias, overload

import numpy as np
import numpy.typing as npt

from ._constants import (
    DataPacking,
    DataType,
    FaceNeighborMode,
    FeCellShape,
    FileType,
    ValueLocation,
    ZoneType,
)
from ._containers import VariableList, ZoneList, select_variable_arrays
from ._elements import faces_by_element, nodes_by_element
from ._utils import public_dir

# Nodes per element for the standard finite-element zone types. ORDERED zones are
# computed from active dimensions instead, see TecplotZoneReader.nodes_per_cell.
_NODES_PER_ELEM: dict[ZoneType, int] = {
    ZoneType.FELINESEG: 2,
    ZoneType.FETRIANGLE: 3,
    ZoneType.FEQUADRILATERAL: 4,
    ZoneType.FETETRAHEDRON: 4,
    ZoneType.FEBRICK: 8,
}


def reshape_face_connections(
    flat: npt.NDArray[np.int64],
    mode: FaceNeighborMode,
    num_connections: int,
) -> npt.NDArray[np.int64] | list[npt.NDArray[np.int64]]:
    """Reshape flat face-neighbor connection values per ``FaceNeighborMode``.

    Shared across formats, any reader whose C/binary layer returns face
    connections as a flat array can call this to get the structured form
    :attr:`TecplotFEZoneReader.face_connections` documents.

    ``LOCAL_ONE_TO_ONE`` (3 values/connection: ``cz1, fz, cz2``) and
    ``GLOBAL_ONE_TO_ONE`` (4 values/connection: ``cz, fz, ZZ, CZ``) are
    uniform, reshaped directly into a 2D array of shape
    ``(num_connections, 3 or 4)``.

    ``LOCAL_ONE_TO_MANY``/``GLOBAL_ONE_TO_MANY`` are ragged: each record
    starts with a fixed 4-value header (``cz, fz, oz, nz``), where ``nz``
    (the record's own 4th value) gives the count of additional neighbor
    references that follow, ``nz`` cell indices for local, ``2*nz``
    zone/cell index pairs for global. Since no single rectangular shape
    fits, each record is returned as its own 1D array, walking the flat
    buffer using each record's own ``nz`` to find where the next one
    starts. This ragged case is rare in practice for the classic FE element
    types this reader targets, "many" typically comes from polygon zones
    instead.

    Args:
        flat: The raw flat array as read from the file/library.
        mode: This zone's face-neighbor mode.
        num_connections: Number of connections, from a dedicated count
            (e.g. ``tecZoneFaceNbrGetNumConnections``), not inferred from
            *flat*'s length, which isn't reliable for the ragged modes.

    Returns:
        A ``(num_connections, 3 or 4)`` array for the one-to-one modes, or
        a list of ``num_connections`` 1D arrays for the one-to-many modes.
    """
    if mode is FaceNeighborMode.LOCAL_ONE_TO_ONE:
        return flat.reshape(num_connections, 3)
    if mode is FaceNeighborMode.GLOBAL_ONE_TO_ONE:
        return flat.reshape(num_connections, 4)

    is_global = mode is FaceNeighborMode.GLOBAL_ONE_TO_MANY
    connections: list[npt.NDArray[np.int64]] = []
    i = 0
    for _ in range(num_connections):
        nz = int(flat[i + 3])
        record_len = 4 + (2 * nz if is_global else nz)
        connections.append(flat[i : i + record_len])
        i += record_len
    return connections


def convert_face_connections_to_zero_based(
    flat: npt.NDArray[np.int64], mode: FaceNeighborMode
) -> npt.NDArray[np.int64]:
    """Convert a flat, fully 1-based face-neighbor array to the public convention.

    Shared by any reader whose source is inherently 1-based throughout (SZL's live C
    calls, DAT's ASCII text), unlike PLT's binary layout which needs its own,
    different conversion.

    For the one-to-one modes, every value in a record (cell, face ordinal, and for
    the global mode, remote zone and remote cell) is an index, so the whole array
    shifts uniformly. The "many" modes are ragged and mix in two non-index fields
    (``oz``, the face obscuration flag, and ``nz``, the trailing-reference count)
    that must stay untouched, so each record is converted individually instead.

    Args:
        flat: The raw flat array, exactly as returned by the source, fully 1-based.
        mode: This zone's face-neighbor mode.

    Returns:
        A new flat array with cell/face/remote-zone fields converted, safe to
        reshape with :func:`reshape_face_connections`.
    """
    one_to_one = (FaceNeighborMode.LOCAL_ONE_TO_ONE, FaceNeighborMode.GLOBAL_ONE_TO_ONE)
    if mode in one_to_one:
        return flat - 1

    flat = flat.copy()
    is_global = mode is FaceNeighborMode.GLOBAL_ONE_TO_MANY
    i = 0
    while i < flat.size:
        nz = int(flat[i + 3])
        rest_count = 2 * nz if is_global else nz
        flat[i] -= 1  # local cell number
        flat[i + 1] -= 1  # face ordinal
        # flat[i + 2] (oz, the obscuration flag) and nz itself are not indices.
        flat[i + 4 : i + 4 + rest_count] -= 1  # trailing cell/zone references
        i += 4 + rest_count
    return flat


def _immutable_setattr(instance: object, name: str, value: object) -> None:
    """Raise, used as every reader class's ``__setattr__``.

    Raises:
        AttributeError: Always raised when called to prevent user-added or modified attributes.
    """
    raise AttributeError(f"{type(instance).__name__} instances are immutable")


def _immutable_delattr(instance: object, name: str) -> None:
    """Raise, used as every reader class's ``__delattr__``.

    Raises:
        AttributeError: Always raised when called to prevent user-removed attributes.
    """
    raise AttributeError(f"{type(instance).__name__} instances are immutable")


# ======================================================================================
# TecplotAuxDataReader
# ======================================================================================


class TecplotAuxDataReader(Mapping[str, str], ABC):
    """Read-only view of one Tecplot auxiliary-data mapping.

    Backs dataset-, zone-, and variable-level auxiliary data for all three formats.
    Subclasses supply the underlying ``{name: value}`` mapping through
    :meth:`_load_data`, called at most once, on first access, and cached for the
    life of the object.

    Implements :class:`collections.abc.Mapping`, so ``get``, ``keys``, ``values``,
    ``items``, ``__contains__``, and ``in`` all work without being redefined here.

    Note:
        A concrete subclass must call ``super().__init__()`` first, then store
        any private fields it needs (the data source to lazily load from) with
        ``object.__setattr__``, the same contract as :class:`TecplotZoneReader`
        and :class:`TecplotVariableReader`.
    """

    __slots__ = ("_cache",)
    _cache: dict[str, str] | None

    def __init__(self) -> None:
        object.__setattr__(self, "_cache", None)

    __setattr__ = _immutable_setattr
    __delattr__ = _immutable_delattr

    @abstractmethod
    def _load_data(self) -> dict[str, str]:
        """Return the underlying mapping. Called at most once, lazily."""

    @property
    def _data(self) -> dict[str, str]:
        data = self._cache
        if data is None:
            data = self._load_data()
            object.__setattr__(self, "_cache", data)
        return data

    def __getitem__(self, key: str) -> str:
        return self._data[key]

    def __len__(self) -> int:
        return len(self._data)

    def __iter__(self) -> Iterator[str]:
        return iter(self._data)

    def __repr__(self) -> str:  # pragma: no cover
        return f"{type(self).__name__}({self._data!r})"

    # Mapping already provides get/keys/values/items via __getitem__ + __iter__ +
    # __len__, but typed overrides are kept here since the base implementations
    # return generic view types rather than the str-specific ones callers expect.

[docs] def keys(self) -> KeysView[str]: """Return the auxiliary data names.""" return self._data.keys()
[docs] def values(self) -> ValuesView[str]: """Return the auxiliary data values.""" return self._data.values()
[docs] def items(self) -> ItemsView[str, str]: """Return the ``(name, value)`` pairs.""" return self._data.items()
[docs] def as_int(self, key: str, default: int | None = None) -> int | None: """Return the value for *key* as :class:`int`, or *default* on failure.""" try: return int(self._data[key]) except (KeyError, ValueError): return default
[docs] def as_float(self, key: str, default: float | None = None) -> float | None: """Return the value for *key* as :class:`float`, or *default* on failure.""" try: return float(self._data[key]) except (KeyError, ValueError): return default
[docs] def as_bool(self, key: str, default: bool | None = None) -> bool | None: """Return the value for *key* as :class:`bool`, or *default* on failure. Recognizes ``true``/``t``/``yes``/``y``/``1`` as True and ``false``/``f``/``no``/``n``/``0`` as False, case-insensitively. """ try: value = self._data[key].strip().lower() except KeyError: return default if value in ("true", "t", "yes", "y", "1"): return True if value in ("false", "f", "no", "n", "0"): return False return default
# ====================================================================================== # TecplotVariableReader # ====================================================================================== class TecplotVariableReader(ABC): """Read-only handle to one variable's metadata and data within a zone. Every metadata field is resolved by the concrete subclass on each access (a single libtecio call, or a lookup in already-parsed metadata), cheap enough in every format that this base does not add its own caching layer on top. Only :attr:`values` reads actual array data, and only when called. Note: ``__setattr__`` is blocked here, which also applies inside a subclass's own ``__init__``. A concrete subclass must store its private fields with ``object.__setattr__(self, "_name", value)`` rather than plain assignment, and should declare its own ``__slots__`` for them. """ __slots__ = () __setattr__ = _immutable_setattr __delattr__ = _immutable_delattr def __repr__(self) -> str: # pragma: no cover parts = [repr(self.name)] if self.is_passive(): parts.append("passive") elif self.shared_zone is not None: parts.append(f"shared(zone={self.shared_zone})") else: parts.append(f"dtype={self.data_type.name}") values = self.values if values is not None: parts.append(f"shape={values.shape}") if self.value_location == ValueLocation.CELL_CENTERED: parts.append("CELL_CENTERED") return f"{type(self).__name__}({', '.join(parts)})" # -- Abstract: one C call / metadata lookup each, format-specific ------------------ @property @abstractmethod def name(self) -> str: """Variable name string.""" @property @abstractmethod def data_type(self) -> DataType: """Stored data type.""" @property @abstractmethod def value_location(self) -> ValueLocation: """NODAL or CELL_CENTERED."""
[docs] @abstractmethod def is_passive(self) -> bool: """True if this variable has no data in this zone."""
@property @abstractmethod def shared_zone(self) -> int | None: """0-based source zone index if shared, else None.""" @property @abstractmethod def num_values(self) -> int: """Number of stored values, 0 for a passive variable."""
[docs] @abstractmethod def get_values( self, value_range: tuple[int | None, int | None] = (None, None), ) -> npt.NDArray[Any] | None: """Read values from disk or memory. Args: value_range: 1-based ``(start, end)``, half-open. ``(None, None)`` reads all values. Returns: The data array, or ``None`` if the variable is passive. A shared variable resolves to its source zone's array. Raises: ValueError: If only one of ``start``/``end`` is given. """
# -- Shared ------------------------------------------------------------------------
[docs] def is_enabled(self) -> bool: """True unless the variable is passive. SZL overrides this with the dataset-level enabled flag it actually stores; PLT and DAT have no such flag and use this default. Returns: bool: ``True`` for an active variable. """ return not self.is_passive()
@property def values(self) -> npt.NDArray[Any] | None: """All values as a NumPy array, or None if passive.""" return self.get_values() # ====================================================================================== # TecplotZoneReader # ====================================================================================== class TecplotZoneReader(ABC): """Read-only handle to one zone's metadata in an open Tecplot file. This is the common base for :class:`TecplotOrderedZoneReader` and :class:`TecplotFEZoneReader`. Only properties that mean the same thing for every zone topology live here, dimensions, node maps, and everything else that's specific to one topology live on the corresponding subclass instead, so accessing e.g. ``.node_map`` on an ordered zone is a plain :exc:`AttributeError` rather than a silent ``None``. Scalar metadata (title, zone type, solution time, strand ID, datapacking) is resolved once at construction and frozen. The variable list and aux data stay lazily loaded on first access, since either can be large enough that eagerly building them for every zone in a file would be wasteful. Args: zone_index: 0-based zone index within the dataset. title: Zone title. zone_type: The zone's :class:`~tecio.libtecio.ZoneType`. solution_time: Solution time, 0.0 for static data. strand_id: Strand ID, 0 for static data. datapacking: On-disk value layout. SZL and every PLT version from v107 onward always supply :attr:`~tecio.libtecio.DataPacking.BLOCK`, those formats have no packing distinction on disk; the field exists purely so code can treat every zone uniformly regardless of source format. The legacy PLT v75 format is the one exception: it genuinely stores some zones interleaved by node/element (POINT/FEPOINT), reported here as :attr:`~tecio.libtecio.DataPacking.POINT`. """ __slots__ = ( "_zone_index", "_title", "_zone_type", "_solution_time", "_strand_id", "_datapacking", "_variable_cache", "_auxdata_cache", ) _zone_index: int _title: str _zone_type: ZoneType _solution_time: float _strand_id: int _datapacking: DataPacking _variable_cache: VariableList[TecplotVariableReader] | None _auxdata_cache: TecplotAuxDataReader | None def __init__( self, zone_index: int, title: str, zone_type: ZoneType, solution_time: float, strand_id: int, datapacking: DataPacking, ) -> None: object.__setattr__(self, "_zone_index", zone_index) object.__setattr__(self, "_title", title) object.__setattr__(self, "_zone_type", zone_type) object.__setattr__(self, "_solution_time", solution_time) object.__setattr__(self, "_strand_id", strand_id) object.__setattr__(self, "_datapacking", datapacking) object.__setattr__(self, "_variable_cache", None) object.__setattr__(self, "_auxdata_cache", None) __setattr__ = _immutable_setattr __delattr__ = _immutable_delattr def __dir__(self) -> list[str]: # pragma: no cover """List only the public attributes and methods. Returns: list[str]: Names of the public attributes and methods, and the dunder names. """ return public_dir(self) def __repr__(self) -> str: # pragma: no cover title = self.title if len(title) > 30: title = title[:29] + "\u2026" extra = f", aux={len(self.auxdata)}" if len(self.auxdata) else "" cls = type(self).__name__ return f"{cls}({title!r}, {self.zone_type.name}, {self._repr_size()}{extra})" @abstractmethod def _repr_size(self) -> str: """Return the shape portion of __repr__, e.g. ``'I=4, J=3, K=1'``.""" # -- Frozen scalar metadata -------------------------------------------------------- @property def zone_index(self) -> int: """0-based zone index within the dataset.""" return self._zone_index @property def title(self) -> str: """Zone title string.""" return self._title @property def zone_type(self) -> ZoneType: """The zone's :class:`~tecio.libtecio.ZoneType`.""" return self._zone_type @property def solution_time(self) -> float: """Solution time, 0.0 for static data.""" return self._solution_time @property def strand_id(self) -> int: """Strand ID, 0 for static data.""" return self._strand_id @property def datapacking(self) -> DataPacking: """On-disk value layout for this zone.""" return self._datapacking
[docs] def is_enabled(self) -> bool: """True unless the zone reports itself disabled. Only SZL can report False here; PLT and DAT have no such flag. Returns: bool: ``True`` whenever called in the base class. SZL may report ``False``, but all other file formats will report ``True``. """ return True
# -- Lazy: variable list, aux data ------------------------------------------------ @property def variables(self) -> VariableList[TecplotVariableReader]: """Variables in this zone, by 0-based index or exact name.""" variables = self._variable_cache if variables is None: variables = VariableList(self._load_variables()) object.__setattr__(self, "_variable_cache", variables) return variables @abstractmethod def _load_variables(self) -> list[TecplotVariableReader]: """Construct this zone's variable readers. Called at most once, lazily.""" @property def auxdata(self) -> TecplotAuxDataReader: """Zone-level auxiliary data.""" aux = self._auxdata_cache if aux is None: aux = self._load_auxdata() object.__setattr__(self, "_auxdata_cache", aux) return aux @abstractmethod def _load_auxdata(self) -> TecplotAuxDataReader: """Construct this zone's aux-data reader. Called at most once, lazily.""" # -- Fully generic ----------------------------------------------------------------- @overload def get_array(self, key: int | str) -> npt.NDArray[Any] | None: ... @overload def get_array(self, key: list[str]) -> tuple[npt.NDArray[Any] | None, ...]: ...
[docs] def get_array( self, key: int | str | list[str] ) -> npt.NDArray[Any] | None | tuple[npt.NDArray[Any] | None, ...]: """Return variable data array(s) for this zone. A single key (0-based index or exact name) returns one array. A list of exact names returns a tuple of arrays in the order given:: p = zone.get_array("p") x, y, z = zone.get_array(["x", "y", "z"]) Returns: One array (or ``None`` only if the variable is passive) for a scalar key; a tuple of such arrays for a list of names. Raises: KeyError: If a name does not exist. IndexError: If an index is out of range. """ return select_variable_arrays(self.variables, key)
# ====================================================================================== # TecplotOrderedZoneReader # ====================================================================================== class TecplotOrderedZoneReader(TecplotZoneReader): """Read-only handle to one ORDERED (IJK-structured) zone. Args: zone_index: 0-based zone index within the dataset. title: Zone title. solution_time: Solution time, 0.0 for static data. strand_id: Strand ID, 0 for static data. datapacking: On-disk value layout. i: Nodal I dimension. j: Nodal J dimension. k: Nodal K dimension. """ __slots__ = ("_i", "_j", "_k") _i: int _j: int _k: int def __init__( self, zone_index: int, title: str, solution_time: float, strand_id: int, datapacking: DataPacking, i: int, j: int, k: int, ) -> None: super().__init__( zone_index=zone_index, title=title, zone_type=ZoneType.ORDERED, solution_time=solution_time, strand_id=strand_id, datapacking=datapacking, ) object.__setattr__(self, "_i", i) object.__setattr__(self, "_j", j) object.__setattr__(self, "_k", k) def _repr_size(self) -> str: return f"I={self._i}, J={self._j}, K={self._k}" @property def I(self) -> int: # noqa: E743 N802 """Nodal I dimension.""" return self._i @property def J(self) -> int: # noqa: N802 """Nodal J dimension.""" return self._j @property def K(self) -> int: # noqa: N802 """Nodal K dimension.""" return self._k @property def dimensions(self) -> tuple[int, int, int]: """``(I, J, K)`` dimensions.""" return (self._i, self._j, self._k) @property def num_nodes(self) -> int: """Number of nodes/points, ``I * J * K``.""" return self._i * self._j * self._k @property def num_elements(self) -> int: """Number of cells.""" # Normalize to proper dimension if self._k == 1 and self._j == 1: # 1D case return self._i - 1 elif self._k == 1 and self._j > 1: # 2D case return (self._i - 1) * (self._j - 1) else: # 3D case return (self._i - 1) * (self._j - 1) * (self._k - 1) # ====================================================================================== # TecplotFEZoneReader # ====================================================================================== class TecplotFEZoneReader(TecplotZoneReader): """Read-only handle to one finite-element zone. Covers the classic element zone types (FELINESEG through FEBRICK). Face-based FEPOLYGON and FEPOLYHEDRON zones are read by :class:`TecplotPolyZoneReader`. Args: zone_index: 0-based zone index within the dataset. title: Zone title. zone_type: The zone's :class:`~tecio.libtecio.ZoneType`. solution_time: Solution time, 0.0 for static data. strand_id: Strand ID, 0 for static data. datapacking: On-disk value layout. num_nodes: Number of nodes/points. num_elements: Number of elements/cells. shared_connectivity: 0-based source zone index if this zone's connectivity is shared, else None. """ __slots__ = ( "_num_nodes", "_num_elements", "_shared_connectivity", "_node_map_cache", "_node_map_loaded", "_face_neighbor_meta_cache", "_face_neighbor_meta_loaded", "_face_connections_cache", "_face_connections_loaded", ) _num_nodes: int _num_elements: int _shared_connectivity: int | None _node_map_cache: npt.NDArray[np.int64] | None _node_map_loaded: bool _face_neighbor_meta_cache: tuple[FaceNeighborMode, int, bool | None] | None _face_neighbor_meta_loaded: bool _face_connections_cache: npt.NDArray[np.int64] | None _face_connections_loaded: bool def __init__( self, zone_index: int, title: str, zone_type: ZoneType, solution_time: float, strand_id: int, datapacking: DataPacking, num_nodes: int, num_elements: int, shared_connectivity: int | None, ) -> None: super().__init__( zone_index=zone_index, title=title, zone_type=zone_type, solution_time=solution_time, strand_id=strand_id, datapacking=datapacking, ) object.__setattr__(self, "_num_nodes", num_nodes) object.__setattr__(self, "_num_elements", num_elements) object.__setattr__(self, "_shared_connectivity", shared_connectivity) object.__setattr__(self, "_node_map_cache", None) object.__setattr__(self, "_node_map_loaded", False) object.__setattr__(self, "_face_neighbor_meta_cache", None) object.__setattr__(self, "_face_neighbor_meta_loaded", False) object.__setattr__(self, "_face_connections_cache", None) object.__setattr__(self, "_face_connections_loaded", False) def _repr_size(self) -> str: return f"N={self._num_nodes}, E={self._num_elements}" @property def num_nodes(self) -> int: """Number of nodes/points.""" return self._num_nodes @property def num_elements(self) -> int: """Number of elements/cells.""" return self._num_elements @property def shared_connectivity(self) -> int | None: """0-based source zone index if connectivity is shared, else None.""" return self._shared_connectivity @property def nodes_per_cell(self) -> int: """Nodes per cell, fixed by zone type. Raises: ValueError: For a zone type without a fixed nodes-per-cell count (not expected here, :class:`TecplotFEZoneReader` is only ever constructed for the classic FE types, but kept as a defensive check rather than an unchecked KeyError). """ zt = self.zone_type if zt in _NODES_PER_ELEM: return _NODES_PER_ELEM[zt] raise ValueError( # pragma: no cover f"ZoneType {zt} does not have a fixed nodes-per-cell count." ) @property def node_map(self) -> npt.NDArray[np.int64] | None: """Node connectivity array ``(num_elements, nodes_per_cell)``. None only if a format cannot resolve connectivity for this zone, e.g. when a shared-connectivity source zone is missing. """ if not self._node_map_loaded: node_map = self._load_node_map() object.__setattr__(self, "_node_map_cache", node_map) object.__setattr__(self, "_node_map_loaded", True) return node_map return self._node_map_cache @abstractmethod def _load_node_map(self) -> npt.NDArray[np.int64] | None: """Read this zone's node connectivity. Called at most once, lazily.""" def _resolve_face_neighbor_meta( self, ) -> tuple[FaceNeighborMode, int, bool | None] | None: if not self._face_neighbor_meta_loaded: result = self._load_face_neighbor_meta() object.__setattr__(self, "_face_neighbor_meta_cache", result) object.__setattr__(self, "_face_neighbor_meta_loaded", True) return result return self._face_neighbor_meta_cache @property def face_neighbor_mode(self) -> FaceNeighborMode | None: """This zone's face-neighbor connection mode. None if the zone has no face-neighbor connections, or if this format doesn't (yet) support reading them, unstructured connectivity alone already implies node adjacency; face neighbors only exist to state adjacency explicitly for non-conformal or multi-zone-connected meshes, which most FE zones don't need. Cheap: reading this never loads the connections themselves, only the small metadata it's paired with, so it's safe to check on every zone without cost. """ result = self._resolve_face_neighbor_meta() return result[0] if result is not None else None @property def num_face_connections(self) -> int | None: """Number of face-neighbor connections in this zone, else None. Not derivable from :meth:`get_face_connections`'s result without loading it, and for the "many" modes, not derivable from its flat length at all, a variable number of neighbor cells per connection means the array's length isn't a fixed multiple of this count. Cheap either way: this never loads the connections themselves. """ result = self._resolve_face_neighbor_meta() return result[1] if result is not None else None @property def face_neighbors_complete(self) -> bool | None: """Whether this zone's explicit face-neighbor data is exhaustive. Tecplot can auto-detect ordinary conformal adjacency from the node map alone; explicit face-neighbor data exists for what auto-detection can't find (non-conformal interfaces, cross-zone adjacency). ``True`` means the explicit data is the entire adjacency picture, nothing else to auto-detect. ``False`` means it's a supplement, Tecplot still auto-detects the rest. ``None`` means either this zone has no face-neighbor data at all (see :attr:`face_neighbor_mode`), or this format has no way to represent the distinction: only DAT's ASCII format actually carries this flag (``FEFACENEIGHBORSCOMPLETE``); neither the classic nor new C APIs have an equivalent, so PLT and SZL always report ``None`` here even when face-neighbor data exists. """ result = self._resolve_face_neighbor_meta() return result[2] if result is not None else None def _load_face_neighbor_meta( self, ) -> tuple[FaceNeighborMode, int, bool | None] | None: """Read this zone's face-neighbor mode, count, and completeness. Called at most once, lazily, and never triggers loading the connections themselves. Default: None (not implemented for this format). A format that overrides this to return real data must also override :meth:`_load_face_connections`. Returns: tuple: Tuple of the neighbor mode, number of connections and completeness flag, or ``None`` if the format does not store them. """ return None
[docs] def get_face_connections( self, reshape: bool = False ) -> npt.NDArray[np.int64] | None: """This zone's face-neighbor connections, else None. Loaded and cached on first access (flat form), independently of :attr:`face_neighbor_mode`/:attr:`num_face_connections`, reading those never triggers this. Args: reshape: If True, and :attr:`face_neighbor_mode` is ``LOCAL_ONE_TO_ONE`` or ``GLOBAL_ONE_TO_ONE``, reshape into a 2D array of shape ``(num_face_connections, 3 or 4)`` instead of the raw flat array. Raises for the "many" modes, a variable number of neighbor cells per connection means there's no single rectangular shape to reshape into. Returns: Flat array (dtype int64) if *reshape* is False (the default), or a 2D array if *reshape* is True and the mode supports it. None if the zone has no face-neighbor connections. Raises: ValueError: If *reshape* is True and :attr:`face_neighbor_mode` is ``LOCAL_ONE_TO_MANY`` or ``GLOBAL_ONE_TO_MANY``. Call without *reshape*, or use :func:`reshape_face_connections` directly, which handles the "many" modes too, returning a list of per-connection arrays instead of raising. """ if self.num_face_connections is None: return None if not self._face_connections_loaded: connections = self._load_face_connections() object.__setattr__(self, "_face_connections_cache", connections) object.__setattr__(self, "_face_connections_loaded", True) else: connections = self._face_connections_cache assert connections is not None # narrowed: num_face_connections was not None if not reshape: return connections mode = self.face_neighbor_mode assert mode is not None # narrowed: num_face_connections was not None above if mode not in ( FaceNeighborMode.LOCAL_ONE_TO_ONE, FaceNeighborMode.GLOBAL_ONE_TO_ONE, ): raise ValueError( "get_face_connections(reshape=True) requires a one-to-one " f"FaceNeighborMode, this zone's mode is {mode.name}, which " "is ragged (a variable number of neighbor cells per " "connection) and has no single rectangular shape. Call " "without reshape to get the flat array, or use " "reshape_face_connections() directly, which returns a " "list of per-connection arrays for the many modes instead " "of raising." ) result = reshape_face_connections(connections, mode, self.num_face_connections) assert isinstance(result, np.ndarray) # narrowed: one-to-one modes above return result
def _load_face_connections(self) -> npt.NDArray[np.int64]: """Read this zone's flat face-neighbor connection values. Called at most once, lazily, and only when :attr:`num_face_connections` is already known to be non-None, so a format overriding :meth:`_load_face_neighbor_meta` to return real data must also override this; the default raises to make a missing override obvious rather than silently returning nothing. """ raise NotImplementedError( f"{type(self).__name__} reports face-neighbor metadata but " "does not implement _load_face_connections." ) # ====================================================================================== # TecplotFEMixedZoneReader # ====================================================================================== class TecplotFEMixedZoneReader(TecplotZoneReader): """Read-only handle to one FEMIXED (mixed finite-element) zone. A FEMIXED zone holds 1 to 16 sections. Every cell in a section has the same shape, and all sections share one spatial dimension (all line, all surface or all volume cells). Cell numbering runs through the sections in order, so cell-centered variables hold ``num_elements`` values, the cells of section 0 first. All indices are 0-based. Args: zone_index: 0-based zone index within the dataset. title: Zone title. solution_time: Solution time, 0.0 for static data. strand_id: Strand ID, 0 for static data. datapacking: On-disk value layout. num_nodes: Number of nodes/points. section_shapes: Cell shape of each section. section_num_elements: Number of cells in each section. shared_connectivity: 0-based source zone index if this zone's connectivity is shared, else None. """ __slots__ = ( "_num_nodes", "_section_shapes", "_section_num_elements", "_shared_connectivity", "_node_maps_cache", ) _num_nodes: int _section_shapes: tuple[FeCellShape, ...] _section_num_elements: tuple[int, ...] _shared_connectivity: int | None _node_maps_cache: tuple[npt.NDArray[np.int64], ...] | None def __init__( self, zone_index: int, title: str, solution_time: float, strand_id: int, datapacking: DataPacking, num_nodes: int, section_shapes: tuple[FeCellShape, ...], section_num_elements: tuple[int, ...], shared_connectivity: int | None, ) -> None: super().__init__( zone_index=zone_index, title=title, zone_type=ZoneType.FEMIXED, solution_time=solution_time, strand_id=strand_id, datapacking=datapacking, ) object.__setattr__(self, "_num_nodes", num_nodes) object.__setattr__(self, "_section_shapes", section_shapes) object.__setattr__(self, "_section_num_elements", section_num_elements) object.__setattr__(self, "_shared_connectivity", shared_connectivity) object.__setattr__(self, "_node_maps_cache", None) def _repr_size(self) -> str: return ( f"N={self._num_nodes}, E={self.num_elements}, S={len(self._section_shapes)}" ) @property def num_nodes(self) -> int: """Number of nodes/points.""" return self._num_nodes @property def num_elements(self) -> int: """Total number of elements/cells over all sections.""" return sum(self._section_num_elements) @property def num_sections(self) -> int: """Number of sections, 1 to 16.""" return len(self._section_shapes) @property def section_shapes(self) -> tuple[FeCellShape, ...]: """Cell shape of each section.""" return self._section_shapes @property def section_num_elements(self) -> tuple[int, ...]: """Number of cells in each section.""" return self._section_num_elements @property def shared_connectivity(self) -> int | None: """0-based source zone index if connectivity is shared, else None.""" return self._shared_connectivity @property def node_maps(self) -> tuple[npt.NDArray[np.int64], ...]: """Node connectivity of each section, ``(section_num_elements, nodes)`` arrays. The arrays are views of one allocation, loaded on first access. Node indices are 0-based. Passing :attr:`section_shapes` and :attr:`node_maps` to :meth:`~tecio.TecplotSzlWriter.write_femixed_zone` writes the zone back. """ node_maps = self._node_maps_cache if node_maps is None: node_maps = self._load_node_maps() object.__setattr__(self, "_node_maps_cache", node_maps) return node_maps @abstractmethod def _load_node_maps(self) -> tuple[npt.NDArray[np.int64], ...]: """Read this zone's per-section connectivity. Called at most once, lazily.""" # ====================================================================================== # TecplotPolyZoneReader # ====================================================================================== PolyArrayKey: TypeAlias = Literal[ "face_node_counts", "face_nodes", "face_left_elements", "face_right_elements", "boundary_connection_counts", "boundary_connection_elements", "boundary_connection_zones", ] # Reference value for "no element" in ``face_left_elements`` and # ``face_right_elements``. Values at or below ``BOUNDARY_REF_BASE`` reference boundary # face ``BOUNDARY_REF_BASE - value``. NO_ELEMENT: Final = -1 BOUNDARY_REF_BASE: Final = -2 def counts_to_offsets(counts: npt.NDArray[np.int64]) -> npt.NDArray[np.int64]: """Return the ``len(counts) + 1`` running offsets for per-item *counts*.""" offsets = np.zeros(counts.size + 1, dtype=np.int64) np.cumsum(counts, out=offsets[1:]) return offsets class TecplotPolyZoneReader(TecplotZoneReader): """Read-only handle to one FEPOLYGON or FEPOLYHEDRON (face-based) zone. A poly zone stores faces instead of per-element node lists. Every face lists its nodes and the elements on its left and right. All indices are 0-based. The face arrays are flat and are returned as stored in the file, never split per element. ``face_left_elements`` and ``face_right_elements`` hold, for each face: * ``>= 0``: the 0-based element index. * ``-1`` (:data:`NO_ELEMENT`): no element on that side (a domain boundary). * ``<= -2``: a boundary face, an entry in the boundary connection arrays, used for neighbors in other zones or faces with several neighbors. The boundary face index is ``-2 - value`` (:data:`BOUNDARY_REF_BASE`). Boundary face ``b`` owns ``boundary_connection_counts[b]`` consecutive entries of ``boundary_connection_elements`` and ``boundary_connection_zones``, which hold the 0-based neighbor element and the 0-based zone containing it. Face-neighbor connections (:class:`~tecio.FaceNeighborMode`) do not apply to poly zones, the left and right elements play that role. For a FEPOLYGON zone each face is an edge with exactly 2 nodes. Its ``face_node_counts`` is synthesized (all 2) and ``face_nodes`` has ``2 * num_faces`` entries. Args: zone_index: 0-based zone index within the dataset. title: Zone title. zone_type: FEPOLYGON or FEPOLYHEDRON. solution_time: Solution time, 0.0 for static data. strand_id: Strand ID, 0 for static data. datapacking: On-disk value layout. num_nodes: Number of nodes/points. num_elements: Number of elements/cells. num_faces: Number of faces. num_boundary_faces: Number of boundary faces. num_boundary_connections: Total number of boundary connections. shared_connectivity: 0-based source zone index if this zone's connectivity is shared, else None. """ __slots__ = ( "_num_nodes", "_num_elements", "_num_faces", "_num_boundary_faces", "_num_boundary_connections", "_shared_connectivity", "_array_cache", ) _num_nodes: int _num_elements: int _num_faces: int _num_boundary_faces: int _num_boundary_connections: int _shared_connectivity: int | None _array_cache: dict[str, npt.NDArray[np.int64]] def __init__( self, zone_index: int, title: str, zone_type: ZoneType, solution_time: float, strand_id: int, datapacking: DataPacking, num_nodes: int, num_elements: int, num_faces: int, num_boundary_faces: int, num_boundary_connections: int, shared_connectivity: int | None, ) -> None: if zone_type not in (ZoneType.FEPOLYGON, ZoneType.FEPOLYHEDRON): raise ValueError(f"Not a poly zone type: {zone_type!r}") super().__init__( zone_index=zone_index, title=title, zone_type=zone_type, solution_time=solution_time, strand_id=strand_id, datapacking=datapacking, ) object.__setattr__(self, "_num_nodes", num_nodes) object.__setattr__(self, "_num_elements", num_elements) object.__setattr__(self, "_num_faces", num_faces) object.__setattr__(self, "_num_boundary_faces", num_boundary_faces) object.__setattr__(self, "_num_boundary_connections", num_boundary_connections) object.__setattr__(self, "_shared_connectivity", shared_connectivity) object.__setattr__(self, "_array_cache", {}) def _repr_size(self) -> str: return f"N={self._num_nodes}, F={self._num_faces}, E={self._num_elements}" @property def num_nodes(self) -> int: """Number of nodes/points.""" return self._num_nodes @property def num_elements(self) -> int: """Number of elements/cells.""" return self._num_elements @property def num_faces(self) -> int: """Number of faces.""" return self._num_faces @property def num_boundary_faces(self) -> int: """Number of boundary faces.""" return self._num_boundary_faces @property def num_boundary_connections(self) -> int: """Total number of boundary connections over all boundary faces.""" return self._num_boundary_connections @property def shared_connectivity(self) -> int | None: """0-based source zone index if connectivity is shared, else None.""" return self._shared_connectivity def _face_map_digest(self) -> str: """Return a hash identifying this zone's grid, for matching grids across zones. The face map is read without filling the array cache, so scanning many zones does not keep their arrays in memory. """ h = hashlib.blake2b(digest_size=16) h.update( f"{self.zone_type.name}:{self._num_nodes}:{self._num_elements}:" f"{self._num_faces}".encode() ) keys: tuple[PolyArrayKey, ...] = ( "face_nodes", "face_left_elements", "face_right_elements", ) if self.zone_type is ZoneType.FEPOLYHEDRON: keys = ("face_node_counts", *keys) for key in keys: arr = np.ascontiguousarray(self._load_array(key)) h.update(arr.data) return h.hexdigest() # -- Lazy face-map arrays ---------------------------------------------------------- def _array(self, key: PolyArrayKey) -> npt.NDArray[np.int64]: """Return the cached array for *key*, loading it on first use.""" cache = self._array_cache arr = cache.get(key) if arr is None: arr = self._load_array(key) cache[key] = arr return arr @abstractmethod def _load_array(self, key: PolyArrayKey) -> npt.NDArray[np.int64]: """Read one face-map array, 0-based, as int64. Called at most once per key. Never called for ``face_node_counts`` of a FEPOLYGON zone, which is synthesized by the base class. """ @property def face_node_counts(self) -> npt.NDArray[np.int64]: """Number of nodes of each face, shape ``(num_faces,)``.""" if self.zone_type is ZoneType.FEPOLYGON: cache = self._array_cache arr = cache.get("face_node_counts") if arr is None: arr = np.full(self._num_faces, 2, dtype=np.int64) cache["face_node_counts"] = arr return arr return self._array("face_node_counts") @property def face_node_offsets(self) -> npt.NDArray[np.int64]: """Running offsets into :attr:`face_nodes`, shape ``(num_faces + 1,)``. The nodes of face ``f`` are ``face_nodes[offsets[f]:offsets[f + 1]]``. """ arr = self._array_cache.get("face_node_offsets") if arr is None: arr = counts_to_offsets(self.face_node_counts) self._array_cache["face_node_offsets"] = arr return arr @property def face_nodes(self) -> npt.NDArray[np.int64]: """Flat 0-based node indices of all faces, in face order.""" return self._array("face_nodes") @property def face_left_elements(self) -> npt.NDArray[np.int64]: """Element on the left of each face, shape ``(num_faces,)``, see class doc.""" return self._array("face_left_elements") @property def face_right_elements(self) -> npt.NDArray[np.int64]: """Element on the right of each face, shape ``(num_faces,)``, see class doc.""" return self._array("face_right_elements") @property def boundary_connection_counts(self) -> npt.NDArray[np.int64]: """Connections of each boundary face, shape ``(num_boundary_faces,)``.""" if self._num_boundary_faces == 0: return np.zeros(0, dtype=np.int64) return self._array("boundary_connection_counts") @property def boundary_connection_offsets(self) -> npt.NDArray[np.int64]: """Running offsets into the boundary connection arrays. Shape ``(num_boundary_faces + 1,)``. """ arr = self._array_cache.get("boundary_connection_offsets") if arr is None: arr = counts_to_offsets(self.boundary_connection_counts) self._array_cache["boundary_connection_offsets"] = arr return arr @property def boundary_connection_elements(self) -> npt.NDArray[np.int64]: """0-based neighbor element of every boundary connection, flat.""" if self._num_boundary_connections == 0: return np.zeros(0, dtype=np.int64) return self._array("boundary_connection_elements") @property def boundary_connection_zones(self) -> npt.NDArray[np.int64]: """0-based zone of the neighbor of every boundary connection, flat.""" if self._num_boundary_connections == 0: return np.zeros(0, dtype=np.int64) return self._array("boundary_connection_zones")
[docs] def element_faces(self) -> tuple[npt.NDArray[np.int64], npt.NDArray[np.int64]]: """Return the faces of every element as ``(offsets, faces)``. The faces of element ``e`` are ``faces[offsets[e]:offsets[e + 1]]``, in ascending face order. They come from :attr:`face_left_elements` and :attr:`face_right_elements`. A side that is no element of this zone (``-1`` or a boundary face reference) is skipped, so a face next to another zone is listed only for its own element. The arrays are computed on each call, not cached. Returns: The ``offsets`` with shape ``(num_elements + 1,)`` and the flat ``faces``. """ return faces_by_element( self.face_left_elements, self.face_right_elements, self._num_elements )
[docs] def element_nodes(self) -> tuple[npt.NDArray[np.int64], npt.NDArray[np.int64]]: """Return the distinct nodes of every element as ``(offsets, nodes)``. The nodes of element ``e`` are ``nodes[offsets[e]:offsets[e + 1]]``. They are the nodes of the element's faces with repeats removed, in ascending order. That is a set, not a cell node order, because a polyhedron has no natural node order. The arrays are computed on each call, not cached. Returns: The ``offsets`` with shape ``(num_elements + 1,)`` and the flat ``nodes``. """ offsets, faces = self.element_faces() return nodes_by_element( self.face_nodes, self.face_node_offsets, offsets, faces, self._num_nodes )
# ====================================================================================== # TecplotReader # ====================================================================================== class TecplotReader(ABC): """Shared interface for all Tecplot file readers (SZL, PLT, DAT). Concrete subclasses (:class:`TecplotSzlReader`, ...) differ in how a file is opened and parsed, SZL keeps a live C file handle and queries it on demand, PLT and DAT parse eagerly and hold no handle, but expose an identical interface once open, so code (including the ParaView plugin) can be written against this base without caring which format produced a given file. """ __slots__ = () @abstractmethod def __init__(self, path: str) -> None: """Open *path* for reading. Declared here so that ``ReaderCls(path)`` type-checks against ``type[TecplotReader]``, e.g. in :func:`~tecio._io.open`'s dispatch table, without needing a cast. Each format's actual constructor may accept a broader path type (PLT also takes ``os.PathLike``); ``str`` is the narrowest common signature, matching how every call site in this package already invokes it. """ # -- Abstract: resolved differently per format ------------------------------------- @property @abstractmethod def path(self) -> str: """Source file path.""" @property @abstractmethod def file_type(self) -> FileType: """FULL, GRID, or SOLUTION.""" @property @abstractmethod def title(self) -> str: """Dataset title string.""" @property @abstractmethod def variables(self) -> list[str]: """Ordered list of variable name strings.""" @property @abstractmethod def zones(self) -> ZoneList[TecplotZoneReader]: """Zones in this file, by 0-based index or slice.""" @property @abstractmethod def auxdata(self) -> TecplotAuxDataReader: """Dataset-level auxiliary data.""" @abstractmethod def _var_auxdata_at(self, var_index: int) -> TecplotAuxDataReader: """Return aux data for variable *var_index* (0-based, unchecked)."""
[docs] def close(self) -> None: # noqa: B027 """Release any open resources. No-op unless overridden. SZL overrides this to close its C file handle; PLT and DAT hold no handle between accesses and use this default. """
# -- Shared ------------------------------------------------------------------------ def __enter__(self) -> TecplotReader: return self def __exit__(self, exc_type: object, exc_val: object, exc_tb: object) -> None: try: self.close() except Exception: if exc_type is None: raise @property def num_vars(self) -> int: """Number of variables in the dataset.""" return len(self.variables) @property def num_zones(self) -> int: """Number of zones in the file.""" return len(self.zones) @property def num_auxdata_items(self) -> int: """Number of dataset-level auxiliary data items.""" return len(self.auxdata) @property def var_auxdata(self) -> list[TecplotAuxDataReader]: """Per-variable auxiliary data, 0-based. Derived from :meth:`get_var_auxdata`, a subclass never implements this separately. """ return [self.get_var_auxdata(i) for i in range(self.num_vars)]
[docs] def get_var_auxdata(self, var_index: int) -> TecplotAuxDataReader: """Return auxiliary data for variable *var_index*. Raises: IndexError: If *var_index* is out of range. """ if var_index < 0 or var_index >= self.num_vars: raise IndexError( f"Variable index {var_index} out of range [0, {self.num_vars - 1}]" ) return self._var_auxdata_at(var_index)
[docs] def get_zone_auxdata(self, zone_index: int) -> TecplotAuxDataReader: """Return auxiliary data for zone *zone_index*. Raises: IndexError: If *zone_index* is out of range. """ if zone_index < 0 or zone_index >= self.num_zones: raise IndexError( f"Zone index {zone_index} out of range [0, {self.num_zones - 1}]" ) return self.zones[zone_index].auxdata
def __repr__(self) -> str: # pragma: no cover cls = type(self).__name__ name = self.path.replace("\\", "/").rsplit("/", 1)[-1] try: parts = [f"path={name!r}"] title = self.title if title: if len(title) > 40: title = title[:25] + "\u2026" parts.append(f"title={title!r}") parts += [ f"file_type={self.file_type.name}", f"zones={self.num_zones}", f"variables={self.num_vars}", ] if self.num_auxdata_items: parts.append(f"aux={self.num_auxdata_items}") return f"{cls}({', '.join(parts)})" except Exception: return f"{cls}(path={name!r}, <unavailable>)"