Source code for tecio.libtecio

"""Python bindings for the TecIO C library.

Ctypes bindings for both the new SZL API (``tec_*``) and the classic PLT API
(``tec*142``), and a Python wrapper function for each C entry point.  The TecIO library
often uses integers with special meanings (zone types, data types, data locations). The
same values are used both for writing and for SZL reading and writing. Enum classes with
descriptive names are defined in :mod:`tecio._constants` and imported here.

Notes:
    - The ctypes bindings are defined conditionall if the symbol exists in the loaded
      TecIO shared object binary such that older versions not containing newer (often
      niche) functions such as :func:`~tecio.libtecio.tecznefemixed142` do not cause the
      entire `tecio` Python package to fail to load.
    - Only loading the available symbols also allows for the `tecio` Python package to
      be used without any TecIO shared object binary available as it is only needed for
      SZL read/write and PLT write. DAT read/write and PLT read have pure Python
      implementations and do not have external dependencies other than NumPy.
    - The load/bind/guard mechanism is defined in :mod:`tecio._utils`
    - After binding, a one-line summary is emitted via :mod:`warnings` (category
      :class:`TecioAvailabilityWarning`) if anything is disabled and is available as
      data via :data:`LIBRARY_LOAD_ERROR` and :data:`UNAVAILABLE_FUNCTIONS`.
"""

from __future__ import annotations

import ctypes
import functools
import warnings
from collections.abc import Sequence
from enum import Enum
from typing import Any

import numpy as np
import numpy.typing as npt

from . import _utils
from ._constants import (
    Boolean,
    DataPacking,
    DataType,
    Debug,
    FaceNeighborMode,
    FeCellShape,
    FileFormat,
    FileType,
    ValueLocation,
    VarStatus,
    ZoneType,
)

__all__ = [
    "TecioError",
    "TecioUnavailableError",
    "TecioAvailabilityWarning",
    "LIBRARY_LOAD_ERROR",
    "LIBRARY_PATH",
    "UNAVAILABLE_FUNCTIONS",
    "tec_file_reader_open",
    "tec_file_reader_close",
    "tec_file_get_type",
    "tec_data_set_get_title",
    "tec_data_set_get_num_vars",
    "tec_data_set_get_num_zones",
    "tec_zone_get_ijk",
    "tec_zone_get_title",
    "tec_zone_get_type",
    "tec_zone_get_num_sections",
    "tec_zone_get_section_metrics",
    "tec_zone_is_enabled",
    "tec_zone_get_solution_time",
    "tec_zone_get_strand_id",
    "is_64bit",
    "tec_zone_node_map_get_64",
    "tec_zone_node_map_get",
    "tec_zone_node_map_get_flat",
    "tec_zone_face_nbr_get_mode",
    "tec_zone_face_nbr_get_num_connections",
    "tec_zone_face_nbr_get_num_values",
    "tec_zone_face_nbrs_are_64bit",
    "tec_zone_face_nbr_get_connections",
    "tec_zone_face_nbr_get_connections_64",
    "tec_var_get_name",
    "tec_var_is_enabled",
    "tec_zone_var_get_type",
    "tec_zone_var_get_value_location",
    "tec_zone_var_is_passive",
    "tec_zone_var_get_shared_zone",
    "tec_zone_connectivity_get_shared_zone",
    "tec_zone_var_get_num_values",
    "tec_zone_var_get_float_values",
    "tec_zone_var_get_double_values",
    "tec_zone_var_get_int32_values",
    "tec_zone_var_get_int16_values",
    "tec_zone_var_get_uint8_values",
    "tec_data_set_aux_data_get_num_items",
    "tec_data_set_aux_data_get_item",
    "tec_var_aux_data_get_num_items",
    "tec_var_aux_data_get_item",
    "tec_zone_aux_data_get_num_items",
    "tec_zone_aux_data_get_item",
    "tec_file_writer_open",
    "tec_file_writer_close",
    "tec_file_writer_flush",
    "tec_zone_create_ijk",
    "tec_zone_create_fe",
    "tec_zone_create_fe_mixed",
    "tec_zone_set_unsteady_options",
    "tec_data_set_add_aux_data",
    "tec_var_add_aux_data",
    "tec_zone_add_aux_data",
    "tec_zone_var_write_double_values",
    "tec_zone_var_write_float_values",
    "tec_zone_var_write_int32_values",
    "tec_zone_var_write_int16_values",
    "tec_zone_var_write_uint8_values",
    "tec_zone_node_map_write32",
    "tec_zone_node_map_write64",
    "tec_zone_face_nbr_write_connections32",
    "tec_zone_face_nbr_write_connections64",
    "tecini142",
    "tecend142",
    "tecflush142",
    "tecfil142",
    "tecforeign142",
    "teczne142",
    "tecpolyzne142",
    "tecznefemixed142",
    "tecdat142",
    "tecnode142",
    "tecface142",
    "tecpolyface142",
    "tecpolybconn142",
    "tecauxstr142",
    "tecvauxstr142",
    "teczauxstr142",
    "tecusr142",
]


# ======================================================================================
# Error classes
# ======================================================================================


