tecio-python 0.3.3__py3-none-any.whl → 0.4.1__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 (36) hide show
  1. tecio/__init__.py +10 -3
  2. tecio/_dat_read.py +306 -45
  3. tecio/_dat_write.py +518 -153
  4. tecio/_io.py +147 -99
  5. tecio/_meta.py +42 -23
  6. tecio/_plt_legacy.py +408 -0
  7. tecio/_plt_read.py +456 -121
  8. tecio/_plt_write.py +446 -131
  9. tecio/_reader.py +387 -55
  10. tecio/_szl_read.py +124 -75
  11. tecio/_szl_write.py +304 -193
  12. tecio/_utils.py +69 -6
  13. tecio/_writer.py +1092 -216
  14. tecio/cli/tec2mat.py +70 -41
  15. tecio/cli/tecaux.py +90 -122
  16. tecio/cli/tecdump.py +45 -6
  17. tecio/cli/tecextract.py +105 -99
  18. tecio/cli/tecfix.py +62 -78
  19. tecio/cli/tecmerge.py +154 -95
  20. tecio/cli/teconvert.py +40 -52
  21. tecio/cli/tecscale.py +210 -122
  22. tecio/cli/tecslice.py +199 -156
  23. tecio/cli/tecstats.py +47 -43
  24. tecio/libtecio.py +117 -61
  25. tecio_python-0.3.3.data/data/share/plugins/matlab/fecplot.m → tecio_python-0.4.1.data/data/share/tecio/plugins/matlab/contourfe.m +3 -3
  26. tecio_python-0.4.1.data/data/share/tecio/plugins/matlab/tecmat2struct.m +137 -0
  27. {tecio_python-0.3.3.data/data/share → tecio_python-0.4.1.data/data/share/tecio}/plugins/paraview/TecplotTecioReader.py +463 -38
  28. tecio_python-0.4.1.data/data/share/tecio/plugins/paraview/TecplotTecioWriter.py +1026 -0
  29. {tecio_python-0.3.3.dist-info → tecio_python-0.4.1.dist-info}/METADATA +25 -9
  30. tecio_python-0.4.1.dist-info/RECORD +38 -0
  31. {tecio_python-0.3.3.dist-info → tecio_python-0.4.1.dist-info}/WHEEL +1 -1
  32. tecio_python-0.3.3.dist-info/RECORD +0 -35
  33. {tecio_python-0.3.3.dist-info → tecio_python-0.4.1.dist-info}/entry_points.txt +0 -0
  34. {tecio_python-0.3.3.dist-info → tecio_python-0.4.1.dist-info}/licenses/LICENSE +0 -0
  35. {tecio_python-0.3.3.dist-info → tecio_python-0.4.1.dist-info}/licenses/NOTICE +0 -0
  36. {tecio_python-0.3.3.dist-info → tecio_python-0.4.1.dist-info}/top_level.txt +0 -0
tecio/_dat_read.py CHANGED
@@ -31,12 +31,15 @@ from ._constants import (
31
31
  )
32
32
  from ._containers import ZoneList
33
33
  from ._reader import (
34
+ PolyArrayKey,
34
35
  TecplotAuxDataReader,
35
36
  TecplotFEZoneReader,
36
37
  TecplotOrderedZoneReader,
38
+ TecplotPolyZoneReader,
37
39
  TecplotReader,
38
40
  TecplotVariableReader,
39
41
  TecplotZoneReader,
42
+ convert_face_connections_to_zero_based,
40
43
  )
41
44
 
42
45
  # --------------------------------------------------------------------------------------
@@ -170,6 +173,9 @@ _MAX_FAST_BLOCK_ITERATIONS: int = 64
170
173
  def _quote(s: str) -> str:
171
174
  """Wrap *s* in double-quotes, escaping embedded double-quotes.
172
175
 
176
+ Returns:
177
+ str: Stripped string.
178
+
173
179
  Example:
174
180
  >>> q = _quote("hello world")
175
181
  """
@@ -179,6 +185,9 @@ def _quote(s: str) -> str:
179
185
  def _unquote(s: str) -> str:
180
186
  r"""Remove surrounding double-quotes and unescape internal ``\\"``.
181
187
 
188
+ Returns:
189
+ str: String without the surrounding quotes.
190
+
182
191
  Example:
183
192
  >>> s = _unquote('"hello \\"world\\""')
184
193
  """
@@ -191,6 +200,9 @@ def _unquote(s: str) -> str:
191
200
  def _strip_comment(line: str) -> str:
192
201
  """Remove a Tecplot ``#`` comment and trailing whitespace.
193
202
 
203
+ Returns:
204
+ str: The line without the comment and trailing whitespace.
205
+
194
206
  Example:
195
207
  >>> clean = _strip_comment(line)
196
208
  """
