Source code for tecio._plt_write

"""Write Tecplot PLT (``.plt``) binary files using the classic TecIO API.

Note:
    PLT's classic API sets output precision once for the *entire file* via ``VIsDouble``
    at ``tecini142`` time.  ``tecdat142``'s own ``IsDouble`` argument does not control
    per-variable output precision, and there is no per-variable type array in
    ``teczne142`` either. Every variable in a PLT file is written at the single,
    file-wide precision set by :attr:`TecplotPltWriter.precision`.
"""

from __future__ import annotations

from collections.abc import Sequence
from typing import Any, cast

import numpy as np
import numpy.typing as npt

from . import libtecio
from ._constants import (
    DataPacking,
    DataType,
    FaceNeighborMode,
    FeCellShape,
    FileFormat,
    FileType,
    ValueLocation,
    ZoneType,
)
from ._meta import ZoneMeta
from ._writer import (
    PassiveVarsSpec,
    PreparedFEZone,
    PreparedOrderedZone,
    PreparedPolyZone,
    TecplotWriter,
    VarSharingSpec,
    convert_face_connections_to_one_based,
    normalize_precision,
    prepare_fe_zone,
    prepare_ordered_zone,
    prepare_poly_zone,
    var_sharing_for_libtecio,
    zone_for_libtecio,
)

# -------------------------------------------------------------------------------------
# Module-level constants
# -------------------------------------------------------------------------------------

# FE zone types supported by :meth:`Write.write_fe_zone`.
_FE_SIMPLE: frozenset[ZoneType] = frozenset({
    ZoneType.FELINESEG,
    ZoneType.FETRIANGLE,
    ZoneType.FEQUADRILATERAL,
    ZoneType.FETETRAHEDRON,
    ZoneType.FEBRICK,
})
# =====================================================================================
# Helpers
# =====================================================================================


def _infer_data_type(dt: DataType | np.dtype) -> DataType:
    """Return a C-supported :class:`DataType` for a :class:`DataType` or NumPy dtype.

    Maps NumPy dtypes to the closest supported Tecplot data type. For PLT format only
    FLOAT and DOUBLE are supported; all integer types are upcast to DOUBLE.  precision
    is promoted to ``FLOAT``; 64-bit integers are promoted to ``INT32``; ``int8`` and
    ``uint8`` map to ``BYTE``.

    Raises:
        ValueError: If the dtype is not supported.
    """
    closest: dict[np.dtype, DataType] = {
        np.dtype(np.float64): DataType.DOUBLE,
        np.dtype(np.float32): DataType.FLOAT,
        np.dtype(np.float16): DataType.FLOAT,
        np.dtype(np.int64): DataType.INT32,
        np.dtype(np.int32): DataType.INT32,
        np.dtype(np.int16): DataType.INT16,
        np.dtype(np.int8): DataType.BYTE,
        np.dtype(np.uint8): DataType.BYTE,
    }

    if isinstance(dt, DataType):
        return dt

    dt_np = np.dtype(dt)

    for key, val in closest.items():
        if dt_np == key:
            return val

    if np.issubdtype(dt_np, np.floating):
        return DataType.FLOAT if dt_np.itemsize <= 4 else DataType.DOUBLE

    if np.issubdtype(dt_np, np.signedinteger):
        return DataType.INT16 if dt_np.itemsize <= 2 else DataType.INT32

    if np.issubdtype(dt_np, np.unsignedinteger):
        return DataType.BYTE

    raise ValueError(f"Unsupported dtype: {dt_np}")


# =====================================================================================
# Local functions
# =====================================================================================


def _write_data(data: npt.ArrayLike, dtype: np.dtype | DataType | None = None) -> None:
    """Write a single variable's data using ``tecdat142``.

    ``tecdat142`` only accepts ``float32`` or ``float64``; integer types are
    upcast to ``float64``. The array is ravelled in Fortran (column-major)
    order before writing, which matches Tecplot's expected BLOCK layout.

    Args:
        data: Array-like of values to write.
        dtype: Intended :class:`DataType` for the variable.

    Output defaults:
    1. Inferrs data_typeype for nummpy arrays
    2. Defaults to double precision for array-like (list, tuple, etc)
    3. Optionally casts to input DataType or numpy dtype.
    4. Assumes data is in the correct shape and order (column major / Fortran order)
    """
    # Mappings between C-supported data types and numpy dtypes
    dtype_to_datatype: dict[np.dtype, DataType] = {
        np.dtype(np.float64): DataType.DOUBLE,
        np.dtype(np.float32): DataType.FLOAT,
        np.dtype(np.int32): DataType.INT32,
        np.dtype(np.int16): DataType.INT16,
        np.dtype(np.uint8): DataType.BYTE,
    }

    # Convert input array-like data to NumPy arrays
    arr = np.asarray(data)

    data_type = (
        _infer_data_type(dtype) if dtype is not None else dtype_to_datatype[arr.dtype]
    )

    # tecdat142 already returns a contiguous array so no need to cast before calling
    if data_type in (DataType.FLOAT, DataType.INT16, DataType.BYTE):
        # All fit within float32's precision
        libtecio.tecdat142(arr.ravel(order="F"), is_double=False)
    else:
        # INT32 max value (~2.1e9) exceeds float32's integer ceiling (2**24 ~= 16.7e6),
        # so write as a double
        libtecio.tecdat142(arr.ravel(order="F"), is_double=True)


