tecio-python 0.4.1__py3-none-any.whl → 0.4.2__py3-none-any.whl

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (35) hide show
  1. tecio/__init__.py +42 -1
  2. tecio/_constants.py +2 -2
  3. tecio/_dat_write.py +32 -0
  4. tecio/_elements.py +1311 -0
  5. tecio/_io.py +49 -4
  6. tecio/_meta.py +8 -0
  7. tecio/_plt_write.py +32 -0
  8. tecio/_reader.py +157 -3
  9. tecio/_szl_read.py +99 -3
  10. tecio/_szl_write.py +261 -0
  11. tecio/_utils.py +10 -10
  12. tecio/_writer.py +234 -3
  13. tecio/cli/tec2mat.py +20 -0
  14. tecio/cli/tecaux.py +11 -1
  15. tecio/cli/tecdump.py +24 -1
  16. tecio/cli/tecelretyp.py +1096 -0
  17. tecio/cli/tecextract.py +21 -2
  18. tecio/cli/tecfix.py +16 -1
  19. tecio/cli/tecmerge.py +226 -34
  20. tecio/cli/teconvert.py +12 -2
  21. tecio/cli/tecscale.py +16 -1
  22. tecio/cli/tecslice.py +24 -3
  23. tecio/libtecio.py +75 -6
  24. {tecio_python-0.4.1.data → tecio_python-0.4.2.data}/data/share/tecio/plugins/paraview/TecplotTecioReader.py +1 -1
  25. {tecio_python-0.4.1.dist-info → tecio_python-0.4.2.dist-info}/METADATA +9 -9
  26. tecio_python-0.4.2.dist-info/RECORD +40 -0
  27. {tecio_python-0.4.1.dist-info → tecio_python-0.4.2.dist-info}/entry_points.txt +1 -0
  28. tecio_python-0.4.1.dist-info/RECORD +0 -38
  29. {tecio_python-0.4.1.data → tecio_python-0.4.2.data}/data/share/tecio/plugins/matlab/contourfe.m +0 -0
  30. {tecio_python-0.4.1.data → tecio_python-0.4.2.data}/data/share/tecio/plugins/matlab/tecmat2struct.m +0 -0
  31. {tecio_python-0.4.1.data → tecio_python-0.4.2.data}/data/share/tecio/plugins/paraview/TecplotTecioWriter.py +0 -0
  32. {tecio_python-0.4.1.dist-info → tecio_python-0.4.2.dist-info}/WHEEL +0 -0
  33. {tecio_python-0.4.1.dist-info → tecio_python-0.4.2.dist-info}/licenses/LICENSE +0 -0
  34. {tecio_python-0.4.1.dist-info → tecio_python-0.4.2.dist-info}/licenses/NOTICE +0 -0
  35. {tecio_python-0.4.1.dist-info → tecio_python-0.4.2.dist-info}/top_level.txt +0 -0
