tecio-python 0.4.0__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 (39) hide show
  1. tecio/__init__.py +46 -2
  2. tecio/_constants.py +2 -2
  3. tecio/_dat_read.py +268 -17
  4. tecio/_dat_write.py +347 -10
  5. tecio/_elements.py +1311 -0
  6. tecio/_io.py +108 -31
  7. tecio/_meta.py +47 -20
  8. tecio/_plt_legacy.py +9 -1
  9. tecio/_plt_read.py +285 -89
  10. tecio/_plt_write.py +286 -9
  11. tecio/_reader.py +460 -19
  12. tecio/_szl_read.py +155 -17
  13. tecio/_szl_write.py +322 -11
  14. tecio/_utils.py +78 -15
  15. tecio/_writer.py +963 -102
  16. tecio/cli/tec2mat.py +69 -30
  17. tecio/cli/tecaux.py +24 -30
  18. tecio/cli/tecdump.py +67 -5
  19. tecio/cli/tecelretyp.py +1096 -0
  20. tecio/cli/tecextract.py +57 -14
  21. tecio/cli/tecfix.py +32 -14
  22. tecio/cli/tecmerge.py +289 -45
  23. tecio/cli/teconvert.py +29 -16
  24. tecio/cli/tecscale.py +40 -13
  25. tecio/cli/tecslice.py +158 -69
  26. tecio/cli/tecstats.py +6 -2
  27. tecio/libtecio.py +192 -67
  28. {tecio_python-0.4.0.data/data/share → tecio_python-0.4.2.data/data/share/tecio}/plugins/matlab/tecmat2struct.m +18 -18
  29. {tecio_python-0.4.0.data/data/share → tecio_python-0.4.2.data/data/share/tecio}/plugins/paraview/TecplotTecioReader.py +463 -38
  30. {tecio_python-0.4.0.data/data/share → tecio_python-0.4.2.data/data/share/tecio}/plugins/paraview/TecplotTecioWriter.py +459 -84
  31. {tecio_python-0.4.0.dist-info → tecio_python-0.4.2.dist-info}/METADATA +33 -17
  32. tecio_python-0.4.2.dist-info/RECORD +40 -0
  33. {tecio_python-0.4.0.dist-info → tecio_python-0.4.2.dist-info}/WHEEL +1 -1
  34. {tecio_python-0.4.0.dist-info → tecio_python-0.4.2.dist-info}/entry_points.txt +1 -0
  35. tecio_python-0.4.0.dist-info/RECORD +0 -38
  36. {tecio_python-0.4.0.data/data/share → tecio_python-0.4.2.data/data/share/tecio}/plugins/matlab/contourfe.m +0 -0
  37. {tecio_python-0.4.0.dist-info → tecio_python-0.4.2.dist-info}/licenses/LICENSE +0 -0
  38. {tecio_python-0.4.0.dist-info → tecio_python-0.4.2.dist-info}/licenses/NOTICE +0 -0
  39. {tecio_python-0.4.0.dist-info → tecio_python-0.4.2.dist-info}/top_level.txt +0 -0
tecio/__init__.py CHANGED
@@ -11,7 +11,7 @@ from importlib import metadata
11
11
  try:
12
12
  __version__ = metadata.version("tecio")
13
13
  except metadata.PackageNotFoundError:
14
- __version__ = "0.4.0"
14
+ __version__ = "0.4.2"
15
15
 
16
16
  from . import cli, libtecio