def _write_connectivity(
    node_map: npt.ArrayLike,
    face_neighbors: npt.ArrayLike | None = None,
) -> None:
    """Write FE connectivity: node map and optional face-neighbour data.

    Args:
        node_map:       Integer array of shape ``(num_cells, nodes_per_cell)``
                        with 1-based node indices.
        face_neighbors: Optional face-neighbour connection array.
    """
    nodes_flat = np.ascontiguousarray(node_map, dtype=np.int32).ravel(order="C")
    libtecio.tecnode142(nodes_flat)

    if face_neighbors is not None:
        face_flat = np.ascontiguousarray(face_neighbors, dtype=np.int32).ravel(
            order="C"
        )
        libtecio.tecface142(face_flat)


# =====================================================================================
# Write class
# =====================================================================================


# ======================================================================================
# TecplotPltWriter
# ======================================================================================


class TecplotPltWriter(TecplotWriter):
    """Write Tecplot PLT (``.plt``) files using the classic TecIO API.

    The classic TecIO API maintains a single implicit global file context;
    only one PLT file may be open at a time. This class wraps that
    procedural API behind the same interface as :class:`~tecio.TecplotSzlWriter`.

    Dataset- and variable-level auxiliary data can be set at any time before
    the first zone is written. They are buffered and flushed automatically
    when the first zone header is created. Zone-level auxiliary data is
    passed directly to each zone-writing method.

    Like :class:`~tecio.TecplotSzlWriter`, the file can be opened *eagerly*
    (when ``variables`` is supplied to ``__init__``) or *lazily* (deferred
    until the first :meth:`write_ordered_zone` or :meth:`write_fe_zone` call, at
    which point ``variables`` must be provided to that call).

    Args:
        path:         Output file path (should end in ``.plt``).
        title:        Dataset title string.
        variables:    Variable name list. If provided the file is opened
                      immediately. If ``None``, the file is opened on the first
                      zone write.
        file_type:    :class:`~libtecio.FileType` enum. Defaults to
                      :attr:`~libtecio.FileType.FULL`.
        precision:    Whole-file storage precision (:attr:`DataType.FLOAT`/``"single"``
                      or :attr:`DataType.DOUBLE`/``"double"``). Unlike SZL, PLT has no
                      per-variable type, so this always resolves to a concrete value;
                      ``None`` is not accepted. Defaults to :attr:`DataType.DOUBLE`.

    Attributes:
        precision:    Whole-file storage precision (:attr:`DataType.FLOAT` or
                      :attr:`DataType.DOUBLE`). Maps directly to ``VIsDouble`` in
                      ``tecini142``.
        _opened:      True once ``tecini142`` has been called (the file has been
                      opened, eagerly or lazily), False before that and after
                      :meth:`close`. Governs whether :meth:`close` calls
                      ``tecend142``, and whether the next zone write needs to open
                      the file first.

    Caution:
        Unlike the SZL writer, zone data must be written strictly in order: header →
        variable data → connectivity. This is enforced internally by the write methods.

    Examples:
        Define file header fields on open.

        >>> with tecio.TecplotPltWriter("out.plt", variables=["X", "Y", "P"]) as w:
        ...     w.write_ordered_zone(data=[x, y, p], title="Zone 1")

        If writer handle is opened with just the file name, the variable name list can
        be provided with the first zone written.

        >>> with tecio.TecplotPltWriter("out.plt") as w:
        ...     w.write_ordered_zone(
        ...         data=[x, y, p],
        ...         variables=["X", "Y", "P"],
        ...         title="Zone 1",
        ...     )
    """

    def __init__(
        self,
        path: str,
        title: str = "untitled",
        variables: list[str] | None = None,
        file_type: FileType = FileType.FULL,
        *,
        precision: DataType | str = DataType.DOUBLE,
    ) -> None:
        """Store configuration; open the file immediately if *variables* given.

        Raises:
            ValueError: If *precision* is not :attr:`DataType.FLOAT` /
                        :attr:`DataType.DOUBLE` (or a recognized string alias for one of
                        them).
        """
        # Set before super().__init__(), which calls self._open() when
        # variables is already known (eager open), and _open() needs this.
        self.precision: DataType = cast(
            DataType, normalize_precision(precision, allow_none=False)
        )
        # Track whether the file has been opened so we know whether to call
        # tecini142 inside open().
        self._opened: bool = False
        super().__init__(path, title, variables, file_type)

    @property
    def _file_format(self) -> str:
        return "plt"

    # -- File lifecycle ---------------------------------------------------------------

    def _open(self, var_names: list[str]) -> None:
        """Call ``tecini142`` and record the variable list.

        This is called at most once per instance — either from ``__init__``
        (eager open) or from the first zone-writing method (lazy open).

        Args:
            var_names: Ordered list of variable name strings.
        """
        self.variables = var_names
        libtecio.tecini142(
            filename=self.path,
            variables=self.variables,
            title=self.title,
            file_format=FileFormat.PLT,
            file_type=self.file_type,
            vis_double=self.precision,
        )
        self._opened = True
        self._meta.set_variables(self.variables)