@@ -393,6 +405,9 @@ def _kv_split(text: str) -> dict[str, str]:
393
405
  Handles quoted values, parenthesised blocks (VARLOCATION, VARSHARELIST), and
394
406
  bracketed lists (PASSIVEVARLIST).
395
407
 
408
+ Returns:
409
+ dict: Mapping of upper-cased keys to their raw string values.
410
+
396
411
  Example:
397
412
  >>> d = _kv_split("I=3, J=4, K=1")
398
413
 
@@ -682,6 +697,9 @@ def _parse_dt(text: str) -> list[DataType]:
682
697
  def _parse_auxdata_line(line: str) -> tuple[str, str]:
683
698
  """Parse ``DATASETAUXDATA name="value"`` → ``(name, value)``.
684
699
 
700
+ Returns:
701
+ tuple: Tuple of the name and value, or empty strings if the line has no ``=``.
702
+
685
703
  Example:
686
704
  >>> name, val = _parse_auxdata_line('DATASETAUXDATA Solver="MyCFD"')
687
705
  """
@@ -696,9 +714,9 @@ def _parse_auxdata_line(line: str) -> tuple[str, str]:
696
714
  def _apply_varauxdata(line: str, var_auxdata_list: list[dict[str, str]]) -> None:
697
715
  """Parse ``VARAUXDATA 1-based-idx name="value"`` and store in list.
698
716
 
699
- *var_auxdata_list* holds plain, mutable dicts, one per variable (index 0 is an
700
- unused placeholder), accumulated during parsing. Wrapped into an immutable
701
- TecplotDatAuxDataReader lazily, only once parsing is complete.
717
+ *var_auxdata_list* holds plain, mutable dicts, one per variable, 0-based,
718
+ accumulated during parsing. Wrapped into an immutable TecplotDatAuxDataReader
719
+ lazily, only once parsing is complete.
702
720
 
703
721
  Example:
704
722
  >>> _apply_varauxdata(line, var_auxdata_list)
@@ -706,14 +724,14 @@ def _apply_varauxdata(line: str, var_auxdata_list: list[dict[str, str]]) -> None
706
724
  m = re.match(r"(?i)VARAUXDATA\s+(\d+)\s+", line)
707
725
  if not m:
708
726
  return
709
- var_idx = int(m.group(1)) # 1-based
727
+ var_idx = int(m.group(1)) - 1 # 1-based in text, converted to 0-based
710
728
  rest = line[m.end() :]
711
729
  eq = rest.find("=")
712
730
  if eq < 0:
713
731
  return
714
732
  name = rest[:eq].strip()
715
733
  value = _unquote(rest[eq + 1 :].strip())
716
- if 1 <= var_idx < len(var_auxdata_list):
734
+ if 0 <= var_idx < len(var_auxdata_list):
717
735
  var_auxdata_list[var_idx][name] = value
718
736
 
719
737
 
@@ -766,7 +784,11 @@ class _LineBuffer:
766
784
  return ""
767
785
 
768
786
  def next_stripped(self) -> str:
769
- """Consume and return the next non-blank stripped line."""
787
+ """Consume and return the next non-blank stripped line.
788
+
789
+ Returns:
790
+ str: The next non-blank line, or an empty string at the end of the file.
791
+ """
770
792
  if self._peeked is None:
771
793
  self.peek_stripped()
772
794
  value = self._peeked or ""
@@ -775,6 +797,19 @@ class _LineBuffer:
775
797
  self._peeked_pos = -1
776
798
  return value
777
799
 
800
+ def skip_blank(self) -> None:
801
+ """Advance past blank and comment-only lines.
802
+
803
+ The vectorized integer readers parse raw lines, so a ``# face nodes`` style
804
+ section comment must be skipped before them or they fall back to the slow path.
805
+ """
806
+ self._peeked = None
807
+ self._peeked_pos = -1
808
+ pos, n = self._pos, len(self._lines)
809
+ while pos < n and not _strip_comment(self._lines[pos]).strip():
810
+ pos += 1
811
+ self._pos = pos
812
+
778
813
  def take_raw(self, count: int) -> list[str]:
779
814
  """Consume and return up to *count* **unprocessed** source lines.
780
815
 
@@ -787,6 +822,9 @@ class _LineBuffer:
787
822
  Intended only for the numeric fast-path readers, which feed the result straight
788
823
  to a whitespace-tolerant NumPy parser and don't need per-line preprocessing.
789
824
 
825
+ Returns:
826
+ list: The raw lines, fewer than *count* at the end of the file.
827
+
790
828
  Example:
791
829
  >>> lines = buf.take_raw(64)