17
17
  from ._constants import (
@@ -30,6 +30,19 @@ from ._constants import (
30
30
  from ._containers import VariableList, ZoneList
31
31
  from ._dat_read import TecplotDatReader
32
32
  from ._dat_write import TecplotDatWriter
33
+ from ._elements import (
34
+ UNKNOWN_SHAPE,
35
+ cell_face_neighbors,
36
+ classify_cells,
37
+ collapse_cells,
38
+ collapsed_zone_type,
39
+ degenerate_edges,
40
+ expand_cells,
41
+ match_cells,
42
+ match_nodes,
43
+ shape_counts,
44
+ split_cells_by_shape,
45
+ )
33
46
  from ._io import (
34
47
  AppendReadWrite,
35
48
  AppendWrite,
@@ -48,8 +61,10 @@ from ._plt_read import TecplotPltReader
48
61
  from ._plt_write import TecplotPltWriter
49
62
  from ._reader import (
50
63
  TecplotAuxDataReader,
64
+ TecplotFEMixedZoneReader,
51
65
  TecplotFEZoneReader,
52
66
  TecplotOrderedZoneReader,
67
+ TecplotPolyZoneReader,
53
68
  TecplotReader,
54
69
  TecplotVariableReader,
55
70
  TecplotZoneReader,
@@ -61,6 +76,20 @@ from ._writer import EmptyZoneWarning, TecplotWriter
61
76
  # Ensure these display as their canonical public name in docs and help(),
62
77
  # rather than the private module they're actually defined in.
63
78
  open.__module__ = "tecio"
79
+ for _func in (
80
+ cell_face_neighbors,
81
+ classify_cells,
82
+ collapse_cells,
83
+ collapsed_zone_type,
84
+ degenerate_edges,
85
+ expand_cells,
86
+ match_cells,
87
+ match_nodes,
88
+ shape_counts,
89
+ split_cells_by_shape,
90
+ ):
91
+ _func.__module__ = "tecio"
92
+ del _func
64
93
  for _cls in (
65
94
  AppendWrite,
66
95
  AppendReadWrite,
@@ -70,6 +99,8 @@ for _cls in (
70
99
  TecplotZoneReader,
71
100
  TecplotOrderedZoneReader,
72
101
  TecplotFEZoneReader,
102
+ TecplotFEMixedZoneReader,
103
+ TecplotPolyZoneReader,
73
104
  TecplotVariableReader,
74
105
  TecplotAuxDataReader,
75
106
  TecplotSzlReader,
@@ -116,6 +147,8 @@ __all__ = [
116
147
  "TecplotZoneReader",
117
148
  "TecplotOrderedZoneReader",
118
149
  "TecplotFEZoneReader",
150
+ "TecplotFEMixedZoneReader",
151
+ "TecplotPolyZoneReader",
119
152
  "TecplotVariableReader",
120
153
  "TecplotAuxDataReader",
121
154
  "TecplotSzlReader",
@@ -126,6 +159,17 @@ __all__ = [
126
159
  "TecplotPltWriter",
127
160
  "TecplotDatWriter",
128
161
  "EmptyZoneWarning",
162
+ "UNKNOWN_SHAPE",
163
+ "cell_face_neighbors",
164
+ "classify_cells",
165
+ "collapse_cells",
166
+ "collapsed_zone_type",
167
+ "degenerate_edges",
168
+ "expand_cells",
169
+ "match_cells",
170
+ "match_nodes",
171
+ "shape_counts",
172
+ "split_cells_by_shape",
129
173
  "Boolean",
130
174
  "DataPacking",
131
175
  "DataType",
@@ -153,5 +197,5 @@ _STANDARD_MODULE_ATTRIBUTES = (
153
197
 
154
198
 
155
199
  # Only public API visible to user
156
- def __dir__() -> list:
200
+ def __dir__() -> list: # pragma: no cover
157
201
  return sorted((*_STANDARD_MODULE_ATTRIBUTES, *__all__))
tecio/_constants.py CHANGED
@@ -148,13 +148,13 @@ class FeCellShape(Enum):
148
148
  - 3D four-node element.
149
149
  * - ``HEXAHEDRON``
150
150
  - ``4``
151
- - 3D six-node element.
151
+ - 3D eight-node element.
152
152
  * - ``PYRAMID``
153
153
  - ``5``
154
154
  - 3D five-node element.
155
155
  * - ``PRISM``
156
156
  - ``6``
157
- - 3D eight-node element.
157
+ - 3D six-node element.
158
158
  """
159
159
 
160
160
  BAR = 0
tecio/_dat_read.py CHANGED
@@ -31,9 +31,11 @@ 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,
@@ -171,6 +173,9 @@ _MAX_FAST_BLOCK_ITERATIONS: int = 64
171
173
  def _quote(s: str) -> str:
172
174
  """Wrap *s* in double-quotes, escaping embedded double-quotes.
173
175
 
176
+ Returns:
177
+ str: Stripped string.
178
+
174
179
  Example:
175
180
  >>> q = _quote("hello world")
176
181
  """
@@ -180,6 +185,9 @@ def _quote(s: str) -> str:
180
185
  def _unquote(s: str) -> str:
181
186
  r"""Remove surrounding double-quotes and unescape internal ``\\"``.
182
187
 
188
+ Returns:
189
+ str: String without the surrounding quotes.
190
+
183
191
  Example:
184
192
  >>> s = _unquote('"hello \\"world\\""')
185
193
  """
@@ -192,6 +200,9 @@ def _unquote(s: str) -> str:
192
200
  def _strip_comment(line: str) -> str:
193
201
  """Remove a Tecplot ``#`` comment and trailing whitespace.
194
202
 
203
+ Returns:
204
+ str: The line without the comment and trailing whitespace.
205
+
195
206
  Example:
196
207
  >>> clean = _strip_comment(line)
197
208
  """
@@ -394,6 +405,9 @@ def _kv_split(text: str) -> dict[str, str]:
394
405
  Handles quoted values, parenthesised blocks (VARLOCATION, VARSHARELIST), and
395
406
  bracketed lists (PASSIVEVARLIST).
396
407
 
408
+ Returns:
409
+ dict: Mapping of upper-cased keys to their raw string values.
410
+
397
411
  Example:
398
412
  >>> d = _kv_split("I=3, J=4, K=1")
399
413
 
@@ -683,6 +697,9 @@ def _parse_dt(text: str) -> list[DataType]:
683
697
  def _parse_auxdata_line(line: str) -> tuple[str, str]:
684
698
  """Parse ``DATASETAUXDATA name="value"`` → ``(name, value)``.
685
699
 
700
+ Returns:
701
+ tuple: Tuple of the name and value, or empty strings if the line has no ``=``.
702
+
686
703
  Example:
687
704
  >>> name, val = _parse_auxdata_line('DATASETAUXDATA Solver="MyCFD"')
688
705
  """
@@ -767,7 +784,11 @@ class _LineBuffer:
767
784
  return ""
768
785
 
769
786
  def next_stripped(self) -> str:
770
- """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
+ """
771
792
  if self._peeked is None:
772
793
  self.peek_stripped()
773
794
  value = self._peeked or ""
@@ -776,6 +797,19 @@ class _LineBuffer:
776
797
  self._peeked_pos = -1
777
798
  return value
778
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
+
779
813
  def take_raw(self, count: int) -> list[str]:
780
814
  """Consume and return up to *count* **unprocessed** source lines.
781
815
 
@@ -788,6 +822,9 @@ class _LineBuffer:
788
822
  Intended only for the numeric fast-path readers, which feed the result straight
789
823
  to a whitespace-tolerant NumPy parser and don't need per-line preprocessing.
790
824
 
825
+ Returns:
826
+ list: The raw lines, fewer than *count* at the end of the file.
827
+
791
828
  Example:
792
829
  >>> lines = buf.take_raw(64)
793
830
  """
@@ -923,7 +960,11 @@ class TecplotDatVariableReader(TecplotVariableReader):
923
960
  return self._value_location
924
961
 
925
962
  def is_passive(self) -> bool:
926
- """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
+ """
927
968
  return self._passive
928
969
 
929
970
  @property
@@ -1025,10 +1066,7 @@ class TecplotDatFEZoneReader(TecplotFEZoneReader):
1025
1066
  DAT has no concept of a disabled zone, so the base class default (always True)
1026
1067
  applies.
1027
1068
 
1028
- FEPOLYGON/FEPOLYHEDRON are not constructed as this class, or at all, the parser
1029
- rejects them with :exc:`ValueError` before reaching here (see ``_parse_zone``), so
1030
- unlike PLT there's no partial-metadata-only case to handle for those types in the
1031
- ASCII reader.
1069
+ FEPOLYGON/FEPOLYHEDRON zones are read as :class:`TecplotDatPolyZoneReader`.
1032
1070
  """
1033
1071
 
1034
1072
  __slots__ = (
@@ -1111,6 +1149,65 @@ class TecplotDatFEZoneReader(TecplotFEZoneReader):
1111
1149
  return TecplotDatAuxDataReader(self._aux_raw)
1112
1150
 
1113
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
+
1114
1211
  class _DatZoneInfo(NamedTuple):
1115
1212
  """Per-zone metadata from a cheap header-only scan."""
1116
1213
 
@@ -1256,9 +1353,7 @@ def _peek_dat_metadata(path: str | os.PathLike) -> _DatMetadata:
1256
1353
  num_nodes = zi * zj * zk
1257
1354
  num_elements = max(zi - 1, 1) * max(zj - 1, 1) * max(zk - 1, 1)
1258
1355
  else:
1259
- # FE zones (including FEPOLYGON/FEPOLYHEDRON, which the full parser can't
1260
- # read data for, but whose header is just as legible as any other zone's)
1261
- # always state counts directly.
1356
+ # FE and poly zones always state counts directly.
1262
1357
  num_nodes = int(kv.get("NODES", kv.get("N", "0")) or "0")
1263
1358
  num_elements = int(kv.get("ELEMENTS", kv.get("E", "0")) or "0")
1264
1359
 
@@ -1267,6 +1362,22 @@ def _peek_dat_metadata(path: str | os.PathLike) -> _DatMetadata:
1267
1362
  return _DatMetadata(title, file_type, variable_names, zones)
1268
1363
 
1269
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
+
1270
1381
  class TecplotDatReader(TecplotReader):
1271
1382
  """Reader for Tecplot ASCII DAT files.
1272
1383
 
@@ -1527,6 +1638,10 @@ class TecplotDatReader(TecplotReader):
1527
1638
  def _parse_zone(self, tokens: _LineBuffer) -> None:
1528
1639
  """Parse one ZONE block (header + data blocks + connectivity).
1529
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
+
1530
1645
  Example:
1531
1646
  >>> self._parse_zone(tokens)
1532
1647
  """
@@ -1559,12 +1674,6 @@ class TecplotDatReader(TecplotReader):
1559
1674
 
1560
1675
  zone_type = _determine_zone_type(kv)
1561
1676
 
1562
- if zone_type in _FE_POLY:
1563
- raise ValueError(
1564
- f"Zone type {zone_type.name!r} is not yet supported by the "
1565
- "ASCII reader."
1566
- )
1567
-
1568
1677
  # Passive/shared variables are parsed here (ahead of var_locs/var_types below,
1569
1678
  # which don't need this ordering) because the point-count inference just below
1570
1679
  # needs active_count first.
@@ -1595,6 +1704,12 @@ class TecplotDatReader(TecplotReader):
1595
1704
  num_nodes = int(kv.get("NODES", kv.get("N", "0")) or "0")
1596
1705
  num_cells = int(kv.get("ELEMENTS", kv.get("E", "0")) or "0")
1597
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
+ )
1598
1713
 
1599
1714
  # Packing: DATAPACKING wins, then legacy F, else BLOCK (Tecplot default).
1600
1715
  if "DATAPACKING" in kv:
@@ -1610,6 +1725,12 @@ class TecplotDatReader(TecplotReader):
1610
1725
  else:
1611
1726
  packing = DataPacking.BLOCK
1612
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
+
1613
1734
  # Face-neighbor connections (finite-element zones only; ordered zones
1614
1735
  # don't need them, adjacency is already implicit in the I/J/K
1615
1736
  # structure). FACENEIGHBORCONNECTIONS is authoritative for how many
@@ -1685,8 +1806,26 @@ class TecplotDatReader(TecplotReader):
1685
1806
  # -- Read connectivity (FE zones only) -----------------------------------------
1686
1807
 
1687
1808
  node_map: npt.NDArray | None = None
1809
+ face_map: dict[str, npt.NDArray[np.int64]] = {}
1688
1810
 
1689
- 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:
1690
1829
  if con_share_zone and self._zones:
1691
1830
  source_zone = self._zones[con_share_zone - 1]
1692
1831
  if isinstance(source_zone, TecplotFEZoneReader):
@@ -1787,6 +1926,30 @@ class TecplotDatReader(TecplotReader):
1787
1926
  for idx, name in enumerate(self._variable_names)
1788
1927
  ]
1789
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
+
1790
1953
  self._zones.append(
1791
1954
  self._build_zone(
1792
1955
  zone_index=zone_index,
@@ -1829,7 +1992,11 @@ class TecplotDatReader(TecplotReader):
1829
1992
  face_connections: npt.NDArray[np.int64] | None = None,
1830
1993
  face_neighbors_complete: bool | None = None,
1831
1994
  ) -> TecplotZoneReader:
1832
- """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
+ """
1833
2000
  if zone_type == ZoneType.ORDERED:
1834
2001
  return TecplotDatOrderedZoneReader(
1835
2002
  zone_index=zone_index,
@@ -1862,6 +2029,64 @@ class TecplotDatReader(TecplotReader):
1862
2029
  face_neighbors_complete=face_neighbors_complete,
1863
2030
  )
1864
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
+
1865
2090
  # -- Block readers -----------------------------------------------------------------
1866
2091
 
1867
2092
  @staticmethod
@@ -1881,6 +2106,10 @@ class TecplotDatReader(TecplotReader):
1881
2106
  from *tokens* at the position the fast path started from, so the two never
1882
2107
  disagree about what was consumed.
1883
2108
 
2109
+ Returns:
2110
+ NDArray: Float64 array of *n_values* values, or fewer if the data block ends
2111
+ early.
2112
+
1884
2113
  See Also:
1885
2114
  :meth:`_read_block_var_data`/:meth:`_read_point_var_data`.
1886
2115
 
@@ -1917,6 +2146,10 @@ class TecplotDatReader(TecplotReader):
1917
2146
  the slow, boundary-aware parser. A ``ValueError`` from ``numpy.fromstring`` is
1918
2147
  allowed to propagate to the caller for the same reason.
1919
2148
 
2149
+ Returns:
2150
+ NDArray: Array of *n_values* values, or ``None`` if the fast path cannot
2151
+ read them.
2152
+
1920
2153
  Example:
1921
2154
  >>> arr = TecplotDatReader._read_float_block_fast(tokens, 100)
1922
2155
 
@@ -1953,6 +2186,9 @@ class TecplotDatReader(TecplotReader):
1953
2186
  :func:`_is_float_block_boundary`) even if *n_values* hasn't been reached
1954
2187
  yet. Slow by design, but guarantees a result either way.
1955
2188
 
2189
+ Returns:
2190
+ NDArray: Float64 array of up to *n_values* values.
2191
+
1956
2192
  Example:
1957
2193
  >>> arr = TecplotDatReader._read_float_block_slow(tokens, 100)
1958
2194
 
@@ -1995,6 +2231,9 @@ class TecplotDatReader(TecplotReader):
1995
2231
  call) is deliberate: :meth:`_read_float_block`'s vectorized fast path already
1996
2232
  costs only a handful of C-level calls per block regardless of size.
1997
2233
 
2234
+ Returns:
2235
+ list: One array per variable, ``None`` for passive and shared variables.
2236
+
1998
2237
  Note:
1999
2238
  Passive and shared variables contribute a ``None`` placeholder to the
2000
2239
  returned list. The caller resolves shared variables against the zones parsed
@@ -2043,6 +2282,9 @@ class TecplotDatReader(TecplotReader):
2043
2282
  its variable's actual declared dtype (from ``DT=``, or the spec's documented
2044
2283
  SINGLE default) right where it's extracted from the interleaved rows.
2045
2284
 
2285
+ Returns:
2286
+ list: One array per variable, ``None`` for passive and shared variables.
2287
+
2046
2288
  See Also:
2047
2289
  :meth:`_read_block_var_data`
2048
2290
 
@@ -2102,6 +2344,9 @@ class TecplotDatReader(TecplotReader):
2102
2344
  tolerant-slow-path split as :meth:`_read_float_block`; see that method's
2103
2345
  docstring for the rationale.
2104
2346
 
2347
+ Returns:
2348
+ NDArray: Int64 array of *n_values* values, or fewer if the data block ends early.
2349
+
2105
2350
  Examples:
2106
2351
  >>> arr = TecplotDatReader._read_int_block(tokens, 24)
2107
2352
  """
@@ -2126,6 +2371,9 @@ class TecplotDatReader(TecplotReader):
2126
2371
  See :meth:`_read_float_block_fast`, which this mirrors exactly except for the
2127
2372
  target dtype.
2128
2373
 
2374
+ Returns:
2375
+ NDArray: Array of *n_values* values, or ``None`` if the fast path cannot read them.
2376
+
2129
2377
  Example:
2130
2378
  >>> arr = TecplotDatReader._read_int_block_fast(tokens, 24)
2131
2379
  """
@@ -2154,6 +2402,9 @@ class TecplotDatReader(TecplotReader):
2154
2402
  def _read_int_block_slow(tokens: _LineBuffer, n_values: int) -> npt.NDArray:
2155
2403
  """Tolerant, token-by-token fallback for :meth:`_read_int_block`.
2156
2404
 
2405
+ Returns:
2406
+ NDArray: Int64 array of up to *n_values* values.
2407
+
2157
2408
  Example:
2158
2409
  >>> arr = TecplotDatReader._read_int_block_slow(tokens, 24)
2159
2410
  """