tecio.TecplotPltWriter#

class tecio.TecplotPltWriter(path, title='untitled', variables=None, file_type=FileType.FULL, *, precision=DataType.DOUBLE)#

Bases: TecplotWriter

Write Tecplot PLT (.plt) files using the classic TecIO API.

The classic TecIO API maintains a single implicit global file context; only one PLT file may be open at a time. This class wraps that procedural API behind the same interface as TecplotSzlWriter.

Dataset- and variable-level auxiliary data can be set at any time before the first zone is written. They are buffered and flushed automatically when the first zone header is created. Zone-level auxiliary data is passed directly to each zone-writing method.

Like TecplotSzlWriter, the file can be opened eagerly (when variables is supplied to __init__) or lazily (deferred until the first write_ordered_zone() or write_fe_zone() call, at which point variables must be provided to that call).

Parameters:
  • path – Output file path (should end in .plt).

  • title – Dataset title string.

  • variables – Variable name list. If provided the file is opened immediately. If None, the file is opened on the first zone write.

  • file_type – FileType enum. Defaults to FULL.

  • precision – Whole-file storage precision (DataType.FLOAT/"single" or DataType.DOUBLE/"double"). Unlike SZL, PLT has no per-variable type, so this always resolves to a concrete value; None is not accepted. Defaults to DataType.DOUBLE.

precision#

Whole-file storage precision (DataType.FLOAT or DataType.DOUBLE). Maps directly to VIsDouble in tecini142.

_opened#

True once tecini142 has been called (the file has been opened, eagerly or lazily), False before that and after close(). Governs whether close() calls tecend142, and whether the next zone write needs to open the file first.

Caution

Unlike the SZL writer, zone data must be written strictly in order: header → variable data → connectivity. This is enforced internally by the write methods.

Examples

Define file header fields on open.

>>> with tecio.TecplotPltWriter("out.plt", variables=["X", "Y", "P"]) as w:
...     w.write_ordered_zone(data=[x, y, p], title="Zone 1")

If writer handle is opened with just the file name, the variable name list can be provided with the first zone written.

>>> with tecio.TecplotPltWriter("out.plt") as w:
...     w.write_ordered_zone(
...         data=[x, y, p],
...         variables=["X", "Y", "P"],
...         title="Zone 1",
...     )

Attributes

meta

Read-only record of everything written to this file so far.

Methods

add_auxdataset_dict(auxdict)

Buffer dataset-level auxiliary data from a dictionary.

add_auxvar_dict(auxdict)

Buffer variable-level auxiliary data from a dictionary.

close()

Finalize and close the PLT file (safe to call more than once).

flush_aux()

Write buffered dataset- and variable-level aux data to the file.

write_fe_zone(data, zone_type[, node_map, ...])

Write a complete finite-element zone.

write_femixed_zone(data[, cell_shapes, ...])

Not supported: PLT files cannot hold FEMIXED zones.

write_ordered_zone(data, *[, title, ...])

Write a complete IJK-ordered zone.

write_poly_zone(data, zone_type, *[, ...])

Write a complete FEPOLYGON or FEPOLYHEDRON (face-based) zone.

close()[source]#

Finalize and close the PLT file (safe to call more than once).

Flushes any buffered aux data first (in case it was added after the first zone, and so never reached the automatic pre-first-zone flush, e.g. add_auxdataset_dict called after a zone is already written), then calls tecend142 if the file was opened.

write_fe_zone(data, zone_type, node_map=None, *, title=None, variables=None, value_locations=None, passive_vars=None, var_sharing=None, con_sharing=None, face_neighbors=None, face_neighbor_mode=None, solution_time=0.0, strand_id=0, aux=None, datapacking=DataPacking.BLOCK)[source]#

Write a complete finite-element zone.

Node and cell counts are inferred from node_map, or if node_map is omitted, from the zone referenced by con_sharing.