[docs] def close(self) -> None: """Finalize and close the PLT file (safe to call more than once). Flushes any buffered aux data first (in case it was added after the first zone, and so never reached the automatic pre-first-zone flush, e.g. ``add_auxdataset_dict`` called after a zone is already written), then calls ``tecend142`` if the file was opened. """ if self._opened: self.flush_aux() libtecio.tecend142() self._opened = False
# -- Aux data: only the per-item write differs from the shared base ---------------- def _write_dataset_aux_item(self, name: str, value: str) -> None: libtecio.tecauxstr142(name, value) def _write_var_aux_item( self, one_based_var_index: int, name: str, value: str ) -> None: libtecio.tecvauxstr142(one_based_var_index, name, value) # -- Structured zone writer --------------------------------------------------------
[docs] def write_ordered_zone( self, data: Sequence[npt.ArrayLike], *, title: str | None = None, variables: list[str] | None = None, value_locations: Sequence[ValueLocation] | None = None, passive_vars: PassiveVarsSpec | None = None, var_sharing: VarSharingSpec | None = None, solution_time: float = 0.0, strand_id: int = 0, aux: dict[str, Any] | None = None, datapacking: DataPacking | str = DataPacking.BLOCK, ) -> None: """Write a complete IJK-ordered zone. The zone header (``teczne142``), variable data (``tecdat142``), and optional zone aux data (``teczauxstr142``) are all written in strict sequence, as required by the classic TecIO API. The zone dimensions ``imax × jmax × kmax`` are inferred from the shape of the first nodal data array. 1-D arrays produce a ``(N, 1, 1)`` zone; 2-D arrays produce an ``(I, J, 1)`` zone. Args: data (Sequence[npt.ArrayLike]): One NumPy array per active (non-passive, non-shared) dataset variable, in dataset order. Array shape is used to infer ``imax``, ``jmax``, and ``kmax``; Fortran (column-major) order is assumed. Pass ``None`` to write a zone header only. title (str): Zone title. Defaults to ``"IJK_Zone_{index}"``, this zone's 0-based index. variables (list[str]): 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 (Sequence[ValueLocation]): Per-active-variable :class:`~tecio.ValueLocation`. Defaults to all ``NODAL``. passive_vars (list | tuple | set | None): Variables to mark passive: a list, tuple, or set of variable names, or of 0-based indices, e.g. ``{"x"}`` or ``[3]``. Defaults to all active (``passive_vars=None``). var_sharing (Mapping[int | str, int]): Variables to share from another zone: a ``{variable: source zone}`` mapping, name or 0-based index to 0-based zone index, e.g. ``{"x": 0, "y": 0}``. Defaults to no sharing. solution_time (float): Solution time for transient data. Default to ``0.0`` if not defined. strand_id (int): Strand ID for transient data. Use ``0`` for static zones. Default to ``0`` (static) if not defined. aux (dict[str, str | float | int]): Zone-level auxiliary data as ``{name: value}`` string pairs. datapacking (DataPacking | str): In :attr:`~tecio.DataPacking.POINT` format, the values for all variables are given for the first point, then the second point, and so on. In :attr:`~tecio.DataPacking.BLOCK` format, all of the values for the first variable are given in a block, then all of the values for the second variable, then all of the values for the third, and so forth. :attr:`~tecio.DataPacking.BLOCK` format must be used for cell-centered data and polyhedral zones (:attr:`~tecio.ZoneType.FEPOLYGON`/:attr:`~tecio.ZoneType.FEPOLYHEDRAL`), as well as for all binary data. `POINT` and `BLOCK` keyword strings also accepted. Defaults to :attr:`~tecio.DataPacking.BLOCK`. Raises: NotImplementedError: If *datapacking* is :attr:`~tecio.libtecio.DataPacking.POINT`. TypeError: If *passive_vars*/*var_sharing* isn't a list/tuple/set/mapping as appropriate, or mixes variable names and indices. ValueError: If I/O operation attempted on closed or None file handle, or a variable is named in both *passive_vars* and *var_sharing*. RuntimeError: If attempting to write variable aux before variables are defined. KeyError: A *passive_vars*/*var_sharing* name doesn't match any dataset variable. IndexError: A *passive_vars*/*var_sharing* index is out of range. """ # Validate inputs if isinstance(datapacking, str): try: datapacking = DataPacking[datapacking.upper()] except KeyError: raise ValueError( f"datapacking={datapacking!r} is not a recognised value; " "use DataPacking.BLOCK or the string 'BLOCK'." ) from None if datapacking != DataPacking.BLOCK: raise NotImplementedError( "DATAPACKING=POINT is an ASCII-only layout and is not supported " "by the PLT binary format. Use DataPacking.BLOCK (the default) " "or write to a .dat file instead." ) # Convert input data to NumPy arrays arrays: list[npt.NDArray] = [np.asarray(arr) for arr in data] # Default title if title is None: title = f"IJK_Zone_{self.current_zone + 1}" # Default variable names (only used on lazy-open first-zone call) if variables is None: variables = [f"V{i}" for i in range(1, len(arrays) + 1)] # Open the file if lazily loaded and flush buffered aux data if not self._opened: self._open(variables) if self.current_zone == -1: self.flush_aux() # Per-active-variable data types inferred from array dtypes (currently overrided # to precision) variable_types = [self.precision] * len(arrays) # Default value locations — all nodal if value_locations is None: value_locations = [ValueLocation.NODAL] * len(arrays) prepared: PreparedOrderedZone | None = prepare_ordered_zone( arrays, variable_types, value_locations=value_locations, passive_vars=passive_vars, var_sharing=var_sharing, dataset_variables=self._check_variables(), meta=self._meta, ) if prepared is None: return passive_flags = prepared.passive_vars share_idx = prepared.var_sharing active_var_idx = prepared.active_var_idx imax, jmax, kmax = prepared.imax, prepared.jmax, prepared.kmax value_locations_global = prepared.value_locations_global variable_types_global = prepared.variable_types_global # Write zone header libtecio.teczne142( zone_title=title, zone_type=ZoneType.ORDERED, imax=imax, jmax=jmax, kmax=kmax, value_locations=value_locations_global, pas_vars=passive_flags, var_sharing=( var_sharing_for_libtecio(share_idx) if any(s is not None for s in share_idx) else None ), con_sharing=0, strand=strand_id, solution_time=solution_time, ) self.current_zone += 1 # Zone-level aux data must be written immediately after teczne142 and # before the first tecdat142 call. if aux is not None: for name, value in aux.items(): libtecio.teczauxstr142(str(name), str(value)) # Write active variable data in dataset-variable order for var_idx, arr, dtype in zip( active_var_idx, arrays, variable_types, strict=True ): self.current_var = var_idx _write_data(arr, dtype) # Finally set zone metadata after successfully completing TecIO calls self._meta.record_zone( ZoneMeta( index=self.current_zone, title=title, zone_type=ZoneType.ORDERED, solution_time=solution_time, strand_id=strand_id, num_aux_items=len(aux) if aux else 0, dimensions=(imax, jmax, kmax), value_locations=tuple(value_locations_global), passive_vars=tuple(bool(p) for p in passive_flags), shared_vars=tuple(share_idx), data_types=tuple(variable_types_global), ) )
# -- Unstructured zone writer ------------------------------------------------------
[docs] def write_fe_zone( self, data: Sequence[npt.ArrayLike], zone_type: ZoneType, node_map: npt.ArrayLike | None = None, *, title: str | None = None, variables: list[str] | None = None, value_locations: Sequence[ValueLocation] | None = None, passive_vars: PassiveVarsSpec | None = None, var_sharing: VarSharingSpec | None = None, con_sharing: int | None = None, face_neighbors: npt.ArrayLike | None = None, face_neighbor_mode: FaceNeighborMode | None = None, solution_time: float = 0.0, strand_id: int = 0, aux: dict[str, Any] | None = None, datapacking: DataPacking | str = DataPacking.BLOCK, ) -> None: """Write a complete finite-element zone. Node and cell counts are inferred from *node_map*, or if *node_map* is omitted, from the zone referenced by *con_sharing*. The full sequence required by the classic TecIO API is issued internally: 1. :func:`~tecio.libtecio.teczne142` — zone header. 2. :func:`~tecio.libtecio.teczauxstr142` — zone-level aux data (if any), before data. 3. :func:`~tecio.libtecio.tecdat142` — one call per active variable. 4. :func:`~tecio.libtecio.tecnode142` — node map (skipped when connectivity is shared via ``con_sharing``). 5. :func:`~tecio.libtecio.tecface142` — face-neighbour connections (if provided). ``FEPOLYGON`` and ``FEPOLYHEDRON`` zones are face-based, write them with :meth:`write_poly_zone`. Args: data (Sequence[npt.ArrayLike]): Sequence of 1-D arrays, one per active (non-passive, non-shared) dataset variable, in dataset order. 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 (ZoneType): FE zone type from the ZoneType enum. Must be one of the types in ``_FE_SIMPLE``. node_map (npt.ArrayLike): Integer array of shape ``(num_cells, nodes_per_cell)`` containing 0-based node indices. Required unless ``con_sharing`` is set, in which case the connectivity are inherited from the source zone instead. title (str): Zone title string. Defaults to ``"FE_Zone_{index}"``, this zone's 0-based index. variables (list[str]): 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 (Sequence[ValueLocation]): Per-active-variable :class:`~tecio.ValueLocation`. Defaults to all ``NODAL``. passive_vars (list | tuple | set | None): Variables to mark passive: a list, tuple, or set of variable names, or of 0-based indices, e.g. ``{"x"}`` or ``[3]``. Defaults to all active (``passive_vars=None``). var_sharing (Mapping[int | str, int]): Variables to share from another zone: a ``{variable: source zone}`` mapping, name or 0-based index to 0-based zone index. Defaults to no sharing (None or an empty mapping). Cross-checked against ``node_map`` / ``con_sharing`` for a consistent node/cell count. con_sharing (int): Optional zone index that the connectivity is shared from. ``None`` indicates no sharing (this zone owns its connectivity). The first zone in a dataset must own its connectivity. Connectivity cannot be shared when face neighbor mode is set to global. Connectivity cannot be shared between cell-based and face-based finite element zones. face_neighbors (npt.ArrayLike): Optional face-neighbor connectivity, always a flat array (whatever shape you pass is flattened before writing). The number of values per connection depends on ``face_neighbor_mode``, a fixed 3 or 4 for the one-to-one modes, a variable, self-describing count per record for the "many" modes. The connection count is always derived from this array, never a separate parameter. face_neighbor_mode (FaceNeighborMode): Default to None meaning no face-neighbor data. If ``face_neighbors`` is supplied without defining a face neighbor mode, it is treated as LOCAL_ONE_TO_ONE. Cannot be defined without also supplying a ``face_neighbors`` array. solution_time (float): Solution time for transient data. Default to ``0.0`` if not defined. strand_id (int): Strand ID for transient data. Use ``0`` for static zones. Default to ``0`` (static) if not defined. aux (dict[str, str | float | int]): Zone-level auxiliary data as ``{name: value}`` string pairs. datapacking (DataPacking | str): In :attr:`~tecio.DataPacking.POINT` format, the values for all variables are given for the first point, then the second point, and so on. In :attr:`~tecio.DataPacking.BLOCK` format, all of the values for the first variable are given in a block, then all of the values for the second variable, then all of the values for the third, and so forth. :attr:`~tecio.DataPacking.BLOCK` format must be used for cell-centered data and polyhedral zones (:attr:`~tecio.ZoneType.FEPOLYGON`/:attr:`~tecio.ZoneType.FEPOLYHEDRAL`), as well as for all binary data. `POINT` and `BLOCK` keyword strings also accepted. Defaults to :attr:`~tecio.DataPacking.BLOCK`. Raises: NotImplementedError: If *datapacking* is :attr:`~tecio.libtecio.DataPacking.POINT`. TypeError: If *passive_vars*/*var_sharing* isn't a list/tuple/set/mapping as appropriate, or mixes variable names and indices. ValueError: For FEPOLYGON or FEPOLYHEDRON (use :meth:`write_poly_zone`); on variable count or array length mismatch; if ``node_map`` is omitted without ``con_sharing``; if ``var_sharing``/``con_sharing`` reference a zone with no recorded node/cell count, or one whose count disagrees with this zone's; or a variable named in both *passive_vars* and *var_sharing*. ValueError: If I/O operation attempted on closed or None file handle. RuntimeError: If attempting to write variable aux before variables are defined. KeyError: A *passive_vars*/*var_sharing* name doesn't match any dataset variable. IndexError: A *passive_vars*/*var_sharing* index is out of range. """ # Validate input if isinstance(datapacking, str): try: datapacking = DataPacking[datapacking.upper()] except KeyError: raise ValueError( f"datapacking={datapacking!r} is not a recognised value; " "use DataPacking.BLOCK or the string 'BLOCK'." ) from None if datapacking != DataPacking.BLOCK: raise NotImplementedError( "DATAPACKING=POINT is an ASCII-only layout and is not supported " "by the PLT binary format. Use DataPacking.BLOCK (the default) " "or write to a .dat file instead." ) if zone_type in (ZoneType.FEPOLYGON, ZoneType.FEPOLYHEDRON): raise ValueError( f"{zone_type.name} zones are face-based, use write_poly_zone." ) if zone_type not in _FE_SIMPLE: raise NotImplementedError( f"Zone type {zone_type.name!r} is not supported by write_fe_zone." ) # Convert input data to NumPy arrays arrays: list[npt.NDArray] = [np.asarray(arr) for arr in data] # Default title if title is None: title = f"FE_Zone_{self.current_zone + 1}" # Default variable names (only used on lazy-open first-zone call) if variables is None: variables = [f"V{i}" for i in range(1, len(arrays) + 1)] # Open the file if lazily loaded and flush buffered aux data if not self._opened: self._open(variables) if self.current_zone == -1: self.flush_aux() # Infer per-variable data types from array dtypes (currently overrided to # precision) variable_types = [self.precision] * len(arrays) # Set default value locations if value_locations is None: value_locations = [ValueLocation.NODAL] * len(arrays) prepared: PreparedFEZone | None = prepare_fe_zone( arrays, variable_types, zone_type, node_map=node_map, value_locations=value_locations, passive_vars=passive_vars, var_sharing=var_sharing, con_sharing=con_sharing, face_neighbors=face_neighbors, face_neighbor_mode=face_neighbor_mode, dataset_variables=self._check_variables(), meta=self._meta, ) if prepared is None: return passive_flags = prepared.passive_vars share_idx = prepared.var_sharing con_sharing = prepared.con_sharing active_var_idx = prepared.active_var_idx num_nodes = prepared.num_nodes num_cells = prepared.num_cells value_locations_global = prepared.value_locations_global variable_types_global = prepared.variable_types_global face_neighbor_mode = prepared.face_neighbor_mode num_face_cons = prepared.num_face_connections # PLT's classic API only supports 32-bit face-neighbor writes, so # the dtype cast (not forced by the shared preparation step, which # leaves it to each format) happens here, right before dispatch. face_neighbors_arr: npt.NDArray | None = None if prepared.face_neighbors_arr is not None: face_neighbors_arr = prepared.face_neighbors_arr.astype(np.int32) # Write zone header. # imax = num_nodes, jmax = num_cells, kmax = 0 for simple FE zones. libtecio.teczne142( zone_title=title, zone_type=zone_type, imax=num_nodes, jmax=num_cells, kmax=0, value_locations=value_locations_global, pas_vars=passive_flags, var_sharing=( var_sharing_for_libtecio(share_idx) if any(s is not None for s in share_idx) else None ), con_sharing=zone_for_libtecio(con_sharing), strand=strand_id, solution_time=solution_time, num_face_connections=num_face_cons, face_nbr_mode=face_neighbor_mode or FaceNeighborMode.LOCAL_ONE_TO_ONE, ) self.current_zone += 1 # Zone-level aux data must be immediately after teczne142, before # any tecdat142 calls. if aux is not None: for name, value in aux.items(): libtecio.teczauxstr142(str(name), str(value)) # Write active variable data in dataset-variable order for var_idx, arr, dtype in zip( active_var_idx, arrays, variable_types, strict=True ): self.current_var = var_idx _write_data(arr, dtype) # Write connectivity (if not shared). Must come after all data arrays. if con_sharing is None: assert node_map is not None face_flat = None if face_neighbors_arr is not None: assert face_neighbor_mode is not None face_flat = convert_face_connections_to_one_based( face_neighbors_arr, face_neighbor_mode ) _write_connectivity(np.asarray(node_map) + 1, face_flat) # Finally set zone metadata after successfully completing TecIO calls self._meta.record_zone( ZoneMeta( index=self.current_zone, title=title, zone_type=zone_type, solution_time=solution_time, strand_id=strand_id, num_aux_items=len(aux) if aux else 0, num_nodes=num_nodes, num_elements=num_cells, value_locations=tuple(value_locations_global), passive_vars=tuple(bool(p) for p in passive_flags), shared_vars=tuple(share_idx), data_types=tuple(variable_types_global), face_neighbor_mode=( face_neighbor_mode if face_neighbors_arr is not None else None ), num_face_connections=num_face_cons or None, ) )
[docs] def write_femixed_zone( self, data: Sequence[npt.ArrayLike], cell_shapes: Sequence[FeCellShape | int | str] | None = None, node_maps: Sequence[npt.ArrayLike] | None = None, *, title: str | None = None, variables: list[str] | None = None, value_locations: Sequence[ValueLocation] | None = None, passive_vars: PassiveVarsSpec | None = None, var_sharing: VarSharingSpec | None = None, con_sharing: int | None = None, solution_time: float = 0.0, strand_id: int = 0, aux: dict[str, Any] | None = None, datapacking: DataPacking | str = DataPacking.BLOCK, ) -> None: """Not supported: PLT files cannot hold FEMIXED zones. The signature matches :meth:`TecplotSzlWriter.write_femixed_zone` so every writer exposes the same interface. Raises: NotImplementedError: Always. Write a ``.szplt`` file instead, see :meth:`TecplotSzlWriter.write_femixed_zone`. """ raise NotImplementedError( "The PLT file format does not support FEMIXED (mixed finite-element) " "zones. Write a .szplt file instead." )
[docs] def write_poly_zone( self, data: Sequence[npt.ArrayLike], zone_type: ZoneType, *, face_nodes: npt.ArrayLike | None = None, face_node_counts: npt.ArrayLike | None = None, face_left_elements: npt.ArrayLike | None = None, face_right_elements: npt.ArrayLike | None = None, boundary_connection_counts: npt.ArrayLike | None = None, boundary_connection_elements: npt.ArrayLike | None = None, boundary_connection_zones: npt.ArrayLike | None = None, title: str | None = None, variables: list[str] | None = None, value_locations: Sequence[ValueLocation] | None = None, passive_vars: PassiveVarsSpec | None = None, var_sharing: VarSharingSpec | None = None, con_sharing: int | None = None, solution_time: float = 0.0, strand_id: int = 0, aux: dict[str, Any] | None = None, datapacking: DataPacking | str = DataPacking.BLOCK, ) -> None: """Write a complete FEPOLYGON or FEPOLYHEDRON (face-based) zone. Node and element counts are inferred from the face map, or from the *con_sharing* source zone when it is omitted. Every index is 0-based. The arguments match what :class:`~tecio.TecplotPolyZoneReader` returns, so a zone read from a file can be written back unchanged. The classic TecIO sequence is issued internally: ``tecpolyzne142`` (header), ``teczauxstr142`` (aux data), ``tecdat142`` (one call per active variable), then ``tecpolyface142`` and, with boundary connections, ``tecpolybconn142``. Connectivity is skipped when shared via *con_sharing*. Args: data (Sequence[npt.ArrayLike]): Sequence of 1-D arrays, one per active (non-passive, non-shared) dataset variable, in dataset order. NODAL arrays need ``num_nodes`` values, CELL_CENTERED arrays ``num_elements``, both inferred from the face map. zone_type (ZoneType): :attr:`~tecio.ZoneType.FEPOLYGON` or :attr:`~tecio.ZoneType.FEPOLYHEDRON`. face_nodes (npt.ArrayLike): Flat 0-based node indices of all faces, in face order. Two per face for a polygon zone. Required unless ``con_sharing`` is set. face_node_counts (npt.ArrayLike): Number of nodes of each face. Required for FEPOLYHEDRON. Optional for FEPOLYGON, where every face has 2 nodes. face_left_elements (npt.ArrayLike): Element on the left of each face: a 0-based element index, ``-1`` for no element, or ``-(b + 2)`` for boundary face ``b`` (0-based). face_right_elements (npt.ArrayLike): Element on the right of each face, same convention as ``face_left_elements``. boundary_connection_counts (npt.ArrayLike): Number of connections of each boundary face. Boundary faces describe neighbors in other zones, or faces with more than one neighbor. boundary_connection_elements (npt.ArrayLike): Flat 0-based neighbor element of every boundary connection. boundary_connection_zones (npt.ArrayLike): Flat 0-based zone of every neighbor element. May only reference a zone already written or this zone. title (str): Zone title string. Defaults to ``"Poly_Zone_{index}"``, with this zone's 0-based index. variables (list[str]): Variable name list, only used when the file has not been opened yet (lazy-open path). Defaults to ``[V1, V2, V3, ...]``. value_locations (Sequence[ValueLocation]): Per-active-variable :class:`~tecio.ValueLocation`. Defaults to all ``NODAL``. passive_vars (list | tuple | set | None): Variables to mark passive: a list, tuple, or set of variable names, or of 0-based indices. Defaults to all active. var_sharing (Mapping[int | str, int]): Variables to share from another zone: a ``{variable: source zone}`` mapping, name or 0-based index to 0-based zone index. con_sharing (int): Zone index to share the face map from, which must be a zone of the same type without boundary faces (TecIO does not allow sharing those). ``None`` means this zone owns its connectivity. solution_time (float): Solution time for transient data. Defaults to ``0.0``. strand_id (int): Strand ID for transient data, ``0`` for static zones. aux (dict[str, str | float | int]): Zone-level auxiliary data as ``{name: value}`` pairs. datapacking (DataPacking | str): Must be :attr:`~tecio.DataPacking.BLOCK`, the only layout of the PLT binary format. Raises: TypeError: If *passive_vars*/*var_sharing* isn't a list/tuple/set/mapping as appropriate, or mixes variable names and indices. ValueError: If *datapacking* is :attr:`~tecio.DataPacking.POINT`. For a *zone_type* other than FEPOLYGON or FEPOLYHEDRON (use :meth:`write_fe_zone`); on a missing, inconsistent, or out of range face map, boundary connection, or variable array. KeyError: A *passive_vars*/*var_sharing* name doesn't match any dataset variable. IndexError: A *passive_vars*/*var_sharing* index is out of range. """ if isinstance(datapacking, str): try: datapacking = DataPacking[datapacking.upper()] except KeyError: raise ValueError( f"datapacking={datapacking!r} is not a recognised value; " "use DataPacking.BLOCK or the string 'BLOCK'." ) from None if datapacking != DataPacking.BLOCK: raise ValueError( "Polygon and polyhedron zones must use BLOCK data packing." ) arrays: list[npt.NDArray] = [np.asarray(arr) for arr in data] if title is None: title = f"Poly_Zone_{self.current_zone + 1}" if variables is None: variables = [f"V{i}" for i in range(1, len(arrays) + 1)] # Open the file if lazily loaded and flush buffered aux data if not self._opened: self._open(variables) if self.current_zone == -1: self.flush_aux() variable_types = [self.precision] * len(arrays) prepared: PreparedPolyZone | None = prepare_poly_zone( arrays, variable_types, zone_type, face_nodes=face_nodes, face_node_counts=face_node_counts, face_left_elements=face_left_elements, face_right_elements=face_right_elements, boundary_connection_counts=boundary_connection_counts, boundary_connection_elements=boundary_connection_elements, boundary_connection_zones=boundary_connection_zones, value_locations=value_locations, passive_vars=passive_vars, var_sharing=var_sharing, con_sharing=con_sharing, dataset_variables=self._check_variables(), meta=self._meta, ) if prepared is None: return conn = prepared.connectivity share_idx = prepared.var_sharing libtecio.tecpolyzne142( zone_title=title, zone_type=zone_type, num_nodes=conn.num_nodes, num_faces=conn.num_faces, num_elements=conn.num_cells, var_sharing=( var_sharing_for_libtecio(share_idx) if any(s is not None for s in share_idx) else None ), value_locations=prepared.value_locations_global, pas_vars=prepared.passive_vars, con_sharing=zone_for_libtecio(prepared.con_sharing), strand=strand_id, solution_time=solution_time, total_num_face_nodes=conn.total_face_nodes, num_connected_boundary_faces=conn.num_boundary_faces, total_num_boundary_connections=conn.num_boundary_connections, ) self.current_zone += 1 # Zone-level aux data must be immediately after the zone header, before data. if aux is not None: for name, value in aux.items(): libtecio.teczauxstr142(str(name), str(value)) for var_idx, arr, dtype in zip( prepared.active_var_idx, arrays, variable_types, strict=True ): self.current_var = var_idx _write_data(arr, dtype) # Face map (if not shared), after all data arrays. TecIO is 1-based with 0 for # no element and -k for the k-th boundary face, which is the 0-based API # convention shifted by one for every array. if prepared.con_sharing is None: assert conn.face_nodes is not None assert ( conn.face_left_elements is not None and conn.face_right_elements is not None ) # Polygon: counts are NULL, every face is a two node edge. libtecio.tecpolyface142( conn.face_node_counts, conn.face_nodes.astype(np.int32) + 1, conn.face_left_elements.astype(np.int32) + 1, conn.face_right_elements.astype(np.int32) + 1, num_faces=conn.num_faces, ) if conn.num_boundary_faces: assert conn.boundary_connection_counts is not None assert conn.boundary_connection_elements is not None assert conn.boundary_connection_zones is not None libtecio.tecpolybconn142( conn.boundary_connection_counts, conn.boundary_connection_elements.astype(np.int32) + 1, conn.boundary_connection_zones.astype(np.int32) + 1, ) # Finally set zone metadata after successfully completing TecIO calls self._meta.record_zone( ZoneMeta( index=self.current_zone, title=title, zone_type=zone_type, solution_time=solution_time, strand_id=strand_id, num_aux_items=len(aux) if aux else 0, num_nodes=conn.num_nodes, num_elements=conn.num_cells, num_faces=conn.num_faces, total_face_nodes=conn.total_face_nodes, num_boundary_faces=conn.num_boundary_faces, num_boundary_connections=conn.num_boundary_connections, value_locations=tuple(prepared.value_locations_global), passive_vars=tuple(prepared.passive_vars), shared_vars=tuple(share_idx), data_types=tuple(prepared.variable_types_global), ) )