"""Write Tecplot SZL (``.szplt``) files via the TecIO C library.
Supports lazy-open (deferred until first zone write), buffered auxiliary
data, and automatic dtype inference from NumPy arrays.
"""
from __future__ import annotations
import ctypes
from collections.abc import Sequence
from typing import Any
import numpy as np
import numpy.typing as npt
from . import libtecio
from ._constants import (
DataPacking,
DataType,
FaceNeighborMode,
FeCellShape,
FileType,
ValueLocation,
ZoneType,
)
from ._meta import ZoneMeta
from ._writer import (
PassiveVarsSpec,
PreparedFEMixedZone,
PreparedFEZone,
PreparedOrderedZone,
TecplotWriter,
VarSharingSpec,
normalize_precision,
prepare_fe_zone,
prepare_femixed_zone,
prepare_ordered_zone,
var_sharing_for_libtecio,
zone_for_libtecio,
)
# --------------------------------------------------------------------------------------
# Module-level constants
# --------------------------------------------------------------------------------------
# FE zone types that use tec_zone_create_fe
_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 the closest C-supported DataType for a DataType or NumPy dtype.
Raises:
ValueError: If the dtype is not supported.
"""
# Mapping of NumPy type categories to closest DataType
closest_dtype_map = {
np.dtype(np.float64): DataType.DOUBLE,
np.dtype(np.float32): DataType.FLOAT,
np.dtype(np.float16): DataType.FLOAT, # promote half → float
np.dtype(np.int64): DataType.INT32, # promote 64-bit → INT32
np.dtype(np.int32): DataType.INT32,
np.dtype(np.int16): DataType.INT16,
np.dtype(np.int8): DataType.BYTE, # small ints → BYTE
np.dtype(np.uint8): DataType.BYTE,
}
if isinstance(dt, DataType):
return dt
dt_np = np.dtype(dt)
for key in closest_dtype_map:
if dt_np == key:
return closest_dtype_map[key]
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}")
# ASCII/enum-name aliases for the two precision options
_STR_TO_PRECISION: dict[str, DataType] = {
"single": DataType.FLOAT,
"float": DataType.FLOAT,
"double": DataType.DOUBLE,
}
def _resolve_written_type(inferred: DataType, precision: DataType | None) -> 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 precision is None:
return inferred
if inferred in (DataType.FLOAT, DataType.DOUBLE):
return precision
return inferred
# ======================================================================================
# Local functions
# ======================================================================================
def _write_data(
handle: ctypes.c_void_p,
zone_num: int,
var_num: int,
data: npt.ArrayLike,
dt: np.dtype | DataType | None = None,
) -> None:
"""Write a single variable's data array to an SZL file.
Infers the data type from the array dtype and dispatches to the
appropriate C write function. Arrays are ravelled in Fortran order.
Args:
handle (ctypes.c_void_p): C library file handle.
zone_num (int): 1-based zone index.
var_num (int): 1-based variable index.
data (npt.ArrayLike): Array of values to write.
dt (np.dtype | DataType | None): Optional explicit data type override.
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)
Raises:
ValueError: If the resolved data type is not supported.
"""
# 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,
}
datatype_to_dtype: dict[DataType, np.dtype] = {
DataType.DOUBLE: np.dtype(np.float64),
DataType.FLOAT: np.dtype(np.float32),
DataType.INT32: np.dtype(np.int32),
DataType.INT16: np.dtype(np.int16),
DataType.BYTE: np.dtype(np.uint8),
}
if dt is not None:
data_type = _infer_data_type(dt)
arr = np.ascontiguousarray(data, dtype=datatype_to_dtype[data_type]).ravel(
order="F"
)
else:
arr = np.ascontiguousarray(data).ravel(order="F")
data_type = dtype_to_datatype[arr.dtype]
if data_type == DataType.DOUBLE:
libtecio.tec_zone_var_write_double_values(handle, zone_num, var_num, arr)
elif data_type == DataType.FLOAT:
libtecio.tec_zone_var_write_float_values(handle, zone_num, var_num, arr)
elif data_type == DataType.INT32:
libtecio.tec_zone_var_write_int32_values(handle, zone_num, var_num, arr)
elif data_type == DataType.INT16:
libtecio.tec_zone_var_write_int16_values(handle, zone_num, var_num, arr)
elif data_type == DataType.BYTE:
libtecio.tec_zone_var_write_uint8_values(handle, zone_num, var_num, arr)
else:
raise ValueError(f"Unsupported DataType: {data_type!r}")
def _write_connectivity(
handle: ctypes.c_void_p,
zone_num: int,
node_map: npt.ArrayLike,
face_neighbors: npt.ArrayLike | None = None,
) -> None:
"""Write FE zone connectivity: node map and optional face-neighbor connections.
Integer width (32 or 64 bit) is chosen automatically from the maximum index value in
each array.
Args:
handle (ctypes.c_void_p): C library file handle.
zone_num (int): 1-based zone index.
node_map (npt.ArrayLike): Connectivity array, 1-based node indices.
face_neighbors (npt.ArrayLike | None): Optional face-neighbor connection array.
Note:
Both arrays are written using the minimum integer width capable of representing
the maximum index value present in each array. No copy is made for C-contiguous
input arrays — ravel(order="C") returns a flat view of the node_map or
face_neighbors without making a copy
Note:
Node and face-neighbor integer widths are chosen independently based on the
maximum value in each respective array.
"""
# Node map
node_map_flat = np.ascontiguousarray(node_map).ravel(order="C")
if node_map_flat.max() > np.iinfo(np.int32).max:
libtecio.tec_zone_node_map_write64(handle, zone_num, node_map_flat)
else:
libtecio.tec_zone_node_map_write32(handle, zone_num, node_map_flat)
# Face neighbors (optional)
if face_neighbors is not None:
face_nbr_flat = np.ascontiguousarray(face_neighbors).ravel(order="C")
if face_nbr_flat.max() > np.iinfo(np.int32).max:
libtecio.tec_zone_face_nbr_write_connections64(
handle, zone_num, face_nbr_flat
)
else:
libtecio.tec_zone_face_nbr_write_connections32(
handle, zone_num, face_nbr_flat
)
def _write_femixed_connectivity(
handle: ctypes.c_void_p,
zone_num: int,
node_maps: Sequence[npt.NDArray],
num_nodes: int,
) -> None:
"""Write the section node maps of a FEMIXED zone, in section order.
All sections of a zone share one integer width, 64 bit only when *num_nodes* does
not fit 32 bits. Each section is converted to 1-based indices of that width in a
single pass, so at most one section is copied at a time.
Args:
handle (ctypes.c_void_p): C library file handle.
zone_num (int): 1-based zone index.
node_maps (Sequence[npt.NDArray]): 0-based ``(num_cells, nodes_per_cell)`` array
of each section.
num_nodes (int): Zone node count.
"""
wide = num_nodes > np.iinfo(np.int32).max
dtype = np.int64 if wide else np.int32
write = (
libtecio.tec_zone_node_map_write64
if wide
else libtecio.tec_zone_node_map_write32
)
for node_map in node_maps:
if node_map.size:
one_based = np.add(node_map, 1, dtype=dtype, casting="unsafe")
write(handle, zone_num, one_based.ravel(order="C"))
def _write_zone_aux_data(
handle: ctypes.c_void_p, aux: dict[int, dict[str, Any]]
) -> None:
"""Write zone-level auxiliary data.
Args:
handle (ctypes.c_void_p): C library file handle.
aux (dict[int, dict[str, Any]]): Mapping of
``{zone_index: {name: value}}``.
Note:
Aux data should be structured as {zone_idx: {name, value}}
"""
for zone_idx, subdict in aux.items():
for name, value in subdict.items():
libtecio.tec_zone_add_aux_data(handle, zone_idx, str(name), str(value))
def _write_variable_aux_data(
handle: ctypes.c_void_p, aux: dict[int, dict[str, Any]]
) -> None:
"""Write variable-level auxiliary data.
Args:
handle (ctypes.c_void_p): C library file handle.
aux (dict[int, dict[str, Any]]): Mapping of ``{var_index: {name: value}}``.
Hint:
Aux data should be structured as ``{var_idx: {name, value}}``
"""
for var_idx, subdict in aux.items():
for name, value in subdict.items():
libtecio.tec_var_add_aux_data(handle, var_idx, str(name), str(value))
def _write_dataset_aux_data(handle: ctypes.c_void_p, aux: dict[str, Any]) -> None:
"""Write dataset-level auxiliary data.
Args:
handle (ctypes.c_void_p): C library file handle.
aux (dict[str, Any]): Mapping of ``{name: value}``.
Hint:
Aux data should be structured as ``{var_idx: {name, value}}``
"""
for name, value in aux.items():
libtecio.tec_data_set_add_aux_data(handle, str(name), str(value))
def _write_aux_data(handle: ctypes.c_void_p, aux: dict[str, dict[Any, Any]]) -> None:
"""Write a combined auxiliary data dictionary to the file.
Args:
handle (ctypes.c_void_p): C library file handle.
aux (dict[str, dict[Any]]): Dict with keys ``"AUXDATA"``, ``"AUXVAR"``,
``"AUXZONE"``, each containing the appropriate nested structure.
Example:
{
"AUXDATASET":
{name1: value1}
{name2: value2}
"AUXVAR": {
1:
{name1: value1}
2:
{name1: value1}
},
"AUXZONE": {
1:
{name1: value1}
{name2: value2}
}
}
"""
for auxtype, auxdict in aux.items():
if auxtype.lower() == "auxdata":
for name, value in auxdict.items():
libtecio.tec_data_set_add_aux_data(handle, str(name), str(value))
elif auxtype.lower() == "auxvar":
for var, subdict in auxdict.items():
for name, value in subdict.items():
libtecio.tec_var_add_aux_data(handle, var, name, value)
elif auxtype.lower() == "auxzone":
for zone, subdict in auxdict.items():
for name, value in subdict.items():
libtecio.tec_zone_add_aux_data(handle, zone, name, value)
# ======================================================================================
# ======================================================================================
# TecplotSzlWriter
# ======================================================================================
class TecplotSzlWriter(TecplotWriter):
"""Write Tecplot SZL (``.szplt``) files with a lazy-open file handle.
Supports lazy-open: if *variables* is ``None`` at construction, the file is created
on the first zone write. Auxiliary data is buffered and flushed automatically before
the first zone.
The tecio library requires a list of variables when the output file is
opened. However if writing data on the fly, it may be beneficial to store file
outputs until the first zone is passed to the writer. Then file header will be
garanteed to be consistent with the first zone variables.
For the SZL API, file contents can be written out of order after creating zones.
Args:
path: Output file path.
title: Dataset title.
variables: Variable name list. ``None`` defers file creation.
file_type: File type enum (FULL, GRID, or SOLUTION).
precision: Optional whole file floating point precision override
(:attr:`DataType.FLOAT`/``"single"`` or
:attr:`DataType.DOUBLE`/``"double"``). Defaults to ``None``: each
variable's type is inferred automatically from its own array's
dtype.
Attributes:
precision: Whole-file floating-point override, or ``None`` for automatic
per-variable inference.
handle: Raw C file handle from ``tec_file_writer_open``, or ``None``
before the file has been opened (or after :meth:`close`).
current_var: 0-based index of the variable most recently passed to a
libtecio write call. Set only while a zone's variable data is
being written, and only ever read by user code inspecting the
writer, not consumed internally; useful for diagnosing which
variable was in progress if a write fails partway through a
zone.
"""
def __init__(
self,
path: str,
title: str = "untitled",
variables: list[str] | None = None,
file_type: FileType = FileType.FULL,
*,
precision: DataType | str | None = None,
) -> None:
"""Store minimum necessary info until first zone is ready to write.
Raises:
ValueError: If *precision* is neither ``None`` nor
: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 | None = normalize_precision(
precision, allow_none=True
)
self.current_var = -1
self.handle: ctypes.c_void_p | None = None
super().__init__(path, title, variables, file_type)
@property
def _file_format(self) -> str:
return "szplt"
# -- Validation checks and errror handling -----------------------------------------
def _check_handle(self) -> ctypes.c_void_p:
"""Return file handle catching errors if the writer has already been closed.
This ensures the that each libtecio call will execute or raise an appropriate
RuntimeError.
Raises:
RuntimeError: If the writer has been closed.
"""
if self.handle is None:
raise RuntimeError(f"I/O operation on closed file: '{self.path}'")
else:
return self.handle
# -- File lifecycle ----------------------------------------------------------------
def _open(self, var_names: list[str]) -> None:
"""Open the file handle. Called exactly once on the first zone."""
self.variables = var_names
self.handle = libtecio.tec_file_writer_open(
filename=self.path,
variables=self.variables,
title=self.title,
file_type=self.file_type,
use_szl=1,
)
self._meta.set_variables(self.variables)
[docs]
def close(self) -> None:
"""Finalise and flush the file (safe to call more than once)."""
if self.handle is not None:
self.flush_aux()
libtecio.tec_file_writer_close(self.handle)
self.handle = None
# -- Aux data: only the per-item write differs from the shared base ----------------
def _write_dataset_aux_item(self, name: str, value: str) -> None:
libtecio.tec_data_set_add_aux_data(self._check_handle(), name, value)
def _write_var_aux_item(
self, one_based_var_index: int, name: str, value: str
) -> None:
libtecio.tec_var_add_aux_data(
self._check_handle(), 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,
flush: bool = False,
) -> None:
"""Write a complete IJK-ordered zone.
Dimensions are inferred from the first array's shape. Arrays may be 1-D, 2-D, or
3-D; missing trailing dimensions default to 1.
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`.
flush (bool):
If ``True``, flush this zone and all previous data to a temporary
intermediate file immediately after writing, releasing data from
memory. Defaults to ``False``. Useful when memory is a concern, but adds
the overhead of a disk write. Temporary files are merged back into the
final output file when :meth:`close` is called.
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 empty file handle, a variable is
named in both *passive_vars* and *var_sharing*, or *datapacking* is not a
recognised value.
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.
Note:
If the file is already open, ``data`` and ``variables`` may be omitted to
write a zone header only. If the file has not been opened yet, ``variables``
must be provided on this call.
Note:
Data arrays are written as DOUBLE precision by default. To write other
types, cast the NumPy arrays before calling (e.g.
``arr.astype(np.float32)``).
Note:
Separate grid files (where all variables are cell-centred) are not handled
automatically; use the low-level API for that case.
"""
# 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 SZL 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]
# Set default title if none provided
if title is None:
title = f"IJK_Zone_{self.current_zone + 1}"
# Set default variable names if none provided. Only relevant if file lazily
# loaded and first zone
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 self.handle is None:
self._open(variables)
if self.current_zone == -1:
self.flush_aux()
# Infer per-variable data types from array dtypes
variable_types = [
_resolve_written_type(_infer_data_type(arr.dtype), self.precision)
for arr in 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. The C library assigns and returns a 1-based zone
# number; converted to 0-based for the public current_zone attribute.
self.current_zone = (
libtecio.tec_zone_create_ijk(
self._check_handle(),
title,
imax,
jmax,
kmax,
var_types=variable_types_global,
value_locations=value_locations_global,
var_sharing=var_sharing_for_libtecio(share_idx),
pas_vars=passive_flags,
)
- 1
)
zone_num = self.current_zone + 1
# Unsteady options
if strand_id != 0 or solution_time != 0.0:
libtecio.tec_zone_set_unsteady_options(
handle=self._check_handle(),
zone=zone_num,
strand=strand_id,
solution_time=solution_time,
)
# Write aux data
if aux is not None:
_write_zone_aux_data(self._check_handle(), {zone_num: aux})
# Write active data only
for var_idx, arr, dtype in zip(
active_var_idx, arrays, variable_types, strict=True
):
self.current_var = var_idx
_write_data(
self._check_handle(),
zone_num=zone_num,
var_num=var_idx + 1,
data=arr,
dt=dtype,
)
# Flush zone data, releasing memory
if flush:
libtecio.tec_file_writer_flush(self._check_handle())
# 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,
flush: bool = False,
) -> 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 32- or 64-bit write path is
chosen automatically from the max index.
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`.
flush:
If ``True``, flush this zone and all previous data to a temporary
intermediate file immediately after writing, releasing data from
memory. Defaults to ``False``. Useful when memory is a concern, but adds
the overhead of a disk write. Temporary files are merged back into the
final output file when :meth:`close` is called.
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 (not supported in SZPLT files, see
: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.
Note:
FE variable arrays are 1-D and node-ordered. ``write_data`` handles dtype
inference and F-order ravel internally, but 1-D arrays are unaffected by
memory order.
"""
# 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 SZL 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 "
"(which SZPLT files do not support)."
)
if zone_type not in _FE_SIMPLE:
raise NotImplementedError(
f"Zone type {zone_type.name!r} is not supported by szl file formats."
)
# Convert input data to NumPy arrays
arrays: list[npt.NDArray] = [np.asarray(arr) for arr in data]
# Set default title if none provided
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(data) + 1)]
# Open the file if lazily loaded and flush buffered aux data
if self.handle is None:
self._open(variables)
if self.current_zone == -1:
self.flush_aux()
# Infer per-variable data types from array dtypes
variable_types = [
_resolve_written_type(_infer_data_type(arr.dtype), self.precision)
for arr in 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_neighbors_arr = prepared.face_neighbors_arr
face_neighbor_mode = prepared.face_neighbor_mode
num_face_cons = prepared.num_face_connections
if face_neighbors_arr is not None:
raise NotImplementedError(
"Writing face-neighbor connections to SZL (.szplt) output is not "
"currently supported. Face-neighbor writing works correctly for PLT "
"and DAT; use one of those formats if you need it."
)
# Write zone header. The C library assigns and returns a 1-based zone
# number; converted to 0-based for the public current_zone attribute.
self.current_zone = (
libtecio.tec_zone_create_fe(
self._check_handle(),
title,
zone_type,
num_nodes,
num_cells,
var_types=variable_types_global,
value_locations=value_locations_global,
pas_vars=passive_flags,
var_sharing=var_sharing_for_libtecio(share_idx),
con_sharing=zone_for_libtecio(con_sharing),
num_face_cons=num_face_cons,
face_nbr_mode=face_neighbor_mode or FaceNeighborMode.LOCAL_ONE_TO_ONE,
)
- 1
)
zone_num = self.current_zone + 1
# Unsteady options
if strand_id != 0 or solution_time != 0.0:
libtecio.tec_zone_set_unsteady_options(
handle=self._check_handle(),
zone=zone_num,
strand=strand_id,
solution_time=solution_time,
)
# Write zone-level aux data
if aux is not None:
_write_zone_aux_data(self._check_handle(), {zone_num: aux})
# Write active data only
for var_idx, arr, dtype in zip(
active_var_idx, arrays, variable_types, strict=True
):
self.current_var = var_idx
_write_data(
self._check_handle(),
zone_num=zone_num,
var_num=var_idx + 1,
data=arr,
dt=dtype,
)
# Write connectivity (if not shared). Node numbers are 0-based in
# Python; the C library expects 1-based node numbers.
if con_sharing is None:
assert node_map is not None
_write_connectivity(
self._check_handle(),
zone_num,
np.asarray(node_map) + 1,
face_neighbors_arr,
)
# Flush zone data, releasing memory
if flush:
libtecio.tec_file_writer_flush(self._check_handle())
# 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,
)
)
# -- FEMIXED zone writer -----------------------------------------------------------
[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,
flush: bool = False,
) -> None:
"""Write a complete FEMIXED (mixed finite-element) zone.
A FEMIXED zone holds 1 to 16 sections, each with one cell shape. A typical use
is a CFD volume mesh of tetrahedra, pyramids, prisms and hexahedra in one zone
rather than every cell padded to a brick. All sections must have the same
spatial dimension (all line, all surface or all volume cells). Cells are
numbered through the sections in order, so a CELL_CENTERED array lists the cells
of the first section first. Only linear (grid order 1) cells are supported.
Node and cell counts are inferred from *node_maps*, or from the zone referenced
by *con_sharing*. The 32- or 64-bit write path is chosen from the node count.
This writer does not write face-neighbor connections.
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 the total cell count over all sections.
cell_shapes (Sequence[FeCellShape]):
Cell shape of each section. A shape name or value is also accepted.
Required unless ``con_sharing`` is set, in which case it must be omitted.
node_maps (Sequence[npt.ArrayLike]):
One integer array per section, of shape ``(num_cells, nodes_per_cell)``
with 0-based node indices. A flat array is reshaped. A section may have
no cells. Required unless ``con_sharing`` is set, in which case it must
be omitted.
title (str):
Zone title string. Defaults to ``"FEMixed_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). 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):
Optional index of a FEMIXED zone to share the connectivity of. The first
zone in a dataset must own 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):
Only :attr:`~tecio.DataPacking.BLOCK` (the default) is supported.
flush:
If ``True``, flush this zone and all previous data to a temporary
intermediate file after writing, releasing data from memory.
Raises:
NotImplementedError:
If *datapacking* is :attr:`~tecio.DataPacking.POINT`.
ValueError:
On a bad section layout or array shape, sections of different spatial
dimension, fewer dataset variables than the cell dimension, a variable
count or array length mismatch, or a bad ``con_sharing`` or
``var_sharing`` source zone. See
:func:`~tecio._writer.prepare_femixed_zone`.
TypeError:
If *passive_vars*/*var_sharing* isn't a list/tuple/set/mapping as
appropriate, or mixes variable names and indices.
KeyError:
A *passive_vars*/*var_sharing* name doesn't match any dataset variable.
IndexError:
A *passive_vars*/*var_sharing* index is out of range.
RuntimeError:
If the writer has been closed.
Note:
SZPLT reorders cells and nodes internally for storage, so the arrays read
back may be a permutation of the arrays written, consistently across all
variables and the node maps.
"""
# 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 SZL binary format. Use DataPacking.BLOCK (the default) "
"or write to a .dat file instead."
)
arrays: list[npt.NDArray] = [np.asarray(arr) for arr in data]
if title is None:
title = f"FEMixed_Zone_{self.current_zone + 1}"
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 self.handle is None:
self._open(variables)
if self.current_zone == -1:
self.flush_aux()
variable_types = [
_resolve_written_type(_infer_data_type(arr.dtype), self.precision)
for arr in arrays
]
prepared: PreparedFEMixedZone | None = prepare_femixed_zone(
arrays,
variable_types,
cell_shapes=cell_shapes,
node_maps=node_maps,
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
share_idx = prepared.var_sharing
# Write zone header. The C library assigns and returns a 1-based zone
# number; converted to 0-based for the public current_zone attribute.
self.current_zone = (
libtecio.tec_zone_create_fe_mixed(
self._check_handle(),
title,
prepared.num_nodes,
prepared.section_shapes,
prepared.section_num_elements,
var_types=prepared.variable_types_global,
var_sharing=var_sharing_for_libtecio(share_idx),
value_locations=prepared.value_locations_global,
pas_vars=prepared.passive_vars,
con_sharing=zone_for_libtecio(prepared.con_sharing),
)
- 1
)
zone_num = self.current_zone + 1
# Unsteady options
if strand_id != 0 or solution_time != 0.0:
libtecio.tec_zone_set_unsteady_options(
handle=self._check_handle(),
zone=zone_num,
strand=strand_id,
solution_time=solution_time,
)
# Write zone-level aux data
if aux is not None:
_write_zone_aux_data(self._check_handle(), {zone_num: aux})
# Write active data only
for var_idx, arr, dtype in zip(
prepared.active_var_idx, arrays, variable_types, strict=True
):
self.current_var = var_idx
_write_data(
self._check_handle(),
zone_num=zone_num,
var_num=var_idx + 1,
data=arr,
dt=dtype,
)
# Write connectivity (if not shared)
if prepared.con_sharing is None:
_write_femixed_connectivity(
self._check_handle(),
zone_num,
prepared.section_node_maps,
prepared.num_nodes,
)
# Flush zone data, releasing memory
if flush:
libtecio.tec_file_writer_flush(self._check_handle())
# Finally set zone metadata after successfully completing TecIO calls
self._meta.record_zone(
ZoneMeta(
index=self.current_zone,
title=title,
zone_type=ZoneType.FEMIXED,
solution_time=solution_time,
strand_id=strand_id,
num_aux_items=len(aux) if aux else 0,
num_nodes=prepared.num_nodes,
num_elements=prepared.num_cells,
section_shapes=prepared.section_shapes,
section_num_elements=prepared.section_num_elements,
value_locations=tuple(prepared.value_locations_global),
passive_vars=tuple(bool(p) for p in prepared.passive_vars),
shared_vars=tuple(share_idx),
data_types=tuple(prepared.variable_types_global),
)
)
[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:
"""Not supported: SZPLT files cannot hold polygon or polyhedron zones.
Raises:
NotImplementedError: Always. Write to a ``.plt`` or ``.dat`` file instead,
see :meth:`TecplotPltWriter.write_poly_zone`.
"""
raise NotImplementedError(
"Polygon and polyhedron zones are not yet supported in SZPLT files by the "
"TecIO library. Write a .plt or .dat file instead."
)