792
830
  """
@@ -922,12 +960,16 @@ class TecplotDatVariableReader(TecplotVariableReader):
922
960
  return self._value_location
923
961
 
924
962
  def is_passive(self) -> bool:
925
- """True if this variable is passive (no data in this zone)."""
963
+ """True if this variable is passive (no data in this zone).
964
+
965
+ Returns:
966
+ bool: ``True`` for a passive variable.
967
+ """
926
968
  return self._passive
927
969
 
928
970
  @property
929
971
  def shared_zone(self) -> int | None:
930
- """1-based source zone index if shared, else None."""
972
+ """0-based source zone index if shared, else None."""
931
973
  return self._shared_zone
932
974
 
933
975
  @property
@@ -985,9 +1027,9 @@ class TecplotDatOrderedZoneReader(TecplotOrderedZoneReader):
985
1027
  self,
986
1028
  zone_index: int,
987
1029
  title: str,
988
- I: int, # noqa: E741 - matches Tecplot's own IJK convention
989
- J: int,
990
- K: int,
1030
+ I: int, # noqa: E741 N803
1031
+ J: int, # noqa: N803
1032
+ K: int, # noqa: N803
991
1033
  solution_time: float,
992
1034
  strand_id: int,
993
1035
  variables: list[TecplotVariableReader],
@@ -1024,10 +1066,7 @@ class TecplotDatFEZoneReader(TecplotFEZoneReader):
1024
1066
  DAT has no concept of a disabled zone, so the base class default (always True)
1025
1067
  applies.
1026
1068
 
1027
- FEPOLYGON/FEPOLYHEDRON are not constructed as this class, or at all, the parser
1028
- rejects them with :exc:`ValueError` before reaching here (see ``_parse_zone``), so
1029
- unlike PLT there's no partial-metadata-only case to handle for those types in the
1030
- ASCII reader.
1069
+ FEPOLYGON/FEPOLYHEDRON zones are read as :class:`TecplotDatPolyZoneReader`.
1031
1070
  """
1032
1071
 