The full sequence required by the classic TecIO API is issued internally:

  1. teczne142() — zone header.

  2. teczauxstr142() — zone-level aux data (if any), before data.

  3. tecdat142() — one call per active variable.

  4. tecnode142() — node map (skipped when connectivity is shared via con_sharing).

  5. tecface142() — face-neighbour connections (if provided).

FEPOLYGON and FEPOLYHEDRON zones are face-based, write them with write_poly_zone().

Parameters:
  • data (Sequence[npt.ArrayLike]) – Sequence of 1-D arrays, one per active (non-passive, non-shared) dataset variable, in dataset order. NODAL arrays must have length num_nodes; CELL_CENTERED arrays must have length num_cells. num_nodes and num_cells are inferred from node_map (or from the con_sharing source zone when node_map is omitted).

  • zone_type (ZoneType) – FE zone type from the ZoneType enum. Must be one of the types in _FE_SIMPLE.

  • node_map (npt.ArrayLike) – Integer array of shape (num_cells, nodes_per_cell) containing 0-based node indices. Required unless con_sharing is set, in which case the connectivity are inherited from the source zone instead.

  • title (str) – Zone title string. Defaults to "FE_Zone_{index}", this zone’s 0-based index.

  • variables (list[str]) – Variable name list. Required only when the file has not been opened yet (lazy-open path). Ignored on subsequent zones once the file is already initialised. Default to [V1, V2, V3, ...] if not provided in open or zone call.

  • value_locations (Sequence[ValueLocation]) – Per-active-variable ValueLocation. Defaults to all NODAL.

  • passive_vars (list | tuple | set | None) – Variables to mark passive: a list, tuple, or set of variable names, or of 0-based indices, e.g. {"x"} or [3]. Defaults to all active (passive_vars=None).

  • var_sharing (Mapping[int | str, int]) – Variables to share from another zone: a {variable: source zone} mapping, name or 0-based index to 0-based zone index. Defaults to no sharing (None or an empty mapping). Cross-checked against node_map / con_sharing for a consistent node/cell count.

  • con_sharing (int) – Optional zone index that the connectivity is shared from. None indicates no sharing (this zone owns its connectivity). The first zone in a dataset must own its connectivity. Connectivity cannot be shared when face neighbor mode is set to global. Connectivity cannot be shared between cell-based and face-based finite element zones.

  • face_neighbors (npt.ArrayLike) – Optional face-neighbor connectivity, always a flat array (whatever shape you pass is flattened before writing). The number of values per connection depends on face_neighbor_mode, a fixed 3 or 4 for the one-to-one modes, a variable, self-describing count per record for the “many” modes. The connection count is always derived from this array, never a separate parameter.

  • face_neighbor_mode (FaceNeighborMode) – Default to None meaning no face-neighbor data. If face_neighbors is supplied without defining a face neighbor mode, it is treated as LOCAL_ONE_TO_ONE. Cannot be defined without also supplying a face_neighbors array.

  • solution_time (float) – Solution time for transient data. Default to 0.0 if not defined.

  • strand_id (int) – Strand ID for transient data. Use 0 for static zones. Default to 0 (static) if not defined.

  • aux (dict[str, str | float | int]) – Zone-level auxiliary data as {name: value} string pairs.

  • datapacking (DataPacking | str) – In POINT format, the values for all variables are given for the first point, then the second point, and so on. In BLOCK format, all of the values for the first variable are given in a block, then all of the values for the second variable, then all of the values for the third, and so forth. BLOCK format must be used for cell-centered data and polyhedral zones (FEPOLYGON/FEPOLYHEDRAL), as well as for all binary data. POINT and BLOCK keyword strings also accepted. Defaults to BLOCK.

Raises:
  • NotImplementedError – If datapacking is POINT.

  • TypeError – If passive_vars/var_sharing isn’t a list/tuple/set/mapping as appropriate, or mixes variable names and indices.

  • ValueError – For FEPOLYGON or FEPOLYHEDRON (use write_poly_zone()); on variable count or array length mismatch; if node_map is omitted without con_sharing; if var_sharing/con_sharing reference a zone with no recorded node/cell count, or one whose count disagrees with this zone’s; or a variable named in both passive_vars and var_sharing.

  • ValueError – If I/O operation attempted on closed or None file handle.

  • RuntimeError – If attempting to write variable aux before variables are defined.

  • KeyError – A passive_vars/var_sharing name doesn’t match any dataset variable.

  • IndexError – A passive_vars/var_sharing index is out of range.