[docs] class TecioError(RuntimeError): """Exception for TecIO C library errors."""
[docs] class TecioUnavailableError(TecioError): """Raised when calling a function whose C symbol is unavailable. Either because no TecIO shared library could be located at all, or because the library that was found doesn't export this particular symbol (typically an older Tecplot version, predating that entry point). """
[docs] class TecioAvailabilityWarning(UserWarning): """Emitted once at import time if any C function could not be bound."""
_lib, _load_error, _library_path = _utils.load_library() lib = _lib # Exception raised while trying to locate/load the shared library, or None # if it loaded successfully LIBRARY_LOAD_ERROR: Exception | None = _load_error # Path to the shared library that was loaded, or None if none could be # located/loaded (see :data:`LIBRARY_LOAD_ERROR`). LIBRARY_PATH: str | None = _library_path # C function names (e.g. ``"tecFileReaderOpen"``) whose symbol could not be # bound, either because no library loaded at all or because the loaded # library doesn't export them UNAVAILABLE_FUNCTIONS: set[str] = set() # Bind one C function's ``restype``/``argtypes`` on this module's ``lib``, pre-applied # against this module's own ``lib``/``UNAVAILABLE_FUNCTIONS`` so each of the ~75 call # sites below only needs to supply ``name``, ``restype``, and ``argtypes``. See # :func:`tecio._utils.bind`. bind_ctypes = functools.partial(_utils.bind, lib=lib, unavailable=UNAVAILABLE_FUNCTIONS) # Decorator guarding a wrapper function behind its required C symbol, pre-applied # against this module's own state and :exc:`TecioUnavailableError` requires_symbol = functools.partial( _utils.requires_symbol, unavailable=UNAVAILABLE_FUNCTIONS, load_error=LIBRARY_LOAD_ERROR, library_path=LIBRARY_PATH, exception_cls=TecioUnavailableError, ) # ====================================================================================== # Local helpers # ====================================================================================== def _prepare_array_for_ctypes( values: npt.ArrayLike, np_dtype, ctype ) -> tuple[Any, int, npt.NDArray]: """Convert an input array to contiguous numpy array and return a ctypes pointer. Args: values: array-like (list, tuple, numpy array) np_dtype: numpy dtype object or type (e.g. np.float32) ctype: corresponding ctypes scalar type (e.g. ctypes.c_float) Returns: ptr: ctypes pointer suitable for passing to the C API count: int number of elements backing_array: the numpy array object (returned to keep it alive) Note: Caller should keep the returned backing_array alive until the native call completes. Note: This function enforces dtype and C-contiguity. """ arr = np.ascontiguousarray(values, dtype=np_dtype) count = int(arr.size) ptr = arr.ctypes.data_as(ctypes.POINTER(ctype)) return ptr, count, arr def _to_int_value(value: int | Enum, enum_class: type[Enum] | None = None) -> int: """Convert Enum or int to int value. (Optional check against enum_class if provided.) Returns: int: Enum value. Raises: ValueError: If *value* is not a member of *enum_class*. """ if isinstance(value, Enum): return value.value v = int(value) if enum_class is not None: try: enum_class(v) except ValueError as e: raise ValueError( f"Invalid value {v} for enum {enum_class.__name__}. " f"Valid values: {[e.value for e in enum_class]}" ) from e return v def _process_sequence(seq: Sequence[int | Enum] | None) -> ctypes.Array | None: """Convert sequence of int/Enum to ctypes array, handling None. Returns: ctypes.Array: 32-bit integers, or ``None`` if *seq* is ``None``. """ if seq is None: return None values = [_to_int_value(v) for v in seq] return (ctypes.c_int32 * len(values))(*values) def _decode(value: bytes | None) -> str: """Decode a ctypes c_char_p value to str, raising if unexpectedly null. Returns: str: utf-8 decoded string. Raises: ValueError: If *value* is ``None``. """ if value is None: raise ValueError("Unexpected null pointer returned from TecIO C library.") return value.decode("utf-8") # ====================================================================================== # C library bindings # - Set the input and output C types for each C function used in this library # ====================================================================================== # -------------------------------------------------------------------------------------- # New SZL API bindings # -------------------------------------------------------------------------------------- # Reading SZL files bind_ctypes( name="tecFileReaderOpen", restype=ctypes.c_int32, argtypes=[ ctypes.c_char_p, ctypes.POINTER(ctypes.c_void_p), ], ) bind_ctypes( name="tecFileReaderClose", restype=ctypes.c_int32, argtypes=[ ctypes.POINTER(ctypes.c_void_p), ], ) bind_ctypes( name="tecFileGetType", restype=ctypes.c_int32, argtypes=[ ctypes.c_void_p, ctypes.POINTER(ctypes.c_int32), ], ) bind_ctypes( name="tecDataSetGetTitle", restype=ctypes.c_int32, argtypes=[ ctypes.c_void_p, ctypes.POINTER(ctypes.c_char_p), ], ) bind_ctypes( name="tecDataSetGetNumVars", restype=ctypes.c_int32, argtypes=[ ctypes.c_void_p, ctypes.POINTER(ctypes.c_int32), ], ) bind_ctypes( name="tecDataSetGetNumZones", restype=ctypes.c_int32, argtypes=[ ctypes.c_void_p, ctypes.POINTER(ctypes.c_int32), ], ) bind_ctypes( name="tecDataSetAuxDataGetNumItems", restype=ctypes.c_int32, argtypes=[ ctypes.c_void_p, ctypes.POINTER(ctypes.c_int32), ], ) # Reading SZL zones bind_ctypes( name="tecZoneGetIJK", restype=ctypes.c_int32, argtypes=[ ctypes.c_void_p, ctypes.c_int32, ctypes.POINTER(ctypes.c_int64), ctypes.POINTER(ctypes.c_int64), ctypes.POINTER(ctypes.c_int64), ], ) bind_ctypes( name="tecZoneGetTitle", restype=ctypes.c_int32, argtypes=[ ctypes.c_void_p, ctypes.c_int32, ctypes.POINTER(ctypes.c_char_p), ], ) bind_ctypes( name="tecZoneGetType", restype=ctypes.c_int32, argtypes=[ ctypes.c_void_p, ctypes.c_int32, ctypes.POINTER(ctypes.c_int32), ], ) bind_ctypes( name="tecZoneGetNumSections", restype=ctypes.c_int32, argtypes=[ ctypes.c_void_p, ctypes.c_int32, ctypes.POINTER(ctypes.c_int32), ], ) bind_ctypes( name="tecZoneGetSectionMetrics", restype=ctypes.c_int32, argtypes=[ ctypes.c_void_p, ctypes.c_int32, # zone ctypes.c_int32, # section ctypes.POINTER(ctypes.c_int32), # cellShape ctypes.POINTER(ctypes.c_int32), # gridOrder ctypes.POINTER(ctypes.c_int32), # basisFunction ctypes.POINTER(ctypes.c_int64), # numElemsInSection ctypes.POINTER(ctypes.c_int32), # numNodesPerCell ], ) bind_ctypes( name="tecZoneIsEnabled", restype=ctypes.c_int32, argtypes=[ ctypes.c_void_p, ctypes.c_int32, ctypes.POINTER(ctypes.c_int32), ], ) bind_ctypes( name="tecZoneGetSolutionTime", restype=ctypes.c_int32, argtypes=[ ctypes.c_void_p, ctypes.c_int32, ctypes.POINTER(ctypes.c_double), ], ) bind_ctypes( name="tecZoneGetStrandID", restype=ctypes.c_int32, argtypes=[ ctypes.c_void_p, ctypes.c_int32, ctypes.POINTER(ctypes.c_int32), ], ) bind_ctypes( name="tecZoneNodeMapIs64Bit", restype=ctypes.c_int32, argtypes=[ ctypes.c_void_p, ctypes.c_int32, ctypes.POINTER(ctypes.c_int32), ], ) bind_ctypes( name="tecZoneNodeMapGet64", restype=ctypes.c_int32, argtypes=[ ctypes.c_void_p, ctypes.c_int32, ctypes.c_int64, ctypes.c_int64, ctypes.POINTER(ctypes.c_int64), ], ) bind_ctypes( name="tecZoneNodeMapGet", restype=ctypes.c_int32, argtypes=[ ctypes.c_void_p, ctypes.c_int32, ctypes.c_int64, ctypes.c_int64, ctypes.POINTER(ctypes.c_int32), ], ) # Reading SZL face neighbors bind_ctypes( name="tecZoneFaceNbrGetMode", restype=ctypes.c_int32, argtypes=[ ctypes.c_void_p, ctypes.c_int32, ctypes.POINTER(ctypes.c_int32), ], ) bind_ctypes( name="tecZoneFaceNbrGetNumConnections", restype=ctypes.c_int32, argtypes=[ ctypes.c_void_p, ctypes.c_int32, ctypes.POINTER(ctypes.c_int64), ], ) bind_ctypes( name="tecZoneFaceNbrGetNumValues", restype=ctypes.c_int32, argtypes=[ ctypes.c_void_p, ctypes.c_int32, ctypes.POINTER(ctypes.c_int64), ], ) bind_ctypes( name="tecZoneFaceNbrsAre64Bit", restype=ctypes.c_int32, argtypes=[ ctypes.c_void_p, ctypes.c_int32, ctypes.POINTER(ctypes.c_int32), ], ) bind_ctypes( name="tecZoneFaceNbrGetConnections", restype=ctypes.c_int32, argtypes=[ ctypes.c_void_p, ctypes.c_int32, ctypes.POINTER(ctypes.c_int32), ], ) bind_ctypes( name="tecZoneFaceNbrGetConnections64", restype=ctypes.c_int32, argtypes=[ ctypes.c_void_p, ctypes.c_int32, ctypes.POINTER(ctypes.c_int64), ], ) # Reading SZL variable data bind_ctypes( name="tecVarGetName", restype=ctypes.c_int32, argtypes=[ ctypes.c_void_p, ctypes.c_int32, ctypes.POINTER(ctypes.c_char_p), ], ) bind_ctypes( name="tecVarIsEnabled", restype=ctypes.c_int32, argtypes=[ ctypes.c_void_p, ctypes.c_int32, ctypes.POINTER(ctypes.c_int32), ], ) bind_ctypes( name="tecZoneVarGetType", restype=ctypes.c_int32, argtypes=[ ctypes.c_void_p, ctypes.c_int32, ctypes.c_int32, ctypes.POINTER(ctypes.c_int32), ], ) bind_ctypes( name="tecZoneVarGetValueLocation", restype=ctypes.c_int32, argtypes=[ ctypes.c_void_p, ctypes.c_int32, ctypes.c_int32, ctypes.POINTER(ctypes.c_int32), ], ) bind_ctypes( name="tecZoneVarIsPassive", restype=ctypes.c_int32, argtypes=[ ctypes.c_void_p, ctypes.c_int32, ctypes.c_int32, ctypes.POINTER(ctypes.c_int32), ], ) bind_ctypes( name="tecZoneVarGetSharedZone", restype=ctypes.c_int32, argtypes=[ ctypes.c_void_p, ctypes.c_int32, ctypes.c_int32, ctypes.POINTER(ctypes.c_int32), ], ) bind_ctypes( name="tecZoneConnectivityGetSharedZone", restype=ctypes.c_int32, argtypes=[ ctypes.c_void_p, ctypes.c_int32, ctypes.POINTER(ctypes.c_int32), ], ) bind_ctypes( name="tecZoneVarGetNumValues", restype=ctypes.c_int32, argtypes=[ ctypes.c_void_p, ctypes.c_int32, ctypes.c_int32, ctypes.POINTER(ctypes.c_int32), ], ) bind_ctypes( name="tecZoneVarGetFloatValues", restype=ctypes.c_int32, argtypes=[ ctypes.c_void_p, # File Handle ctypes.c_int32, # Zone index ctypes.c_int32, # Variable index ctypes.c_int64, # Start index ctypes.c_int64, # Number of values ctypes.POINTER(ctypes.c_float), # Values ], ) bind_ctypes( name="tecZoneVarGetDoubleValues", restype=ctypes.c_int32, argtypes=[ ctypes.c_void_p, # File Handle ctypes.c_int32, # Zone index ctypes.c_int32, # Variable index ctypes.c_int64, # Start index ctypes.c_int64, # Number of values ctypes.POINTER(ctypes.c_double), # Values ], ) bind_ctypes( name="tecZoneVarGetInt32Values", restype=ctypes.c_int32, argtypes=[ ctypes.c_void_p, # File Handle ctypes.c_int32, # Zone index ctypes.c_int32, # Variable index ctypes.c_int64, # Start index ctypes.c_int64, # Number of values ctypes.POINTER(ctypes.c_int32), # Values ], ) bind_ctypes( name="tecZoneVarGetInt16Values", restype=ctypes.c_int32, argtypes=[ ctypes.c_void_p, # File Handle ctypes.c_int32, # Zone index ctypes.c_int32, # Variable index ctypes.c_int64, # Start index ctypes.c_int64, # Number of values ctypes.POINTER(ctypes.c_int16), # Values ], ) bind_ctypes( name="tecZoneVarGetUInt8Values", restype=ctypes.c_int32, argtypes=[ ctypes.c_void_p, # File Handle ctypes.c_int32, # Zone index ctypes.c_int32, # Variable index ctypes.c_int64, # Start index ctypes.c_int64, # Number of values ctypes.POINTER(ctypes.c_uint8), # Values ], ) # Reading SZL aux data bind_ctypes( name="tecDataSetAuxDataGetNumItems", restype=ctypes.c_int32, argtypes=[ ctypes.c_void_p, ctypes.POINTER(ctypes.c_int32), ], ) bind_ctypes( name="tecDataSetAuxDataGetItem", restype=ctypes.c_int32, argtypes=[ ctypes.c_void_p, ctypes.c_int32, ctypes.POINTER(ctypes.c_char_p), ctypes.POINTER(ctypes.c_char_p), ], ) bind_ctypes( name="tecVarAuxDataGetNumItems", restype=ctypes.c_int32, argtypes=[ ctypes.c_void_p, ctypes.c_int32, ctypes.POINTER(ctypes.c_int32), ], ) bind_ctypes( name="tecVarAuxDataGetItem", restype=ctypes.c_int32, argtypes=[ ctypes.c_void_p, ctypes.c_int32, ctypes.c_int32, ctypes.POINTER(ctypes.c_char_p), ctypes.POINTER(ctypes.c_char_p), ], ) bind_ctypes( name="tecZoneAuxDataGetNumItems", restype=ctypes.c_int32, argtypes=[ ctypes.c_void_p, ctypes.c_int32, ctypes.POINTER(ctypes.c_int32), ], ) bind_ctypes( name="tecZoneAuxDataGetItem", restype=ctypes.c_int32, argtypes=[ ctypes.c_void_p, ctypes.c_int32, ctypes.c_int32, ctypes.POINTER(ctypes.c_char_p), ctypes.POINTER(ctypes.c_char_p), ], ) # Output file initialization and file handling bind_ctypes( name="tecFileWriterOpen", restype=ctypes.c_int32, argtypes=[ ctypes.c_char_p, # fileName ctypes.c_char_p, # dataSetTitle ctypes.c_char_p, # varNames (comma separated) ctypes.c_int32, # useSZL (1) ctypes.c_int32, # fileType ctypes.c_int32, # reserved / options ctypes.c_void_p, # gridFileHandle (optional) ctypes.POINTER(ctypes.c_void_p), # out fileHandle ], ) bind_ctypes( name="tecFileWriterClose", restype=ctypes.c_int32, argtypes=[ ctypes.POINTER(ctypes.c_void_p), ], ) bind_ctypes( name="tecFileWriterFlush", restype=ctypes.c_int32, argtypes=[ ctypes.c_void_p, # fileHandle ctypes.c_int32, # numZonesToRetain ctypes.POINTER(ctypes.c_int32), # zonesToRetain ], ) # Write Zone Headers bind_ctypes( name="tecZoneCreateIJK", restype=ctypes.c_int32, argtypes=[ ctypes.c_void_p, # file_handle ctypes.c_char_p, # zoneTitle ctypes.c_int64, # I ctypes.c_int64, # J ctypes.c_int64, # K ctypes.POINTER(ctypes.c_int32), # varTypes ctypes.POINTER(ctypes.c_int32), # shareVarFromZone ctypes.POINTER(ctypes.c_int32), # valueLocations ctypes.POINTER(ctypes.c_int32), # passiveVarList ctypes.c_int32, # shareFaceNeighborsFromZone ctypes.c_int64, # numFaceConnections ctypes.c_int32, # faceNeighborMode ctypes.POINTER(ctypes.c_int32), # out zone ], ) bind_ctypes( name="tecZoneCreateFE", restype=ctypes.c_int32, argtypes=[ ctypes.c_void_p, # file_handle ctypes.c_char_p, # zoneTitle ctypes.c_int32, # ZoneType ctypes.c_int64, # numNodes ctypes.c_int64, # numCells ctypes.POINTER(ctypes.c_int32), # varTypes ctypes.POINTER(ctypes.c_int32), # shareVarFromZone ctypes.POINTER(ctypes.c_int32), # valueLocations ctypes.POINTER(ctypes.c_int32), # passiveVarList ctypes.c_int32, # shareFaceNeighborsFromZone ctypes.c_int64, # numFaceConnections ctypes.c_int32, # faceNeighborMode ctypes.POINTER(ctypes.c_int32), # out zone ], ) bind_ctypes( name="tecZoneCreateFEMixed", restype=ctypes.c_int32, argtypes=[ ctypes.c_void_p, # file_handle ctypes.c_char_p, # zoneTitle ctypes.c_int64, # numNodes ctypes.c_int32, # numSections ctypes.POINTER(ctypes.c_int32), # cellShapePerSection ctypes.POINTER(ctypes.c_int32), # gridOrderPerSection ctypes.POINTER(ctypes.c_int32), # basisFnPerSection ctypes.POINTER(ctypes.c_int64), # numElementsPerSection ctypes.POINTER(ctypes.c_int32), # varTypes ctypes.POINTER(ctypes.c_int32), # shareVarFromZone ctypes.POINTER(ctypes.c_int32), # valueLocations ctypes.POINTER(ctypes.c_int32), # passiveVarList ctypes.c_int32, # shareConnectivityFromZone ctypes.c_int64, # numFaceConnections ctypes.c_int32, # faceNeighborMode ctypes.POINTER(ctypes.c_int32), # out zone ], ) # Optional fields bind_ctypes( name="tecZoneSetUnsteadyOptions", restype=ctypes.c_int32, argtypes=[ ctypes.c_void_p, # file_handle ctypes.c_int32, # zone ctypes.c_double, # solutionTime ctypes.c_int32, # strand ], ) bind_ctypes( name="tecDataSetAddAuxData", restype=ctypes.c_int32, argtypes=[ ctypes.c_void_p, # fileHandle ctypes.c_char_p, # name ctypes.c_char_p, # value ], ) bind_ctypes( name="tecVarAddAuxData", restype=ctypes.c_int32, argtypes=[ ctypes.c_void_p, # fileHandle ctypes.c_int32, # varIndex (1-based) ctypes.c_char_p, # name ctypes.c_char_p, # value ], ) bind_ctypes( name="tecZoneAddAuxData", restype=ctypes.c_int32, argtypes=[ ctypes.c_void_p, # fileHandle ctypes.c_int32, # zoneIndex (1-based) ctypes.c_char_p, # name ctypes.c_char_p, # value ], ) # Write variable value functions bind_ctypes( name="tecZoneVarWriteDoubleValues", restype=ctypes.c_int32, argtypes=[ ctypes.c_void_p, # file handle ctypes.c_int32, # zone index ctypes.c_int32, # variable index ctypes.c_int32, # partition index (0 for non-partitioned zones) ctypes.c_int64, # number of values to write ctypes.POINTER(ctypes.c_double), # pointer to values array ], ) bind_ctypes( name="tecZoneVarWriteFloatValues", restype=ctypes.c_int32, argtypes=[ ctypes.c_void_p, # file handle ctypes.c_int32, # zone index ctypes.c_int32, # variable index ctypes.c_int32, # partition index (0 for non-partitioned zones) ctypes.c_int64, # number of values to write ctypes.POINTER(ctypes.c_float), # pointer to values array ], ) bind_ctypes( name="tecZoneVarWriteInt32Values", restype=ctypes.c_int32, argtypes=[ ctypes.c_void_p, # file handle ctypes.c_int32, # zone index ctypes.c_int32, # variable index ctypes.c_int32, # partition index (0 for non-partitioned zones) ctypes.c_int64, # number of values to write ctypes.POINTER(ctypes.c_int32), # pointer to values array ], ) bind_ctypes( name="tecZoneVarWriteInt16Values", restype=ctypes.c_int32, argtypes=[ ctypes.c_void_p, # file handle ctypes.c_int32, # zone index ctypes.c_int32, # variable index ctypes.c_int32, # partition index (0 for non-partitioned zones) ctypes.c_int64, # number of values to write ctypes.POINTER(ctypes.c_int16), # pointer to values array ], ) bind_ctypes( name="tecZoneVarWriteUInt8Values", restype=ctypes.c_int32, argtypes=[ ctypes.c_void_p, # file handle ctypes.c_int32, # zone index ctypes.c_int32, # variable index ctypes.c_int32, # partition index (0 for non-partitioned zones) ctypes.c_int64, # number of values to write ctypes.POINTER(ctypes.c_uint8), # pointer to values array ], ) # Write Zone Connectivity (FE zones only) bind_ctypes( name="tecZoneNodeMapWrite32", restype=ctypes.c_int32, argtypes=[ ctypes.c_void_p, # fileHandle ctypes.c_int32, # zone index(1-based) ctypes.c_int32, # partition index (MPI) ctypes.c_int32, # isOneBased (Boolean) ctypes.c_int64, # nodeCount ctypes.POINTER(ctypes.c_int32), # array of nodes ], ) bind_ctypes( name="tecZoneNodeMapWrite64", restype=ctypes.c_int32, argtypes=[ ctypes.c_void_p, # fileHandle ctypes.c_int32, # zone index(1-based) ctypes.c_int32, # partition index (MPI) ctypes.c_int32, # isOneBased (Boolean) ctypes.c_int64, # nodeCount ctypes.POINTER(ctypes.c_int64), # array of nodes ], ) bind_ctypes( name="tecZoneFaceNbrWriteConnections32", restype=ctypes.c_int32, argtypes=[ ctypes.c_void_p, # fileHandle ctypes.c_int32, # zone (1-based) ctypes.POINTER(ctypes.c_int32), # faceNeighbors ], ) bind_ctypes( name="tecZoneFaceNbrWriteConnections64", restype=ctypes.c_int32, argtypes=[ ctypes.c_void_p, # fileHandle ctypes.c_int32, # zone (1-based) ctypes.POINTER(ctypes.c_int64), # faceNeighbors ], ) # -------------------------------------------------------------------------------------- # Classic API bindings # -------------------------------------------------------------------------------------- # File initialization and finalization bind_ctypes( name="tecini142", restype=ctypes.c_int32, argtypes=[ ctypes.c_char_p, # Title ctypes.c_char_p, # Variables ctypes.c_char_p, # FName ctypes.c_char_p, # ScratchDir ctypes.POINTER(ctypes.c_int32), # FileFormat (0=PLT, 1=SZPLT) ctypes.POINTER(ctypes.c_int32), # FileType (0=FULL, 1=GRID, 2=SOLUTION) ctypes.POINTER(ctypes.c_int32), # Debug ctypes.POINTER(ctypes.c_int32), # VIsDouble ], ) bind_ctypes( name="tecend142", restype=ctypes.c_int32, argtypes=[], ) bind_ctypes( name="tecflush142", restype=ctypes.c_int32, argtypes=[ ctypes.POINTER(ctypes.c_int32), # NumZonesToRetain ctypes.POINTER(ctypes.c_int32), # ZonesToRetain ], ) bind_ctypes( name="tecfil142", restype=ctypes.c_int32, argtypes=[ ctypes.POINTER(ctypes.c_int32), # OutputFileHandle ], ) bind_ctypes( name="tecforeign142", restype=ctypes.c_int32, argtypes=[ ctypes.POINTER(ctypes.c_int32), # OutputForeignByteOrder ], ) # Zone creation bind_ctypes( name="teczne142", restype=ctypes.c_int32, argtypes=[ ctypes.c_char_p, # ZoneTitle ctypes.POINTER(ctypes.c_int32), # ZoneType ctypes.POINTER(ctypes.c_int32), # IMx (or NumNodes for FE) ctypes.POINTER(ctypes.c_int32), # JMx (or NumElements for FE) ctypes.POINTER(ctypes.c_int32), # KMx ctypes.POINTER(ctypes.c_int32), # ICellMax ctypes.POINTER(ctypes.c_int32), # JCellMax ctypes.POINTER(ctypes.c_int32), # KCellMax ctypes.POINTER(ctypes.c_double), # SolutionTime ctypes.POINTER(ctypes.c_int32), # StrandID ctypes.POINTER(ctypes.c_int32), # ParentZone ctypes.POINTER(ctypes.c_int32), # IsBlock (1=Block, 0=Point) ctypes.POINTER(ctypes.c_int32), # NumFaceConnections ctypes.POINTER(ctypes.c_int32), # FaceNeighborMode ctypes.POINTER(ctypes.c_int32), # TotalNumFaceNodes (for poly zones) ctypes.POINTER(ctypes.c_int32), # NumConnectedBoundaryFaces (for poly) ctypes.POINTER(ctypes.c_int32), # TotalNumBoundaryConnections (for poly) ctypes.POINTER(ctypes.c_int32), # PassiveVarList ctypes.POINTER(ctypes.c_int32), # ValueLocation ctypes.POINTER(ctypes.c_int32), # ShareVarFromZone ctypes.POINTER(ctypes.c_int32), # ShareConnectivityFromZone ], ) bind_ctypes( name="tecpolyzne142", restype=ctypes.c_int32, argtypes=[ ctypes.c_char_p, # ZoneTitle ctypes.POINTER(ctypes.c_int32), # ZoneType (FEPOLYGON or FEPOLYHEDRON) ctypes.POINTER(ctypes.c_int32), # NumNodes ctypes.POINTER(ctypes.c_int32), # NumElements ctypes.POINTER(ctypes.c_int64), # NumFaces ctypes.POINTER(ctypes.c_int64), # TotalNumFaceNodes ctypes.POINTER(ctypes.c_double), # SolutionTime ctypes.POINTER(ctypes.c_int32), # StrandID ctypes.POINTER(ctypes.c_int32), # ParentZone ctypes.POINTER(ctypes.c_int32), # NumConnectedBoundaryFaces ctypes.POINTER(ctypes.c_int32), # TotalNumBoundaryConnections ctypes.POINTER(ctypes.c_int32), # PassiveVarList ctypes.POINTER(ctypes.c_int32), # ValueLocation ctypes.POINTER(ctypes.c_int32), # ShareVarFromZone ctypes.POINTER(ctypes.c_int32), # ShareConnectivityFromZone ], ) bind_ctypes( name="tecznefemixed142", restype=ctypes.c_int32, argtypes=[ ctypes.c_char_p, # ZoneTitle ctypes.POINTER(ctypes.c_int64), # NumNodes ctypes.POINTER(ctypes.c_int32), # NumSections ctypes.POINTER(ctypes.c_int32), # CellShapePerSection ctypes.POINTER(ctypes.c_int32), # GridOrderPerSection ctypes.POINTER(ctypes.c_int32), # BasisFnPerSection ctypes.POINTER(ctypes.c_int64), # NumElementsPerSection ctypes.POINTER(ctypes.c_double), # SolutionTime ctypes.POINTER(ctypes.c_int32), # StrandID ctypes.POINTER(ctypes.c_int32), # NumFaceConnections ctypes.POINTER(ctypes.c_int32), # FaceNeighborMode ctypes.POINTER(ctypes.c_int32), # PassiveVarList ctypes.POINTER(ctypes.c_int32), # ValueLocation ctypes.POINTER(ctypes.c_int32), # ShareVarFromZone ctypes.POINTER(ctypes.c_int32), # ShareConnectivityFromZone ], ) # Partitioned zone creation bind_ctypes( name="tecijkptn142", restype=ctypes.c_int32, argtypes=[ ctypes.POINTER(ctypes.c_int32), # PartitionOwnerZone ctypes.POINTER(ctypes.c_int32), # IMin ctypes.POINTER(ctypes.c_int32), # JMin ctypes.POINTER(ctypes.c_int32), # KMin ctypes.POINTER(ctypes.c_int32), # IMax ctypes.POINTER(ctypes.c_int32), # JMax ctypes.POINTER(ctypes.c_int32), # KMax ], ) bind_ctypes( name="tecfeptn142", restype=ctypes.c_int32, argtypes=[ ctypes.POINTER(ctypes.c_int32), # PartitionOwnerZone ctypes.POINTER(ctypes.c_int32), # NumNodes ctypes.POINTER(ctypes.c_int32), # NumElements ], ) bind_ctypes( name="tecfemixedptn142", restype=ctypes.c_int32, argtypes=[ ctypes.POINTER(ctypes.c_int32), # PartitionOwnerZone ctypes.POINTER(ctypes.c_int32), # NumNodes ctypes.POINTER(ctypes.c_int32), # NumElements ctypes.POINTER(ctypes.c_int32), # NumNodesPerElement ], ) # Data writing bind_ctypes( name="tecdat142", restype=ctypes.c_int32, argtypes=[ ctypes.POINTER(ctypes.c_int32), # N (number of values) ctypes.c_void_p, # FieldData (void pointer for flexibility) ctypes.POINTER(ctypes.c_int32), # IsDouble (1=double, 0=float) ], ) # Connectivity writing bind_ctypes( name="tecnod142", restype=ctypes.c_int32, argtypes=[ ctypes.POINTER(ctypes.c_int32), # NData (connectivity array) ], ) bind_ctypes( name="tecnode142", restype=ctypes.c_int32, argtypes=[ ctypes.POINTER(ctypes.c_int32), # N (number of values) ctypes.POINTER(ctypes.c_int32), # NData (connectivity array) ], ) bind_ctypes( name="tecznemap142", restype=ctypes.c_int32, argtypes=[ ctypes.POINTER(ctypes.c_int32), # N (number of values) ctypes.POINTER(ctypes.c_int32), # NodeMap ], ) bind_ctypes( name="tecface142", restype=ctypes.c_int32, argtypes=[ ctypes.POINTER(ctypes.c_int32), # FaceConnections ], ) bind_ctypes( name="tecpolyface142", restype=ctypes.c_int32, argtypes=[ ctypes.POINTER(ctypes.c_int32), # NumFaces ctypes.POINTER(ctypes.c_int32), # FaceNodeCounts ctypes.POINTER(ctypes.c_int32), # FaceNodes ctypes.POINTER(ctypes.c_int32), # FaceLeftElems ctypes.POINTER(ctypes.c_int32), # FaceRightElems ], ) bind_ctypes( name="tecpolybconn142", restype=ctypes.c_int32, argtypes=[ ctypes.POINTER(ctypes.c_int32), # NumBoundaryFaces ctypes.POINTER(ctypes.c_int32), # BoundaryConnectionCounts ctypes.POINTER(ctypes.c_int32), # BoundaryConnectionElems ctypes.POINTER(ctypes.c_int32), # BoundaryConnectionZones ], ) # Auxiliary data bind_ctypes( name="tecauxstr142", restype=ctypes.c_int32, argtypes=[ ctypes.c_char_p, # Name ctypes.c_char_p, # Value ], ) bind_ctypes( name="tecvauxstr142", restype=ctypes.c_int32, argtypes=[ ctypes.POINTER(ctypes.c_int32), # Var (1-based variable index) ctypes.c_char_p, # Name ctypes.c_char_p, # Value ], ) bind_ctypes( name="teczauxstr142", restype=ctypes.c_int32, argtypes=[ ctypes.c_char_p, # Name ctypes.c_char_p, # Value ], ) # MPI initialization (for parallel I/O) bind_ctypes( name="tecmpiinit142", restype=ctypes.c_int32, argtypes=[ ctypes.POINTER(ctypes.c_int32), # Communicator ctypes.POINTER(ctypes.c_int32), # MainRank ], ) # User-defined data (custom records) bind_ctypes( name="tecusr142", restype=ctypes.c_int32, argtypes=[ ctypes.c_char_p, # UserRec ], ) if UNAVAILABLE_FUNCTIONS: # pragma: no cover - environment-dependent if LIBRARY_LOAD_ERROR is not None: _reason = f"no TecIO shared library could be loaded ({LIBRARY_LOAD_ERROR})" else: _reason = f"the loaded library ({LIBRARY_PATH}) doesn't export them" warnings.warn( f"tecio.libtecio: {len(UNAVAILABLE_FUNCTIONS)} function(s) unavailable, " f"{_reason}. Calling one of these raises TecioUnavailableError; see " "tecio.libtecio.UNAVAILABLE_FUNCTIONS for the full list. DAT reading and " "writing is unaffected, it does not use this library. Affected: " + ", ".join(sorted(UNAVAILABLE_FUNCTIONS)), TecioAvailabilityWarning, stacklevel=2, ) # ====================================================================================== # Wrappers for C functions # - 1-to-1 python functions to format python inputs/ouputs to C TecIO functions # - "New" API functions (tecXxxXxx) are wrapped by equivaltly named tec_xxx_xxx # python funcitons # - "Classic" API functions (TECXXXX142) wrapped by equivaltly named tecxxx142 python # funcitons # - Scope for this library is limited to IO for data related file records (geometry and # text records are ignored) # - Some MPI funcion python wrappers are included, but not yet fully implemented # - Wherever data arrays are output, conversion to numpy arrays is handled in the # wrapper function # ====================================================================================== # -------------------------------------------------------------------------------------- # New read API (SZL/.szplt): # - tec_file_reader_open returns an explicit file handle that is passed to every # subsequent call, making the target file unambiguous # - Multiple files can be read simultaneously by holding multiple handles at once # - Fucntions are available to query dataset/zone/variable metadata before reading any # data, and data can be read in any order by referencing the file handle + # zone/variable index # - General organization of functions: # - tec_file_* functions operate on the file # - tec_data_set_* functions query whole dataset metadata # - tec_zone_* functions query zone level metadata (type, dimensions, title, solution # time, strand ID, node map, aux data) # - tec_var_* functions query variable-level metadata (name, aux data) # - tec_zone_var_* functions read variable values for a given zone and variable index # -------------------------------------------------------------------------------------- # -- Reading SZL files -----------------------------------------------------------------
[docs] @requires_symbol("tecFileReaderOpen") def tec_file_reader_open(file_name: str) -> ctypes.c_void_p: """Open an SZL file for reading. Args: file_name (str): Path to the ``.szplt`` file. Returns: Opaque file handle for subsequent TecIO calls. Raises: TecioError: If the file cannot be opened. """ assert lib is not None # narrowed: @requires_symbol already checked handle = ctypes.c_void_p(0) ret = lib.tecFileReaderOpen( ctypes.c_char_p(bytes(file_name, encoding="UTF-8")), ctypes.byref(handle), ) if ret != 0: raise TecioError( f"SzlFile Initialization Error: file_name={file_name}, return_code={ret}" ) return handle
[docs] @requires_symbol("tecFileReaderClose") def tec_file_reader_close(handle: ctypes.c_void_p) -> None: """Close an SZL file reader handle and release its resources. Args: handle: File handle from :func:`tec_file_reader_open`. Raises: TecioError: On C library error. """ assert lib is not None # narrowed: @requires_symbol already checked ret = lib.tecFileReaderClose(ctypes.byref(handle)) if ret != 0: raise TecioError( f"tecFileReaderClose Error: handle={handle}, return_code={ret}" )
[docs] @requires_symbol("tecFileGetType") def tec_file_get_type(handle: ctypes.c_void_p) -> FileType: """Get the file type for an opened SZL file. Args: handle (ctypes.c_void_p): File handle from :func:`tec_file_reader_open`. Returns: :class:`FileType` enum (FULL, GRID, or SOLUTION). Raises: TecioError: On C library error. """ assert lib is not None # narrowed: @requires_symbol already checked file_type = ctypes.c_int32(0) ret = lib.tecFileGetType(handle, ctypes.byref(file_type)) if ret != 0: raise TecioError(f"Error getting file type: handle:{handle}, return_code={ret}") return FileType(file_type.value)
[docs] @requires_symbol("tecDataSetGetTitle") def tec_data_set_get_title(handle: ctypes.c_void_p) -> str: """Read the dataset title string. Args: handle (ctypes.c_void_p): File handle. Returns: UTF-8 decoded dataset title. Raises: TecioError: On C library error. """ assert lib is not None # narrowed: @requires_symbol already checked title = ctypes.c_char_p(0) ret = lib.tecDataSetGetTitle(handle, ctypes.byref(title)) if ret != 0: raise TecioError( f"Error getting data set title: handle={handle}, return_code={ret}" ) return _decode(title.value)
[docs] @requires_symbol("tecDataSetGetNumVars") def tec_data_set_get_num_vars(handle: ctypes.c_void_p) -> int: """Query the number of variables in the dataset. Args: handle (ctypes.c_void_p): File handle. Returns: Number of variables. Raises: TecioError: On C library error. """ assert lib is not None # narrowed: @requires_symbol already checked num_vars = ctypes.c_int32(0) ret = lib.tecDataSetGetNumVars(handle, ctypes.byref(num_vars)) if ret != 0: raise TecioError( f"Error getting number of variables: handle={handle}, return_code={ret}" ) return num_vars.value
[docs] @requires_symbol("tecDataSetGetNumZones") def tec_data_set_get_num_zones(handle: ctypes.c_void_p) -> int: """Query the number of zones in the dataset. Args: handle (ctypes.c_void_p): File handle. Returns: Number of zones. Raises: TecioError: On C library error. """ assert lib is not None # narrowed: @requires_symbol already checked num_zones = ctypes.c_int32(0) ret = lib.tecDataSetGetNumZones(handle, ctypes.byref(num_zones)) if ret != 0: raise TecioError( f"Error getting number of zones: handle={handle}, return_code={ret}" ) return num_zones.value
# -- Reading SZL zones -----------------------------------------------------------------
[docs] @requires_symbol("tecZoneGetIJK") def tec_zone_get_ijk(handle: ctypes.c_void_p, zone_index: int) -> tuple[int, int, int]: """Get zone dimensions (ORDERED) or node/element counts (FE). Args: handle (ctypes.c_void_p): File handle. zone_index (int): 1-based zone index. Returns: ``(I, J, K)`` for ORDERED zones, or ``(num_nodes, num_elements, 0)`` for FE zones. Raises: TecioError: On C library error. """ assert lib is not None # narrowed: @requires_symbol already checked imax = ctypes.c_int64(0) jmax = ctypes.c_int64(0) kmax = ctypes.c_int64(0) ret = lib.tecZoneGetIJK( handle, ctypes.c_int32(zone_index), ctypes.byref(imax), ctypes.byref(jmax), ctypes.byref(kmax), ) if ret != 0: raise TecioError( f"Error getting zone data indices: : handle={handle}, " f"zone_index={zone_index}, return_code={ret}" ) return imax.value, jmax.value, kmax.value
[docs] @requires_symbol("tecZoneGetTitle") def tec_zone_get_title(handle: ctypes.c_void_p, zone_index: int) -> str: """Read the title for a zone. Args: handle (ctypes.c_void_p): File handle. zone_index (int): 1-based zone index. Returns: Zone title string. Raises: TecioError: On C library error. """ assert lib is not None # narrowed: @requires_symbol already checked zone_title = ctypes.c_char_p(0) ret = lib.tecZoneGetTitle( handle, ctypes.c_int32(zone_index), ctypes.byref(zone_title) ) if ret != 0: raise TecioError( f"tecZoneGetTitle Error: handle={handle}, " f"zone_index={zone_index}, return_code={ret}" ) return _decode(zone_title.value)
[docs] @requires_symbol("tecZoneGetType") def tec_zone_get_type(handle: ctypes.c_void_p, zone_index: int) -> ZoneType: """Query the zone type. Args: handle (ctypes.c_void_p): File handle. zone_index (int): 1-based zone index. Returns: :class:`ZoneType` enum value. Raises: TecioError: On C library error. """ assert lib is not None # narrowed: @requires_symbol already checked zone_type = ctypes.c_int32(0) ret = lib.tecZoneGetType( handle, ctypes.c_int32(zone_index), ctypes.byref(zone_type) ) if ret != 0: raise TecioError( f"tecZoneGetType Error: handle={handle}, " f"zone_index={zone_index}, return_code={ret}" ) return ZoneType(zone_type.value)
@requires_symbol("tecZoneGetNumSections") def tec_zone_get_num_sections(handle: ctypes.c_void_p, zone_index: int) -> int: """Get the number of sections in a FEMIXED zone. Only meaningful for zones of :attr:`ZoneType.FEMIXED`. Args: handle (ctypes.c_void_p): File handle. zone_index (int): 1-based zone index. Returns: Number of sections (1-16) in the zone. Raises: TecioError: On C library error. """ assert lib is not None # narrowed: @requires_symbol already checked num_sections = ctypes.c_int32(0) ret = lib.tecZoneGetNumSections( handle, ctypes.c_int32(zone_index), ctypes.byref(num_sections) ) if ret != 0: raise TecioError( f"tecZoneGetNumSections Error: handle={handle}, " f"zone_index={zone_index}, return_code={ret}" ) return num_sections.value @requires_symbol("tecZoneGetSectionMetrics") def tec_zone_get_section_metrics( handle: ctypes.c_void_p, zone_index: int, section_index: int ) -> tuple[FeCellShape, int, int, int, int]: """Get metrics for one section of a FEMIXED zone. Only meaningful for zones of :attr:`ZoneType.FEMIXED`; use :func:`tec_zone_get_num_sections` first to get the section count. Args: handle (ctypes.c_void_p): File handle. zone_index (int): 1-based zone index. section_index (int): 1-based section index. Returns: ``(cell_shape, grid_order, basis_function, num_elements, num_nodes_per_cell)`` for the requested section. Raises: TecioError: On C library error. """ assert lib is not None # narrowed: @requires_symbol already checked cell_shape = ctypes.c_int32(0) grid_order = ctypes.c_int32(0) basis_function = ctypes.c_int32(0) num_elements = ctypes.c_int64(0) num_nodes_per_cell = ctypes.c_int32(0) ret = lib.tecZoneGetSectionMetrics( handle, ctypes.c_int32(zone_index), ctypes.c_int32(section_index), ctypes.byref(cell_shape), ctypes.byref(grid_order), ctypes.byref(basis_function), ctypes.byref(num_elements), ctypes.byref(num_nodes_per_cell), ) if ret != 0: raise TecioError( f"tecZoneGetSectionMetrics Error: handle={handle}, " f"zone_index={zone_index}, section_index={section_index}, " f"return_code={ret}" ) return ( FeCellShape(cell_shape.value), grid_order.value, basis_function.value, num_elements.value, num_nodes_per_cell.value, )
[docs] @requires_symbol("tecZoneIsEnabled") def tec_zone_is_enabled(handle: ctypes.c_void_p, zone_index: int) -> bool: """Check whether a zone is enabled. Args: handle (ctypes.c_void_p): File handle. zone_index (int): 1-based zone index. Returns: True if the zone is enabled. Raises: TecioError: On C library error. """ assert lib is not None # narrowed: @requires_symbol already checked is_enabled = ctypes.c_int32(0) ret = lib.tecZoneIsEnabled( handle, ctypes.c_int32(zone_index), ctypes.byref(is_enabled) ) if ret != 0: raise TecioError( f"tecZoneIsEnabled Error: handle={handle}, " f"zone_index={zone_index}, return_code={ret}" ) return bool(is_enabled.value)
[docs] @requires_symbol("tecZoneGetSolutionTime") def tec_zone_get_solution_time(handle: ctypes.c_void_p, zone_index: int) -> float: """Read the solution time for a zone. Args: handle (ctypes.c_void_p): File handle. zone_index (int): 1-based zone index. Returns: Solution time (double precision). Raises: TecioError: On C library error. """ assert lib is not None # narrowed: @requires_symbol already checked solution_time = ctypes.c_double(0) ret = lib.tecZoneGetSolutionTime( handle, ctypes.c_int32(zone_index), ctypes.byref(solution_time), ) if ret != 0: raise TecioError( f"tecZoneGetSolutionTime Error: handle={handle}, " f"zone_index={zone_index}, return_code={ret}" ) return solution_time.value
[docs] @requires_symbol("tecZoneGetStrandID") def tec_zone_get_strand_id(handle: ctypes.c_void_p, zone_index: int) -> int: """Get the strand ID for a zone. Args: handle (ctypes.c_void_p): File handle. zone_index (int): 1-based zone index. Returns: Strand ID integer. Raises: TecioError: On C library error. """ assert lib is not None # narrowed: @requires_symbol already checked strand_id = ctypes.c_int32(0) ret = lib.tecZoneGetStrandID( handle, ctypes.c_int32(zone_index), ctypes.byref(strand_id) ) if ret != 0: raise TecioError( f"tecZoneGetStrandID Error: handle={handle}, " f"zone_index={zone_index}, return_code={ret}" ) return strand_id.value
[docs] @requires_symbol("tecZoneNodeMapIs64Bit") def is_64bit(handle: ctypes.c_void_p, zone_index: int) -> bool: """Check whether a zone's node-map uses 64-bit indices. Args: handle (ctypes.c_void_p): File handle. zone_index (int): 1-based zone index. Returns: True if 64-bit, False if 32-bit. Raises: TecioError: On C library error. """ assert lib is not None # narrowed: @requires_symbol already checked is64bit = ctypes.c_int32(0) ret = lib.tecZoneNodeMapIs64Bit( handle, ctypes.c_int32(zone_index), ctypes.byref(is64bit) ) if ret != 0: raise TecioError( f"tecZoneNodeMapIs64Bit Error: handle={handle}, " f"zone_index={zone_index}, return_code={ret}" ) return bool(is64bit.value)
[docs] @requires_symbol("tecZoneNodeMapGet64") def tec_zone_node_map_get_64( handle: ctypes.c_void_p, zone_index: int, num_elements: int, nodes_per_cell: int, ) -> npt.NDArray[np.int64]: """Read a 64-bit node map for an FE zone. Args: handle (ctypes.c_void_p): File handle. zone_index (int): 1-based zone index. num_elements (int): Number of elements to read. nodes_per_cell (int): Nodes per element. Returns: Array of shape ``(num_elements, nodes_per_cell)`` with dtype int64. Raises: TecioError: On C library error. """ assert lib is not None # narrowed: @requires_symbol already checked size_of_array = num_elements * nodes_per_cell nodemap = (ctypes.c_int64 * size_of_array)() ret = lib.tecZoneNodeMapGet64( handle, ctypes.c_int32(zone_index), ctypes.c_int64(1), ctypes.c_int64(num_elements), ctypes.cast( nodemap, ctypes.POINTER(ctypes.c_int64), ), ) if ret != 0: raise TecioError( f"tecZoneNodeMapGet64 Error: handle={handle}, " f"zone_index={zone_index}, num_elements={num_elements}, " f"nodes_per_cell={nodes_per_cell}, return_code={ret}" ) return np.ctypeslib.as_array(nodemap).reshape(num_elements, nodes_per_cell)
[docs] @requires_symbol("tecZoneNodeMapGet") def tec_zone_node_map_get( handle: ctypes.c_void_p, zone_index: int, num_elements: int, nodes_per_cell: int, ) -> npt.NDArray[np.int32]: """Read a 32-bit node map for an FE zone. Args: handle (ctypes.c_void_p): File handle. zone_index (int): 1-based zone index. num_elements (int): Number of elements to read. nodes_per_cell (int): Nodes per element. Returns: Array of shape ``(num_elements, nodes_per_cell)`` with dtype int32. Raises: TecioError: On C library error. """ assert lib is not None # narrowed: @requires_symbol already checked size_of_array = num_elements * nodes_per_cell nodemap = (ctypes.c_int32 * size_of_array)() ret = lib.tecZoneNodeMapGet( handle, ctypes.c_int32(zone_index), ctypes.c_int64(1), ctypes.c_int64(num_elements), ctypes.cast( nodemap, ctypes.POINTER(ctypes.c_int32), ), ) if ret != 0: raise TecioError( f"tecZoneNodeMapGet Error: handle={handle}, " f"zone_index={zone_index}, num_elements={num_elements}, " f"nodes_per_cell={nodes_per_cell}, return_code={ret}" ) return np.ctypeslib.as_array(nodemap).reshape(num_elements, nodes_per_cell)
[docs] @requires_symbol("tecZoneNodeMapGet") @requires_symbol("tecZoneNodeMapGet64") def tec_zone_node_map_get_flat( handle: ctypes.c_void_p, zone_index: int, num_elements: int, num_values: int, is_64bit: bool = False, ) -> npt.NDArray[np.int32] | npt.NDArray[np.int64]: """Read a whole FE zone node map as one flat array. Intended for FEMIXED zones, where cells have different node counts so the node map has no single ``(num_elements, nodes_per_cell)`` shape. The cells of each section are stored back to back, in section order. Args: handle (ctypes.c_void_p): File handle. zone_index (int): 1-based zone index. For a zone that shares connectivity this must be the zone that owns it, reading a sharing zone's own node map crashes the C library. num_elements (int): Total number of cells in the zone, over all sections. num_values (int): Total number of node map values, the sum over sections of cells times nodes per cell. is_64bit (bool): Whether the zone's node map is 64-bit, see :func:`is_64bit`. Returns: Flat 1-based node numbers, dtype int64 if *is_64bit* else int32. Raises: TecioError: On C library error. Note: Always reads from the first cell. For FEMIXED zones the C library does not honor a partial cell range, it returns more cells than requested, which would overrun a buffer sized for the request. """ assert lib is not None # narrowed: @requires_symbol already checked if is_64bit: nodes: npt.NDArray[np.int32] | npt.NDArray[np.int64] = np.empty( num_values, dtype=np.int64 ) ptr = nodes.ctypes.data_as(ctypes.POINTER(ctypes.c_int64)) ret = lib.tecZoneNodeMapGet64( handle, ctypes.c_int32(zone_index), ctypes.c_int64(1), ctypes.c_int64(num_elements), ptr, ) else: nodes = np.empty(num_values, dtype=np.int32) ptr32 = nodes.ctypes.data_as(ctypes.POINTER(ctypes.c_int32)) ret = lib.tecZoneNodeMapGet( handle, ctypes.c_int32(zone_index), ctypes.c_int64(1), ctypes.c_int64(num_elements), ptr32, ) if ret != 0: raise TecioError( f"tecZoneNodeMap Error: handle={handle}, zone_index={zone_index}, " f"num_elements={num_elements}, num_values={num_values}, " f"is_64bit={is_64bit}, return_code={ret}" ) return nodes
@requires_symbol("tecZoneFaceNbrGetMode") def tec_zone_face_nbr_get_mode( handle: ctypes.c_void_p, zone_index: int ) -> FaceNeighborMode: """Get the face-neighbor mode for a zone. Args: handle (ctypes.c_void_p): File handle. zone_index (int): 1-based zone index. Returns: :class:`FaceNeighborMode` enum value. Raises: TecioError: On C library error. """ assert lib is not None # narrowed: @requires_symbol already checked mode = ctypes.c_int32(0) ret = lib.tecZoneFaceNbrGetMode( handle, ctypes.c_int32(zone_index), ctypes.byref(mode) ) if ret != 0: raise TecioError( f"tecZoneFaceNbrGetMode Error: handle={handle}, " f"zone_index={zone_index}, return_code={ret}" ) return FaceNeighborMode(mode.value) @requires_symbol("tecZoneFaceNbrGetNumConnections") def tec_zone_face_nbr_get_num_connections( handle: ctypes.c_void_p, zone_index: int ) -> int: """Get the number of face-neighbor connections for a zone. This is a count of distinct connections, not a flat value count, see :func:`tec_zone_face_nbr_get_num_values` for the latter. How many raw values make up one connection depends on :func:`tec_zone_face_nbr_get_mode` (e.g. 3 per connection for ``LOCAL_ONE_TO_ONE``). Args: handle (ctypes.c_void_p): File handle. zone_index (int): 1-based zone index. Returns: Number of face-neighbor connections, 0 if the zone has none. Raises: TecioError: On C library error. """ assert lib is not None # narrowed: @requires_symbol already checked num_connections = ctypes.c_int64(0) ret = lib.tecZoneFaceNbrGetNumConnections( handle, ctypes.c_int32(zone_index), ctypes.byref(num_connections) ) if ret != 0: raise TecioError( f"tecZoneFaceNbrGetNumConnections Error: handle={handle}, " f"zone_index={zone_index}, return_code={ret}" ) return num_connections.value @requires_symbol("tecZoneFaceNbrGetNumValues") def tec_zone_face_nbr_get_num_values(handle: ctypes.c_void_p, zone_index: int) -> int: """Get the number of face-neighbor connection values for a zone. This is the flat length of the array returned by :func:`tec_zone_face_nbr_get_connections` (or its 64-bit counterpart), not a count of connections, the number of values per connection depends on :func:`tec_zone_face_nbr_get_mode`. Args: handle (ctypes.c_void_p): File handle. zone_index (int): 1-based zone index. Returns: Number of face-neighbor connection values, 0 if the zone has none. Raises: TecioError: On C library error. """ assert lib is not None # narrowed: @requires_symbol already checked num_values = ctypes.c_int64(0) ret = lib.tecZoneFaceNbrGetNumValues( handle, ctypes.c_int32(zone_index), ctypes.byref(num_values) ) if ret != 0: raise TecioError( f"tecZoneFaceNbrGetNumValues Error: handle={handle}, " f"zone_index={zone_index}, return_code={ret}" ) return num_values.value @requires_symbol("tecZoneFaceNbrsAre64Bit") def tec_zone_face_nbrs_are_64bit(handle: ctypes.c_void_p, zone_index: int) -> bool: """Check whether a zone's face-neighbor connections use 64-bit indices. Determines whether to call :func:`tec_zone_face_nbr_get_connections` or :func:`tec_zone_face_nbr_get_connections64`. Args: handle (ctypes.c_void_p): File handle. zone_index (int): 1-based zone index. Returns: True if connections are 64-bit, False if 32-bit. Raises: TecioError: On C library error. """ assert lib is not None # narrowed: @requires_symbol already checked is_64bit = ctypes.c_int32(0) ret = lib.tecZoneFaceNbrsAre64Bit( handle, ctypes.c_int32(zone_index), ctypes.byref(is_64bit) ) if ret != 0: raise TecioError( f"tecZoneFaceNbrsAre64Bit Error: handle={handle}, " f"zone_index={zone_index}, return_code={ret}" ) return bool(is_64bit.value) @requires_symbol("tecZoneFaceNbrGetConnections") def tec_zone_face_nbr_get_connections( handle: ctypes.c_void_p, zone_index: int, num_values: int ) -> npt.NDArray[np.int32]: """Read 32-bit face-neighbor connections for a zone. Args: handle (ctypes.c_void_p): File handle. zone_index (int): 1-based zone index. num_values (int): Flat value count, from :func:`tec_zone_face_nbr_get_num_values`. Returns: Flat array of face-neighbor connection values, dtype int32. Group into individual connections according to :func:`tec_zone_face_nbr_get_mode`. Raises: TecioError: On C library error. """ assert lib is not None # narrowed: @requires_symbol already checked connections = (ctypes.c_int32 * num_values)() ret = lib.tecZoneFaceNbrGetConnections( handle, ctypes.c_int32(zone_index), ctypes.cast(connections, ctypes.POINTER(ctypes.c_int32)), ) if ret != 0: raise TecioError( f"tecZoneFaceNbrGetConnections Error: handle={handle}, " f"zone_index={zone_index}, num_values={num_values}, " f"return_code={ret}" ) return np.ctypeslib.as_array(connections) @requires_symbol("tecZoneFaceNbrGetConnections64") def tec_zone_face_nbr_get_connections_64( handle: ctypes.c_void_p, zone_index: int, num_values: int ) -> npt.NDArray[np.int64]: """Read 64-bit face-neighbor connections for a zone. Args: handle (ctypes.c_void_p): File handle. zone_index (int): 1-based zone index. num_values (int): Flat value count, from :func:`tec_zone_face_nbr_get_num_values`. Returns: Flat array of face-neighbor connection values, dtype int64. Group into individual connections according to :func:`tec_zone_face_nbr_get_mode`. Raises: TecioError: On C library error. """ assert lib is not None # narrowed: @requires_symbol already checked connections = (ctypes.c_int64 * num_values)() ret = lib.tecZoneFaceNbrGetConnections64( handle, ctypes.c_int32(zone_index), ctypes.cast(connections, ctypes.POINTER(ctypes.c_int64)), ) if ret != 0: raise TecioError( f"tecZoneFaceNbrGetConnections64 Error: handle={handle}, " f"zone_index={zone_index}, num_values={num_values}, " f"return_code={ret}" ) return np.ctypeslib.as_array(connections) # -- Reading SZL variable data ---------------------------------------------------------
[docs] @requires_symbol("tecVarGetName") def tec_var_get_name(handle: ctypes.c_void_p, var_index: int) -> str: """Get a variable name by index. Args: handle (ctypes.c_void_p): File handle. var_index (int): 1-based variable index. Returns: Variable name string. Raises: TecioError: On C library error. """ assert lib is not None # narrowed: @requires_symbol already checked var_name = ctypes.c_char_p(0) ret = lib.tecVarGetName(handle, ctypes.c_int32(var_index), ctypes.byref(var_name)) if ret != 0: raise TecioError( f"tecVarGetName Error: handle={handle}, " f"var_index={var_index}, return_code={ret}" ) return _decode(var_name.value)
[docs] @requires_symbol("tecVarIsEnabled") def tec_var_is_enabled(handle: ctypes.c_void_p, var_index: int) -> bool: """Check whether a variable is enabled. Args: handle (ctypes.c_void_p): File handle. var_index (int): 1-based variable index. Returns: True if the variable is enabled. Raises: TecioError: On C library error. """ assert lib is not None # narrowed: @requires_symbol already checked is_enabled = ctypes.c_int32(0) ret = lib.tecVarIsEnabled( handle, ctypes.c_int32(var_index), ctypes.byref(is_enabled) ) if ret != 0: raise TecioError( f"tecVarIsEnabled Error: handle={handle}, " f"var_index={var_index}, return_code={ret}" ) return bool(is_enabled.value)
[docs] @requires_symbol("tecZoneVarGetType") def tec_zone_var_get_type( handle: ctypes.c_void_p, zone_index: int, var_index: int ) -> DataType: """Get the data type for a variable in a zone. Args: handle (ctypes.c_void_p): File handle. zone_index (int): 1-based zone index. var_index (int): 1-based variable index. Returns: :class:`DataType` enum value. Raises: TecioError: On C library error. """ assert lib is not None # narrowed: @requires_symbol already checked var_type = ctypes.c_int32(0) ret = lib.tecZoneVarGetType( handle, ctypes.c_int32(zone_index), ctypes.c_int32(var_index), ctypes.byref(var_type), ) if ret != 0: raise TecioError( f"tecZoneVarGetType Error: handle={handle}, zone_index={zone_index}, " f"var_index={var_index}, return_code={ret}" ) return DataType(var_type.value)
[docs] @requires_symbol("tecZoneVarGetValueLocation") def tec_zone_var_get_value_location( handle: ctypes.c_void_p, zone_index: int, var_index: int ) -> ValueLocation: """Get the value location for a zone variable. Args: handle (ctypes.c_void_p): File handle. zone_index (int): 1-based zone index. var_index (int): 1-based variable index. Returns: :class:`ValueLocation` enum (NODAL or CELL_CENTERED). Raises: TecioError: On C library error. """ assert lib is not None # narrowed: @requires_symbol already checked value_location = ctypes.c_int32(0) ret = lib.tecZoneVarGetValueLocation( handle, ctypes.c_int32(zone_index), ctypes.c_int32(var_index), ctypes.byref(value_location), ) if ret != 0: raise TecioError( f"tecZoneVarGetValueLocation Error: handle={handle}, " f"zone_index={zone_index}, var_index={var_index}, return_code={ret}" ) return ValueLocation(value_location.value)
[docs] @requires_symbol("tecZoneVarIsPassive") def tec_zone_var_is_passive( handle: ctypes.c_void_p, zone_index: int, var_index: int ) -> bool: """Check whether a zone variable is passive. Args: handle (ctypes.c_void_p): File handle. zone_index (int): 1-based zone index. var_index (int): 1-based variable index. Returns: True if the variable is passive in this zone. Raises: TecioError: On C library error. """ assert lib is not None # narrowed: @requires_symbol already checked is_passive = ctypes.c_int32(0) ret = lib.tecZoneVarIsPassive( handle, ctypes.c_int32(zone_index), ctypes.c_int32(var_index), ctypes.byref(is_passive), ) if ret != 0: raise TecioError( f"tecZoneVarIsPassive Error: handle={handle}, zone_index={zone_index}, " f"var_index={var_index}, return_code={ret}" ) return bool(is_passive.value)
[docs] @requires_symbol("tecZoneVarGetSharedZone") def tec_zone_var_get_shared_zone( handle: ctypes.c_void_p, zone_index: int, var_index: int ) -> int | None: """Get the shared zone index for a variable. Args: handle (ctypes.c_void_p): File handle. zone_index (int): 1-based zone index. var_index (int): 1-based variable index. Returns: Shared zone index, or None if not shared. Raises: TecioError: On C library error. """ assert lib is not None # narrowed: @requires_symbol already checked shared_zone = ctypes.c_int32(0) ret = lib.tecZoneVarGetSharedZone( handle, ctypes.c_int32(zone_index), ctypes.c_int32(var_index), ctypes.byref(shared_zone), ) if ret != 0: raise TecioError( f"tecZoneVarGetSharedZone Error: handle={handle}, " f"zone_index={zone_index}, var_index={var_index}, return_code={ret}" ) return shared_zone.value if shared_zone.value != 0 else None
@requires_symbol("tecZoneConnectivityGetSharedZone") def tec_zone_connectivity_get_shared_zone( handle: ctypes.c_void_p, zone_index: int ) -> int | None: """Get the shared zone index for unstructured mesh connectivity data. Args: handle (ctypes.c_void_p): File handle. zone_index (int): 1-based zone index. Returns: Shared zone index, or None if not shared. Raises: TecioError: On C library error. """ assert lib is not None # narrowed: @requires_symbol already checked shared_zone = ctypes.c_int32(0) ret = lib.tecZoneConnectivityGetSharedZone( handle, ctypes.c_int32(zone_index), ctypes.byref(shared_zone), ) if ret != 0: raise TecioError( f"tecZoneConnectivityGetSharedZone Error: handle={handle}, " f"zone_index={zone_index}, return_code={ret}" ) return shared_zone.value if shared_zone.value != 0 else None
[docs] @requires_symbol("tecZoneVarGetNumValues") def tec_zone_var_get_num_values( handle: ctypes.c_void_p, zone_index: int, var_index: int ) -> int: """Query the number of values for a zone variable. Args: handle (ctypes.c_void_p): File handle. zone_index (int): 1-based zone index. var_index (int): 1-based variable index. Returns: Number of values. Raises: TecioError: On C library error. """ assert lib is not None # narrowed: @requires_symbol already checked num_values = ctypes.c_int32(0) ret = lib.tecZoneVarGetNumValues( handle, ctypes.c_int32(zone_index), ctypes.c_int32(var_index), ctypes.byref(num_values), ) if ret != 0: raise TecioError( f"tecZoneVarGetNumValues Error: handle={handle}, " f"zone_index={zone_index}, var_index={var_index}, return_code={ret}" ) return num_values.value
[docs] @requires_symbol("tecZoneVarGetFloatValues") def tec_zone_var_get_float_values( handle: ctypes.c_void_p, zone_index: int, var_index: int, start_index: int, num_values: int, ) -> npt.NDArray[np.float32]: """Read float32 values for a zone variable. Args: handle (ctypes.c_void_p): File handle. zone_index (int): 1-based zone index. var_index (int): 1-based variable index. start_index (int): 1-based start position. num_values (int): Number of values to read. Returns: NumPy float32 array of length *num_values*. Raises: TecioError: On C library error. """ assert lib is not None # narrowed: @requires_symbol already checked values = (ctypes.c_float * num_values)() ret = lib.tecZoneVarGetFloatValues( handle, ctypes.c_int32(zone_index), ctypes.c_int32(var_index), ctypes.c_int64(start_index), ctypes.c_int64(num_values), ctypes.cast( values, ctypes.POINTER(ctypes.c_float), ), ) if ret != 0: raise TecioError( f"tecZoneVarGetFloatValues Error: handle={handle}, " f"zone_index={zone_index}, var_index={var_index}, " f"start_index={start_index}, num_values={num_values}, return_code={ret}" ) return np.ctypeslib.as_array(values)
[docs] @requires_symbol("tecZoneVarGetDoubleValues") def tec_zone_var_get_double_values( handle: ctypes.c_void_p, zone_index: int, var_index: int, start_index: int, num_values: int, ) -> npt.NDArray[np.float64]: """Read float64 values for a zone variable. Args: handle (ctypes.c_void_p): File handle. zone_index (int): 1-based zone index. var_index (int): 1-based variable index. start_index (int): 1-based start position. num_values (int): Number of values to read. Returns: NumPy float64 array of length *num_values*. Raises: TecioError: On C library error. """ assert lib is not None # narrowed: @requires_symbol already checked values = (ctypes.c_double * num_values)() ret = lib.tecZoneVarGetDoubleValues( handle, ctypes.c_int32(zone_index), ctypes.c_int32(var_index), ctypes.c_int64(start_index), ctypes.c_int64(num_values), ctypes.cast( values, ctypes.POINTER(ctypes.c_double), ), ) if ret != 0: raise TecioError( f"tecZoneVarGetDoubleValues Error: handle={handle}, " f"zone_index={zone_index}, var_index={var_index}, " f"start_index={start_index}, num_values={num_values}, return_code={ret}" ) return np.ctypeslib.as_array(values)
[docs] @requires_symbol("tecZoneVarGetInt32Values") def tec_zone_var_get_int32_values( handle: ctypes.c_void_p, zone_index: int, var_index: int, start_index: int, num_values: int, ) -> npt.NDArray[np.int32]: """Read int32 values for a zone variable. Args: handle (ctypes.c_void_p): File handle. zone_index (int): 1-based zone index. var_index (int): 1-based variable index. start_index (int): 1-based start position. num_values (int): Number of values to read. Returns: NumPy int32 array of length *num_values*. Raises: TecioError: On C library error. """ assert lib is not None # narrowed: @requires_symbol already checked values = (ctypes.c_int32 * num_values)() ret = lib.tecZoneVarGetInt32Values( handle, ctypes.c_int32(zone_index), ctypes.c_int32(var_index), ctypes.c_int64(start_index), ctypes.c_int64(num_values), ctypes.cast( values, ctypes.POINTER(ctypes.c_int32), ), ) if ret != 0: raise TecioError( f"tecZoneVarGetInt32Values Error: handle={handle}, " f"zone_index={zone_index}, var_index={var_index}, " f"start_index={start_index}, num_values={num_values}, return_code={ret}" ) return np.ctypeslib.as_array(values)
[docs] @requires_symbol("tecZoneVarGetInt16Values") def tec_zone_var_get_int16_values( handle: ctypes.c_void_p, zone_index: int, var_index: int, start_index: int, num_values: int, ) -> npt.NDArray[np.int16]: """Read int16 values for a zone variable. Args: handle (ctypes.c_void_p): File handle. zone_index (int): 1-based zone index. var_index (int): 1-based variable index. start_index (int): 1-based start position. num_values (int): Number of values to read. Returns: NumPy int16 array of length *num_values*. Raises: TecioError: On C library error. """ assert lib is not None # narrowed: @requires_symbol already checked values = (ctypes.c_int16 * num_values)() ret = lib.tecZoneVarGetInt16Values( handle, ctypes.c_int32(zone_index), ctypes.c_int32(var_index), ctypes.c_int64(start_index), ctypes.c_int64(num_values), ctypes.cast( values, ctypes.POINTER(ctypes.c_int16), ), ) if ret != 0: raise TecioError( f"tecZoneVarGetInt16Values Error: handle={handle}, " f"zone_index={zone_index}, var_index={var_index}, " f"start_index={start_index}, num_values={num_values}, return_code={ret}" ) return np.ctypeslib.as_array(values)
[docs] @requires_symbol("tecZoneVarGetUInt8Values") def tec_zone_var_get_uint8_values( handle: ctypes.c_void_p, zone_index: int, var_index: int, start_index: int, num_values: int, ) -> npt.NDArray[np.uint8]: """Read uint8 values for a zone variable. Args: handle (ctypes.c_void_p): File handle. zone_index (int): 1-based zone index. var_index (int): 1-based variable index. start_index (int): 1-based start position. num_values (int): Number of values to read. Returns: NumPy uint8 array of length *num_values*. Raises: TecioError: On C library error. """ assert lib is not None # narrowed: @requires_symbol already checked values = (ctypes.c_uint8 * num_values)() ret = lib.tecZoneVarGetUInt8Values( handle, ctypes.c_int32(zone_index), ctypes.c_int32(var_index), ctypes.c_int64(start_index), ctypes.c_int64(num_values), ctypes.cast( values, ctypes.POINTER(ctypes.c_uint8), ), ) if ret != 0: raise TecioError( f"tecZoneVarGetUInt8Values Error: handle={handle}, " f"zone_index={zone_index}, var_index={var_index}, " f"start_index={start_index}, num_values={num_values}, return_code={ret}" ) return np.ctypeslib.as_array(values)
# -- Reading SZL aux data --------------------------------------------------------------
[docs] @requires_symbol("tecDataSetAuxDataGetNumItems") def tec_data_set_aux_data_get_num_items(handle: ctypes.c_void_p) -> int: """Get the number of dataset-level auxiliary data items. Args: handle (ctypes.c_void_p): File handle. Returns: Number of auxiliary data items. Raises: TecioError: On C library error. """ assert lib is not None # narrowed: @requires_symbol already checked num_auxdata_items = ctypes.c_int32(0) ret = lib.tecDataSetAuxDataGetNumItems(handle, ctypes.byref(num_auxdata_items)) if ret != 0: raise TecioError( f"tecDataSetAuxDataGetNumItems Error: handle={handle}, return_code={ret}" ) return num_auxdata_items.value
[docs] @requires_symbol("tecDataSetAuxDataGetItem") def tec_data_set_aux_data_get_item( handle: ctypes.c_void_p, item_index: int ) -> tuple[str, str]: """Read a dataset-level auxiliary data item. Args: handle (ctypes.c_void_p): File handle. item_index (int): 1-based item index. Returns: ``(name, value)`` string tuple. Raises: TecioError: On C library error. """ assert lib is not None # narrowed: @requires_symbol already checked name = ctypes.c_char_p(0) value = ctypes.c_char_p(0) ret = lib.tecDataSetAuxDataGetItem( handle, ctypes.c_int32(item_index), ctypes.byref(name), ctypes.byref(value), ) if ret != 0: raise TecioError( f"tecDataSetAuxDataGetItem Error: handle={handle}, " f"item_index={item_index}, return_code={ret}" ) return _decode(name.value), _decode(value.value)
[docs] @requires_symbol("tecVarAuxDataGetNumItems") def tec_var_aux_data_get_num_items(handle: ctypes.c_void_p, var_index: int) -> int: """Get the number of auxiliary data items for a variable. Args: handle (ctypes.c_void_p): File handle. var_index (int): 1-based variable index. Returns: Number of auxiliary data items. Raises: TecioError: On C library error. """ assert lib is not None # narrowed: @requires_symbol already checked num_items = ctypes.c_int32(0) ret = lib.tecVarAuxDataGetNumItems( handle, ctypes.c_int32(var_index), ctypes.byref(num_items) ) if ret != 0: raise TecioError( f"tecVarAuxDataGetNumItems Error: handle={handle}, " f"var_index={var_index}, return_code={ret}" ) return num_items.value
[docs] @requires_symbol("tecVarAuxDataGetItem") def tec_var_aux_data_get_item( handle: ctypes.c_void_p, var_index: int, item_index: int ) -> tuple[str, str]: """Read a variable-level auxiliary data item. Args: handle (ctypes.c_void_p): File handle. var_index (int): 1-based variable index. item_index (int): 1-based item index. Returns: ``(name, value)`` string tuple. Raises: TecioError: On C library error. """ assert lib is not None # narrowed: @requires_symbol already checked name = ctypes.c_char_p(0) value = ctypes.c_char_p(0) ret = lib.tecVarAuxDataGetItem( handle, ctypes.c_int32(var_index), ctypes.c_int32(item_index), ctypes.byref(name), ctypes.byref(value), ) if ret != 0: raise TecioError( f"tecVarAuxDataGetItem Error: handle={handle}, var_index={var_index}, " f"item_index={item_index}, return_code={ret}" ) return _decode(name.value), _decode(value.value)
[docs] @requires_symbol("tecZoneAuxDataGetNumItems") def tec_zone_aux_data_get_num_items(handle: ctypes.c_void_p, zone_index: int) -> int: """Get the number of auxiliary data items for a zone. Args: handle (ctypes.c_void_p): File handle. zone_index (int): 1-based zone index. Returns: Number of auxiliary data items. Raises: TecioError: On C library error. """ assert lib is not None # narrowed: @requires_symbol already checked num_items = ctypes.c_int32(0) ret = lib.tecZoneAuxDataGetNumItems( handle, ctypes.c_int32(zone_index), ctypes.byref(num_items) ) if ret != 0: raise TecioError( f"tecZoneAuxDataGetNumItems Error: handle={handle}, " f"zone_index={zone_index}, return_code={ret}" ) return num_items.value
[docs] @requires_symbol("tecZoneAuxDataGetItem") def tec_zone_aux_data_get_item( handle: ctypes.c_void_p, zone_index: int, item_index: int ) -> tuple[str, str]: """Read a zone-level auxiliary data item. Args: handle (ctypes.c_void_p): File handle. zone_index (int): 1-based zone index. item_index (int): 1-based item index. Returns: ``(name, value)`` string tuple. Raises: TecioError: On C library error. """ assert lib is not None # narrowed: @requires_symbol already checked name = ctypes.c_char_p(0) value = ctypes.c_char_p(0) ret = lib.tecZoneAuxDataGetItem( handle, ctypes.c_int32(zone_index), ctypes.c_int32(item_index), ctypes.byref(name), ctypes.byref(value), ) if ret != 0: raise TecioError( f"tecZoneAuxDataGetItem Error: handle={handle}, zone_index={zone_index}, " f"item_index={item_index}, return_code={ret}" ) return _decode(name.value), _decode(value.value)
# -------------------------------------------------------------------------------------- # New write API (SZL/.szplt): # - tec_file_writer_open returns an explicit file handle that is passed to every # subsequent call, making the target file unambiguous # - Multiple files can be written simultaneously by holding multiple handles at once # tec_zone_create_ijk / tec_zone_create_fe append a new zone record and return a # 1-based zone index # - Variable data, node maps, aux data, and unsteady options are written by referencing # the file handle + zone/variable index, so they can be written in any order after # zone creation # - tec_file_writer_close finalizes and flushes the file # -------------------------------------------------------------------------------------- # -- Initialization and File Handling --------------------------------------------------
[docs] @requires_symbol("tecFileWriterOpen") def tec_file_writer_open( filename: str, variables: Sequence[str], title: str = "Untitled", file_type: FileType = FileType.FULL, use_szl: int = 1, grid_file_handle: ctypes.c_void_p | None = None, ) -> ctypes.c_void_p: """Open a writer handle for creating SZL files. Args: filename (str): Output file path. variables (Sequence[str]): Variable name list. title (str): Dataset title. file_type (FileType): File type enum. use_szl (int): SZL flag (1 to use SZL format). grid_file_handle (ctypes.c_void_p | None): Optional handle to an existing grid file for solution-only output. Returns: Opaque writer handle for subsequent write calls. Raises: TecioError: On C library error. TypeError: If *file_type* is not a :class:`FileType`. """ assert lib is not None # narrowed: @requires_symbol already checked if not isinstance(file_type, FileType): raise TypeError("file_type must be a libtecio.FileType enum") assert all(len(v) <= 128 for v in variables), "Variables limited to 128 characters" varstring = ", ".join(variables) handle = ctypes.c_void_p() ret = lib.tecFileWriterOpen( ctypes.c_char_p(filename.encode("utf-8")), ctypes.c_char_p(title.encode("utf-8")), ctypes.c_char_p(varstring.encode("utf-8")), ctypes.c_int32(use_szl), ctypes.c_int32(file_type.value), ctypes.c_int32(0), grid_file_handle if grid_file_handle is not None else None, ctypes.byref(handle), ) if ret != 0: raise TecioError( f"tecFileWriterOpen Error: file_name={filename!r}, title={title!r}, " f"variables={variables!r}, file_type={file_type!r}, return_code={ret}" ) return handle
[docs] @requires_symbol("tecFileWriterClose") def tec_file_writer_close(handle: ctypes.c_void_p) -> None: """Close a writer handle and finalise the output file. Args: handle (ctypes.c_void_p): Writer handle. Raises: TecioError: On C library error. """ assert lib is not None # narrowed: @requires_symbol already checked ret = lib.tecFileWriterClose(ctypes.byref(handle)) if ret != 0: raise TecioError( f"tecFileWriterClose Error: handle={handle}, return_code={ret}" )
[docs] @requires_symbol("tecFileWriterFlush") def tec_file_writer_flush( handle: ctypes.c_void_p, num_zones_to_retain: int = 0, zones_to_retain: Sequence[int] | None = None, ) -> None: """Flush written zone data to a temporary intermediate file. Args: handle (ctypes.c_void_p): Writer handle. num_zones_to_retain (int): Number of zones to keep in memory. zones_to_retain (Sequence[int] | None): 1-based zone indices to retain. Raises: TecioError: On C library error. Important: SZL Only! Note: Used to reduce memory usage for large files. All zone data written so far, other than any zones listed in ``zones_to_retain``, is written out to a temporary file on disk and released from memory. Note: Retained zones can still be modified. Note: Temporary files created by flushing are merged into the final output file when :func:`tec_file_writer_close` is called. """ assert lib is not None # narrowed: @requires_symbol already checked zones_ptr = None if zones_to_retain is not None and len(zones_to_retain) > 0: zones_array = (ctypes.c_int32 * len(zones_to_retain))(*zones_to_retain) zones_ptr = ctypes.cast(zones_array, ctypes.POINTER(ctypes.c_int32)) else: zones_ptr = ctypes.POINTER(ctypes.c_int32)() ret = lib.tecFileWriterFlush( handle, ctypes.c_int32(num_zones_to_retain), zones_ptr, ) if ret != 0: raise TecioError( f"tecFileWriterFlush Error: handle={handle}, " f"num_zones_to_retain={num_zones_to_retain}, " f"zones_to_retain={zones_to_retain}, " f"return_code={ret}" )
# -- Write Zone Headers ----------------------------------------------------------------
[docs] @requires_symbol("tecZoneCreateIJK") def tec_zone_create_ijk( handle: ctypes.c_void_p, zone_title: str, imax: int, jmax: int, kmax: int, var_types: Sequence[DataType | int], var_sharing: Sequence[int] | None = None, value_locations: Sequence[int | ValueLocation] | None = None, pas_vars: Sequence[VarStatus | bool | int] | None = None, face_nbr_sharing: int = 0, num_face_cons: int = 0, face_nbr_mode: FaceNeighborMode | int = FaceNeighborMode.LOCAL_ONE_TO_ONE, ) -> int: """Create an ordered IJK zone for writing. Args: handle (ctypes.c_void_p): Writer handle. zone_title (str): Zone title. imax (int): I dimension. jmax (int): J dimension. kmax (int): K dimension. var_types (Sequence[DataType | int]): Per-variable data types. var_sharing (Sequence[int] | None): Optional per-variable sharing source zones. Must be same length as var_types if provided. None/null means all no variable sharing. value_locations (Sequence[int | ValueLocation] | None): Optional per-variable data locations. pas_vars (Sequence[bool | int] | None): Optional per-variable passive flags or 1/True if passive else 0/False. Must be same length as var_types if provided. None/null means all variables are active. face_nbr_sharing (int): Optional face-neighbor sharing source zone. num_face_cons (int): Optional number of face connections. face_nbr_mode (FaceNeighborMode | int): Optional face-neighbor mode. Returns: 1-based zone index of the created zone. Raises: TecioError: On C library error. """ assert lib is not None # narrowed: @requires_symbol already checked zone_out = ctypes.c_int32() # Create C array for varable types var_types_ptr = (ctypes.c_int32 * len(var_types))(*[ _to_int_value(v, DataType) for v in var_types ]) # Create C array for variable sharing var_sharing_ptr = None if var_sharing is not None: var_sharing_ptr = (ctypes.c_int32 * len(var_sharing))(*list(var_sharing)) # Create C array for value locations value_locations_ptr = None if value_locations is not None: value_locations_ptr = (ctypes.c_int32 * len(value_locations))(*[ _to_int_value(v, ValueLocation) for v in value_locations ]) # Create C array for passive variable flags pas_vars_ptr = None if pas_vars is not None: pas_vars_ptr = (ctypes.c_int32 * len(pas_vars))(*[ _to_int_value(v, Boolean) for v in pas_vars ]) ret = lib.tecZoneCreateIJK( handle, ctypes.c_char_p(zone_title.encode("utf-8")), ctypes.c_int64(imax), ctypes.c_int64(jmax), ctypes.c_int64(kmax), var_types_ptr, var_sharing_ptr, value_locations_ptr, pas_vars_ptr, ctypes.c_int32(face_nbr_sharing), # face neighbor sharing source zone ctypes.c_int64(num_face_cons), # number of face connections ctypes.c_int32( _to_int_value(face_nbr_mode, FaceNeighborMode) ), # face neighbor mode ctypes.byref(zone_out), ) if ret != 0: raise TecioError( f"tecZoneCreateIJK Error: zone_title={zone_title!r}, " f"imax={imax}, jmax={jmax}, kmax={kmax}, " f"var_types_len={len(var_types) if var_types is not None else 0}, " f"return_code={ret}" ) return zone_out.value
[docs] @requires_symbol("tecZoneCreateFE") def tec_zone_create_fe( handle: ctypes.c_void_p, zone_title: str, zone_type: int | ZoneType, num_nodes: int, num_cells: int, var_types: Sequence[DataType | int], var_sharing: Sequence[int] | None = None, value_locations: Sequence[int | ValueLocation] | None = None, pas_vars: Sequence[bool | int] | None = None, con_sharing: int = 0, num_face_cons: int = 0, face_nbr_mode: FaceNeighborMode | int = FaceNeighborMode.LOCAL_ONE_TO_ONE, ) -> int: """Create a finite-element zone for writing. Args: handle (ctypes.c_void_p): Writer handle. zone_title (str): Zone title. zone_type (int | ZoneType): FE zone type. num_nodes (int): Number of nodes. num_cells (int): Number of cells/elements. var_types (Sequence[DataType | int]): Optional per-variable data types. var_sharing (Sequence[int] | None): Optional per-variable sharing source zones. Must be same length as var_types if provided. None/null means all no variable sharing. value_locations (Sequence[int | ValueLocation] | None): Optional per-variable data locations. pas_vars (Sequence[bool | int] | None): Optional per-variable passive flags or 1/True if passive else 0/False. Must be same length as var_types if provided. None/null means all variables are active. con_sharing (int): Optional connectivity sharing source zone (0 = none). Connectivity and/or face neighbors cannot be shared when the face neighbor mode is set to Global. Connectivity cannot be shared between cell-based and face-based finite element zones. num_face_cons (int): Optional number of face connections. face_nbr_mode (FaceNeighborMode | int): Optional face-neighbor mode. Returns: 1-based zone index of the created zone. Raises: TecioError: On C library error. """ assert lib is not None # narrowed: @requires_symbol already checked zone_out = ctypes.c_int32() # Create C array for varable types var_types_ptr = (ctypes.c_int32 * len(var_types))(*[ _to_int_value(v, DataType) for v in var_types ]) # Create C array for variable sharing var_sharing_ptr = None if var_sharing is not None: var_sharing_ptr = (ctypes.c_int32 * len(var_sharing))(*list(var_sharing)) # Create C array for value locations value_locations_ptr = None if value_locations is not None: value_locations_ptr = (ctypes.c_int32 * len(value_locations))(*[ _to_int_value(v, ValueLocation) for v in value_locations ]) # Create C array for passive variable flags pas_vars_ptr = None if pas_vars is not None: pas_vars_ptr = (ctypes.c_int32 * len(pas_vars))(*[ _to_int_value(v, Boolean) for v in pas_vars ]) ret = lib.tecZoneCreateFE( handle, ctypes.c_char_p(zone_title.encode("utf-8")), ctypes.c_int32(_to_int_value(zone_type)), ctypes.c_int64(num_nodes), ctypes.c_int64(num_cells), var_types_ptr, var_sharing_ptr, value_locations_ptr, pas_vars_ptr, ctypes.c_int32(con_sharing), # connectivity sharing ctypes.c_int64(num_face_cons), # num face connections ctypes.c_int32( _to_int_value(face_nbr_mode, FaceNeighborMode) ), # face neighbor mode ctypes.byref(zone_out), ) if ret != 0: raise TecioError( f"tecZoneCreateFE Error: zone_title={zone_title!r}, " f"ZoneType={zone_type!r}, NODES={num_nodes}, CELLS={num_cells}, " f"var_types_len={len(var_types) if var_types is not None else 0}, " f"return_code={ret}" ) return zone_out.value
@requires_symbol("tecZoneCreateFEMixed") def tec_zone_create_fe_mixed( handle: ctypes.c_void_p, zone_title: str, num_nodes: int, cell_shapes_per_section: Sequence[int | FeCellShape], num_elements_per_section: Sequence[int], var_types: Sequence[DataType | int], grid_order_per_section: Sequence[int] | None = None, var_sharing: Sequence[int] | None = None, value_locations: Sequence[int | ValueLocation] | None = None, pas_vars: Sequence[bool | int] | None = None, con_sharing: int = 0, num_face_cons: int = 0, face_nbr_mode: FaceNeighborMode | int = FaceNeighborMode.LOCAL_ONE_TO_ONE, ) -> int: """Create a FEMIXED zone for writing. A FEMIXED zone groups cells into 1-16 sections; every cell within one section shares the same shape and grid order. All sections in a zone must share the same spatial dimensionality (all line, all surface, or all volume cell types), not a mix of them. Args: handle (ctypes.c_void_p): Writer handle. zone_title (str): Zone title. num_nodes (int): Total number of nodes for the zone. cell_shapes_per_section (Sequence[int | FeCellShape]): Cell shape for each section. Length determines the number of sections (1-16). num_elements_per_section (Sequence[int]): Number of elements in each section. Must be the same length as cell_shapes_per_section. var_types (Sequence[DataType | int]): Per-variable data types. grid_order_per_section (Sequence[int] | None): Grid order (1-4) for each section. None defaults to linear (1) for every section. var_sharing (Sequence[int] | None): Optional per-variable sharing source zones. Must be same length as var_types if provided. None means no variable sharing. value_locations (Sequence[int | ValueLocation] | None): Optional per-variable data locations. pas_vars (Sequence[bool | int] | None): Optional per-variable passive flags. Must be same length as var_types if provided. None means all variables are active. con_sharing (int): Optional connectivity sharing source zone (0 = none). num_face_cons (int): Optional number of face connections. face_nbr_mode (FaceNeighborMode | int): Optional face-neighbor mode. Returns: 1-based zone index of the created zone. Raises: TecioError: On C library error. ValueError: If cell_shapes_per_section and num_elements_per_section (or grid_order_per_section, if provided) have mismatched lengths, or there are not between 1 and 16 sections. Note: The basis function per section is always 0 (the only value the C library currently accepts), so it isn't exposed as a parameter here. """ assert lib is not None # narrowed: @requires_symbol already checked num_sections = len(cell_shapes_per_section) if not 1 <= num_sections <= 16: raise ValueError( f"tecZoneCreateFEMixed requires 1-16 sections, got {num_sections}" ) if len(num_elements_per_section) != num_sections: raise ValueError( "cell_shapes_per_section and num_elements_per_section must be " f"the same length ({num_sections} != " f"{len(num_elements_per_section)})" ) if grid_order_per_section is None: grid_order_per_section = [1] * num_sections elif len(grid_order_per_section) != num_sections: raise ValueError( "grid_order_per_section must be the same length as " f"cell_shapes_per_section ({num_sections} != " f"{len(grid_order_per_section)})" ) zone_out = ctypes.c_int32() cell_shapes_ptr = (ctypes.c_int32 * num_sections)(*[ _to_int_value(v, FeCellShape) for v in cell_shapes_per_section ]) grid_order_ptr = (ctypes.c_int32 * num_sections)(*list(grid_order_per_section)) basis_fn_ptr = (ctypes.c_int32 * num_sections)(*([0] * num_sections)) num_elements_ptr = (ctypes.c_int64 * num_sections)(*list(num_elements_per_section)) # Create C array for variable types var_types_ptr = (ctypes.c_int32 * len(var_types))(*[ _to_int_value(v, DataType) for v in var_types ]) # Create C array for variable sharing var_sharing_ptr = None if var_sharing is not None: var_sharing_ptr = (ctypes.c_int32 * len(var_sharing))(*list(var_sharing)) # Create C array for value locations value_locations_ptr = None if value_locations is not None: value_locations_ptr = (ctypes.c_int32 * len(value_locations))(*[ _to_int_value(v, ValueLocation) for v in value_locations ]) # Create C array for passive variable flags pas_vars_ptr = None if pas_vars is not None: pas_vars_ptr = (ctypes.c_int32 * len(pas_vars))(*[ _to_int_value(v, Boolean) for v in pas_vars ]) ret = lib.tecZoneCreateFEMixed( handle, ctypes.c_char_p(zone_title.encode("utf-8")), ctypes.c_int64(num_nodes), ctypes.c_int32(num_sections), cell_shapes_ptr, grid_order_ptr, basis_fn_ptr, num_elements_ptr, var_types_ptr, var_sharing_ptr, value_locations_ptr, pas_vars_ptr, ctypes.c_int32(con_sharing), ctypes.c_int64(num_face_cons), ctypes.c_int32(_to_int_value(face_nbr_mode, FaceNeighborMode)), ctypes.byref(zone_out), ) if ret != 0: raise TecioError( f"tecZoneCreateFEMixed Error: zone_title={zone_title!r}, " f"NODES={num_nodes}, SECTIONS={num_sections}, return_code={ret}" ) return zone_out.value # -- Optional fields -------------------------------------------------------------------
[docs] @requires_symbol("tecZoneSetUnsteadyOptions") def tec_zone_set_unsteady_options( handle: ctypes.c_void_p, zone: int, strand: int = 0, solution_time: float = 0.0 ) -> None: """Set time/strand metadata for a zone. Args: handle (ctypes.c_void_p): Writer handle. zone (int): 1-based zone index. strand (int): Strand ID. solution_time (float): Solution time. Raises: TecioError: On C library error. """ assert lib is not None # narrowed: @requires_symbol already checked ret = lib.tecZoneSetUnsteadyOptions( handle, ctypes.c_int32(zone), ctypes.c_double(solution_time), ctypes.c_int32(strand), ) if ret != 0: raise TecioError( f"tecZoneSetUnsteadyOptions Error: zone={zone}, strand={strand}, " f"solution_time={solution_time}, return_code={ret}" )
[docs] @requires_symbol("tecDataSetAddAuxData") def tec_data_set_add_aux_data( handle: ctypes.c_void_p, name: str, value: str, ) -> None: """Add a dataset-level auxiliary data record. Args: handle (ctypes.c_void_p): Writer handle. name (str): Auxiliary data name. value (str): Auxiliary data value. Raises: TecioError: On C library error. """ assert lib is not None # narrowed: @requires_symbol already checked ret = lib.tecDataSetAddAuxData( handle, ctypes.c_char_p(name.encode("utf-8")), ctypes.c_char_p(value.encode("utf-8")), ) if ret != 0: raise TecioError( f"tecDataSetAddAuxData Error: name={name!r}, value={value!r}, " f"return_code={ret}" )
[docs] @requires_symbol("tecVarAddAuxData") def tec_var_add_aux_data( handle: ctypes.c_void_p, var_index: int, name: str, value: str, ) -> None: """Add a variable-level auxiliary data record. Args: handle (ctypes.c_void_p): Writer handle. var_index (int): 1-based variable index. name (str): Auxiliary data name. value (str): Auxiliary data value. Raises: TecioError: On C library error. """ assert lib is not None # narrowed: @requires_symbol already checked ret = lib.tecVarAddAuxData( handle, ctypes.c_int32(var_index), ctypes.c_char_p(name.encode("utf-8")), ctypes.c_char_p(value.encode("utf-8")), ) if ret != 0: raise TecioError( f"tecVarAddAuxData Error: var_index={var_index}, name={name!r}, " f"value={value!r}, return_code={ret}" )
[docs] @requires_symbol("tecZoneAddAuxData") def tec_zone_add_aux_data( handle: ctypes.c_void_p, zone_index: int, name: str, value: str, ) -> None: """Add a zone-level auxiliary data record. Args: handle (ctypes.c_void_p): Writer handle. zone_index (int): 1-based zone index. name (str): Auxiliary data name. value (str): Auxiliary data value. Raises: TecioError: On C library error. """ assert lib is not None # narrowed: @requires_symbol already checked ret = lib.tecZoneAddAuxData( handle, ctypes.c_int32(zone_index), ctypes.c_char_p(name.encode("utf-8")), ctypes.c_char_p(value.encode("utf-8")), ) if ret != 0: raise TecioError( f"tecZoneAddAuxData Error: zone_index={zone_index}, name={name!r}, " f"value={value!r}, return_code={ret}" )
# -- Write variable value functions ----------------------------------------------------
[docs] @requires_symbol("tecZoneVarWriteDoubleValues") def tec_zone_var_write_double_values( handle: ctypes.c_void_p, zone: int, var: int, values: npt.ArrayLike ) -> None: """Write float64 values for a zone variable. Args: handle (ctypes.c_void_p): Writer handle. zone (int): 1-based zone index. var (int): 1-based variable index. values (npt.ArrayLike): Array of float64 values. Raises: TecioError: On C library error. """ assert lib is not None # narrowed: @requires_symbol already checked ptr, count, _backing = _prepare_array_for_ctypes( values, np.float64, ctypes.c_double ) ret = lib.tecZoneVarWriteDoubleValues( handle, ctypes.c_int32(zone), ctypes.c_int32(var), ctypes.c_int32(0), ctypes.c_int64(count), ptr, ) if ret != 0: raise TecioError( f"tecZoneVarWriteDoubleValues Error: zone={zone}, var={var}, " f"count={count}, return_code={ret}" )
[docs] @requires_symbol("tecZoneVarWriteFloatValues") def tec_zone_var_write_float_values( handle: ctypes.c_void_p, zone: int, var: int, values: npt.ArrayLike ) -> None: """Write float32 values for a zone variable. Args: handle (ctypes.c_void_p): Writer handle. zone (int): 1-based zone index. var (int): 1-based variable index. values (npt.ArrayLike): Array of float32 values. Raises: TecioError: On C library error. """ assert lib is not None # narrowed: @requires_symbol already checked ptr, count, _backing = _prepare_array_for_ctypes(values, np.float32, ctypes.c_float) ret = lib.tecZoneVarWriteFloatValues( handle, ctypes.c_int32(zone), # zone index (1-based) ctypes.c_int32(var), # variable index (1-based) ctypes.c_int32(0), # partition index (MPI) ctypes.c_int64(count), # number of values ptr, ) if ret != 0: raise TecioError( f"tecZoneVarWriteFloatValues Error: zone={zone}, var={var}, " f"count={count}, return_code={ret}" )
[docs] @requires_symbol("tecZoneVarWriteInt32Values") def tec_zone_var_write_int32_values( handle: ctypes.c_void_p, zone: int, var: int, values: npt.ArrayLike ) -> None: """Write int32 values for a zone variable. Args: handle (ctypes.c_void_p): Writer handle. zone (int): 1-based zone index. var (int): 1-based variable index. values (npt.ArrayLike): Array of int32 values. Raises: TecioError: On C library error. """ assert lib is not None # narrowed: @requires_symbol already checked ptr, count, _backing = _prepare_array_for_ctypes(values, np.int32, ctypes.c_int32) ret = lib.tecZoneVarWriteInt32Values( handle, ctypes.c_int32(zone), ctypes.c_int32(var), ctypes.c_int32(0), ctypes.c_int64(count), ptr, ) if ret != 0: raise TecioError( f"tecZoneVarWriteInt32Values Error: zone={zone}, var={var}, " f"count={count}, return_code={ret}" )
[docs] @requires_symbol("tecZoneVarWriteInt16Values") def tec_zone_var_write_int16_values( handle: ctypes.c_void_p, zone: int, var: int, values: npt.ArrayLike ) -> None: """Write int16 values for a zone variable. Args: handle (ctypes.c_void_p): Writer handle. zone (int): 1-based zone index. var (int): 1-based variable index. values (npt.ArrayLike): Array of int16 values. Raises: TecioError: On C library error. """ assert lib is not None # narrowed: @requires_symbol already checked ptr, count, _backing = _prepare_array_for_ctypes(values, np.int16, ctypes.c_int16) ret = lib.tecZoneVarWriteInt16Values( handle, ctypes.c_int32(zone), ctypes.c_int32(var), ctypes.c_int32(0), ctypes.c_int64(count), ptr, ) if ret != 0: raise TecioError( f"tecZoneVarWriteInt16Values Error: zone={zone}, var={var}, " f"count={count}, return_code={ret}" )
[docs] @requires_symbol("tecZoneVarWriteUInt8Values") def tec_zone_var_write_uint8_values( handle: ctypes.c_void_p, zone: int, var: int, values: npt.ArrayLike ) -> None: """Write uint8 values for a zone variable. Args: handle (ctypes.c_void_p): Writer handle. zone (int): 1-based zone index. var (int): 1-based variable index. values (npt.ArrayLike): Array of uint8 values. Raises: TecioError: On C library error. """ assert lib is not None # narrowed: @requires_symbol already checked ptr, count, _backing = _prepare_array_for_ctypes(values, np.uint8, ctypes.c_uint8) ret = lib.tecZoneVarWriteUInt8Values( handle, ctypes.c_int32(zone), ctypes.c_int32(var), ctypes.c_int32(0), ctypes.c_int64(count), ptr, ) if ret != 0: raise TecioError( f"tecZoneVarWriteUInt8Values Error: zone={zone}, var={var}, " f"count={count}, return_code={ret}" )
# -- Write Zone Connectivity (FE zones only) -------------------------------------------
[docs] @requires_symbol("tecZoneNodeMapWrite32") def tec_zone_node_map_write32( handle: ctypes.c_void_p, zone: int, nodes: npt.ArrayLike, partition: int = 0, is_one_based: bool | int = True, ) -> None: """Write 32-bit node map entries for an FE zone. Args: handle (ctypes.c_void_p): Writer handle. zone (int): 1-based zone index. nodes (npt.ArrayLike): Array of int32 node indices. partition (int): Partition index (0 for non-partitioned). is_one_based (bool | int): Whether indices are 1-based. Raises: TecioError: On C library error. Note: Use for zones with fewer than ~2 billion node map entries. Note: Can be called multiple times per zone; total entries must match zone definition. Note: Node indices are 1-based by convention in Tecplot. """ assert lib is not None # narrowed: @requires_symbol already checked ptr, count, _backing = _prepare_array_for_ctypes(nodes, np.int32, ctypes.c_int32) ret = lib.tecZoneNodeMapWrite32( handle, ctypes.c_int32(zone), ctypes.c_int32(partition), ctypes.c_int32(_to_int_value(is_one_based, Boolean)), ctypes.c_int64(count), ptr, ) if ret != 0: raise TecioError( f"tecZoneNodeMapWrite32 Error: zone={zone}, partition={partition}, " f"count={count}, return_code={ret}" )
[docs] @requires_symbol("tecZoneNodeMapWrite64") def tec_zone_node_map_write64( handle: ctypes.c_void_p, zone: int, nodes: npt.ArrayLike, partition: int = 0, is_one_based: bool | int = True, ) -> None: """Write 64-bit node map entries for an FE zone. Args: handle (ctypes.c_void_p): Writer handle. zone (int): 1-based zone index. nodes (npt.ArrayLike): Array of int64 node indices. partition (int): Partition index (0 for non-partitioned). is_one_based (bool | int): Whether indices are 1-based. Raises: TecioError: On C library error. Note: Use for zones with fewer than ~2 billion node map entries. Note: Can be called multiple times per zone; total entries must match zone definition. Note: Node indices are 1-based by convention in Tecplot. """ assert lib is not None # narrowed: @requires_symbol already checked ptr, count, _backing = _prepare_array_for_ctypes(nodes, np.int64, ctypes.c_int64) ret = lib.tecZoneNodeMapWrite64( handle, ctypes.c_int32(zone), ctypes.c_int32(partition), ctypes.c_int32(_to_int_value(is_one_based, Boolean)), ctypes.c_int64(count), ptr, ) if ret != 0: raise TecioError( f"tecZoneNodeMapWrite64 Error: zone={zone}, partition={partition}, " f"count={count}, return_code={ret}" )
[docs] @requires_symbol("tecZoneFaceNbrWriteConnections32") def tec_zone_face_nbr_write_connections32( handle: ctypes.c_void_p, zone: int, face_neighbors: npt.ArrayLike, ) -> None: """Write 32-bit face-neighbor connections for an FE zone. Args: handle (ctypes.c_void_p): Writer handle. zone (int): 1-based zone index. face_neighbors (npt.ArrayLike): Array of int32 face-neighbor indices. Raises: TecioError: On C library error. Note: ``num_face_cons`` and ``face_nbr_mode`` must be set when creating the zone via :func:`tec_zone_create_ijk` or :func:`tec_zone_create_fe`. Note: Use for zones with fewer than ~2 billion face neighbor entries. Note: Can be called multiple times. Total entries must match num_face_cons declared at zone creation. Note: Face neighbors have expensive performance implications. Use face neighbors only to manually specify connections that are not defined via the connectivity list. """ assert lib is not None # narrowed: @requires_symbol already checked ptr, count, _backing = _prepare_array_for_ctypes( face_neighbors, np.int32, ctypes.c_int32 ) ret = lib.tecZoneFaceNbrWriteConnections32( handle, ctypes.c_int32(zone), ptr, ) if ret != 0: raise TecioError( f"tecZoneFaceNbrWriteConnections32 Error: zone={zone}, " f"count={count}, return_code={ret}" )
[docs] @requires_symbol("tecZoneFaceNbrWriteConnections64") def tec_zone_face_nbr_write_connections64( handle: ctypes.c_void_p, zone: int, face_neighbors: npt.ArrayLike, ) -> None: """Write 64-bit face-neighbor connections for an FE zone. Args: handle (ctypes.c_void_p): Writer handle. zone (int): 1-based zone index. face_neighbors (npt.ArrayLike): Array of int64 face-neighbor indices. Raises: TecioError: On C library error. Note: ``num_face_cons`` and ``face_nbr_mode`` must be set when creating the zone via :func:`tec_zone_create_ijk` or :func:`tec_zone_create_fe`. Note: Use for zones with more than ~2 billion face neighbor entries. Note: Can be called multiple times. Total entries must match num_face_cons declared at zone creation. Note: Face neighbors have expensive performance implications. Use face neighbors only to manually specify connections that are not defined via the connectivity list. """ assert lib is not None # narrowed: @requires_symbol already checked ptr, count, _backing = _prepare_array_for_ctypes( face_neighbors, np.int64, ctypes.c_int64 ) ret = lib.tecZoneFaceNbrWriteConnections64( handle, ctypes.c_int32(zone), ptr, ) if ret != 0: raise TecioError( f"tecZoneFaceNbrWriteConnections64 Error: zone={zone}, " f"count={count}, return_code={ret}" )
# -------------------------------------------------------------------------------------- # Classic API (PLT/.plt AND SZL/.szplt): # - No handle is returned — the library maintains a single implicit global file context # - Only one file can be active at a time; tecfil142 must be called to switch between # files if writing multiple files simultainously # - tecini142 initializes the file and sets the global context; all subsequent calls # implicitly target this file # - Zone records (teczne142), data (tecdat142), and node maps (tecnode142) must be # written strictly in order — each zone's header followed immediately by its data # before the next zone is declared # - tecend142 finalizes and closes the active file # -------------------------------------------------------------------------------------- # -- File initialization and finalization ----------------------------------------------
[docs] @requires_symbol("tecini142") def tecini142( filename: str, variables: Sequence[str], title: str = "Untitled", scratch_dir: str = ".", file_format: int | FileFormat = FileFormat.PLT, file_type: int | FileType = FileType.FULL, debug: int | Debug = Debug.FALSE, vis_double: int | DataType = DataType.DOUBLE, ) -> None: """Initialise a Tecplot data file (classic API). Args: filename (str): Output file path. Supports PLT and SZPLT extensions. variables (Sequence[str]): Variable name list. title (str): Dataset title. scratch_dir (str): Scratch directory for temporary files. file_format (int | FileFormat): FileFormat.PLT (0) or FileFormat.SZPLT (1) file_type (int | FileType): FileType.FULL (0), GRID (1), or SOLUTION (2) debug (int | Debug): Debug.FALSE (0) or Debug.TRUE (1) vis_double (int | DataType): DataType.DOUBLE (1) or DataType.FLOAT (0). PLT files do not suport integer zone variables. Use the new API functions to create integer zone variables for SZPLT files. Raises: TecioError: On C library error. TypeError: If *file_type* is not a :class:`FileType`. Note: Must be called before any zone or data operations Note: Call :func:`tecend142()` to finalize the file """ assert lib is not None # narrowed: @requires_symbol already checked if not isinstance(file_type, FileType): raise TypeError("file_type must be a libtecio.FileType enum") assert all(len(v) <= 128 for v in variables), "Variables limited to 128 characters" varstring = ", ".join(variables) vis_double_c = ctypes.c_int32( 1 if _to_int_value(vis_double) == DataType.DOUBLE.value else 0 ) ret = lib.tecini142( ctypes.c_char_p(title.encode("utf-8")), ctypes.c_char_p(varstring.encode("utf-8")), ctypes.c_char_p(filename.encode("utf-8")), ctypes.c_char_p(scratch_dir.encode("utf-8")), ctypes.c_int32(_to_int_value(file_format)), ctypes.c_int32(_to_int_value(file_type)), ctypes.c_int32(_to_int_value(debug)), vis_double_c, ) if ret != 0: raise TecioError(f"tecini142 Error: filename={filename!r}, return_code={ret}")
[docs] @requires_symbol("tecend142") def tecend142() -> None: """Finalise and close the active Tecplot data file. Raises: TecioError: On C library error. Note: Must be called after all data has been written Note: Flushes all pending data and closes the file """ assert lib is not None # narrowed: @requires_symbol already checked ret = lib.tecend142() if ret != 0: raise TecioError(f"tecend142 Error: return_code={ret}")
[docs] @requires_symbol("tecflush142") def tecflush142( num_zones_to_retain: int = 0, zones_to_retain: Sequence[int] | None = None, ) -> None: """Flush data to disk, optionally retaining zones in memory (SZL only). Args: num_zones_to_retain (int): Number of zones to keep in memory. zones_to_retain (Sequence[int] | None): 1-based zone indices to retain. Raises: TecioError: On C library error. Important: SZL Only! Note: Used to reduce memory usage for large files. Note: Retained zones can still be modified. """ assert lib is not None # narrowed: @requires_symbol already checked num_zones_c = ctypes.c_int32(num_zones_to_retain) zones_ptr = None if zones_to_retain is not None and len(zones_to_retain) > 0: zones_array = (ctypes.c_int32 * len(zones_to_retain))(*zones_to_retain) zones_ptr = ctypes.cast(zones_array, ctypes.POINTER(ctypes.c_int32)) else: zones_ptr = ctypes.POINTER(ctypes.c_int32)() ret = lib.tecflush142( ctypes.byref(num_zones_c), zones_ptr, ) if ret != 0: raise TecioError(f"tecflush142 Error: return_code={ret}")
[docs] @requires_symbol("tecfil142") def tecfil142() -> int: """Get the file handle for the current output file. Returns: File handle integer. Raises: TecioError: On C library error. Note: Used for advanced file operations. """ assert lib is not None # narrowed: @requires_symbol already checked output_file_handle = ctypes.c_int32(0) ret = lib.tecfil142(ctypes.byref(output_file_handle)) if ret != 0: raise TecioError(f"tecfil142 Error: return_code={ret}") return output_file_handle.value
[docs] @requires_symbol("tecforeign142") def tecforeign142(output_foreign_byte_order: int) -> None: """Set foreign byte order for output. Args: output_foreign_byte_order (int): 0 = native, 1 = foreign. Raises: TecioError: On C library error. """ assert lib is not None # narrowed: @requires_symbol already checked foreign_c = ctypes.c_int32(output_foreign_byte_order) ret = lib.tecforeign142(ctypes.byref(foreign_c)) if ret != 0: raise TecioError(f"tecforeign142 Error: return_code={ret}")
# -- Zone creation ---------------------------------------------------------------------
[docs] @requires_symbol("teczne142") def teczne142( zone_title: str, zone_type: int | ZoneType, imax: int, jmax: int, kmax: int, var_sharing: Sequence[int] | None = None, value_locations: Sequence[int | ValueLocation] | None = None, pas_vars: Sequence[int | VarStatus] | None = None, con_sharing: int = 0, strand: int = 0, solution_time: float = 0.0, num_face_connections: int = 0, face_nbr_mode: int | FaceNeighborMode = FaceNeighborMode.LOCAL_ONE_TO_ONE, total_num_face_nodes: int = 0, num_connected_boundary_faces: int = 0, total_num_boundary_connections: int = 0, ) -> None: """Create a new zone in the active file (classic API). Args: zone_title (str): Zone title. zone_type (int | ZoneType): Zone type enum or integer (0=ORDERED, 1=FELINESEG, etc.). imax (int): I dimension (or num nodes for FE). jmax (int): J dimension (or num elements for FE). kmax (int): K dimension or NumFaces for FEPOLYGON and FEPOLYHEDRON. Not used for all other finite element zone types. var_sharing (Sequence[int] | None): List of zone indices to share variables from (0: No sharing, Null: no variables are shared from other zones) value_locations (Sequence[int | ValueLocation] | None): Per-variable data locations. pas_vars (Sequence[int | VarStatus] | None): List of VarStatus enums or 0/1 for passive variables. Must be same length as var_sharing if provided. None/null means all variables are active. con_sharing (int): Connectivity sharing source zone number. strand (int): Strand ID for transient data (0 for static data, positive integer for transient data). solution_time (float): Solution time. num_face_connections (int): Number of face connections (for cell-based FE zones only. The number of face connections that will be passed to ``tecface142``). face_nbr_mode (int | FaceNeighborMode): FaceNeighborMode enum. Used for cell-based FE and ordered zones only. Type of face connection that will be passed in routine ``tecface142``. total_num_face_nodes (int): Total face nodes (poly zones). num_connected_boundary_faces (int): Boundary faces (poly zones). total_num_boundary_connections (int): Boundary connections (poly zones). Raises: TecioError: On C library error. Hint: For ORDERED zones: imx, jmx, kmx are dimensions. Note: For FE zones: imax=NumNodes, jmax=NumElements, kmax=0 (unless higher order element) """ assert lib is not None # narrowed: @requires_symbol already checked # Create C array for passive variable flags pas_vars_ptr = None if pas_vars is not None: pas_vars_ptr = (ctypes.c_int32 * len(pas_vars))(*[ _to_int_value(v, Boolean) for v in pas_vars ]) # Create C array for value locations value_locations_ptr = None if value_locations is not None: value_locations_ptr = (ctypes.c_int32 * len(value_locations))(*[ _to_int_value(v, ValueLocation) for v in value_locations ]) # Create C array for variable sharing var_sharing_ptr = None if var_sharing is not None: var_sharing_ptr = (ctypes.c_int32 * len(var_sharing))(*list(var_sharing)) ret = lib.teczne142( ctypes.c_char_p(zone_title.encode("utf-8")), ctypes.c_int32(_to_int_value(zone_type)), ctypes.c_int32(imax), ctypes.c_int32(jmax), ctypes.c_int32(kmax), ctypes.c_int32(0), # I-cell dimension (Reserved for future use. Set to zero) ctypes.c_int32(0), # J-cell dimension (Reserved for future use. Set to zero) ctypes.c_int32(0), # K-cell dimension (Reserved for future use. Set to zero) ctypes.c_double(solution_time), ctypes.c_int32(strand), ctypes.c_int32(0), # Deprecated. Enter 0 for this value ctypes.c_int32(_to_int_value(DataPacking.BLOCK)), # Deprecated. Always set to 1 ctypes.c_int32(num_face_connections), ctypes.c_int32(_to_int_value(face_nbr_mode)), ctypes.c_int32(total_num_face_nodes), ctypes.c_int32(num_connected_boundary_faces), ctypes.c_int32(total_num_boundary_connections), pas_vars_ptr, value_locations_ptr, var_sharing_ptr, ctypes.c_int32(con_sharing), ) if ret != 0: raise TecioError( f"teczne142 Error: zone_title={zone_title!r}, return_code={ret}" )
[docs] @requires_symbol("tecpolyzne142") def tecpolyzne142( zone_title: str, zone_type: int | ZoneType, num_nodes: int, num_faces: int, num_elements: int, var_sharing: Sequence[int] | None = None, value_locations: Sequence[int | ValueLocation] | None = None, pas_vars: Sequence[int | VarStatus] | None = None, con_sharing: int = 0, strand: int = 0, solution_time: float = 0.0, total_num_face_nodes: int = 0, num_connected_boundary_faces: int = 0, total_num_boundary_connections: int = 0, ) -> None: """Create a polygonal or polyhedral zone (classic API). Args: zone_title (str): Zone title. zone_type (int | ZoneType): ``ZoneType.FEPOLYGON`` or ``ZoneType.FEPOLYHEDRON``. num_nodes (int): Number of nodes. num_faces (int): Number of faces. num_elements (int): Number of elements. var_sharing (Sequence[int] | None): List of zone indices to share variables from (0: No sharing, Null: no variables are shared from other zones). Must be same length as value_locations and pas_vars if provided. value_locations (Sequence[int | ValueLocation] | None): Per-variable data locations. pas_vars (Sequence[int | VarStatus] | None): ist of VarStatus enums or 0/1 for passive variables. Must be same length as value_locations and var_sharing if provided. None/null means all variables are active. con_sharing (int): Connectivity sharing source zone. strand (int): Strand ID for transient data (0 for static data, positive integer for transient data). solution_time (float): Solution time for transient data. total_num_face_nodes (int): Total face nodes. num_connected_boundary_faces (int): Boundary faces. total_num_boundary_connections (int): Boundary connections. Raises: TecioError: On C library error. """ assert lib is not None # narrowed: @requires_symbol already checked # Create C array for passive variable flags pas_vars_ptr = None if pas_vars is not None: pas_vars_ptr = (ctypes.c_int32 * len(pas_vars))(*[ _to_int_value(v, Boolean) for v in pas_vars ]) # Create C array for value locations value_locations_ptr = None if value_locations is not None: value_locations_ptr = (ctypes.c_int32 * len(value_locations))(*[ _to_int_value(v, ValueLocation) for v in value_locations ]) # Create C array for variable sharing var_sharing_ptr = None if var_sharing is not None: var_sharing_ptr = (ctypes.c_int32 * len(var_sharing))(*list(var_sharing)) ret = lib.tecpolyzne142( ctypes.c_char_p(zone_title.encode("utf-8")), ctypes.c_int32(_to_int_value(zone_type)), ctypes.c_int32(num_nodes), ctypes.c_int32(num_elements), ctypes.c_int64(num_faces), ctypes.c_int64(total_num_face_nodes), ctypes.c_double(solution_time), ctypes.c_int32(strand), ctypes.c_int32(0), # Parent zone deprecated. ctypes.c_int32(num_connected_boundary_faces), ctypes.c_int32(total_num_boundary_connections), pas_vars_ptr, value_locations_ptr, var_sharing_ptr, ctypes.c_int32(con_sharing), ) if ret != 0: raise TecioError( f"tecpolyzne142 Error: zone_title={zone_title!r}, return_code={ret}" )
[docs] @requires_symbol("tecznefemixed142") def tecznefemixed142( zone_title: str, num_nodes: int, cell_shapes_per_section: Sequence[int | FeCellShape], num_elements_per_section: Sequence[int], grid_order_per_section: Sequence[int] | None = None, solution_time: float = 0.0, strand_id: int = 0, num_face_connections: int = 0, face_neighbor_mode: int | FaceNeighborMode = FaceNeighborMode.LOCAL_ONE_TO_ONE, passive_var_list: Sequence[int | VarStatus] | None = None, value_location: Sequence[int | ValueLocation] | None = None, share_var_from_zone: Sequence[int] | None = None, share_connectivity_from_zone: int = 0, ) -> None: """Create a FEMIXED zone (classic API). A FEMIXED zone groups cells into 1-16 sections; every cell within one section shares the same shape and grid order. All sections in a zone must share the same spatial dimensionality (all line, all surface, or all volume cell types), not a mix of them. Args: zone_title (str): Zone title. num_nodes (int): Total number of nodes for the zone. cell_shapes_per_section (Sequence[int | FeCellShape]): Cell shape for each section. Length determines the number of sections (1-16). num_elements_per_section (Sequence[int]): Number of elements in each section. Must be the same length as cell_shapes_per_section. grid_order_per_section (Sequence[int] | None): Grid order (1-4) for each section. None defaults to linear (1) for every section. solution_time (float): Solution time. strand_id (int): Strand ID for transient data (0 for static data, positive integer for transient data). num_face_connections (int): Number of face connections that will be passed to ``tecface142``. face_neighbor_mode (int | FaceNeighborMode): Face-neighbor mode. passive_var_list (Sequence[int | VarStatus] | None): List of VarStatus enums or 0/1 for passive variables. None means all variables are active. value_location (Sequence[int | ValueLocation] | None): Per-variable data locations. None means all variables are nodal. share_var_from_zone (Sequence[int] | None): List of zone indices to share variables from. None means no variable sharing. share_connectivity_from_zone (int): Zone index to share connectivity from (0 = none). Raises: TecioError: On C library error. ValueError: If cell_shapes_per_section and num_elements_per_section (or grid_order_per_section, if provided) have mismatched lengths, or there are not between 1 and 16 sections. Note: The basis function per section is always 0 (the only value the C library currently accepts), so it isn't exposed as a parameter here. """ assert lib is not None # narrowed: @requires_symbol already checked num_sections = len(cell_shapes_per_section) if not 1 <= num_sections <= 16: raise ValueError(f"tecznefemixed142 requires 1-16 sections, got {num_sections}") if len(num_elements_per_section) != num_sections: raise ValueError( "cell_shapes_per_section and num_elements_per_section must be " f"the same length ({num_sections} != " f"{len(num_elements_per_section)})" ) if grid_order_per_section is None: grid_order_per_section = [1] * num_sections elif len(grid_order_per_section) != num_sections: raise ValueError( "grid_order_per_section must be the same length as " f"cell_shapes_per_section ({num_sections} != " f"{len(grid_order_per_section)})" ) cell_shapes_ptr = (ctypes.c_int32 * num_sections)(*[ _to_int_value(v, FeCellShape) for v in cell_shapes_per_section ]) grid_order_ptr = (ctypes.c_int32 * num_sections)(*list(grid_order_per_section)) basis_fn_ptr = (ctypes.c_int32 * num_sections)(*([0] * num_sections)) num_elements_ptr = (ctypes.c_int64 * num_sections)(*list(num_elements_per_section)) # Create C array for passive variable flags pas_vars_ptr = None if passive_var_list is not None: pas_vars_ptr = (ctypes.c_int32 * len(passive_var_list))(*[ _to_int_value(v, Boolean) for v in passive_var_list ]) # Create C array for value locations value_loc_ptr = None if value_location is not None: value_loc_ptr = (ctypes.c_int32 * len(value_location))(*[ _to_int_value(v, ValueLocation) for v in value_location ]) # Create C array for variable sharing share_var_ptr = None if share_var_from_zone is not None: share_var_ptr = (ctypes.c_int32 * len(share_var_from_zone))( *list(share_var_from_zone) ) ret = lib.tecznefemixed142( ctypes.c_char_p(zone_title.encode("utf-8")), ctypes.c_int64(num_nodes), ctypes.c_int32(num_sections), cell_shapes_ptr, grid_order_ptr, basis_fn_ptr, num_elements_ptr, ctypes.c_double(solution_time), ctypes.c_int32(strand_id), ctypes.c_int32(num_face_connections), ctypes.c_int32(_to_int_value(face_neighbor_mode)), pas_vars_ptr, value_loc_ptr, share_var_ptr, ctypes.c_int32(share_connectivity_from_zone), ) if ret != 0: raise TecioError( f"tecznefemixed142 Error: zone_title={zone_title!r}, return_code={ret}" )
# -- Data writing ----------------------------------------------------------------------
[docs] @requires_symbol("tecdat142") def tecdat142( field_data: npt.ArrayLike, is_double: bool = True, ) -> None: """Write field data to the current zone (classic API). Args: field_data (npt.ArrayLike): Array of field values. is_double (bool): True for double precision, False for single. Raises: TecioError: On C library error. Important: Data must be written in the order specified by dataset variables and zone definition Hint: If variable is shared or passive, skip writing data for that variable Note: For ORDERED zones: data should be ordered with the I dimension varying fastest, then J, then K Note: For FE zones: data should be ordered by node index for nodal variables, and by element index for cell-centered variables """ assert lib is not None # narrowed: @requires_symbol already checked # Convert to appropriate numpy array if is_double: arr = np.ascontiguousarray(field_data, dtype=np.float64) data_ptr = arr.ctypes.data_as(ctypes.c_void_p) is_double_c = ctypes.c_int32(1) else: arr = np.ascontiguousarray(field_data, dtype=np.float32) data_ptr = arr.ctypes.data_as(ctypes.c_void_p) is_double_c = ctypes.c_int32(0) ret = lib.tecdat142( ctypes.c_int32(arr.size), data_ptr, is_double_c, ) if ret != 0: raise TecioError( f"tecdat142 Error: n={arr.size}, is_double={is_double}, return_code={ret}" )
# -- Connectivity writing --------------------------------------------------------------
[docs] @requires_symbol("tecnode142") def tecnode142(nodes: npt.ArrayLike) -> None: """Write node connectivity for an FE zone (classic API). Args: nodes (npt.ArrayLike): Array of 1-based node indices. Raises: TecioError: On C library error. Important: Node indices are 1-based (Fortran convention) Hint: - For FEBRICK elements: 8 nodes per element. - For FETETRAHEDRON elements: 4 nodes per element. """ assert lib is not None # narrowed: @requires_symbol already checked nodes_array = np.ascontiguousarray(nodes, dtype=np.int32) n = ctypes.c_int32(nodes_array.size) nodes_ptr = nodes_array.ctypes.data_as(ctypes.POINTER(ctypes.c_int32)) ret = lib.tecnode142( ctypes.byref(n), nodes_ptr, ) if ret != 0: raise TecioError( f"tecnode142 Error: n_nodes={nodes_array.size}, return_code={ret}" )
[docs] @requires_symbol("tecface142") def tecface142(face_connections: npt.ArrayLike) -> None: """Write face-neighbor connections (classic API). Args: face_connections (npt.ArrayLike): Array of face connection data. Raises: TecioError: On C library error. Note: Used to specify face-to-face connectivity between zones. """ assert lib is not None # narrowed: @requires_symbol already checked face_conn_array = np.ascontiguousarray(face_connections, dtype=np.int32) face_conn_ptr = face_conn_array.ctypes.data_as(ctypes.POINTER(ctypes.c_int32)) ret = lib.tecface142(face_conn_ptr) if ret != 0: raise TecioError(f"tecface142 Error: return_code={ret}")
[docs] @requires_symbol("tecpolyface142") def tecpolyface142( face_node_counts: npt.ArrayLike | None, face_nodes: npt.ArrayLike, face_left_elems: npt.ArrayLike, face_right_elems: npt.ArrayLike, num_faces: int | None = None, ) -> None: """Write face data for polygonal/polyhedral zones (classic API). Args: face_node_counts (npt.ArrayLike | None): Number of nodes per face, or ``None`` for a polygonal zone (every face has two nodes). face_nodes (npt.ArrayLike): Concatenated face node indices. face_left_elems (npt.ArrayLike): Left element per face. face_right_elems (npt.ArrayLike): Right element per face. num_faces (int | None): Number of faces, required when ``face_node_counts`` is ``None``. Raises: TecioError: On C library error. ValueError: If ``face_node_counts`` and ``num_faces`` are both ``None``. Note: ``face_node_counts`` has one entry per face. Note: ``face_nodes`` is a concatenated list of all face node indices. Hint: Element indices are 1-based; 0 indicates boundary. """ assert lib is not None # narrowed: @requires_symbol already checked face_nodes_array = np.ascontiguousarray(face_nodes, dtype=np.int32) face_left_elems_array = np.ascontiguousarray(face_left_elems, dtype=np.int32) face_right_elems_array = np.ascontiguousarray(face_right_elems, dtype=np.int32) face_node_counts_ptr = None if face_node_counts is None: if num_faces is None: raise ValueError("num_faces is required when face_node_counts is None") else: face_node_counts_array = np.ascontiguousarray(face_node_counts, dtype=np.int32) num_faces = face_node_counts_array.size face_node_counts_ptr = face_node_counts_array.ctypes.data_as( ctypes.POINTER(ctypes.c_int32) ) num_faces_c = ctypes.c_int32(num_faces) face_nodes_ptr = face_nodes_array.ctypes.data_as(ctypes.POINTER(ctypes.c_int32)) face_left_elems_ptr = face_left_elems_array.ctypes.data_as( ctypes.POINTER(ctypes.c_int32) ) face_right_elems_ptr = face_right_elems_array.ctypes.data_as( ctypes.POINTER(ctypes.c_int32) ) ret = lib.tecpolyface142( ctypes.byref(num_faces_c), face_node_counts_ptr, face_nodes_ptr, face_left_elems_ptr, face_right_elems_ptr, ) if ret != 0: raise TecioError( f"tecpolyface142 Error: num_faces={num_faces}, return_code={ret}" )
[docs] @requires_symbol("tecpolybconn142") def tecpolybconn142( boundary_connection_counts: npt.ArrayLike, boundary_connection_elems: npt.ArrayLike, boundary_connection_zones: npt.ArrayLike, ) -> None: """Write boundary connections for poly zones (classic API). Args: boundary_connection_counts (npt.ArrayLike): Connections per boundary face. boundary_connection_elems (npt.ArrayLike): 1-based element index of every connection, concatenated over the boundary faces. boundary_connection_zones (npt.ArrayLike): 1-based zone number of every connection, same length as ``boundary_connection_elems``. Required: TecIO crashes the process on a null array. A zone must already exist (the current zone counts), so a connection cannot point to a later zone. Raises: TecioError: On C library error. ValueError: If the array lengths are inconsistent. TecIO reads the arrays without a bounds check, so a short array would be read past its end. Note: Used to specify connectivity to neighboring zones at boundaries. """ assert lib is not None # narrowed: @requires_symbol already checked bconn_counts_array = np.ascontiguousarray( boundary_connection_counts, dtype=np.int32 ) bconn_elems_array = np.ascontiguousarray(boundary_connection_elems, dtype=np.int32) total = int(bconn_counts_array.sum()) if bconn_elems_array.size != total: raise ValueError( f"boundary_connection_elems has {bconn_elems_array.size} entries but " f"boundary_connection_counts sums to {total}." ) num_boundary_faces = ctypes.c_int32(bconn_counts_array.size) bconn_counts_ptr = bconn_counts_array.ctypes.data_as(ctypes.POINTER(ctypes.c_int32)) bconn_elems_ptr = bconn_elems_array.ctypes.data_as(ctypes.POINTER(ctypes.c_int32)) # TecIO reads the zone numbers as INT32, not INT16 as the Fortran documentation # states: an int16 array is read as pairs and yields garbage zone numbers. bconn_zones_array = np.ascontiguousarray(boundary_connection_zones, dtype=np.int32) if bconn_zones_array.size != total: raise ValueError( f"boundary_connection_zones has {bconn_zones_array.size} entries but " f"boundary_connection_counts sums to {total}." ) bconn_zones_ptr = bconn_zones_array.ctypes.data_as(ctypes.POINTER(ctypes.c_int32)) ret = lib.tecpolybconn142( ctypes.byref(num_boundary_faces), bconn_counts_ptr, bconn_elems_ptr, bconn_zones_ptr, ) if ret != 0: raise TecioError( f"tecpolybconn142 Error: num_boundary_faces={bconn_counts_array.size}, " f"return_code={ret}" )
# -- Auxiliary data --------------------------------------------------------------------
[docs] @requires_symbol("tecauxstr142") def tecauxstr142(name: str, value: str) -> None: """Add dataset-level auxiliary data (classic API). Args: name (str): Auxiliary data name. value (str): Auxiliary data value. Raises: TecioError: On C library error. Note: Must be called after ``tecini142`` but before first ``teczne142``. """ assert lib is not None # narrowed: @requires_symbol already checked ret = lib.tecauxstr142( ctypes.c_char_p(name.encode("utf-8")), ctypes.c_char_p(value.encode("utf-8")), ) if ret != 0: raise TecioError( f"tecauxstr142 Error: name={name!r}, value={value!r}, return_code={ret}" )
[docs] @requires_symbol("tecvauxstr142") def tecvauxstr142(var: int, name: str, value: str) -> None: """Add variable-level auxiliary data (classic API). Args: var (int): 1-based variable index. name (str): Auxiliary data name. value (str): Auxiliary data value. Raises: TecioError: On C library error. Note: Must be called after ``tecini142`` but before first ``teczne142``. """ assert lib is not None # narrowed: @requires_symbol already checked var_c = ctypes.c_int32(var) ret = lib.tecvauxstr142( ctypes.byref(var_c), ctypes.c_char_p(name.encode("utf-8")), ctypes.c_char_p(value.encode("utf-8")), ) if ret != 0: raise TecioError( f"tecvauxstr142 Error: var={var}, name={name!r}, value={value!r}, " f"return_code={ret}" )
[docs] @requires_symbol("teczauxstr142") def teczauxstr142(name: str, value: str) -> None: """Add zone-level auxiliary data (classic API). Args: name (str): Auxiliary data name. value (str): Auxiliary data value. Raises: TecioError: On C library error. Note: Must be called after ``teczne142`` for the current zone. """ assert lib is not None # narrowed: @requires_symbol already checked ret = lib.teczauxstr142( ctypes.c_char_p(name.encode("utf-8")), ctypes.c_char_p(value.encode("utf-8")), ) if ret != 0: raise TecioError( f"teczauxstr142 Error: name={name!r}, value={value!r}, return_code={ret}" )
# -- User-defined data (custom records) ------------------------------------------------
[docs] @requires_symbol("tecusr142") def tecusr142(user_rec: str) -> None: """Write a user-defined data record (classic API). Args: user_rec (str): User-defined data string. Raises: TecioError: On C library error. Note: Used to write custom data records into the file. Data is preserved but not interpreted by Tecplot """ assert lib is not None # narrowed: @requires_symbol already checked ret = lib.tecusr142(ctypes.c_char_p(user_rec.encode("utf-8"))) if ret != 0: raise TecioError(f"tecusr142 Error: user_rec={user_rec!r}, return_code={ret}")