tecio-python 0.2.0__py3-none-any.whl → 0.2.2__py3-none-any.whl

tecio/dat/_write.py

@@ -250,9 +250,9 @@ def _stage_point_rows(
 ) -> None:
     """Write *cols* as ``DATAPACKING=POINT`` rows into *buf*.
 
-    Each element of *cols* is the flat value array for one variable.  One tab-separated
+    Each element of *cols* is the flat value array for one variable. One tab-separated
     row is written per point (node or cell): all variable values for that point appear
-    on the same line.  All column arrays must have the same length.  Does nothing when
+    on the same line. All column arrays must have the same length. Does nothing when
     *cols* is empty.
 
     Example:
@@ -288,12 +288,12 @@ class Write:
         path:
             Destination file path.
         title:
-            Dataset title.  Defaults to ``"untitled"``.
+            Dataset title. Defaults to ``"untitled"``.
         variables:
             Variable name list.  ``None`` defers file creation until the first
             zone-writing call (lazy open).
         file_type:
-            :class:`FileType` enum.  Defaults to :attr:`FileType.FULL`.
+            :class:`FileType` enum. Defaults to :attr:`FileType.FULL`.
         precision:
             Uniform floating point precision for the whole file.  :attr:`DataType.FLOAT`
             (default; ``"single"``) or :attr:`DataType.DOUBLE` (``"double"``). Also
@@ -509,24 +509,24 @@ class Write:
         Zone dimensions are inferred from the shape of the first NODAL array.
 
         Args:
-            data:            One NumPy array per dataset variable.  Array shape is used
+            data:            One NumPy array per dataset variable. Array shape is used
                              to infer ``imax``, ``jmax``, and ``kmax``; Fortran
-                             (column-major) order is assumed.  Pass ``None`` to write a
+                             (column-major) order is assumed. Pass ``None`` to write a
                              zone header only.
-            title:           Zone title.  Defaults to ``"IJK_Zone_{current_zone + 1}"``.
-            variables:       Variable name list.  Required on the first call when the
+            title:           Zone title. Defaults to ``"IJK_Zone_{current_zone + 1}"``.
+            variables:       Variable name list. Required on the first call when the
                              file has not been opened yet (lazy-open path); ignored once
                              the file is already initialised. Default to ``[V1, V2, V3,
                              ...]`` if not provided in open or zone call.
-            value_locations: Per-variable :class:`~libtecio.ValueLocation`.  Defaults to
+            value_locations: Per-variable :class:`~libtecio.ValueLocation`. Defaults to
                              all ``NODAL``.
-            passive_vars:    Per-variable passive flags.  Defaults to all active
+            passive_vars:    Per-variable passive flags. Defaults to all active
                              (``False``).
-            var_sharing:     Per-variable share-from zone index (1-based).  Defaults to
+            var_sharing:     Per-variable share-from zone index (1-based). Defaults to
                              no sharing (all zeros).
-            solution_time:   Solution time for transient data.  Use ``0.0`` for static
+            solution_time:   Solution time for transient data. Use ``0.0`` for static
                              zones. Default to ``0.0`` if not defined.
-            strand_id:       Strand ID for transient data.  Use ``0`` for static
+            strand_id:       Strand ID for transient data. Use ``0`` for static
                              zones. Default to ``0`` (static) if not defined.
             aux:             Zone-level auxiliary data as ``{name: value}`` string
                              pairs.
@@ -795,12 +795,12 @@ class Write:
             ``FEPOLYGON`` and ``FEPOLYHEDRON`` raise :exc:`NotImplementedError`.
 
         Args:
-            data:            Sequence of 1-D arrays, one per dataset variable.  NODAL
+            data:            Sequence of 1-D arrays, one per dataset variable. NODAL
                              arrays must have length ``num_nodes``; CELL_CENTERED arrays
                              must have length ``num_cells``.  ``num_nodes`` and
                              ``num_cells`` are inferred from ``node_map`` (or from the
                              ``con_sharing`` source zone when ``node_map`` is omitted).
-            zone_type:       FE zone type from the ZoneType enum.  Must be one of the
+            zone_type:       FE zone type from the ZoneType enum. Must be one of the
                              types in ``_FE_SIMPLE``.
             node_map:        Integer array of shape ``(num_cells, nodes_per_cell)``
                              containing 1-based node indices.  32- or 64-bit write is
@@ -808,17 +808,17 @@ class Write:
                              Required unless ``con_sharing`` is set, in which case the
                              connectivity -- and the node/cell counts derived from it --
                              are inherited from the source zone instead.
-            title:           Zone title string.  Defaults to ``"FE_Zone_{current_zone +
+            title:           Zone title string. Defaults to ``"FE_Zone_{current_zone +
                              1}"`` if not provided.
-            variables:       Variable name list.  Required only when the file has not
-                             been opened yet (lazy-open path).  Ignored on subsequent
+            variables:       Variable name list. Required only when the file has not
+                             been opened yet (lazy-open path). Ignored on subsequent
                              zones once the file is already initialised. Default to
                              ``[V1, V2, V3, ...]`` if not provided in open or zone call.
-            value_locations: Per-variable ValueLocation.  Defaults to all NODAL.
-            passive_vars:    Per-variable passive flags.  Defaults to all active
+            value_locations: Per-variable ValueLocation. Defaults to all NODAL.
+            passive_vars:    Per-variable passive flags. Defaults to all active
                              (False).
-            var_sharing:     Per-variable share from zone index.  Defaults to no
-                             sharing.  Cross-checked against ``node_map`` /
+            var_sharing:     Per-variable share from zone index. Defaults to no
+                             sharing. Cross-checked against ``node_map`` /
                              ``con_sharing`` for a consistent node/cell count.
             con_sharing:     Optional zone index that the connectivity is shared from.
                              ``None`` or ``0`` indicates no sharing (this zone owns its

tecio/libtecio.py

@@ -234,7 +234,7 @@ class DataPacking(Enum):
     """Zone data packing order for ASCII (``.dat``) files.
 
     Controls whether data is laid out variable-by-variable or point-by-point
