tecio-python 0.1.1__tar.gz → 0.2.1__tar.gz

{tecio_python-0.1.1/tecio_python.egg-info → tecio_python-0.2.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: tecio-python
-Version: 0.1.1
+Version: 0.2.1
 Summary: Python interface for reading and writing Tecplot data files
 Project-URL: Homepage, https://github.com/meersman/tecio
 Project-URL: Documentation, https://meersman.github.io/tecio/
@@ -97,7 +97,7 @@ Reading a file:
 
 ```python
 with tecio.open("sine.szplt", "r") as tec:
-    print(tec.variables)   # ['x', 'y']
+    print(tec.variables)  # ['x', 'y']
     x = tec.zone[0].variable[0].values
     y = tec.zone[0].variable[1].values
     # or

{tecio_python-0.1.1 → tecio_python-0.2.1}/README.md

@@ -53,7 +53,7 @@ Reading a file:
 
 ```python
 with tecio.open("sine.szplt", "r") as tec:
-    print(tec.variables)   # ['x', 'y']
+    print(tec.variables)  # ['x', 'y']
     x = tec.zone[0].variable[0].values
     y = tec.zone[0].variable[1].values
     # or

{tecio_python-0.1.1 → tecio_python-0.2.1}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "tecio-python"
-version = "0.1.1"
+version = "0.2.1"
 description = "Python interface for reading and writing Tecplot data files"
 
 readme = "README.md"
@@ -37,6 +37,8 @@ Issues = "https://github.com/meersman/tecio/issues"
 Changelog = "https://github.com/meersman/tecio/blob/main/docs/changelog.md"
 
 [project.scripts]
+tec2mat = "tecio.cli.tec2mat:main"
+tecaux = "tecio.cli.tecaux:main"
 teconvert = "tecio.cli.teconvert:main"
 tecdump = "tecio.cli.tecdump:main"
 tecextract = "tecio.cli.tecextract:main"
@@ -45,7 +47,6 @@ tecmerge = "tecio.cli.tecmerge:main"
 tecscale = "tecio.cli.tecscale:main"
 tecslice = "tecio.cli.tecslice:main"
 tecstats = "tecio.cli.tecstats:main"
-tec2mat = "tecio.cli.tec2mat:main"
 
 [project.optional-dependencies]
 dev = [

{tecio_python-0.1.1 → tecio_python-0.2.1}/tecio/__init__.py

@@ -11,7 +11,7 @@ try:
 except metadata.PackageNotFoundError:
     __version__ = "0.0.0"
 
-from . import cli, dat, libtecio, plt, szl, utils
+from . import cli, dat, libtecio, plt, szl
 from ._containers import VariableList, ZoneList
 from ._io import AppendReadWrite, AppendWrite, open
 
@@ -28,7 +28,6 @@ __all__ = [
     "dat",
     "plt",
     "szl",
-    "utils",
     "cli",
     "AppendWrite",
     "AppendReadWrite",

tecio_python-0.2.1/tecio/_meta.py

@@ -0,0 +1,168 @@
+r"""Structural metadata records shared by the Tecplot file writers.
+
+The writer for each output format -- SZL (``.szplt``), PLT (``.plt``), and ASCII DAT
+(``.dat``) -- keeps a running, in-memory description of what it has committed to disk:
+the dataset header, auxiliary-data counts, and one record per zone.  Defining that
+description once here lets all three writers share a single representation instead of
+each maintaining ad-hoc bookkeeping.
+
+The records mirror the file- and zone-level fields of the Tecplot data format
+(``TECINI142`` for the file header and ``TECZNE142`` for each zone): dataset title, file
+type, variable names, and the per-variable passive, value-location, and share-from
+arrays, together with per-zone dimensions and aux-item counts.
+
+Design notes:
+    * Only lightweight descriptors are stored -- shapes, enums, and small integers --
+      never the variable data arrays, so the record stays cheap in memory even for files
+      with many zones.
+    * ``slots=True`` removes the per-instance ``__dict__``, and immutable tuple fields
+      keep the per-variable lists compact.  A :class:`ZoneMeta` is a write-once snapshot
+      and is therefore ``frozen``; :class:`WriterMeta` is mutable because it grows as
+      zones are written.
+    * Enum types are imported only under :data:`typing.TYPE_CHECKING`.  With ``from
+      __future__ import annotations`` the annotations are never evaluated at runtime,
+      which keeps this module free of any import cycle with :mod:`tecio.libtecio`.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from typing import TYPE_CHECKING
+
+if TYPE_CHECKING:
+    from .libtecio import DataType, FileType, ValueLocation, ZoneType
+
+
+# =====================================================================================
+# Zone-level record
+# =====================================================================================
+
+
+@dataclass(slots=True, frozen=True)
+class ZoneMeta:
+    """Lightweight, write-once description of a single written zone.
+
+    Per-variable fields (:attr:`value_locations`, :attr:`passive_vars`,
+    :attr:`shared_vars`, :attr:`data_types`) span every dataset variable and correspond
+    to the ``ValueLocation``, ``PassiveVarList``, ``ShareVarFromZone``, and
+    variable-type arrays of a ``TECZNE142`` zone header.
+
+    Attributes:
+        index:           1-based zone index returned by the C library.
+        title:           Zone title.
+        zone_type:       The zone's :class:`~tecio.libtecio.ZoneType`.
+        solution_time:   Solution time (``0.0`` for static zones).
+        strand_id:       Strand ID (``0`` for static zones).
+        num_aux_items:   Number of zone-level auxiliary items written.
+        dimensions:      Nodal ``(imax, jmax, kmax)`` for ORDERED zones, else ``None``.
+        num_nodes:       Node count for FE zones, else ``None``.
+        num_elements:    Element count for FE zones, else ``None``.
+        value_locations: Per-variable value location, full dataset length.
+        passive_vars:    Per-variable passive flags, full dataset length.
+        shared_vars:     Per-variable share-from zone index (1-based; ``0`` for not
+                         shared), full dataset length.
+        data_types:      Per-variable data type, full dataset length.
+
+    """
+
+    index: int
+    title: str
+    zone_type: ZoneType
+    solution_time: float = 0.0
+    strand_id: int = 0
+    num_aux_items: int = 0
+    # Ordered zones carry IJK dimensions; FE zones carry node/element counts.
+    dimensions: tuple[int, int, int] | None = None
+    num_nodes: int | None = None
+    num_elements: int | None = None
+    # Per-variable descriptors (length == dataset variable count).
+    value_locations: tuple[ValueLocation, ...] = ()
+    passive_vars: tuple[bool, ...] = ()
+    shared_vars: tuple[int, ...] = ()
+    data_types: tuple[DataType, ...] = ()
+
+    @property
+    def nodal_shape(self) -> tuple[int, int, int] | None:
+        """Nodal ``(imax, jmax, kmax)`` for ORDERED zones, else ``None``."""
+        return self.dimensions
+
+    @property
+    def cell_shape(self) -> tuple[int, ...] | None:
+        """Cell-centred ``(imax-1, jmax-1, kmax-1)`` (floored at 1) or ``None``."""
+        if self.dimensions is None:
+            return None
+        return tuple(max(n - 1, 1) for n in self.dimensions)
+
+
+# =====================================================================================
+# Dataset-level record
+# =====================================================================================
+
+
+@dataclass(slots=True)
+class WriterMeta:
+    """Running record of everything a writer has committed to a file.
+
+    Populated incrementally as the file header, auxiliary data, and zones are
+    written, so it always reflects the current on-disk state.  It is the single
+    source of truth for cross-zone validation (for example, resolving the shape
+    of a shared variable) and is suitable for summarising the writer state.
+
+    Attributes:
+        path:                  Output file path.
+        title:                 Dataset title.
+        file_type:             :class:`~tecio.libtecio.FileType` of the output.
+        file_format:           Format tag, e.g. ``"szplt"``, ``"plt"``, or
+                               ``"dat"``.
+        variables:             Variable name list, or ``None`` before the file
+                               header has been written (lazy-open).
+        num_dataset_aux_items: Count of dataset-level aux items written.
+        num_var_aux_items:     Total variable-level aux items written.
+        zones:                 Mapping of 1-based zone index to :class:`ZoneMeta`,
+                               in write order.
+    """
+
+    path: str
+    title: str
+    file_type: FileType
+    file_format: str
+    variables: list[str] | None = None
+    num_dataset_aux_items: int = 0
+    num_var_aux_items: int = 0
+    zones: dict[int, ZoneMeta] = field(default_factory=dict)
+
+    # -- Derived quantities -----------------------------------------------------------
+
+    @property
+    def num_vars(self) -> int:
+        """Number of dataset variables, or ``0`` before the header is written."""
+        return len(self.variables) if self.variables is not None else 0
+
+    @property
+    def num_zones(self) -> int:
+        """Number of zones written so far."""
+        return len(self.zones)
+
+    # -- Update methods (called by the writer as it commits data) ---------------------
+
+    def set_variables(self, names: list[str]) -> None:
+        """Record the dataset variable names once the header is written."""
+        self.variables = names
+
+    def note_dataset_aux(self, count: int) -> None:
+        """Accumulate the number of dataset-level aux items written."""
+        self.num_dataset_aux_items += count
+
+    def note_var_aux(self, count: int) -> None:
+        """Accumulate the number of variable-level aux items written."""
+        self.num_var_aux_items += count
+
+    def record_zone(self, zone: ZoneMeta) -> None:
+        """Register a fully written zone by its 1-based index."""
+        self.zones[zone.index] = zone
+
+    # -- Retrieval helpers ------------------------------------------------------------
+
+    def zone(self, index: int) -> ZoneMeta | None:
+        """Return the :class:`ZoneMeta` for *index*, or ``None`` if unknown."""
+        return self.zones.get(index)

{tecio_python-0.1.1 → tecio_python-0.2.1}/tecio/cli/tec2mat.py

@@ -69,7 +69,10 @@ Output structure:
           .var_locations          cell    'NODAL' | 'CELL_CENTERED' | ''
           .var_dtypes             cell    'FLOAT' | 'DOUBLE' | 'INT32' | ...
           .var_shared_from        array   1-based source zone, or 0 if not shared
-          .node_map               array   (num_elements x nodes_per_cell), FE only
+          .node_map               array   (num_elements x nodes_per_cell), FE only,
+                                          omitted if connectivity is shared
+          .node_map_shared_from   double  1-based source zone, FE only, present only
+                                          if this zone shares its connectivity
 
     Variable arrays are stored at their on-disk NumPy dtype, so single/double/integer
     precision is preserved.  The real variable names are kept only in ``info.var_names``
@@ -79,7 +82,9 @@ Output structure:
     Passive and shared variables carry no data: their ``var_<k>`` field is an empty
     matrix ``[]``.  A shared variable is therefore never duplicated on disk -- the data
     lives in its source zone and ``var_shared_from`` records where, so the MATLAB user
-    can dereference it (see the examples below).
+    can dereference it (see the examples below).  Shared FE connectivity follows the
+    same convention: a zone sharing its node map has no ``node_map`` field at all, only
+    ``node_map_shared_from``.
 
 Examples:
     Convert an SZL file to ``flow.mat``::
@@ -119,6 +124,17 @@ Examples:
             end
         end
 
+    Shared FE connectivity resolves the same way, via ``node_map_shared_from``::
+
+        function m = tecnodemap(d, zoneIdx)
+            z = d.(sprintf('zone_%d', zoneIdx));
+            if isfield(z, 'node_map')
+                m = z.node_map;
+            else
+                m = d.(sprintf('zone_%d', z.node_map_shared_from)).node_map;
+            end
+        end
+
 See Also:
     * :mod:`tecio.cli.teconvert`: Convert between Tecplot file formats (``.szplt``,
       ``.plt``, ``.dat``) without leaving the Tecplot ecosystem.
@@ -153,9 +169,9 @@ import numpy as np
 from .. import open as tecio_open
 from ..libtecio import ZoneType
 
-# ---------------------------------------------------------------------------
+# --------------------------------------------------------------------------------------
 # Constants
-# ---------------------------------------------------------------------------
+# --------------------------------------------------------------------------------------
 
 #: Zone types whose connectivity is face-based and cannot be read; their
 #: node map is omitted from the output.
@@ -165,17 +181,18 @@ _FE_POLY: frozenset[ZoneType] = frozenset({
 })
 
 
-# ---------------------------------------------------------------------------
+# --------------------------------------------------------------------------------------
 # Argument parsing
-# ---------------------------------------------------------------------------
+# --------------------------------------------------------------------------------------
 
 
 def _parse_args(argv: Sequence[str] | None = None) -> argparse.Namespace:
     parser = argparse.ArgumentParser(
         prog="tec2mat",
         description=(
-            "Convert a Tecplot file to a MATLAB .mat file.  Each input file maps to "
-            "one output file, with every zone stored as a named struct."
+            # -|-------------------|---------------------------------------------|
+            "Convert a Tecplot file to a MATLAB .mat file.  Each input file maps\n"
+            "to one output file, with every zone stored as a named struct."
         ),
         epilog=(
             "Example usage:\n"
@@ -236,9 +253,9 @@ def _parse_args(argv: Sequence[str] | None = None) -> argparse.Namespace:
     return parser.parse_args(argv)
 
 
-# ---------------------------------------------------------------------------
+# --------------------------------------------------------------------------------------
 # Conversion helpers
-# ---------------------------------------------------------------------------
+# --------------------------------------------------------------------------------------
 
 
 def _build_info_dict(reader: Any) -> dict[str, Any]:
@@ -360,19 +377,28 @@ def _zone_to_dict(zone: Any, num_vars: int) -> dict[str, Any]:
     d["var_dtypes"] = np.array(dtypes, dtype=object)
     d["var_shared_from"] = shared_from
 
-    # Connectivity for simple FE zones only.  Ordered zones have no node map,
-    # and poly zones expose none through the readers.
+    # Connectivity for simple FE zones only.  Ordered zones have no node map, and poly
+    # zones expose none through the readers.
+    #
+    # A zone that shares connectivity is handled the same way as a shared variable
+    # above: rather than duplicating the (potentially large) node map into every zone's
+    # struct, store the 1-based source zone number so the MATLAB user can dereference
+    # zone_<src>.node_map themselves.
     if zone.zone_type != ZoneType.ORDERED and zone.zone_type not in _FE_POLY:
-        node_map = zone.node_map
-        if node_map is not None:
-            d["node_map"] = node_map
+        con_src = zone.shared_connectivity
+        if con_src is not None:
+            d["node_map_shared_from"] = np.int32(con_src)
+        else:
+            node_map = zone.node_map
+            if node_map is not None:
+                d["node_map"] = node_map
 
     return d
 
 
-# ---------------------------------------------------------------------------
+# --------------------------------------------------------------------------------------
 # Main entry point
-# ---------------------------------------------------------------------------
+# --------------------------------------------------------------------------------------
 
 
 def main(argv: Sequence[str] | None = None) -> int:
@@ -384,9 +410,9 @@ def main(argv: Sequence[str] | None = None) -> int:
     """
     args = _parse_args(argv)
 
-    # SciPy is an optional dependency, imported lazily so that merely importing
-    # this module (e.g. to call main() from a script) does not require SciPy
-    # unless the tool is actually run.
+    # SciPy is an optional dependency, imported lazily so that merely importing this
+    # module (e.g. to call main() from a script) does not require SciPy unless the tool
+    # is actually run.
     try:
         from scipy import io as scipy_io
     except ImportError: