r"""Write Tecplot ASCII DAT (``.dat`` / ``.tec``) files.
Supported ``DATAPACKING`` modes for writing:
* ``BLOCK`` -- one contiguous value block per variable (default).
* ``POINT`` -- one row of all active nodal variable values per node,
followed by a separate row-per-cell section for cell-centred variables.
Pass ``datapacking="POINT"`` to :meth:`~TecplotDatWriter.write_ordered_zone`
or :meth:`~TecplotDatWriter.write_fe_zone`.
* Poly zones (:meth:`~TecplotDatWriter.write_poly_zone`) are always ``BLOCK``.
"""
from __future__ import annotations
import contextlib
# Standard library
import io
import os
from collections.abc import Sequence
from typing import Any, cast
# Third-party
import numpy as np
import numpy.typing as npt
from ._constants import (
DataPacking,
DataType,
FaceNeighborMode,
FeCellShape,
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,
)
# -------------------------------------------------------------------------------------
# Module-level constants
# -------------------------------------------------------------------------------------
# FE zone types fully supported for reading and writing
_FE_SIMPLE: frozenset[ZoneType] = frozenset({
ZoneType.FELINESEG,
ZoneType.FETRIANGLE,
ZoneType.FEQUADRILATERAL,
ZoneType.FETETRAHEDRON,
ZoneType.FEBRICK,
})
# Zone types whose connectivity is face-based
_FE_POLY: frozenset[ZoneType] = frozenset({
ZoneType.FEPOLYGON,
ZoneType.FEPOLYHEDRON,
})
# Nodes per element for each supported simple FE type
_NODES_PER_ELEM: dict[ZoneType, int] = {
ZoneType.FELINESEG: 2,
ZoneType.FETRIANGLE: 3,
ZoneType.FEQUADRILATERAL: 4,
ZoneType.FETETRAHEDRON: 4,
ZoneType.FEBRICK: 8,
}
# ASCII keyword to ZoneType
_STR_TO_ZONETYPE: dict[str, ZoneType] = {
"ordered": ZoneType.ORDERED,
"felineseg": ZoneType.FELINESEG,
"fetriangle": ZoneType.FETRIANGLE,
"fequadrilateral": ZoneType.FEQUADRILATERAL,
"fetetrahedron": ZoneType.FETETRAHEDRON,
"febrick": ZoneType.FEBRICK,
"fepolygon": ZoneType.FEPOLYGON,
"fepolyhedron": ZoneType.FEPOLYHEDRON,
}
# ASCII keyword to FileType
_STR_TO_FILETYPE: dict[str, FileType] = {
"full": FileType.FULL,
"grid": FileType.GRID,
"solution": FileType.SOLUTION,
}
# ZoneType ASCII keyword
_ZONETYPE_STR: dict[ZoneType, str] = {
ZoneType.ORDERED: "Ordered",
ZoneType.FELINESEG: "FELineSeg",
ZoneType.FETRIANGLE: "FETriangle",
ZoneType.FEQUADRILATERAL: "FEQuadrilateral",
ZoneType.FETETRAHEDRON: "FETetrahedron",
ZoneType.FEBRICK: "FEBrick",
ZoneType.FEPOLYGON: "FEPolygon",
ZoneType.FEPOLYHEDRON: "FEPolyhedron",
}
# FileType to ASCII keyword
_FILETYPE_STR: dict[FileType, str] = {
FileType.GRID: "GRID",
FileType.SOLUTION: "SOLUTION",
}
# FaceNeighborMode to ASCII keyword
_FACENEIGHBORMODE_STR: dict[FaceNeighborMode, str] = {
FaceNeighborMode.LOCAL_ONE_TO_ONE: "LOCALONETOONE",
FaceNeighborMode.LOCAL_ONE_TO_MANY: "LOCALONETOMANY",
FaceNeighborMode.GLOBAL_ONE_TO_ONE: "GLOBALONETOONE",
FaceNeighborMode.GLOBAL_ONE_TO_MANY: "GLOBALONETOMANY",
}
# DataType to NumPy dtype string
_DT_TO_DTYPE: dict[DataType, str] = {
DataType.FLOAT: "f4",
DataType.DOUBLE: "f8",
DataType.INT32: "i4",
DataType.INT16: "i2",
DataType.BYTE: "u1",
}
# DataType to ASCII DT= keyword
_DATATYPE_STR: dict[DataType, str] = {
DataType.FLOAT: "SINGLE",
DataType.DOUBLE: "DOUBLE",
DataType.INT32: "LONGINT",
DataType.INT16: "SHORTINT",
DataType.BYTE: "BYTE",
}
# ASCII DT= keyword (and common aliases) to DataType, case-insensitive lookup
_STR_TO_DATATYPE: dict[str, DataType] = {
"single": DataType.FLOAT,
"float": DataType.FLOAT,
"double": DataType.DOUBLE,
"longint": DataType.INT32,
"shortint": DataType.INT16,
"byte": DataType.BYTE,
}
# Significant digits that guarantee a lossless round-trip for each floating precision
# (matches the IEEE 754 theoretical bounds)
_SIG_DIGITS_FOR_PRECISION: dict[DataType, int] = {
DataType.FLOAT: 9,
DataType.DOUBLE: 17,
}
# Values per line for Write data blocks
_VALUES_PER_LINE: int = 5
#: Indentation applied to every zone-header line after the first
_INDENT: str = " "
# Indentation applied to data and connectivity lines
_DATA_INDENT: str = _INDENT + " "
#: Separator written between adjacent values on a data line
_VALUE_SEP: str = " "
# =====================================================================================
# Helpers
# =====================================================================================
def _quote(s: str) -> str:
"""Wrap *s* in double-quotes, escaping embedded double-quotes.
Returns:
str: Stripped string.
"""
return '"' + str(s).replace('"', '\\"') + '"'
def _unquote(s: str) -> str:
r"""Remove surrounding double-quotes and unescape internal ``\\"``.
Returns:
str: String without the surrounding quotes.
"""
s = s.strip()
if len(s) >= 2 and s[0] == '"' and s[-1] == '"':
return s[1:-1].replace('\\"', '"')
return s
def _strip_comment(line: str) -> str:
"""Remove a Tecplot ``#`` comment and trailing whitespace.
Returns:
str: The line without the comment and trailing whitespace.
"""
idx = line.find("#")
return line[:idx].rstrip() if idx >= 0 else line.rstrip()
def _infer_data_type(arr: npt.NDArray) -> DataType:
"""Return the most appropriate :class:`DataType` for *arr*'s dtype."""
dtype = arr.dtype
if dtype.kind == "f":
return DataType.DOUBLE if dtype.itemsize >= 8 else DataType.FLOAT
if dtype.kind in ("i", "u"):
if dtype.itemsize >= 4:
return DataType.INT32
if dtype.itemsize == 2:
return DataType.INT16
return DataType.BYTE
return DataType.FLOAT
def _resolve_written_type(inferred: DataType, precision: DataType) -> DataType:
"""Return the :class:`DataType` actually written for one variable.
*precision* overrides *inferred* only when *inferred* is itself a floating-point
type (FLOAT or DOUBLE). Integer-inferred variables (INT32/INT16/BYTE) always keep
their own inferred type, unaffected by *precision*. A variable holding a meaningful
integer (a CPU number, an index, a count) should never be silently coerced by a
setting that's conceptually about floating-point precision.
"""
if inferred in (DataType.FLOAT, DataType.DOUBLE):
return precision
return inferred
def _make_float_fmt(sig_digits: int) -> str:
"""Return a ``format()``-compatible scientific-notation format string."""
return f" .{max(sig_digits - 1, 0)}e"
def _stage_float_array(buf: io.StringIO, arr: npt.NDArray, fmt: str) -> None:
"""Write a 1-D float array to *buf* in scientific notation.
Values are written ``_VALUES_PER_LINE`` per line, each line indented by
``_DATA_INDENT`` and the values separated by ``_VALUE_SEP`` so that columns align.
"""
flat = np.asarray(arr).ravel()
vpl = _VALUES_PER_LINE
for start in range(0, flat.size, vpl):
chunk = flat[start : start + vpl]
buf.write(
_DATA_INDENT + _VALUE_SEP.join(format(float(v), fmt) for v in chunk) + "\n"
)
def _stage_point_rows(
buf: io.StringIO,
cols: list[npt.NDArray],
fmt: str,
) -> None:
"""Write *cols* as ``DATAPACKING=POINT`` rows into *buf*.
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
*cols* is empty.
Example:
>>> _stage_point_rows(buf, [x_flat, y_flat, p_flat], ".8e")
"""
if not cols:
return
# Stack into a (n_points, n_vars) matrix then write row by row.
matrix = np.column_stack(cols) if len(cols) > 1 else cols[0].reshape(-1, 1)
for row in matrix:
buf.write(
_DATA_INDENT + _VALUE_SEP.join(format(float(v), fmt) for v in row) + "\n"
)
def _stage_connectivity_row(buf: io.StringIO, row: npt.NDArray) -> None:
"""Write one element's node indices to *buf* as space-separated ints."""
buf.write(_DATA_INDENT + " ".join(str(int(n)) for n in row) + "\n")
def _stage_int_block(
buf: io.StringIO, label: str, arr: npt.NDArray, per_line: int = 10
) -> None:
"""Write a flat integer array to *buf* under a ``# label`` comment line.
Tecplot writes the face-map sections of poly zones this way, ``per_line`` values
per line, and the reader skips the comment.
"""
buf.write(f"# {label}\n")
flat = arr.ravel()
for start in range(0, flat.size, per_line):
chunk = flat[start : start + per_line].tolist()
buf.write(_DATA_INDENT + " ".join(map(str, chunk)) + "\n")
# ======================================================================================
# TecplotDatWriter
# ======================================================================================
class TecplotDatWriter(TecplotWriter):
r"""Write Tecplot ASCII (``.dat``/``.tec``) files.
The public interface matches :class:`~tecio.TecplotSzlWriter` and
:class:`~tecio.TecplotPltWriter`.
Args:
path: Destination file path.
title: Dataset title. Defaults to ``"untitled"``.
variables: Variable name list. ``None`` defers file creation until the first
zone-writing call (lazy open).
file_type: :class:`~libtecio.FileType` enum. Defaults to
:attr:`~libtecio.FileType.FULL`.
precision: Uniform floating point precision for the whole file.
:attr:`DataType.FLOAT` (default; ``"single"``) or
:attr:`DataType.DOUBLE` (``"double"``). Also accepts those
strings directly (``"single"``/``"double"``, or ``"float"`` for
the enum's own name). Applies only to floating-point variables: a
``float64`` array is downcast to ``SINGLE`` under the default, but
integer variables (LONGINT/SHORTINT/BYTE) always keep their own
inferred type in the zone's ``DT=`` declaration regardless of
*precision*. Also sets the significant digit count used for every
variable uniformly (9 for FLOAT, 17 for DOUBLE).
Attributes:
precision: Uniform floating-point precision for the file. Governs the
ASCII significant-digit count and which of FLOAT/DOUBLE is
declared for float-inferred variables; integer-inferred
variables keep their own type regardless (see *precision*
above).
_fp: The open text file handle, or ``None`` before the file has
been opened (or after :meth:`close`).
_opened: True once the file has been opened (eagerly or lazily) and
its header written, False before that and after
:meth:`close`.
_float_fmt: ``format()``-compatible scientific-notation format string
derived from *precision* (9 significant digits for FLOAT, 17
for DOUBLE), used to print every floating-point value in the
file.
"""
def __init__(
self,
path: str,
title: str = "untitled",
variables: list[str] | None = None,
file_type: FileType = FileType.FULL,
*,
precision: DataType | str = DataType.FLOAT,
) -> 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 these.
self.precision: DataType = cast(
DataType, normalize_precision(precision, allow_none=False)
)
self._fp: io.TextIOWrapper | None = None
self._opened: bool = False
self._float_fmt: str = _make_float_fmt(
_SIG_DIGITS_FOR_PRECISION[self.precision]
)
super().__init__(path, title, variables, file_type)
@property
def _file_format(self) -> str:
return "dat"
# -- Validation checks and errror handling -----------------------------------------
def _check_handle(self) -> io.TextIOWrapper:
"""Return the file handle, raising if the file has been closed.
Raises:
ValueError: If the file has been closed.
"""
if self._fp is None:
raise ValueError(f"I/O operation on closed file: '{self.path}'")
return self._fp
# -- File lifecycle ---------------------------------------------------------------
def _open(self, var_names: list[str]) -> None:
"""Open the output file and write the dataset header.
Raises:
ValueError: If ``var_names`` is empty.
"""
if not var_names:
raise ValueError("Write requires at least one variable name.")
self.variables = var_names
self._fp = open(self.path, "w", encoding="utf-8", newline="\n") # noqa: SIM115
self._write_file_header()
self._opened = True
self._meta.set_variables(self.variables)
[docs]
def close(self) -> None:
"""Flush and close the output 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); DAT's ``DATASETAUXDATA``/``VARAUXDATA`` keywords are valid
anywhere in the file, including after the last zone, so this is
always a legal position to write them.
"""
if self._fp is not None:
self.flush_aux()
self._fp.flush()
self._fp.close()
self._fp = None
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:
self._check_handle().write(f"DATASETAUXDATA {name}={_quote(value)}\n")
def _write_var_aux_item(
self, one_based_var_index: int, name: str, value: str
) -> None:
self._check_handle().write(
f"VARAUXDATA {one_based_var_index} {name}={_quote(value)}\n"
)
# -- 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.
Zone dimensions are inferred from the shape of the first NODAL array.
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:
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.
"""
if isinstance(datapacking, str):
try:
datapacking = DataPacking[datapacking.upper()]
except KeyError:
raise ValueError(
f"datapacking={datapacking!r} is not supported; "
"use DataPacking.BLOCK, DataPacking.POINT, or their "
"string equivalents."
) from None
new_zone_index = self.current_zone + 1
if title is None:
title = f"IJK_Zone_{new_zone_index}"
if variables is None:
variables = [f"V{i}" for i in range(1, len(data) + 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()
# Convert input data to NumPy arrays
arrays: list[npt.NDArray] = [np.asarray(arr) for arr in data]
variable_types = [
_resolve_written_type(_infer_data_type(arr), self.precision)
for arr in arrays
]
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,
on_error=self._handle_zone_error,
)
if prepared is None:
return
passive_flags = prepared.passive_vars
share_idx = prepared.var_sharing
imax, jmax, kmax = prepared.imax, prepared.jmax, prepared.kmax
value_locations_global = prepared.value_locations_global
variable_types_global = prepared.variable_types_global
buf = io.StringIO()
self._stage_zone_header(
buf,
title,
ZoneType.ORDERED,
imax=imax,
jmax=jmax,
kmax=kmax,
solution_time=solution_time,
strand_id=strand_id,
passive_vars=passive_flags,
var_sharing=share_idx,
value_locations_global=value_locations_global,
variable_types_global=variable_types_global,
aux=aux,
datapacking=datapacking,
)
if datapacking == DataPacking.POINT:
# Nodal section: one row per node, all nodal vars per row.
nodal_cols = [
np.asarray(arr, dtype=_DT_TO_DTYPE[dt]).ravel(order="F")
for arr, dt, loc in zip(
data, variable_types, value_locations, strict=True
)
if loc == ValueLocation.NODAL
]
_stage_point_rows(buf, nodal_cols, self._float_fmt)
# Cell-centred section: one row per cell, all CC vars per row.
cc_cols = [
np.asarray(arr, dtype=_DT_TO_DTYPE[dt]).ravel(order="F")
for arr, dt, loc in zip(
data, variable_types, value_locations, strict=True
)
if loc == ValueLocation.CELL_CENTERED
]
_stage_point_rows(buf, cc_cols, self._float_fmt)
else:
for arr, dt in zip(data, variable_types, strict=False):
cast = np.asarray(arr, dtype=_DT_TO_DTYPE[dt]).ravel(order="F")
_stage_float_array(buf, cast, self._float_fmt)
self._check_handle().write(buf.getvalue())
self.current_zone = new_zone_index
# 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,
face_neighbors_complete: bool | 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*.
Warning:
``FEPOLYGON`` and ``FEPOLYHEDRON`` are face-based and raise
:exc:`ValueError`, 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.
face_neighbors_complete (bool):
Whether ``face_neighbors`` is the entire adjacency picture (``True``),
Tecplot shouldn't auto-detect anything further, or a supplement to
auto-detected conformal adjacency (``False``). ``None`` (the default)
omits the ``FEFACENEIGHBORSCOMPLETE`` keyword entirely, deferring to the
Tecplot default. ASCII-only: neither the classic nor new C API can
express this, so it has no equivalent on
:class:`~tecio.TecplotSzlWriter` or :class:`~tecio.TecplotPltWriter`.
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:
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.
"""
if isinstance(datapacking, str):
try:
datapacking = DataPacking[datapacking.upper()]
except KeyError:
raise ValueError(
f"datapacking={datapacking!r} is not supported; "
"use DataPacking.BLOCK, DataPacking.POINT, or their "
"string equivalents."
) from None
if zone_type in _FE_POLY:
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!r} is not supported by write_fe_zone."
)
new_zone_index = self.current_zone + 1
if title is None:
title = f"FE_Zone_{new_zone_index}"
if variables is None:
variables = [f"V{i}" for i in range(1, len(data) + 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 = [
_resolve_written_type(_infer_data_type(np.asarray(arr)), self.precision)
for arr in data
]
# Convert input data to NumPy arrays
arrays: list[npt.NDArray] = [np.asarray(arr) for arr in data]
if value_locations is None:
value_locations = [ValueLocation.NODAL] * len(data)
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,
on_error=self._handle_zone_error,
)
if prepared is None:
return
passive_flags = prepared.passive_vars
share_idx = prepared.var_sharing
con_sharing = prepared.con_sharing
num_nodes = prepared.num_nodes
num_cells = prepared.num_cells
value_locations_global = prepared.value_locations_global
variable_types_global = prepared.variable_types_global
# DAT writes face-neighbor rows via the same int-index-based
# walk/reshape as node_map (see below), so the dtype cast (not
# forced by the shared preparation step, which leaves it to each
# format) happens here, matching what DAT always used before.
face_neighbors_arr: npt.NDArray | None = None
if prepared.face_neighbors_arr is not None:
face_neighbors_arr = prepared.face_neighbors_arr.astype(np.intp)
face_neighbor_mode = prepared.face_neighbor_mode
num_face_connections = prepared.num_face_connections
buf = io.StringIO()
self._stage_zone_header(
buf,
title,
zone_type,
num_nodes=num_nodes,
num_elements=num_cells,
solution_time=solution_time,
strand_id=strand_id,
passive_vars=passive_flags,
var_sharing=share_idx,
value_locations_global=value_locations_global,
variable_types_global=variable_types_global,
con_sharing=con_sharing,
aux=aux,
datapacking=datapacking,
num_face_connections=num_face_connections,
face_neighbor_mode=face_neighbor_mode or FaceNeighborMode.LOCAL_ONE_TO_ONE,
face_neighbors_complete=face_neighbors_complete,
)
if datapacking == DataPacking.POINT:
# Nodal section: one row per node, all nodal vars per row.
nodal_cols = [
np.asarray(arr, dtype=_DT_TO_DTYPE[dt]).ravel()
for arr, dt, loc in zip(
data, variable_types, value_locations, strict=True
)
if loc == ValueLocation.NODAL
]
_stage_point_rows(buf, nodal_cols, self._float_fmt)
# Cell-centred section: one row per cell, all CC vars per row.
cc_cols = [
np.asarray(arr, dtype=_DT_TO_DTYPE[dt]).ravel()
for arr, dt, loc in zip(
data, variable_types, value_locations, strict=True
)
if loc == ValueLocation.CELL_CENTERED
]
_stage_point_rows(buf, cc_cols, self._float_fmt)
else:
for arr, dt in zip(data, variable_types, strict=False):
cast = np.asarray(arr, dtype=_DT_TO_DTYPE[dt]).ravel()
_stage_float_array(buf, cast, self._float_fmt)
# Write connectivity (if not shared). Node numbers are 0-based in Python;
# ASCII text always uses 1-based node numbers.
if con_sharing is None:
assert node_map is not None
conn = (
np.asarray(node_map, dtype=np.intp).reshape(
num_cells, _NODES_PER_ELEM[zone_type]
)
+ 1
)
for row in conn:
_stage_connectivity_row(buf, row)
# Write face-neighbor connections (if provided). Cell and remote-zone
# references are 0-based in Python; ASCII text is always fully 1-based.
if face_neighbors_arr is not None:
assert face_neighbor_mode is not None # narrowed above
flat = convert_face_connections_to_one_based(
face_neighbors_arr, face_neighbor_mode
)
one_to_one = (
FaceNeighborMode.LOCAL_ONE_TO_ONE,
FaceNeighborMode.GLOBAL_ONE_TO_ONE,
)
if face_neighbor_mode in one_to_one:
values_per = (
3 if face_neighbor_mode is FaceNeighborMode.LOCAL_ONE_TO_ONE else 4
)
for row in flat.reshape(num_face_connections, values_per):
_stage_connectivity_row(buf, row)
else:
# "Many" modes: ragged, each record's own 4th value (nz)
# gives the count of additional neighbor references that
# follow it, matching the reader's own walk exactly.
is_global = face_neighbor_mode is FaceNeighborMode.GLOBAL_ONE_TO_MANY
i = 0
for _ in range(num_face_connections):
nz = int(flat[i + 3])
record_len = 4 + (2 * nz if is_global else nz)
_stage_connectivity_row(buf, flat[i : i + record_len])
i += record_len
self._check_handle().write(buf.getvalue())
self.current_zone = new_zone_index
# 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_connections 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: DAT 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 DAT 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 in
Python and shifted to the 1-based ASCII convention here (0 for no element,
``-k`` for the k-th boundary face).
The face map follows the variable blocks as integer sections introduced by the
same ``#`` comment lines Tecplot writes: ``# node count per face`` (polyhedra
only), ``# face nodes``, ``# left elements``, ``# right elements``, and with
boundary connections ``# boundary connection counts``, ``# boundary connection
elements``, and ``# boundary connection zones``. Nothing is written for a zone
that shares connectivity.
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`. Tecplot refuses ``POINT``
for poly zones, whether or not they have cell-centered variables.
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 supported; "
"use DataPacking.BLOCK or its string equivalent."
) from None
if datapacking != DataPacking.BLOCK:
raise ValueError(
"Polygon and polyhedron zones must use BLOCK data packing."
)
new_zone_index = self.current_zone + 1
if title is None:
title = f"Poly_Zone_{new_zone_index}"
if variables is None:
variables = [f"V{i}" for i in range(1, len(data) + 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()
arrays: list[npt.NDArray] = [np.asarray(arr) for arr in data]
variable_types = [
_resolve_written_type(_infer_data_type(arr), self.precision)
for arr in 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,
on_error=self._handle_zone_error,
)
if prepared is None:
return
conn = prepared.connectivity
buf = io.StringIO()
self._stage_zone_header(
buf,
title,
zone_type,
num_nodes=conn.num_nodes,
num_elements=conn.num_cells,
solution_time=solution_time,
strand_id=strand_id,
passive_vars=prepared.passive_vars,
var_sharing=prepared.var_sharing,
value_locations_global=prepared.value_locations_global,
variable_types_global=prepared.variable_types_global,
con_sharing=prepared.con_sharing,
aux=aux,
datapacking=datapacking,
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,
)
for arr, dt in zip(arrays, variable_types, strict=True):
_stage_float_array(
buf, arr.astype(_DT_TO_DTYPE[dt], copy=False), self._float_fmt
)
# Face map (if not shared). ASCII is the 0-based API convention plus one for
# every array: 0 for no element and -k for the k-th boundary face.
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
)
if zone_type is ZoneType.FEPOLYHEDRON:
assert conn.face_node_counts is not None
_stage_int_block(buf, "node count per face", conn.face_node_counts)
_stage_int_block(buf, "face nodes", conn.face_nodes.astype(np.int64) + 1)
_stage_int_block(
buf, "left elements", conn.face_left_elements.astype(np.int64) + 1
)
_stage_int_block(
buf, "right elements", conn.face_right_elements.astype(np.int64) + 1
)
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
_stage_int_block(
buf, "boundary connection counts", conn.boundary_connection_counts
)
_stage_int_block(
buf,
"boundary connection elements",
conn.boundary_connection_elements.astype(np.int64) + 1,
)
_stage_int_block(
buf,
"boundary connection zones",
conn.boundary_connection_zones.astype(np.int64) + 1,
)
self._check_handle().write(buf.getvalue())
self.current_zone = new_zone_index
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(prepared.var_sharing),
data_types=tuple(prepared.variable_types_global),
)
)
# -- Private helpers --------------------------------------------------------------
def _handle_zone_error(self) -> None:
"""Delete the output file if no zone has been committed yet."""
if self.current_zone == -1:
if self._fp is not None:
self._fp.close()
self._fp = None
self._opened = False
with contextlib.suppress(OSError):
os.remove(self.path)
def _write_file_header(self) -> None:
"""Write TITLE, optional FILETYPE, and VARIABLES lines."""
fp = self._check_handle()
fp.write(f"TITLE = {_quote(self.title)}\n")
if self.file_type in _FILETYPE_STR:
fp.write(f"FILETYPE = {_FILETYPE_STR[self.file_type]}\n")
var_lines = "\n".join(_quote(v) for v in self._check_variables())
fp.write(f"VARIABLES = {var_lines}\n")
def _stage_zone_header(
self,
buf: io.StringIO,
title: str,
zone_type: ZoneType,
imax: int = 0,
jmax: int = 0,
kmax: int = 0,
num_nodes: int = 0,
num_elements: int = 0,
solution_time: float = 0.0,
strand_id: int = 0,
passive_vars: Sequence[bool | int] | None = None,
var_sharing: Sequence[int | None] | None = None,
value_locations_global: list[ValueLocation] | None = None,
variable_types_global: list[DataType] | None = None,
con_sharing: int | None = None,
aux: dict[str, Any] | None = None,
datapacking: DataPacking = DataPacking.BLOCK,
num_face_connections: int = 0,
face_neighbor_mode: FaceNeighborMode = FaceNeighborMode.LOCAL_ONE_TO_ONE,
face_neighbors_complete: bool | None = None,
num_faces: int = 0,
total_face_nodes: int = 0,
num_boundary_faces: int = 0,
num_boundary_connections: int = 0,
) -> None:
"""Write a ``ZONE`` header block into the staging buffer *buf*."""
zt_str = _ZONETYPE_STR[zone_type]
# First line is never indented; every subsequent header line is indented.
buf.write(f"ZONE T={_quote(title)}\n")
buf.write(
f"{_INDENT}STRANDID={strand_id}, SOLUTIONTIME={float(solution_time)}\n"
)
if zone_type == ZoneType.ORDERED:
buf.write(f"{_INDENT}I={imax}, J={jmax}, K={kmax}, ZONETYPE={zt_str}\n")
elif zone_type in _FE_POLY:
buf.write(
f"{_INDENT}Nodes={num_nodes}, Faces={num_faces}, "
f"Elements={num_elements}, ZONETYPE={zt_str}\n"
)
else:
buf.write(
f"{_INDENT}Nodes={num_nodes}, Elements={num_elements}, "
f"ZONETYPE={zt_str}\n"
)
buf.write(f"{_INDENT}DATAPACKING={datapacking.name}\n")
if zone_type in _FE_POLY:
# A polygon face always has 2 nodes, so only polyhedra record the total.
face_nodes_str = (
f"TotalNumFaceNodes={total_face_nodes}, "
if zone_type is ZoneType.FEPOLYHEDRON
else ""
)
buf.write(
f"{_INDENT}{face_nodes_str}"
f"NumConnectedBoundaryFaces={num_boundary_faces}, "
f"TotalNumBoundaryConnections={num_boundary_connections}\n"
)
if num_face_connections > 0:
buf.write(f"{_INDENT}FACENEIGHBORCONNECTIONS={num_face_connections}\n")
buf.write(
f"{_INDENT}FACENEIGHBORMODE="
f"{_FACENEIGHBORMODE_STR[face_neighbor_mode]}\n"
)
if face_neighbors_complete is not None:
complete_str = "YES" if face_neighbors_complete else "NO"
buf.write(f"{_INDENT}FEFACENEIGHBORSCOMPLETE={complete_str}\n")
if variable_types_global:
dt_str = " ".join(_DATATYPE_STR[dt] for dt in variable_types_global)
buf.write(f"{_INDENT}DT=({dt_str})\n")
if value_locations_global:
cc = [
i + 1
for i, loc in enumerate(value_locations_global)
if loc == ValueLocation.CELL_CENTERED
]
if cc:
buf.write(
f"{_INDENT}VARLOCATION=([{','.join(str(i) for i in cc)}]"
"=CELLCENTERED)\n"
)
if passive_vars:
pidx = [str(i + 1) for i, f in enumerate(passive_vars) if f]
if pidx:
buf.write(f"{_INDENT}PASSIVEVARLIST=[{','.join(pidx)}]\n")
if var_sharing and any(z is not None for z in var_sharing):
entries = [
f"[{i + 1}]={z + 1}" for i, z in enumerate(var_sharing) if z is not None
]
if entries:
buf.write(f"{_INDENT}VARSHARELIST=({','.join(entries)})\n")
if con_sharing is not None:
buf.write(f"{_INDENT}CONNECTIVITYSHAREZONE={con_sharing + 1}\n")
if aux:
for name, value in aux.items():
buf.write(f"{_INDENT}AUXDATA {name}={_quote(value)}\n")