1033
1072
  __slots__ = (
@@ -1110,6 +1149,65 @@ class TecplotDatFEZoneReader(TecplotFEZoneReader):
1110
1149
  return TecplotDatAuxDataReader(self._aux_raw)
1111
1150
 
1112
1151
 
1152
+ class TecplotDatPolyZoneReader(TecplotPolyZoneReader):
1153
+ """Poly (FEPOLYGON / FEPOLYHEDRON) zone reader for ASCII DAT files.
1154
+
1155
+ Like :class:`TecplotDatFEZoneReader`, the whole zone is already parsed and held in
1156
+ memory at construction, so the lazy hooks just hand back stored arrays. The face
1157
+ map is already converted to the public 0-based convention.
1158
+ """
1159
+
1160
+ __slots__ = ("_variables", "_aux_raw", "_face_map")
1161
+ _variables: list[TecplotVariableReader]
1162
+ _aux_raw: dict[str, str]
1163
+ _face_map: dict[str, npt.NDArray[np.int64]]
1164
+
1165
+ def __init__(
1166
+ self,
1167
+ zone_index: int,
1168
+ title: str,
1169
+ zone_type: ZoneType,
1170
+ num_nodes: int,
1171
+ num_elements: int,
1172
+ num_faces: int,
1173
+ num_boundary_faces: int,
1174
+ num_boundary_connections: int,
1175
+ solution_time: float,
1176
+ strand_id: int,
1177
+ variables: list[TecplotVariableReader],
1178
+ auxdata: dict[str, str],
1179
+ face_map: dict[str, npt.NDArray[np.int64]],
1180
+ datapacking: DataPacking = DataPacking.BLOCK,
1181
+ shared_connectivity: int | None = None,
1182
+ ) -> None:
1183
+ super().__init__(
1184
+ zone_index=zone_index,
1185
+ title=title,
1186
+ zone_type=zone_type,
1187
+ solution_time=solution_time,
1188
+ strand_id=strand_id,
1189
+ datapacking=datapacking,
1190
+ num_nodes=num_nodes,
1191
+ num_elements=num_elements,
1192
+ num_faces=num_faces,
1193
+ num_boundary_faces=num_boundary_faces,
1194
+ num_boundary_connections=num_boundary_connections,
1195
+ shared_connectivity=shared_connectivity,
1196
+ )
1197
+ object.__setattr__(self, "_variables", variables)
1198
+ object.__setattr__(self, "_aux_raw", auxdata)
1199
+ object.__setattr__(self, "_face_map", face_map)
1200
+
1201
+ def _load_variables(self) -> list[TecplotVariableReader]:
1202
+ return self._variables
1203
+
1204
+ def _load_array(self, key: PolyArrayKey) -> npt.NDArray[np.int64]:
1205
+ return self._face_map[key]
1206
+
1207
+ def _load_auxdata(self) -> TecplotAuxDataReader:
1208
+ return TecplotDatAuxDataReader(self._aux_raw)
1209
+
1210
+
1113
1211
  class _DatZoneInfo(NamedTuple):
1114
1212
  """Per-zone metadata from a cheap header-only scan."""
1115
1213
 
@@ -1255,9 +1353,7 @@ def _peek_dat_metadata(path: str | os.PathLike) -> _DatMetadata:
1255
1353
  num_nodes = zi * zj * zk
1256
1354
  num_elements = max(zi - 1, 1) * max(zj - 1, 1) * max(zk - 1, 1)
1257
1355
  else:
1258
- # FE zones (including FEPOLYGON/FEPOLYHEDRON, which the full parser can't
1259
- # read data for, but whose header is just as legible as any other zone's)
1260
- # always state counts directly.
1356
+ # FE and poly zones always state counts directly.
1261
1357
  num_nodes = int(kv.get("NODES", kv.get("N", "0")) or "0")
1262
1358
  num_elements = int(kv.get("ELEMENTS", kv.get("E", "0")) or "0")
1263
1359
 
@@ -1266,6 +1362,22 @@ def _peek_dat_metadata(path: str | os.PathLike) -> _DatMetadata:
1266
1362
  return _DatMetadata(title, file_type, variable_names, zones)
1267
1363
 
1268
1364
 
1365
+ def _face_map_of(zone: TecplotPolyZoneReader) -> dict[str, npt.NDArray[np.int64]]:
1366
+ """Return the face-map arrays of an already parsed poly zone."""
1367
+ face_map = {
1368
+ "face_nodes": zone.face_nodes,
1369
+ "face_left_elements": zone.face_left_elements,
1370
+ "face_right_elements": zone.face_right_elements,
1371
+ }
1372
+ if zone.zone_type is ZoneType.FEPOLYHEDRON:
1373
+ face_map["face_node_counts"] = zone.face_node_counts
1374
+ if zone.num_boundary_faces:
1375
+ face_map["boundary_connection_counts"] = zone.boundary_connection_counts
1376
+ face_map["boundary_connection_elements"] = zone.boundary_connection_elements
1377
+ face_map["boundary_connection_zones"] = zone.boundary_connection_zones
1378
+ return face_map
1379
+
1380
+
1269
1381
  class TecplotDatReader(TecplotReader):
1270
1382
  """Reader for Tecplot ASCII DAT files.
1271
1383
 
@@ -1306,9 +1418,9 @@ class TecplotDatReader(TecplotReader):
1306
1418
  # TecplotDatAuxDataReader lazily, only once fully parsed.
1307
1419
  self._dataset_auxdata_raw: dict[str, str] = {}
1308
1420
  self._dataset_auxdata: TecplotAuxDataReader | None = None
1309
- # Index 0 is an unused placeholder so that 1-based indexing works directly;
1310
- # populated once num_vars is known, see _parse().
1311
- self._var_auxdata_raw: list[dict[str, str]] = [{}]
1421
+ # 0-based, one dict per variable; populated once num_vars is known, see
1422
+ # _parse().
1423
+ self._var_auxdata_raw: list[dict[str, str]] = []
1312
1424
  # Raw VARAUXDATA lines seen before the first zone, buffered by
1313
1425
  # _parse_file_header() and applied once _var_auxdata_raw is allocated with the
1314
1426
  # correct length (num_vars isn't known until the header finishes parsing).
@@ -1377,7 +1489,7 @@ class TecplotDatReader(TecplotReader):
1377
1489
  self._parse_file_header(tokens)
1378
1490
 
1379
1491
  # Build per-variable aux data slots now that num_vars is known.
1380
- self._var_auxdata_raw = [{}] + [{} for _ in range(self.num_vars)]
1492
+ self._var_auxdata_raw = [{} for _ in range(self.num_vars)]
1381
1493
 
1382
1494
  # Now that _var_auxdata exists, apply any VARAUXDATA lines that appeared before
1383
1495
  # the first zone
@@ -1526,6 +1638,10 @@ class TecplotDatReader(TecplotReader):
1526
1638
  def _parse_zone(self, tokens: _LineBuffer) -> None:
1527
1639
  """Parse one ZONE block (header + data blocks + connectivity).
1528
1640
 
1641
+ Raises:
1642
+ ValueError: If the data packing is unsupported, a poly zone is not BLOCK
1643
+ packed, or ``DT=`` does not give one type per variable.
1644
+
1529
1645
  Example:
1530
1646
  >>> self._parse_zone(tokens)
1531
1647
  """
@@ -1558,12 +1674,6 @@ class TecplotDatReader(TecplotReader):
1558
1674
 
1559
1675
  zone_type = _determine_zone_type(kv)
1560
1676
 
1561
- if zone_type in _FE_POLY:
1562
- raise ValueError(
1563
- f"Zone type {zone_type.name!r} is not yet supported by the "
1564
- "ASCII reader."
1565
- )
1566
-
1567
1677
  # Passive/shared variables are parsed here (ahead of var_locs/var_types below,
1568
1678
  # which don't need this ordering) because the point-count inference just below
1569
1679
  # needs active_count first.
@@ -1581,11 +1691,11 @@ class TecplotDatReader(TecplotReader):
1581
1691
  active_count = self.num_vars - len(passive_set) - len(share_map)
1582
1692
  num_nodes = self._infer_ordered_point_count(tokens, active_count)
1583
1693
  I = num_nodes # noqa E741
1584
- J = K = 1
1694
+ J = K = 1 # noqa: N806
1585
1695
  else:
1586
- I = int(kv.get("I", "1") or "1") # noqa E741
1587
- J = int(kv.get("J", "1") or "1")
1588
- K = int(kv.get("K", "1") or "1")
1696
+ I = int(kv.get("I", "1") or "1") # noqa: E741 N806
1697
+ J = int(kv.get("J", "1") or "1") # noqa: N806
1698
+ K = int(kv.get("K", "1") or "1") # noqa: N806
1589
1699
  num_nodes = I * J * K
1590
1700
  num_cells = max(I - 1, 1) * max(J - 1, 1) * max(K - 1, 1)
1591
1701
  else:
@@ -1594,6 +1704,12 @@ class TecplotDatReader(TecplotReader):
1594
1704
  num_nodes = int(kv.get("NODES", kv.get("N", "0")) or "0")
1595
1705
  num_cells = int(kv.get("ELEMENTS", kv.get("E", "0")) or "0")
1596
1706
  I, J, K = num_nodes, num_cells, 0 # noqa E741
1707
+ num_faces = int(kv.get("FACES", "0") or "0")
1708
+ total_face_nodes = int(kv.get("TOTALNUMFACENODES", "0") or "0")
1709
+ num_boundary_faces = int(kv.get("NUMCONNECTEDBOUNDARYFACES", "0") or "0")
1710
+ num_boundary_connections = int(
1711
+ kv.get("TOTALNUMBOUNDARYCONNECTIONS", "0") or "0"
1712
+ )
1597
1713
 
1598
1714
  # Packing: DATAPACKING wins, then legacy F, else BLOCK (Tecplot default).
1599
1715
  if "DATAPACKING" in kv:
@@ -1609,6 +1725,12 @@ class TecplotDatReader(TecplotReader):
1609
1725
  else:
1610
1726
  packing = DataPacking.BLOCK
1611
1727
 
1728
+ # Tecplot refuses POINT for face-based zones, so match it.
1729
+ if zone_type in _FE_POLY and packing != DataPacking.BLOCK:
1730
+ raise ValueError(
1731
+ "Polygon and polyhedron zones must use BLOCK data packing."
1732
+ )
1733
+
1612
1734
  # Face-neighbor connections (finite-element zones only; ordered zones
1613
1735
  # don't need them, adjacency is already implicit in the I/J/K
1614
1736
  # structure). FACENEIGHBORCONNECTIONS is authoritative for how many
@@ -1684,8 +1806,26 @@ class TecplotDatReader(TecplotReader):
1684
1806
  # -- Read connectivity (FE zones only) -----------------------------------------
1685
1807
 
1686
1808
  node_map: npt.NDArray | None = None
1809
+ face_map: dict[str, npt.NDArray[np.int64]] = {}
1687
1810
 
1688
- if zone_type != ZoneType.ORDERED:
1811
+ if zone_type in _FE_POLY:
1812
+ if con_share_zone and self._zones:
1813
+ source_zone = self._zones[con_share_zone - 1]
1814
+ if isinstance(source_zone, TecplotPolyZoneReader):
1815
+ face_map = _face_map_of(source_zone)
1816
+ num_faces = source_zone.num_faces
1817
+ num_boundary_faces = source_zone.num_boundary_faces
1818
+ num_boundary_connections = source_zone.num_boundary_connections
1819
+ else:
1820
+ face_map = self._read_poly_face_map(
1821
+ tokens,
1822
+ zone_type,
1823
+ num_faces,
1824
+ total_face_nodes,
1825
+ num_boundary_faces,
1826
+ num_boundary_connections,
1827
+ )
1828
+ elif zone_type != ZoneType.ORDERED:
1689
1829
  if con_share_zone and self._zones:
1690
1830
  source_zone = self._zones[con_share_zone - 1]
1691
1831
  if isinstance(source_zone, TecplotFEZoneReader):
@@ -1696,12 +1836,15 @@ class TecplotDatReader(TecplotReader):
1696
1836
  else:
1697
1837
  nodes_per_cell = _NODES_PER_ELEM[zone_type]
1698
1838
  flat = self._read_int_block(tokens, num_cells * nodes_per_cell)
1699
- node_map = flat.reshape(num_cells, nodes_per_cell)
1839
+ # Node numbers are 1-based in ASCII; convert to 0-based indices
1840
+ # that point directly into the corresponding coordinate array.
1841
+ node_map = flat.reshape(num_cells, nodes_per_cell) - 1
1700
1842
 
1701
1843
  # -- Read face-neighbor connections (FE zones only, if declared) ---------------
1702
1844
  #
1703
- # Immediately follows connectivity in the file. Values are already
1704
- # 1-based in ASCII (unlike PLT's binary layout, no +1 needed here).
1845
+ # Immediately follows connectivity in the file. Values are 1-based in ASCII;
1846
+ # cell references, remote-zone references, and the face ordinal are all
1847
+ # converted to 0-based below.
1705
1848
 
1706
1849
  face_connections: npt.NDArray[np.int64] | None = None
1707
1850
  one_to_one = (
@@ -1715,6 +1858,9 @@ class TecplotDatReader(TecplotReader):
1715
1858
  face_connections = self._read_int_block(
1716
1859
  tokens, declared_face_connections * values_per
1717
1860
  )
1861
+ face_connections = convert_face_connections_to_zero_based(
1862
+ face_connections, face_neighbor_mode
1863
+ )
1718
1864
  elif face_neighbor_mode is not None:
1719
1865
  # "Many" modes: ragged, each record's own 4th value (nz) gives the
1720
1866
  # count of additional neighbor references that follow it.
@@ -1730,6 +1876,9 @@ class TecplotDatReader(TecplotReader):
1730
1876
  face_connections = (
1731
1877
  np.concatenate(pieces) if pieces else np.empty(0, dtype=np.int64)
1732
1878
  )
1879
+ face_connections = convert_face_connections_to_zero_based(
1880
+ face_connections, face_neighbor_mode
1881
+ )
1733
1882
 
1734
1883
  # -- Build ReadVariable and ReadZone objects -----------------------------------
1735
1884
 
@@ -1758,13 +1907,13 @@ class TecplotDatReader(TecplotReader):
1758
1907
  self._zones[src_zone_1based - 1].variables[var_idx].values
1759
1908
  )
1760
1909
 
1761
- # This zone's own 1-based index
1762
- zone_index = len(self._zones) + 1
1910
+ # This zone's own 0-based index
1911
+ zone_index = len(self._zones)
1763
1912
 
1764
1913
  read_vars: list[TecplotVariableReader] = [
1765
1914
  TecplotDatVariableReader(
1766
1915
  zone_index=zone_index,
1767
- var_index=idx + 1,
1916
+ var_index=idx,
1768
1917
  name=name,
1769
1918
  data=_shaped(
1770
1919
  var_arrays[idx],
@@ -1772,11 +1921,35 @@ class TecplotDatReader(TecplotReader):
1772
1921
  ),
1773
1922
  value_location=var_locs.get(idx, ValueLocation.NODAL),
1774
1923
  is_passive=(idx in passive_set),
1775
- shared_zone=share_map.get(idx, None),
1924
+ shared_zone=(share_map[idx] - 1 if idx in share_map else None),
1776
1925
  )
1777
1926
  for idx, name in enumerate(self._variable_names)
1778
1927
  ]
1779
1928
 
1929
+ if zone_type in _FE_POLY:
1930
+ self._zones.append(
1931
+ TecplotDatPolyZoneReader(
1932
+ zone_index=zone_index,
1933
+ title=zone_title,
1934
+ zone_type=zone_type,
1935
+ num_nodes=num_nodes,
1936
+ num_elements=num_cells,
1937
+ num_faces=num_faces,
1938
+ num_boundary_faces=num_boundary_faces,
1939
+ num_boundary_connections=num_boundary_connections,
1940
+ solution_time=solution_time,
1941
+ strand_id=strand_id,
1942
+ variables=read_vars,
1943
+ auxdata=zone_aux,
1944
+ face_map=face_map,
1945
+ datapacking=packing,
1946
+ shared_connectivity=(con_share_zone - 1)
1947
+ if con_share_zone
1948
+ else None,
1949
+ )
1950
+ )
1951
+ return
1952
+
1780
1953
  self._zones.append(
1781
1954
  self._build_zone(
1782
1955
  zone_index=zone_index,
@@ -1791,7 +1964,7 @@ class TecplotDatReader(TecplotReader):
1791
1964
  auxdata=zone_aux,
1792
1965
  node_map=node_map,
1793
1966
  datapacking=packing,
1794
- shared_connectivity=con_share_zone if con_share_zone else None,
1967
+ shared_connectivity=(con_share_zone - 1) if con_share_zone else None,
1795
1968
  face_neighbor_mode=face_neighbor_mode,
1796
1969
  num_face_connections=declared_face_connections or None,
1797
1970
  face_connections=face_connections,
@@ -1804,9 +1977,9 @@ class TecplotDatReader(TecplotReader):
1804
1977
  zone_index: int,
1805
1978
  title: str,
1806
1979
  zone_type: ZoneType,
1807
- I: int, # noqa: E741 - matches Tecplot's own IJK convention
1808
- J: int,
1809
- K: int,
1980
+ I: int, # noqa: E741 N803
1981
+ J: int, # noqa: N803
1982
+ K: int, # noqa: N803
1810
1983
  solution_time: float,
1811
1984
  strand_id: int,
1812
1985
  variables: list[TecplotVariableReader],
@@ -1819,7 +1992,11 @@ class TecplotDatReader(TecplotReader):
1819
1992
  face_connections: npt.NDArray[np.int64] | None = None,
1820
1993
  face_neighbors_complete: bool | None = None,
1821
1994
  ) -> TecplotZoneReader:
1822
- """Construct the right concrete zone reader for one parsed zone."""
1995
+ """Construct the right concrete zone reader for one parsed zone.
1996
+
1997
+ Returns:
1998
+ TecplotZoneReader: The reader class that matches *zone_type*.
1999
+ """
1823
2000
  if zone_type == ZoneType.ORDERED:
1824
2001
  return TecplotDatOrderedZoneReader(
1825
2002
  zone_index=zone_index,
@@ -1852,6 +2029,64 @@ class TecplotDatReader(TecplotReader):
1852
2029
  face_neighbors_complete=face_neighbors_complete,
1853
2030
  )
1854
2031
 
2032
+ @staticmethod
2033
+ def _read_poly_face_map(
2034
+ tokens: _LineBuffer,
2035
+ zone_type: ZoneType,
2036
+ num_faces: int,
2037
+ total_face_nodes: int,
2038
+ num_boundary_faces: int,
2039
+ num_boundary_connections: int,
2040
+ ) -> dict[str, npt.NDArray[np.int64]]:
2041
+ """Read the integer face-map sections that follow a poly zone's variables.
2042
+
2043
+ The sections are introduced by ``#`` comments, which are skipped. All indices
2044
+ are 1-based in ASCII (0 for no element, ``-k`` for the k-th boundary face), so
2045
+ every array is shifted down by one to the public convention.
2046
+
2047
+ Returns:
2048
+ dict: Face map arrays by name, with 0-based indices.
2049
+
2050
+ Raises:
2051
+ ValueError: If a section is shorter than the header declares.
2052
+ """
2053
+
2054
+ def section(name: str, count: int, shift: int = 0) -> npt.NDArray[np.int64]:
2055
+ tokens.skip_blank()
2056
+ arr = TecplotDatReader._read_int_block(tokens, count)
2057
+ if arr.size != count:
2058
+ raise ValueError(
2059
+ f"Poly zone section '{name}' has {arr.size} values, expected "
2060
+ f"{count}."
2061
+ )
2062
+ return arr - shift if shift else arr
2063
+
2064
+ face_map: dict[str, npt.NDArray[np.int64]] = {}
2065
+ if zone_type is ZoneType.FEPOLYHEDRON:
2066
+ counts = section("node count per face", num_faces)
2067
+ if int(counts.sum()) != total_face_nodes:
2068
+ raise ValueError(
2069
+ f"Poly zone node counts sum to {int(counts.sum())}, but "
2070
+ f"TotalNumFaceNodes is {total_face_nodes}."
2071
+ )
2072
+ face_map["face_node_counts"] = counts
2073
+ face_map["face_nodes"] = section("face nodes", total_face_nodes, 1)
2074
+ else:
2075
+ face_map["face_nodes"] = section("face nodes", 2 * num_faces, 1)
2076
+ face_map["face_left_elements"] = section("left elements", num_faces, 1)
2077
+ face_map["face_right_elements"] = section("right elements", num_faces, 1)
2078
+ if num_boundary_faces:
2079
+ face_map["boundary_connection_counts"] = section(
2080
+ "boundary connection counts", num_boundary_faces
2081
+ )
2082
+ face_map["boundary_connection_elements"] = section(
2083
+ "boundary connection elements", num_boundary_connections, 1
2084
+ )
2085
+ face_map["boundary_connection_zones"] = section(
2086
+ "boundary connection zones", num_boundary_connections, 1
2087
+ )
2088
+ return face_map
2089
+
1855
2090
  # -- Block readers -----------------------------------------------------------------
1856
2091
 
1857
2092
  @staticmethod
@@ -1871,6 +2106,10 @@ class TecplotDatReader(TecplotReader):
1871
2106
  from *tokens* at the position the fast path started from, so the two never
1872
2107
  disagree about what was consumed.
1873
2108
 
2109
+ Returns:
2110
+ NDArray: Float64 array of *n_values* values, or fewer if the data block ends
2111
+ early.
2112
+
1874
2113
  See Also:
1875
2114
  :meth:`_read_block_var_data`/:meth:`_read_point_var_data`.
1876
2115
 
@@ -1907,6 +2146,10 @@ class TecplotDatReader(TecplotReader):
1907
2146
  the slow, boundary-aware parser. A ``ValueError`` from ``numpy.fromstring`` is
1908
2147
  allowed to propagate to the caller for the same reason.
1909
2148
 
2149
+ Returns:
2150
+ NDArray: Array of *n_values* values, or ``None`` if the fast path cannot
2151
+ read them.
2152
+
1910
2153
  Example:
1911
2154
  >>> arr = TecplotDatReader._read_float_block_fast(tokens, 100)
1912
2155
 
@@ -1943,6 +2186,9 @@ class TecplotDatReader(TecplotReader):
1943
2186
  :func:`_is_float_block_boundary`) even if *n_values* hasn't been reached
1944
2187
  yet. Slow by design, but guarantees a result either way.
1945
2188
 
2189
+ Returns:
2190
+ NDArray: Float64 array of up to *n_values* values.
2191
+
1946
2192
  Example:
1947
2193
  >>> arr = TecplotDatReader._read_float_block_slow(tokens, 100)
1948
2194
 
@@ -1985,6 +2231,9 @@ class TecplotDatReader(TecplotReader):
1985
2231
  call) is deliberate: :meth:`_read_float_block`'s vectorized fast path already
1986
2232
  costs only a handful of C-level calls per block regardless of size.
1987
2233
 
2234
+ Returns:
2235
+ list: One array per variable, ``None`` for passive and shared variables.
2236
+
1988
2237
  Note:
1989
2238
  Passive and shared variables contribute a ``None`` placeholder to the
1990
2239
  returned list. The caller resolves shared variables against the zones parsed
@@ -2033,6 +2282,9 @@ class TecplotDatReader(TecplotReader):
2033
2282
  its variable's actual declared dtype (from ``DT=``, or the spec's documented
2034
2283
  SINGLE default) right where it's extracted from the interleaved rows.
2035
2284
 
2285
+ Returns:
2286
+ list: One array per variable, ``None`` for passive and shared variables.
2287
+
2036
2288
  See Also:
2037
2289
  :meth:`_read_block_var_data`
2038
2290
 
@@ -2092,6 +2344,9 @@ class TecplotDatReader(TecplotReader):
2092
2344
  tolerant-slow-path split as :meth:`_read_float_block`; see that method's
2093
2345
  docstring for the rationale.
2094
2346
 
2347
+ Returns:
2348
+ NDArray: Int64 array of *n_values* values, or fewer if the data block ends early.
2349
+
2095
2350
  Examples:
2096
2351
  >>> arr = TecplotDatReader._read_int_block(tokens, 24)
2097
2352
  """
@@ -2116,6 +2371,9 @@ class TecplotDatReader(TecplotReader):
2116
2371
  See :meth:`_read_float_block_fast`, which this mirrors exactly except for the
2117
2372
  target dtype.
2118
2373
 
2374
+ Returns:
2375
+ NDArray: Array of *n_values* values, or ``None`` if the fast path cannot read them.
2376
+
2119
2377
  Example:
2120
2378
  >>> arr = TecplotDatReader._read_int_block_fast(tokens, 24)
2121
2379
  """
@@ -2144,6 +2402,9 @@ class TecplotDatReader(TecplotReader):
2144
2402
  def _read_int_block_slow(tokens: _LineBuffer, n_values: int) -> npt.NDArray:
2145
2403
  """Tolerant, token-by-token fallback for :meth:`_read_int_block`.
2146
2404
 
2405
+ Returns:
2406
+ NDArray: Int64 array of up to *n_values* values.
2407
+
2147
2408
  Example:
2148
2409
  >>> arr = TecplotDatReader._read_int_block_slow(tokens, 24)
2149
2410
  """