-    in the ASCII file.  The ``DATAPACKING`` keyword in a zone header takes one
+    in the ASCII file. The ``DATAPACKING`` keyword in a zone header takes one
     of these two values.
 
     .. list-table::
@@ -693,6 +693,12 @@ lib.tecFileWriterClose.restype = ctypes.c_int32
 lib.tecFileWriterClose.argtypes = [
     ctypes.POINTER(ctypes.c_void_p),
 ]
+lib.tecFileWriterFlush.restype = ctypes.c_int32
+lib.tecFileWriterFlush.argtypes = [
+    ctypes.c_void_p,  # fileHandle
+    ctypes.c_int32,  # numZonesToRetain
+    ctypes.POINTER(ctypes.c_int32),  # zonesToRetain
+]
 
 # Write Zone Headers
 lib.tecZoneCreateIJK.restype = ctypes.c_int32
@@ -1071,7 +1077,7 @@ lib.tecusr142.argtypes = [
 # --------------------------------------------------------------------------------------
 
 
-# Reading SZL files
+# -- Reading SZL files -----------------------------------------------------------------
 def tec_file_reader_open(file_name: str) -> ctypes.c_void_p:
     """Open an SZL file for reading.
 
@@ -1204,7 +1210,7 @@ def tec_data_set_get_num_zones(handle: ctypes.c_void_p) -> int:
     return num_zones.value
 
 
-# Reading SZL zones
+# -- Reading SZL zones -----------------------------------------------------------------
 def tec_zone_get_ijk(handle: ctypes.c_void_p, zone_index: int) -> tuple[int, int, int]:
     """Get zone dimensions (ORDERED) or node/element counts (FE).
 
@@ -1488,7 +1494,7 @@ def tec_zone_node_map_get(
     return np.ctypeslib.as_array(nodemap).reshape(num_elements, nodes_per_cell)
 
 
-# Reading SZL variable data
+# -- Reading SZL variable data ---------------------------------------------------------
 def tec_var_get_name(handle: ctypes.c_void_p, var_index: int) -> str:
     """Get a variable name by index.
 
@@ -1962,7 +1968,7 @@ def tec_zone_var_get_uint8_values(
     return np.ctypeslib.as_array(values)
 
 
-# Reading SZL aux data
+# -- Reading SZL aux data --------------------------------------------------------------
 def tec_data_set_aux_data_get_num_items(handle: ctypes.c_void_p) -> int:
     """Get the number of dataset-level auxiliary data items.
 
@@ -2157,7 +2163,7 @@ def tec_zone_aux_data_get_item(
 # --------------------------------------------------------------------------------------
 
 
-# Initialization and File Handling
+# -- Initialization and File Handling --------------------------------------------------
 def tec_file_writer_open(
     filename: str,
     variables: Sequence[str],
@@ -2225,7 +2231,58 @@ def tec_file_writer_close(handle: ctypes.c_void_p) -> None:
         )
 
 
-# Write Zone Headers
+def tec_file_writer_flush(
+    handle: ctypes.c_void_p,
+    num_zones_to_retain: int = 0,
+    zones_to_retain: Sequence[int] | None = None,
+) -> None:
+    """Flush written zone data to a temporary intermediate file.
+
+    Args:
+        handle (ctypes.c_void_p): Writer handle.
+        num_zones_to_retain (int): Number of zones to keep in memory.
+        zones_to_retain (Sequence[int] | None): 1-based zone indices to retain.
+
+    Raises:
+        TecioError: On C library error.
+
+    Important:
+        SZL Only!
+
+    Note:
+        Used to reduce memory usage for large files. All zone data written so far, other
+        than any zones listed in ``zones_to_retain``, is written out to a temporary file
+        on disk and released from memory.
+
+    Note:
+        Retained zones can still be modified.
+
+    Note:
+        Temporary files created by flushing are merged into the final output file when
+        :func:`tec_file_writer_close` is called.
+    """
+    zones_ptr = None
+    if zones_to_retain is not None and len(zones_to_retain) > 0:
+        zones_array = (ctypes.c_int32 * len(zones_to_retain))(*zones_to_retain)
+        zones_ptr = ctypes.cast(zones_array, ctypes.POINTER(ctypes.c_int32))
+    else:
+        zones_ptr = ctypes.POINTER(ctypes.c_int32)()
+
+    ret = lib.tecFileWriterFlush(
+        handle,
+        ctypes.c_int32(num_zones_to_retain),
+        zones_ptr,
+    )
+    if ret != 0:
+        raise TecioError(
+            f"tecFileWriterFlush Error: handle={handle}, "
+            f"num_zones_to_retain={num_zones_to_retain}, "
+            f"zones_to_retain={zones_to_retain}, "
+            f"return_code={ret}"
+        )
+
+
+# -- Write Zone Headers ----------------------------------------------------------------
 def tec_zone_create_ijk(
     handle: ctypes.c_void_p,
     zone_title: str,
@@ -2417,7 +2474,7 @@ def tec_zone_create_fe(
     return zone_out.value
 
 
-# Optional fields
+# -- Optional fields -------------------------------------------------------------------
 def tec_zone_set_unsteady_options(
     handle: ctypes.c_void_p, zone: int, strand: int = 0, solution_time: float = 0.0
 ) -> None:
@@ -2532,7 +2589,7 @@ def tec_zone_add_aux_data(
         )
 
 
-# ---- Write variable value functions --------------------------------
+# -- Write variable value functions ----------------------------------------------------
 def tec_zone_var_write_double_values(
     handle: ctypes.c_void_p, zone: int, var: int, values: npt.ArrayLike
 ) -> None:
@@ -2690,7 +2747,7 @@ def tec_zone_var_write_uint8_values(
         )
 
 
-# Write Zone Connectivity (FE zones only)
+# -- Write Zone Connectivity (FE zones only) -------------------------------------------
 def tec_zone_node_map_write32(
     handle: ctypes.c_void_p,
     zone: int,
@@ -2889,7 +2946,7 @@ def tec_zone_face_nbr_write_connections64(
 # --------------------------------------------------------------------------------------
 
 
-# File initialization and finalization
+# -- File initialization and finalization ----------------------------------------------
 def tecini142(
     filename: str,
     variables: Sequence[str],
@@ -3039,7 +3096,7 @@ def tecforeign142(output_foreign_byte_order: int) -> None:
         raise TecioError(f"tecforeign142 Error: return_code={ret}")
 
 
-# Zone creation
+# -- Zone creation ---------------------------------------------------------------------
 def teczne142(
     zone_title: str,
     zone_type: int | ZoneType,
@@ -3329,7 +3386,7 @@ def tecznefemixed142(
         )
 
 
-# Data writing
+# -- Data writing ----------------------------------------------------------------------
 def tecdat142(
     field_data: npt.ArrayLike,
     is_double: bool = True,
@@ -3379,7 +3436,7 @@ def tecdat142(
         )
 
 
-# Connectivity writing
+# -- Connectivity writing --------------------------------------------------------------
 def tecnode142(nodes: npt.ArrayLike) -> None:
     """Write node connectivity for an FE zone (classic API).
 
@@ -3538,7 +3595,7 @@ def tecpolybconn142(
         )
 
 
-# Auxiliary data
+# -- Auxiliary data --------------------------------------------------------------------
 def tecauxstr142(name: str, value: str) -> None:
     """Add dataset-level auxiliary data (classic API).
 
@@ -3613,7 +3670,7 @@ def teczauxstr142(name: str, value: str) -> None:
         )
 
 
-# User-defined data (custom records)
+# -- User-defined data (custom records) ------------------------------------------------
 def tecusr142(user_rec: str) -> None:
     """Write a user-defined data record (classic API).
 

tecio/plt/_read.py

@@ -1,21 +1,21 @@
 r"""Native binary reader for Tecplot PLT (``.plt``) files.
 
 This module provides a pure-Python / NumPy reader for Tecplot PLT binary files (format
-versions v112 and v191).  It is a **standalone debugging module** intended to be
+versions v112 and v191). It is a **standalone debugging module** intended to be
 integrated into the existing :mod:`plt` module once validated.
 
 Notes:
     * **No byte-swapping boilerplate.** The INT32 value of ``1`` written immediately
-      after the magic number is used to detect endianness at open time.  All subsequent
+      after the magic number is used to detect endianness at open time. All subsequent
       reads use the correct NumPy byte-order prefix (``"<"`` or ``">"``).
     * **Lazy variable data.** Zone and variable *metadata* is parsed during ``__init__``
-      and stored as lightweight dataclass attributes.  Actual numeric data is read from
+      and stored as lightweight dataclass attributes. Actual numeric data is read from
       disk only when ``.values`` (or ``.get_values()``) is called, matching the
       behaviour of :class:`szl.ReadVariable`.
     * **No text / geometry support.** Header records with markers 399.0 (geometry) and
       499.0 (text) are detected and skipped without parsing their contents.
     * **v112 and v191 zone headers.** Zone marker ``299.0`` → v112 header; ``298.0`` →
-      v191 header.  Both are fully supported.
+      v191 header. Both are fully supported.
 
 Limitations
     * FEPOLYGON and FEPOLYHEDRON zones are parsed for metadata but face-map reading is
@@ -92,7 +92,7 @@ _DATATYPE_DTYPE: dict[DataType, str] = {
     DataType.BYTE: "u1",
 }
 
-# PLT format variable location integers → ValueLocation enum.  The PLT spec uses 0 =
+# PLT format variable location integers → ValueLocation enum. The PLT spec uses 0 =
 # Node, 1 = Cell Centered (format guide §IV.iv), which is the opposite of the
 # ValueLocation enum (CELL_CENTERED=0, NODAL=1).
 _PLT_VALUELOCATION_MAP: dict[int, ValueLocation] = {
@@ -155,7 +155,7 @@ def _read_string(fp: io.BufferedIOBase, byte_order: str) -> str:
     """Read a null-terminated string stored as INT32 code-points.
 
     The PLT format stores each character as a 4-byte integer (see Note 1 of the format
-    spec).  The string is terminated by a zero INT32.
+    spec). The string is terminated by a zero INT32.
     """
     chars: list[str] = []
     while True:
@@ -250,7 +250,7 @@ class _ZoneMeta:
 class ReadAuxData:
     """Dictionary-like interface for PLT auxiliary data.
 
-    Values are stored as plain Python strings.  Convenience converters ``as_int``,
+    Values are stored as plain Python strings. Convenience converters ``as_int``,
     ``as_float``, and ``as_bool`` are provided to match the :class:`szl.ReadAuxData`
     API.
     """
@@ -376,11 +376,11 @@ class ReadVariable:
     def _resolve_data_meta(self) -> _ZoneMeta | None:
         """Return the :class:`_ZoneMeta` that owns this variable's data.
 
-        For a variable this zone stores itself this is simply ``self._meta``.  For a
+        For a variable this zone stores itself this is simply ``self._meta``. For a
         shared variable, the chain of per-variable ``shared_zone`` references is
         followed to the owning zone (with a cycle/range guard against malformed
         files) -- the variable-level analogue of
-        :meth:`ReadZone._resolve_connectivity_meta`.  Returns ``None`` when the
+        :meth:`ReadZone._resolve_connectivity_meta`. Returns ``None`` when the
         share cannot be resolved, e.g. when ``all_metas`` was not supplied at
         construction.
         """
@@ -511,7 +511,7 @@ class ReadVariable:
             return None
 
         # Resolve to the zone that actually owns this variable's data (self for unshared
-        # variables, the share-chain source otherwise).  The resolved meta describes the
+        # variables, the share-chain source otherwise). The resolved meta describes the
         # on-disk block being read, so it also drives the count, dtype, and ordered-zone
         # reshape/ghost-trim logic below.
         meta = self._resolve_data_meta()
@@ -561,7 +561,7 @@ class ReadVariable:
         if full_read and meta.zone_type == ZoneType.ORDERED:
             ni, nj, nk = meta.i_max, meta.j_max, meta.k_max
             if meta.value_locations[self.var_index - 1] == ValueLocation.CELL_CENTERED:
-                # On disk: i * j * (k-1) values in Fortran order.  Ghost padding
+                # On disk: i * j * (k-1) values in Fortran order. Ghost padding
                 # occupies the last row in I and J after reshape, so reshape to (ni, nj,
                 # nk-1) then slice to (ni-1, nj-1, nk-1) to discard the ghost values and
                 # return only significant cells.
@@ -727,7 +727,7 @@ class ReadZone:
     ) -> npt.NDArray | None | tuple[npt.NDArray | 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
+        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, suitable for unpacking::
 
             p = zone.get_array("p")
@@ -735,7 +735,7 @@ class ReadZone:
 
         Returns:
             One array (or ``None`` if the variable is passive or shared) for a scalar
-            key; a tuple of such arrays for a list of names.  A single-element list
+            key; a tuple of such arrays for a list of names. A single-element list
             yields a 1-tuple, not a bare array.
 
         Raises:
@@ -750,10 +750,10 @@ class ReadZone:
     def _resolve_connectivity_meta(self) -> _ZoneMeta | None:
         """Return the :class:`_ZoneMeta` that owns this zone's connectivity.
 
-        For a zone with its own connectivity this is simply ``self._meta``.  For a zone
+        For a zone with its own connectivity this is simply ``self._meta``. For a zone
         that shares connectivity, the chain of ``connectivity_shared_zone`` references
         is followed to the owning zone (with a cycle/range guard against malformed
-        files).  Returns ``None`` when the share cannot be resolved -- e.g. when
+        files). Returns ``None`` when the share cannot be resolved -- e.g. when
         ``all_metas`` was not supplied at construction.
         """
         meta = self._meta
@@ -839,7 +839,7 @@ class ReadZone:
 class _PltParser:
     """Low-level PLT binary parser.
 
-    Called once from :class:`Read.__init__`.  After construction the following
+    Called once from :class:`Read.__init__`. After construction the following
     attributes are available:
 
         ===================   ===============================================
@@ -1137,7 +1137,7 @@ class _PltParser:
     def _parse_data_section(self, fp: io.BufferedIOBase) -> None:
         """Parse the data section and record variable file offsets.
 
-        The EOHMARKER has already been consumed by :meth:`_parse_header`.  We iterate
+        The EOHMARKER has already been consumed by :meth:`_parse_header`. We iterate
         over zones in declaration order, matching each data block to the corresponding
         :class:`_ZoneMeta` in ``self.zones``.
         """
@@ -1201,7 +1201,7 @@ class _PltParser:
         """Record file offsets for each active variable data block.
 
         Data is stored in **block** order (all values for variable 0, then all values
-        for variable 1, …).  We seek rather than read so we do not load the data into
+        for variable 1, …). We seek rather than read so we do not load the data into
         memory.
         """
         for v in range(num_vars):
@@ -1228,7 +1228,7 @@ class _PltParser:
         """Return the number of values on disk for variable *var_idx*.
 
         For cell-centered variables in ORDERED zones the PLT format writes ``IMax * JMax
-        * (KMax - 1)`` values on disk (see Note 5 of the format spec).  The significant
+        * (KMax - 1)`` values on disk (see Note 5 of the format spec). The significant
         cell count is ``(I-1) * (J-1) * (K-1)``; the remainder are ghost (zero-padded)
         values that are trimmed in :meth:`ReadVariable.get_values` after reshaping.
 
@@ -1242,7 +1242,7 @@ class _PltParser:
             j = max(meta.j_max, 1)
             k = max(meta.k_max, 1)
             if loc == ValueLocation.CELL_CENTERED:
-                # PLT Note 5: IMax * JMax * (KMax - 1) values on disk.  Only K is
+                # PLT Note 5: IMax * JMax * (KMax - 1) values on disk. Only K is
                 # reduced; I and J retain their full extent as ghost padding in the
                 # Fortran-order layout.
                 return i * j * max(k - 1, 1)
@@ -1427,7 +1427,7 @@ class Read:
         """Context manager protocol for read-only file interfaces.
 
         Read classes hold no open file handle between accesses, so there is nothing to
-        release on exit.  Provided for API consistency with the Write classes and to
+        release on exit. Provided for API consistency with the Write classes and to
         support the ``with tecio.open(...) as r:`` pattern.
         """
         pass