write_femixed_zone(data, cell_shapes=None, node_maps=None, *, title=None, variables=None, value_locations=None, passive_vars=None, var_sharing=None, con_sharing=None, solution_time=0.0, strand_id=0, aux=None, datapacking=DataPacking.BLOCK)[source]#

Not supported: PLT files cannot hold FEMIXED zones.

The signature matches TecplotSzlWriter.write_femixed_zone() so every writer exposes the same interface.

Raises:

NotImplementedError – Always. Write a .szplt file instead, see TecplotSzlWriter.write_femixed_zone().

write_ordered_zone(data, *, title=None, variables=None, value_locations=None, passive_vars=None, var_sharing=None, solution_time=0.0, strand_id=0, aux=None, datapacking=DataPacking.BLOCK)[source]#

Write a complete IJK-ordered zone.

The zone header (teczne142), variable data (tecdat142), and optional zone aux data (teczauxstr142) are all written in strict sequence, as required by the classic TecIO API.

The zone dimensions imax × jmax × kmax are inferred from the shape of the first nodal data array. 1-D arrays produce a (N, 1, 1) zone; 2-D arrays produce an (I, J, 1) zone.

Parameters:
  • data (Sequence[npt.ArrayLike]) – One NumPy array per active (non-passive, non-shared) dataset variable, in dataset order. Array shape is used to infer imax, jmax, and kmax; Fortran (column-major) order is assumed. Pass None to write a zone header only.

  • title (str) – Zone title. Defaults to "IJK_Zone_{index}", this zone’s 0-based index.

  • variables (list[str]) – Variable name list. Required on the first call when the file has not been opened yet (lazy-open path); ignored once the file is already initialised. Default to [V1, V2, V3, ...] if not provided in open or zone call.

  • value_locations (Sequence[ValueLocation]) – Per-active-variable ValueLocation. Defaults to all NODAL.

  • passive_vars (list | tuple | set | None) – Variables to mark passive: a list, tuple, or set of variable names, or of 0-based indices, e.g. {"x"} or [3]. Defaults to all active (passive_vars=None).

  • var_sharing (Mapping[int | str, int]) – Variables to share from another zone: a {variable: source zone} mapping, name or 0-based index to 0-based zone index, e.g. {"x": 0, "y": 0}. Defaults to no sharing.

  • solution_time (float) – Solution time for transient data. Default to 0.0 if not defined.

  • strand_id (int) – Strand ID for transient data. Use 0 for static zones. Default to 0 (static) if not defined.

  • aux (dict[str, str | float | int]) – Zone-level auxiliary data as {name: value} string pairs.

  • datapacking (DataPacking | str) – In POINT format, the values for all variables are given for the first point, then the second point, and so on. In BLOCK format, all of the values for the first variable are given in a block, then all of the values for the second variable, then all of the values for the third, and so forth. BLOCK format must be used for cell-centered data and polyhedral zones (FEPOLYGON/FEPOLYHEDRAL), as well as for all binary data. POINT and BLOCK keyword strings also accepted. Defaults to BLOCK.

Raises:
  • NotImplementedError – If datapacking is POINT.

  • TypeError – If passive_vars/var_sharing isn’t a list/tuple/set/mapping as appropriate, or mixes variable names and indices.

  • ValueError – If I/O operation attempted on closed or None file handle, or a variable is named in both passive_vars and var_sharing.

  • RuntimeError – If attempting to write variable aux before variables are defined.

  • KeyError – A passive_vars/var_sharing name doesn’t match any dataset variable.

  • IndexError – A passive_vars/var_sharing index is out of range.