tecio/_szl_write.py CHANGED
@@ -18,6 +18,7 @@ from ._constants import (
18
18
  DataPacking,
19
19
  DataType,
20
20
  FaceNeighborMode,
21
+ FeCellShape,
21
22
  FileType,
22
23
  ValueLocation,
23
24
  ZoneType,
@@ -25,12 +26,14 @@ from ._constants import (
25
26
  from ._meta import ZoneMeta
26
27
  from ._writer import (
27
28
  PassiveVarsSpec,
29
+ PreparedFEMixedZone,
28
30
  PreparedFEZone,
29
31
  PreparedOrderedZone,
30
32
  TecplotWriter,
31
33
  VarSharingSpec,
32
34
  normalize_precision,
33
35
  prepare_fe_zone,
36
+ prepare_femixed_zone,
34
37
  prepare_ordered_zone,
35
38
  var_sharing_for_libtecio,
36
39
  zone_for_libtecio,
@@ -236,6 +239,38 @@ def _write_connectivity(
236
239
  )
237
240
 
238
241
 
242
+ def _write_femixed_connectivity(
243
+ handle: ctypes.c_void_p,
244
+ zone_num: int,
245
+ node_maps: Sequence[npt.NDArray],
246
+ num_nodes: int,
247
+ ) -> None:
248
+ """Write the section node maps of a FEMIXED zone, in section order.
249
+
250
+ All sections of a zone share one integer width, 64 bit only when *num_nodes* does
251
+ not fit 32 bits. Each section is converted to 1-based indices of that width in a
252
+ single pass, so at most one section is copied at a time.
253
+
254
+ Args:
255
+ handle (ctypes.c_void_p): C library file handle.
256
+ zone_num (int): 1-based zone index.
257
+ node_maps (Sequence[npt.NDArray]): 0-based ``(num_cells, nodes_per_cell)`` array
258
+ of each section.
259
+ num_nodes (int): Zone node count.
260
+ """
261
+ wide = num_nodes > np.iinfo(np.int32).max
262
+ dtype = np.int64 if wide else np.int32
263
+ write = (
264
+ libtecio.tec_zone_node_map_write64
265
+ if wide
266
+ else libtecio.tec_zone_node_map_write32
267
+ )
268
+ for node_map in node_maps:
269
+ if node_map.size:
270
+ one_based = np.add(node_map, 1, dtype=dtype, casting="unsafe")
271
+ write(handle, zone_num, one_based.ravel(order="C"))
272
+
273
+
239
274
  def _write_zone_aux_data(
240
275
  handle: ctypes.c_void_p, aux: dict[int, dict[str, Any]]
241
276
  ) -> None:
@@ -975,6 +1010,232 @@ class TecplotSzlWriter(TecplotWriter):
975
1010
  )
976
1011
  )
977
1012
 
1013
+ # -- FEMIXED zone writer -----------------------------------------------------------
1014
+
1015
+ def write_femixed_zone(
1016
+ self,
1017
+ data: Sequence[npt.ArrayLike],
1018
+ cell_shapes: Sequence[FeCellShape | int | str] | None = None,
1019
+ node_maps: Sequence[npt.ArrayLike] | None = None,
1020
+ *,
1021
+ title: str | None = None,
1022
+ variables: list[str] | None = None,
1023
+ value_locations: Sequence[ValueLocation] | None = None,
1024
+ passive_vars: PassiveVarsSpec | None = None,
1025
+ var_sharing: VarSharingSpec | None = None,
1026
+ con_sharing: int | None = None,
1027
+ solution_time: float = 0.0,
1028
+ strand_id: int = 0,
1029
+ aux: dict[str, Any] | None = None,
1030
+ datapacking: DataPacking | str = DataPacking.BLOCK,
1031
+ flush: bool = False,
1032
+ ) -> None:
1033
+ """Write a complete FEMIXED (mixed finite-element) zone.
1034
+
1035
+ A FEMIXED zone holds 1 to 16 sections, each with one cell shape. A typical use
1036
+ is a CFD volume mesh of tetrahedra, pyramids, prisms and hexahedra in one zone
1037
+ rather than every cell padded to a brick. All sections must have the same
1038
+ spatial dimension (all line, all surface or all volume cells). Cells are
1039
+ numbered through the sections in order, so a CELL_CENTERED array lists the cells
1040
+ of the first section first. Only linear (grid order 1) cells are supported.
1041
+
1042
+ Node and cell counts are inferred from *node_maps*, or from the zone referenced
1043
+ by *con_sharing*. The 32- or 64-bit write path is chosen from the node count.
1044
+ This writer does not write face-neighbor connections.
1045
+
1046
+ Args:
1047
+ data (Sequence[npt.ArrayLike]):
1048
+ Sequence of 1-D arrays, one per active (non-passive, non-shared) dataset
1049
+ variable, in dataset order. NODAL arrays must have length ``num_nodes``,
1050
+ CELL_CENTERED arrays the total cell count over all sections.
1051
+ cell_shapes (Sequence[FeCellShape]):
1052
+ Cell shape of each section. A shape name or value is also accepted.
1053
+ Required unless ``con_sharing`` is set, in which case it must be omitted.
1054
+ node_maps (Sequence[npt.ArrayLike]):
1055
+ One integer array per section, of shape ``(num_cells, nodes_per_cell)``
1056
+ with 0-based node indices. A flat array is reshaped. A section may have
1057
+ no cells. Required unless ``con_sharing`` is set, in which case it must
1058
+ be omitted.
1059
+ title (str):
1060
+ Zone title string. Defaults to ``"FEMixed_Zone_{index}"``, this zone's
1061
+ 0-based index.
1062
+ variables (list[str]):
1063
+ Variable name list. Required only when the file has not been opened yet
1064
+ (lazy-open path). Defaults to ``[V1, V2, V3, ...]``.
1065
+ value_locations (Sequence[ValueLocation]):
1066
+ Per-active-variable :class:`~tecio.ValueLocation`. Defaults to all
1067
+ ``NODAL``.
1068
+ passive_vars (list | tuple | set | None):
1069
+ Variables to mark passive: a list, tuple, or set of variable names, or
1070
+ of 0-based indices. Defaults to all active.
1071
+ var_sharing (Mapping[int | str, int]):
1072
+ Variables to share from another zone: a ``{variable: source zone}``
1073
+ mapping, name or 0-based index to 0-based zone index.
1074
+ con_sharing (int):
1075
+ Optional index of a FEMIXED zone to share the connectivity of. The first
1076
+ zone in a dataset must own its connectivity.
1077
+ solution_time (float):
1078
+ Solution time for transient data. Defaults to ``0.0``.
1079
+ strand_id (int):
1080
+ Strand ID for transient data, ``0`` for static zones.
1081
+ aux (dict[str, str | float | int]):
1082
+ Zone-level auxiliary data as ``{name: value}`` pairs.
1083
+ datapacking (DataPacking | str):
1084
+ Only :attr:`~tecio.DataPacking.BLOCK` (the default) is supported.
1085
+ flush:
1086
+ If ``True``, flush this zone and all previous data to a temporary
1087
+ intermediate file after writing, releasing data from memory.
1088
+
1089
+ Raises:
1090
+ NotImplementedError:
1091
+ If *datapacking* is :attr:`~tecio.DataPacking.POINT`.
1092
+ ValueError:
1093
+ On a bad section layout or array shape, sections of different spatial
1094
+ dimension, fewer dataset variables than the cell dimension, a variable
1095
+ count or array length mismatch, or a bad ``con_sharing`` or
1096
+ ``var_sharing`` source zone. See
1097
+ :func:`~tecio._writer.prepare_femixed_zone`.
1098
+ TypeError:
1099
+ If *passive_vars*/*var_sharing* isn't a list/tuple/set/mapping as
1100
+ appropriate, or mixes variable names and indices.
1101
+ KeyError:
1102
+ A *passive_vars*/*var_sharing* name doesn't match any dataset variable.
1103
+ IndexError:
1104
+ A *passive_vars*/*var_sharing* index is out of range.
1105
+ RuntimeError:
1106
+ If the writer has been closed.
1107
+
1108
+ Note:
1109
+ SZPLT reorders cells and nodes internally for storage, so the arrays read
1110
+ back may be a permutation of the arrays written, consistently across all
1111
+ variables and the node maps.
1112
+ """
1113
+ # Validate input
1114
+ if isinstance(datapacking, str):
1115
+ try:
1116
+ datapacking = DataPacking[datapacking.upper()]
1117
+ except KeyError:
1118
+ raise ValueError(
1119
+ f"datapacking={datapacking!r} is not a recognised value; "
1120
+ "use DataPacking.BLOCK or the string 'BLOCK'."
1121
+ ) from None
1122
+ if datapacking != DataPacking.BLOCK:
1123
+ raise NotImplementedError(
1124
+ "DATAPACKING=POINT is an ASCII-only layout and is not supported "
1125
+ "by the SZL binary format. Use DataPacking.BLOCK (the default) "
1126
+ "or write to a .dat file instead."
1127
+ )
1128
+
1129
+ arrays: list[npt.NDArray] = [np.asarray(arr) for arr in data]
1130
+ if title is None:
1131
+ title = f"FEMixed_Zone_{self.current_zone + 1}"
1132
+ if variables is None:
1133
+ variables = [f"V{i}" for i in range(1, len(data) + 1)]
1134
+
1135
+ # Open the file if lazily loaded and flush buffered aux data
1136
+ if self.handle is None:
1137
+ self._open(variables)
1138
+ if self.current_zone == -1:
1139
+ self.flush_aux()
1140
+
1141
+ variable_types = [
1142
+ _resolve_written_type(_infer_data_type(arr.dtype), self.precision)
1143
+ for arr in arrays
1144
+ ]
1145
+ prepared: PreparedFEMixedZone | None = prepare_femixed_zone(
1146
+ arrays,
1147
+ variable_types,
1148
+ cell_shapes=cell_shapes,
1149
+ node_maps=node_maps,
1150
+ value_locations=value_locations,
1151
+ passive_vars=passive_vars,
1152
+ var_sharing=var_sharing,
1153
+ con_sharing=con_sharing,
1154
+ dataset_variables=self._check_variables(),
1155
+ meta=self._meta,
1156
+ )
1157
+ if prepared is None:
1158
+ return
1159
+ share_idx = prepared.var_sharing
1160
+
1161
+ # Write zone header. The C library assigns and returns a 1-based zone
1162
+ # number; converted to 0-based for the public current_zone attribute.
1163
+ self.current_zone = (
1164
+ libtecio.tec_zone_create_fe_mixed(
1165
+ self._check_handle(),
1166
+ title,
1167
+ prepared.num_nodes,
1168
+ prepared.section_shapes,
1169
+ prepared.section_num_elements,
1170
+ var_types=prepared.variable_types_global,
1171
+ var_sharing=var_sharing_for_libtecio(share_idx),
1172
+ value_locations=prepared.value_locations_global,
1173
+ pas_vars=prepared.passive_vars,
1174
+ con_sharing=zone_for_libtecio(prepared.con_sharing),
1175
+ )
1176
+ - 1
1177
+ )
1178
+ zone_num = self.current_zone + 1
1179
+
1180
+ # Unsteady options
1181
+ if strand_id != 0 or solution_time != 0.0:
1182
+ libtecio.tec_zone_set_unsteady_options(
1183
+ handle=self._check_handle(),
1184
+ zone=zone_num,
1185
+ strand=strand_id,
1186
+ solution_time=solution_time,
1187
+ )
1188
+
1189
+ # Write zone-level aux data
1190
+ if aux is not None:
1191
+ _write_zone_aux_data(self._check_handle(), {zone_num: aux})
1192
+
1193
+ # Write active data only
1194
+ for var_idx, arr, dtype in zip(
1195
+ prepared.active_var_idx, arrays, variable_types, strict=True
1196
+ ):
1197
+ self.current_var = var_idx
1198
+ _write_data(
1199
+ self._check_handle(),
1200
+ zone_num=zone_num,
1201
+ var_num=var_idx + 1,
1202
+ data=arr,
1203
+ dt=dtype,
1204
+ )
1205
+
1206
+ # Write connectivity (if not shared)
1207
+ if prepared.con_sharing is None:
1208
+ _write_femixed_connectivity(
1209
+ self._check_handle(),
1210
+ zone_num,
1211
+ prepared.section_node_maps,
1212
+ prepared.num_nodes,
1213
+ )
1214
+
1215
+ # Flush zone data, releasing memory
1216
+ if flush:
1217
+ libtecio.tec_file_writer_flush(self._check_handle())
1218
+
1219
+ # Finally set zone metadata after successfully completing TecIO calls
1220
+ self._meta.record_zone(
1221
+ ZoneMeta(
1222
+ index=self.current_zone,
1223
+ title=title,
1224
+ zone_type=ZoneType.FEMIXED,
1225
+ solution_time=solution_time,
1226
+ strand_id=strand_id,
1227
+ num_aux_items=len(aux) if aux else 0,
1228
+ num_nodes=prepared.num_nodes,
1229
+ num_elements=prepared.num_cells,
1230
+ section_shapes=prepared.section_shapes,
1231
+ section_num_elements=prepared.section_num_elements,
1232
+ value_locations=tuple(prepared.value_locations_global),
1233
+ passive_vars=tuple(bool(p) for p in prepared.passive_vars),
1234
+ shared_vars=tuple(share_idx),
1235
+ data_types=tuple(prepared.variable_types_global),
1236
+ )
1237
+ )
1238
+
978
1239
  def write_poly_zone(
979
1240
  self,
980
1241
  data: Sequence[npt.ArrayLike],
tecio/_utils.py CHANGED
@@ -33,7 +33,7 @@ _TEC_EXECUTABLE_ALIASES = (
33
33
  _VERSION_REGEX = re.compile(r"(20\d{2})\s*[Rr]\s*(\d+)")
34
34
 
35
35
 
36
- def public_dir(obj: object) -> list[str]:
36
+ def public_dir(obj: object) -> list[str]: # pragma: no cover
37
37
  """Return ``dir(obj)`` without single underscore (private) names.
38
38
 
39
39
  Dunder names are kept so that introspection tools keep working. Attribute access
@@ -46,7 +46,7 @@ def public_dir(obj: object) -> list[str]:
46
46
  ]
47
47
 
48
48
 
49
- def _run_which(cmd: str) -> str | None:
49
+ def _run_which(cmd: str) -> str | None: # pragma: no cover - environment-dependent
50
50
  """Run `which cmd` explicitly as a fallback.
51
51
 
52
52
  Returns:
@@ -67,7 +67,7 @@ def _run_which(cmd: str) -> str | None:
67
67
  return path if path else None
68
68
 
69
69
 
70
- def _find_tec_executable() -> str:
70
+ def _find_tec_executable() -> str: # pragma: no cover - environment-dependent
71
71
  """Locate Tecplot executable using multiple strategies.
72
72
 
73
73
  Returns:
@@ -128,7 +128,7 @@ def _find_tec_executable() -> str:
128
128
  )
129
129
 
130
130
 
131
- def _extract_version_from_path(path: str) -> str | None:
131
+ def _extract_version_from_path(path: str) -> str | None: # pragma: no cover
132
132
  """Extract Tecplot version YYYYR# from a filesystem path.
133
133
 
134
134
  Returns:
@@ -141,7 +141,7 @@ def _extract_version_from_path(path: str) -> str | None:
141
141
  return None
142
142
 
143
143
 
144
- def _extract_version_from_executable(exe_path: str) -> str | None:
144
+ def _extract_version_from_executable(exe_path: str) -> str | None: # pragma: no cover
145
145
  """Ask Tecplot executable for its version.
146
146
 
147
147
  Returns:
@@ -166,12 +166,12 @@ def _extract_version_from_executable(exe_path: str) -> str | None:
166
166
  return None
167
167
 
168
168
 
169
- def get_tec_exe() -> str:
169
+ def get_tec_exe() -> str: # pragma: no cover - environment-dependent
170
170
  """Return absolute path to Tecplot executable."""
171
171
  return _find_tec_executable()
172
172
 
173
173
 
174
- def get_tec_bin() -> str:
174
+ def get_tec_bin() -> str: # pragma: no cover - environment-dependent
175
175
  """Return Tecplot bin directory.
176
176
 
177
177
  - macOS: Contents/Frameworks
@@ -214,7 +214,7 @@ def get_tec_bin() -> str:
214
214
  return bin_dir
215
215
 
216
216
 
217
- def get_tecio_lib() -> str:
217
+ def get_tecio_lib() -> str: # pragma: no cover - environment-dependent
218
218
  """Return full path to the TecIO shared library.
219
219
 
220
220
  Search order:
@@ -374,7 +374,7 @@ def requires_symbol(
374
374
  "this symbol."
375
375
  )
376
376
 
377
- return unavailable_func # ty: ignore[invalid-return-type]
377
+ return unavailable_func # ty: ignore[invalid-explicit-return]
378
378
 
379
379
  return decorator
380
380
 
@@ -416,7 +416,7 @@ def get_tec_version() -> str:
416
416
  def convert_to_szl(
417
417
  input_path: str | os.PathLike,
418
418
  output_path: str | os.PathLike | None = None,
419
- ) -> Path:
419
+ ) -> Path: # pragma: no cover
420
420
  """Convert a Tecplot data file to SZL (``.szplt``) format from the command line.
421
421
 
422
422
  Returns:
tecio/_writer.py CHANGED
@@ -3,7 +3,8 @@
3
3
  Every format's writer (SZL, PLT, DAT) exposes the same lifecycle: construct with a path
4
4
  and optional variable list (eager or lazy open), buffer auxiliary data with
5
5
  :meth:`~TecplotWriter.add_auxdataset_dict`/ :meth:`~TecplotWriter.add_auxvar_dict`,
6
- write zones with ``write_ordered_zone``/ ``write_fe_zone``/ ``write_poly_zone``, and
6
+ write zones with ``write_ordered_zone``/ ``write_fe_zone``/ ``write_femixed_zone``/
7
+ ``write_poly_zone``, and
7
8
  close (directly or via context manager). This module defines the parts of that
8
9
  lifecycle that are identical across formats once, so the three writers can no longer
9
10
  drift apart the way the readers had.
@@ -43,10 +44,12 @@ from ._constants import (
43
44
  DataPacking,
44
45
  DataType,
45
46
  FaceNeighborMode,
47
+ FeCellShape,
46
48
  FileType,
47
49
  ValueLocation,
48
50
  ZoneType,
49
51
  )
52
+ from ._elements import CELL_SHAPE_DIMENSION, CELL_SHAPE_NUM_NODES
50
53
  from ._meta import WriterMeta
51
54
  from ._utils import public_dir
52
55
 
@@ -193,7 +196,7 @@ def validate_face_neighbors(
193
196
  """
194
197
  faces_per_cell = _FACES_PER_ELEM.get(zone_type)
195
198
  if faces_per_cell is None:
196
- return # poly/mixed zones: no fixed face count, not this function's job
199
+ return # poly/FEMIXED zones: no fixed face count, not this function's job
197
200
 
198
201
  def check_cell(cz: int, pos: int) -> None:
199
202
  if not 0 <= cz < num_cells:
@@ -1036,6 +1039,214 @@ def prepare_fe_zone(
1036
1039
  )
1037
1040
 
1038
1041
 
1042
+ @dataclass
1043
+ class PreparedFEMixedZone:
1044
+ """Validated, normalized inputs for writing one FEMIXED zone.
1045
+
1046
+ Everything a writer needs to proceed straight to its zone-creation call, already
1047
+ validated and shape-consistent.
1048
+ """
1049
+
1050
+ value_locations: list[ValueLocation]
1051
+ passive_vars: list[bool]
1052
+ var_sharing: list[int | None]
1053
+ con_sharing: int | None
1054
+ active_var_idx: list[int] # 0-based dataset indices being written now
1055
+ num_nodes: int
1056
+ num_cells: int
1057
+ section_shapes: tuple[FeCellShape, ...]
1058
+ section_num_elements: tuple[int, ...]
1059
+ section_node_maps: list[npt.NDArray] # empty when connectivity is shared
1060
+ value_locations_global: list[ValueLocation]
1061
+ variable_types_global: list[DataType]
1062
+
1063
+
1064
+ def _as_cell_shape(shape: FeCellShape | int | str) -> FeCellShape:
1065
+ """Return *shape* as a :class:`FeCellShape`, from a member, value or name.
1066
+
1067
+ Raises:
1068
+ ValueError: If *shape* is not a member, value or name of :class:`FeCellShape`.
1069
+ """
1070
+ if isinstance(shape, FeCellShape):
1071
+ return shape
1072
+ if isinstance(shape, str):
1073
+ try:
1074
+ return FeCellShape[shape.upper()]
1075
+ except KeyError:
1076
+ raise ValueError(f"Unknown cell shape name {shape!r}.") from None
1077
+ return FeCellShape(shape)
1078
+
1079
+
1080
+ def _check_section_node_map(
1081
+ node_map: npt.ArrayLike, shape: FeCellShape, section: int
1082
+ ) -> npt.NDArray:
1083
+ """Return one section's node map as a validated ``(cells, nodes)`` array.
1084
+
1085
+ Raises:
1086
+ ValueError: If the array is not integer, does not hold whole cells of *shape*
1087
+ or holds a negative node index.
1088
+ """
1089
+ nodes_per_cell = CELL_SHAPE_NUM_NODES[shape]
1090
+ arr = np.asarray(node_map)
1091
+ if arr.dtype.kind not in "iu":
1092
+ raise ValueError(
1093
+ f"Section {section} node map must hold integers, got dtype {arr.dtype}."
1094
+ )
1095
+ if arr.ndim == 1 and arr.size % nodes_per_cell == 0:
1096
+ arr = arr.reshape(-1, nodes_per_cell)
1097
+ if arr.ndim != 2 or arr.shape[1] != nodes_per_cell:
1098
+ raise ValueError(
1099
+ f"Section {section} ({shape.name}) node map must have shape "
1100
+ f"(num_cells, {nodes_per_cell}), got {arr.shape}."
1101
+ )
1102
+ if arr.size and int(arr.min()) < 0:
1103
+ raise ValueError(f"Section {section} node map has a negative node index.")
1104
+ return arr
1105
+
1106
+
1107
+ def prepare_femixed_zone(
1108
+ arrays: Sequence[npt.NDArray],
1109
+ variable_types: Sequence[DataType],
1110
+ *,
1111
+ cell_shapes: Sequence[FeCellShape | int | str] | None,
1112
+ node_maps: Sequence[npt.ArrayLike] | None,
1113
+ value_locations: Sequence[ValueLocation] | None,
1114
+ passive_vars: PassiveVarsSpec | None,
1115
+ var_sharing: VarSharingSpec | None,
1116
+ con_sharing: int | None,
1117
+ dataset_variables: Sequence[str],
1118
+ meta: WriterMeta,
1119
+ ) -> PreparedFEMixedZone | None:
1120
+ """Validate and normalize inputs for writing a FEMIXED zone.
1121
+
1122
+ Shared across formats. Derives the section layout and node/cell counts from
1123
+ *cell_shapes* and *node_maps* (or the *con_sharing* source zone), then resolves and
1124
+ validates the variable arguments exactly as :func:`prepare_fe_zone` does, counting
1125
+ cells over all sections.
1126
+
1127
+ Args:
1128
+ arrays: NumPy arrays already converted from the caller's raw data, one per
1129
+ active (non-passive, non-shared) variable.
1130
+ variable_types: Per-active-variable data type, one per array in *arrays*.
1131
+ cell_shapes: Cell shape of each section (1 to 16), as :class:`FeCellShape`
1132
+ members, values or names. None if *con_sharing* is set.
1133
+ node_maps: One 0-based ``(num_cells, nodes_per_cell)`` integer array per section
1134
+ (a flat array is reshaped). None if *con_sharing* is set.
1135
+ value_locations: Per-active-variable value location, or None for all-NODAL.
1136
+ passive_vars: Variables to mark passive, see :func:`prepare_fe_zone`.
1137
+ var_sharing: Variables to share from another zone, see :func:`prepare_fe_zone`.
1138
+ con_sharing: Source zone index to share connectivity from, or None.
1139
+ dataset_variables: The full dataset variable name list.
1140
+ meta: The writer's own zone metadata, for resolving shared source zones.
1141
+
1142
+ Returns:
1143
+ A :class:`PreparedFEMixedZone`, or ``None`` after an :class:`EmptyZoneWarning`
1144
+ when every dataset variable is passive or shared.
1145
+
1146
+ Raises:
1147
+ TypeError: *passive_vars*/*var_sharing* isn't a list/tuple/set/mapping as
1148
+ appropriate, or mixes variable names and indices.
1149
+ ValueError: On any inconsistency: a section count outside 1 to 16, mismatched
1150
+ or malformed section arrays, sections of different spatial dimension, fewer
1151
+ dataset variables than the cell dimension (the library needs one coordinate
1152
+ variable per dimension and crashes without them), a zone with no cells,
1153
+ con_sharing referencing a zone that is not a written FEMIXED zone, or any
1154
+ variable validation failure.
1155
+ KeyError: A *passive_vars*/*var_sharing* name doesn't match any dataset
1156
+ variable.
1157
+ IndexError: A *passive_vars*/*var_sharing* index is out of range.
1158
+ """
1159
+ section_maps: list[npt.NDArray] = []
1160
+ if con_sharing is not None:
1161
+ if cell_shapes is not None or node_maps is not None:
1162
+ raise ValueError(
1163
+ "cell_shapes and node_maps must be omitted when connectivity is shared "
1164
+ "from another zone via con_sharing."
1165
+ )
1166
+ src_zone = meta.zone(con_sharing)
1167
+ if (
1168
+ src_zone is None
1169
+ or src_zone.section_shapes is None
1170
+ or src_zone.section_num_elements is None
1171
+ or src_zone.num_nodes is None
1172
+ ):
1173
+ raise ValueError(
1174
+ f"con_sharing={con_sharing} references a zone that has not been "
1175
+ "written yet, or is not a FEMIXED zone."
1176
+ )
1177
+ shapes = src_zone.section_shapes
1178
+ counts = src_zone.section_num_elements
1179
+ num_nodes = src_zone.num_nodes
1180
+ else:
1181
+ if cell_shapes is None or node_maps is None:
1182
+ raise ValueError(
1183
+ "cell_shapes and node_maps must be provided unless connectivity is "
1184
+ "shared from another zone via con_sharing."
1185
+ )
1186
+ if len(cell_shapes) != len(node_maps):
1187
+ raise ValueError(
1188
+ f"cell_shapes has {len(cell_shapes)} sections but node_maps has "
1189
+ f"{len(node_maps)}."
1190
+ )
1191
+ shapes = tuple(_as_cell_shape(shape) for shape in cell_shapes)
1192
+ if not 1 <= len(shapes) <= 16:
1193
+ raise ValueError(
1194
+ f"A FEMIXED zone needs 1 to 16 sections, got {len(shapes)}."
1195
+ )
1196
+ section_maps = [
1197
+ _check_section_node_map(nm, shape, i)
1198
+ for i, (nm, shape) in enumerate(zip(node_maps, shapes, strict=True))
1199
+ ]
1200
+ counts = tuple(int(nm.shape[0]) for nm in section_maps)
1201
+ if sum(counts) == 0:
1202
+ raise ValueError("A FEMIXED zone needs at least one cell.")
1203
+ num_nodes = max(int(nm.max()) for nm in section_maps if nm.size) + 1
1204
+
1205
+ dimensions = {CELL_SHAPE_DIMENSION[shape] for shape in shapes}
1206
+ if len(dimensions) > 1:
1207
+ raise ValueError(
1208
+ "All sections of a FEMIXED zone must have the same spatial dimension, got "
1209
+ + ", ".join(shape.name for shape in shapes)
1210
+ + "."
1211
+ )
1212
+ dimension = dimensions.pop()
1213
+ if len(dataset_variables) < dimension:
1214
+ raise ValueError(
1215
+ f"{dimension}-dimensional cells need at least {dimension} (coordinate) "
1216
+ f"variables, the dataset has {len(dataset_variables)}."
1217
+ )
1218
+
1219
+ num_cells = sum(counts)
1220
+ zone_vars = _prepare_zone_variables(
1221
+ arrays,
1222
+ variable_types,
1223
+ value_locations=value_locations,
1224
+ passive_vars=passive_vars,
1225
+ var_sharing=var_sharing,
1226
+ dataset_variables=dataset_variables,
1227
+ num_nodes=num_nodes,
1228
+ num_cells=num_cells,
1229
+ meta=meta,
1230
+ stacklevel=4,
1231
+ )
1232
+ if zone_vars is None:
1233
+ return None
1234
+ return PreparedFEMixedZone(
1235
+ value_locations=list(zone_vars.value_locations),
1236
+ passive_vars=zone_vars.passive_flags,
1237
+ var_sharing=list(zone_vars.share_idx),
1238
+ con_sharing=con_sharing,
1239
+ active_var_idx=zone_vars.active_var_idx,
1240
+ num_nodes=num_nodes,
1241
+ num_cells=num_cells,
1242
+ section_shapes=shapes,
1243
+ section_num_elements=counts,
1244
+ section_node_maps=section_maps,
1245
+ value_locations_global=zone_vars.value_locations_global,
1246
+ variable_types_global=zone_vars.variable_types_global,
1247
+ )
1248
+
1249
+
1039
1250
  @dataclass
1040
1251
  class _PolyConnectivity:
1041
1252
  """Validated face map of a poly zone plus the counts derived from it."""
@@ -1779,7 +1990,7 @@ class TecplotWriter(ABC):
1779
1990
  aux: dict[str, Any] | None = None,
1780
1991
  datapacking: DataPacking | str = DataPacking.BLOCK,
1781
1992
  ) -> None:
1782
- """Write a complete IJK-ordered zone. See the concrete subclass for details."""
1993
+ """Write a complete structured zone."""
1783
1994
 
1784
1995
  @abstractmethod
1785
1996
  def write_fe_zone(
@@ -1802,6 +2013,26 @@ class TecplotWriter(ABC):
1802
2013
  ) -> None:
1803
2014
  """Write a complete finite-element zone."""
1804
2015
 
2016
+ @abstractmethod
2017
+ def write_femixed_zone(
2018
+ self,
2019
+ data: Sequence[npt.ArrayLike],
2020
+ cell_shapes: Sequence[FeCellShape | int | str] | None = None,
2021
+ node_maps: Sequence[npt.ArrayLike] | None = None,
2022
+ *,
2023
+ title: str | None = None,
2024
+ variables: list[str] | None = None,
2025
+ value_locations: Sequence[ValueLocation] | None = None,
2026
+ passive_vars: PassiveVarsSpec | None = None,
2027
+ var_sharing: VarSharingSpec | None = None,
2028
+ con_sharing: int | None = None,
2029
+ solution_time: float = 0.0,
2030
+ strand_id: int = 0,
2031
+ aux: dict[str, Any] | None = None,
2032
+ datapacking: DataPacking | str = DataPacking.BLOCK,
2033
+ ) -> None:
2034
+ """Write a complete FEMIXED zone."""
2035
+
1805
2036
  @abstractmethod
1806
2037
  def write_poly_zone(
1807
2038
  self,