tecio.TecplotSzlWriter#

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

Bases: TecplotWriter

Write Tecplot SZL (.szplt) files with a lazy-open file handle.

Supports lazy-open: if variables is None at construction, the file is created on the first zone write. Auxiliary data is buffered and flushed automatically before the first zone.

The tecio library requires a list of variables when the output file is opened. However if writing data on the fly, it may be beneficial to store file outputs until the first zone is passed to the writer. Then file header will be garanteed to be consistent with the first zone variables.

For the SZL API, file contents can be written out of order after creating zones.

Parameters:
  • path – Output file path.

  • title – Dataset title.

  • variables – Variable name list. None defers file creation.

  • file_type – File type enum (FULL, GRID, or SOLUTION).

  • precision – Optional whole file floating point precision override (DataType.FLOAT/"single" or DataType.DOUBLE/"double"). Defaults to None: each variable’s type is inferred automatically from its own array’s dtype.

precision#

Whole-file floating-point override, or None for automatic per-variable inference.

handle#

Raw C file handle from tec_file_writer_open, or None before the file has been opened (or after close()).

current_var#

0-based index of the variable most recently passed to a libtecio write call. Set only while a zone’s variable data is being written, and only ever read by user code inspecting the writer, not consumed internally; useful for diagnosing which variable was in progress if a write fails partway through a zone.

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()

Finalise and flush the 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, ...])

Write a complete FEMIXED (mixed finite-element) zone.

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

Write a complete IJK-ordered zone.

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

Not supported: SZPLT files cannot hold polygon or polyhedron zones.

close()[source]#

Finalise and flush the file (safe to call more than once).

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, flush=False)[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 32- or 64-bit write path is chosen automatically from the max index.

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.

  • flush – If True, flush this zone and all previous data to a temporary intermediate file immediately after writing, releasing data from memory. Defaults to False. Useful when memory is a concern, but adds the overhead of a disk write. Temporary files are merged back into the final output file when close() is called.

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 (not supported in SZPLT files, see 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.

Note

FE variable arrays are 1-D and node-ordered. write_data handles dtype inference and F-order ravel internally, but 1-D arrays are unaffected by memory order.

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, flush=False)[source]#

Write a complete FEMIXED (mixed finite-element) zone.

A FEMIXED zone holds 1 to 16 sections, each with one cell shape. A typical use is a CFD volume mesh of tetrahedra, pyramids, prisms and hexahedra in one zone rather than every cell padded to a brick. All sections must have the same spatial dimension (all line, all surface or all volume cells). Cells are numbered through the sections in order, so a CELL_CENTERED array lists the cells of the first section first. Only linear (grid order 1) cells are supported.

Node and cell counts are inferred from node_maps, or from the zone referenced by con_sharing. The 32- or 64-bit write path is chosen from the node count. This writer does not write face-neighbor connections.

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 the total cell count over all sections.

  • cell_shapes (Sequence[FeCellShape]) – Cell shape of each section. A shape name or value is also accepted. Required unless con_sharing is set, in which case it must be omitted.

  • node_maps (Sequence[npt.ArrayLike]) – One integer array per section, of shape (num_cells, nodes_per_cell) with 0-based node indices. A flat array is reshaped. A section may have no cells. Required unless con_sharing is set, in which case it must be omitted.

  • title (str) – Zone title string. Defaults to "FEMixed_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). 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) – Optional index of a FEMIXED zone to share the connectivity of. The first zone in a dataset must own 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) – Only BLOCK (the default) is supported.

  • flush – If True, flush this zone and all previous data to a temporary intermediate file after writing, releasing data from memory.

Raises:
  • NotImplementedError – If datapacking is POINT.

  • ValueError – On a bad section layout or array shape, sections of different spatial dimension, fewer dataset variables than the cell dimension, a variable count or array length mismatch, or a bad con_sharing or var_sharing source zone. See prepare_femixed_zone().

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

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

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

  • RuntimeError – If the writer has been closed.

Note

SZPLT reorders cells and nodes internally for storage, so the arrays read back may be a permutation of the arrays written, consistently across all variables and the node maps.

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, flush=False)[source]#

Write a complete IJK-ordered zone.

Dimensions are inferred from the first array’s shape. Arrays may be 1-D, 2-D, or 3-D; missing trailing dimensions default to 1.

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.

  • flush (bool) – If True, flush this zone and all previous data to a temporary intermediate file immediately after writing, releasing data from memory. Defaults to False. Useful when memory is a concern, but adds the overhead of a disk write. Temporary files are merged back into the final output file when close() is called.

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 empty file handle, a variable is named in both passive_vars and var_sharing, or datapacking is not a recognised value.

  • 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.

Note

If the file is already open, data and variables may be omitted to write a zone header only. If the file has not been opened yet, variables must be provided on this call.

Note

Data arrays are written as DOUBLE precision by default. To write other types, cast the NumPy arrays before calling (e.g. arr.astype(np.float32)).

Note

Separate grid files (where all variables are cell-centred) are not handled automatically; use the low-level API for that case.

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]#

Not supported: SZPLT files cannot hold polygon or polyhedron zones.

Raises:

NotImplementedError – Always. Write to a .plt or .dat file instead, see TecplotPltWriter.write_poly_zone().