write_poly_zone(data, zone_type, *, face_nodes=None, face_node_counts=None, face_left_elements=None, face_right_elements=None, boundary_connection_counts=None, boundary_connection_elements=None, boundary_connection_zones=None, title=None, variables=None, value_locations=None, passive_vars=None, var_sharing=None, con_sharing=None, solution_time=0.0, strand_id=0, aux=None, datapacking=DataPacking.BLOCK)[source]#

Write a complete FEPOLYGON or FEPOLYHEDRON (face-based) zone.

Node and element counts are inferred from the face map, or from the con_sharing source zone when it is omitted. Every index is 0-based. The arguments match what TecplotPolyZoneReader returns, so a zone read from a file can be written back unchanged.

The classic TecIO sequence is issued internally: tecpolyzne142 (header), teczauxstr142 (aux data), tecdat142 (one call per active variable), then tecpolyface142 and, with boundary connections, tecpolybconn142. Connectivity is skipped when shared via con_sharing.

Parameters:
  • data (Sequence[npt.ArrayLike]) – Sequence of 1-D arrays, one per active (non-passive, non-shared) dataset variable, in dataset order. NODAL arrays need num_nodes values, CELL_CENTERED arrays num_elements, both inferred from the face map.

  • zone_type (ZoneType) – FEPOLYGON or FEPOLYHEDRON.

  • face_nodes (npt.ArrayLike) – Flat 0-based node indices of all faces, in face order. Two per face for a polygon zone. Required unless con_sharing is set.

  • face_node_counts (npt.ArrayLike) – Number of nodes of each face. Required for FEPOLYHEDRON. Optional for FEPOLYGON, where every face has 2 nodes.

  • face_left_elements (npt.ArrayLike) – Element on the left of each face: a 0-based element index, -1 for no element, or -(b + 2) for boundary face b (0-based).

  • face_right_elements (npt.ArrayLike) – Element on the right of each face, same convention as face_left_elements.

  • boundary_connection_counts (npt.ArrayLike) – Number of connections of each boundary face. Boundary faces describe neighbors in other zones, or faces with more than one neighbor.

  • boundary_connection_elements (npt.ArrayLike) – Flat 0-based neighbor element of every boundary connection.

  • boundary_connection_zones (npt.ArrayLike) – Flat 0-based zone of every neighbor element. May only reference a zone already written or this zone.

  • title (str) – Zone title string. Defaults to "Poly_Zone_{index}", with this zone’s 0-based index.

  • variables (list[str]) – Variable name list, only used when the file has not been opened yet (lazy-open path). Defaults to [V1, V2, V3, ...].

  • value_locations (Sequence[ValueLocation]) – Per-active-variable ValueLocation. Defaults to all NODAL.

  • passive_vars (list | tuple | set | None) – Variables to mark passive: a list, tuple, or set of variable names, or of 0-based indices. Defaults to all active.

  • var_sharing (Mapping[int | str, int]) – Variables to share from another zone: a {variable: source zone} mapping, name or 0-based index to 0-based zone index.

  • con_sharing (int) – Zone index to share the face map from, which must be a zone of the same type without boundary faces (TecIO does not allow sharing those). None means this zone owns its connectivity.

  • solution_time (float) – Solution time for transient data. Defaults to 0.0.

  • strand_id (int) – Strand ID for transient data, 0 for static zones.

  • aux (dict[str, str | float | int]) – Zone-level auxiliary data as {name: value} pairs.

  • datapacking (DataPacking | str) – Must be BLOCK, the only layout of the PLT binary format.

Raises:
  • TypeError – If passive_vars/var_sharing isn’t a list/tuple/set/mapping as appropriate, or mixes variable names and indices.

  • ValueError – If datapacking is POINT. For a zone_type other than FEPOLYGON or FEPOLYHEDRON (use write_fe_zone()); on a missing, inconsistent, or out of range face map, boundary connection, or variable array.

  • KeyError – A passive_vars/var_sharing name doesn’t match any dataset variable.

  • IndexError – A passive_vars/var_sharing index is out of range.