API Reference#

tecio is designed around a single entry point, tecio.open(), which opens a Tecplot file for reading, writing, or appending and returns the appropriate reader or writer based on the file extension. In most cases you will not need to instantiate TecplotSzlReader, TecplotSzlWriter, or any other class directly; tecio.open() selects and returns the correct one.

Mode

Description

"r"

Read an existing file

"w"

Write a new file

"x"

Write, failing if the file already exists

"a"

Append new zones to an existing file

"a+"

Append and read in the same session

Extension

Format

.szplt

Tecplot SZL binary (subzone-loadable)

.plt, .bin, .bbin, .bbin8

Tecplot PLT binary

.dat, .tec

Tecplot ASCII


Indexing#

From the Tecplot Data Format Guide,

All indexing in Tecplot data files (including zones and variables) is 1-based, so the last index is exactly equal to (not one less than) the count of the element type. An exception is nodes in finite-element zones, which can be specified to be zero-based. C and C++ programmers in particular should be wary of off-by-one errors when dealing with Tecplot data.

tecio’s Python API follows standard Python convention everywhere instead: every zone, variable, node, and cell index it accepts or reports is 0-based, the same as indexing a list or a NumPy array. This applies uniformly, from container indexing to zone_index/var_index to every function or method parameter that names a zone or variable.

Container indexing is 0-based:

r.zones[0]  # the FIRST zone
r.zones[0].variables[0]  # the FIRST variable in that zone

zone_index reports that same 0-based position:

r.zones[0].zone_index  # == 0
r.zones[2].zone_index  # == 2

For read variables, var_index reports the 0-based position within its zone, and zone_index reports the 0-based index of the parent zone:

r.zones[0].variables[0].var_index  # == 0
r.zones[2].variables[0].zone_index  # == 2

Data access method get_array also uses 0-based indexing:

r.zones[0].get_array(0)  # data array for FIRST variable
r.zones[0].get_array([1, 3, 5])  # tuple of data arrays for 2nd, 4th and 6th variables

Auxiliary data access follows the same rule. get_var_auxdata and get_zone_auxdata take a 0-based index, same as zone_index and var_index:

r.get_var_auxdata(0)  # the FIRST variable's aux data
r.get_zone_auxdata(0)  # the FIRST zone's aux data

Two places keep Tecplot’s native 1-based numbering on purpose, since they hand values to (or read them from) something other than this Python API: the raw tecio.libtecio C function wrappers, which pass zone/variable/ node arguments straight through to TecIO, and the tec2mat CLI, which converts every index to 1-based on the way into its .mat output so the same values work directly in MATLAB. The text of ASCII .dat/.tec files is also 1-based, matching how Tecplot 360 itself reads and writes that format, but values tecio parses back out of a .dat file follow the same 0-based convention as every other format.


Core Classes#

These classes define the interface every reader and writer shares, regardless of which of the three file formats produced or is producing the data. See Readers and Writers for the full property/method reference.

Reading

Class

Description

TecplotReader

One open file: title, variables, zones, dataset-level aux data

TecplotZoneReader

Shared zone interface: title, type, solution time, strand ID, variables, aux data

TecplotOrderedZoneReader

Adds I/J/K/dimensions for IJK-ordered zones

TecplotFEZoneReader

Adds node_map/nodes_per_cell/shared_connectivity for finite-element zones

TecplotFEMixedZoneReader

Adds section_shapes/section_num_elements/node_maps for FEMIXED zones, SZL only

TecplotPolyZoneReader

Adds the face map (face_nodes, face_left_elements, face_right_elements, boundary connections) for polygon and polyhedron zones

TecplotVariableReader

One variable’s metadata and data within a zone

TecplotAuxDataReader

Read-only, dict-like view of one auxiliary-data mapping

Writing

Class

Description

TecplotWriter

Shared writer interface: construction, aux-data staging, zone writing, closing

TecplotZoneReader returns either TecplotOrderedZoneReader, TecplotFEZoneReader, TecplotFEMixedZoneReader or TecplotPolyZoneReader for structured, unstructured, FEMIXED and polygon/polyhedron data respectivly as these zone types have properties that are not shared (e.g. dimensions vs. node_map vs. face_nodes). Accessing a zone property no included in the zone type raises AttributeError. To check, use isinstance(zone, TecplotOrderedZoneReader) (or the FE equivalent) or zone reader object property zone_type for the more in depth identifyer ZoneType.


Format-Specific Classes#

tecio.open() constructs one of these six classes for you, based on the file extension. Construct one directly only if you want to bypass the extension-based dispatch, e.g. to force a specific format regardless of file name.

TecplotSzlReader

Reader for Tecplot .szplt files.

TecplotPltReader

Reader for Tecplot .plt binary files.

TecplotDatReader

Reader for Tecplot ASCII DAT files.

TecplotSzlWriter

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

TecplotPltWriter

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

TecplotDatWriter

Write Tecplot ASCII (.dat/.tec) files.

See Readers and Writers for each class’s full documentation, including per-format memory-model notes and parameter comparison tables. TecplotPltReader also reads several older PLT binary versions (v75, v107, v111), see Legacy PLT Versions.


Accessing Variable Data#

Every reader’s zones and variables properties return one of two format-agnostic container types rather than a plain list. Both support the same indexing, iteration, and len() you would expect from a list, plus name-based and slice-based access:

with tecio.open("flow.szplt") as r:
    r.zones[
        0
    ]  # -> TecplotOrderedZoneReader, TecplotFEZoneReader, TecplotFEMixedZoneReader, ...
    r.zones[1:4]  # -> ZoneList (sub-range, same kind)
    r.zones[0].variables  # -> VariableList
    r.zones[0].variables["x"]  # -> TecplotVariableReader, by exact name
    r.zones[0].variables[2]  # -> TecplotVariableReader, by 0-based index

Indexing a ZoneList or VariableList always returns an element or a sub-collection of the same kind — never a raw array. To pull the underlying NumPy data for one or more variables in a single zone, use TecplotZoneReader.get_array, shared by every zone type and every format:

p = r.zones[0].get_array("p")  # ndarray | None
p = r.zones[0].get_array(2)  # by 0-based index
x, y, z = r.zones[0].get_array(["x", "y", "z"])  # tuple, for unpacking

A single key (index or name) returns one array; a list of names returns a tuple of arrays in the order given, suitable for unpacking. There is deliberately no cross-zone array accessor — to pull one variable across many zones (e.g. a transient sequence), iterate explicitly so the outer axis stays in your code, and stack only when you know the shapes match:

seq = [z.get_array("p") for z in r.zones]  # list[ndarray | None]
stack = np.stack(seq)  # only if every zone matches

get_array returns None for a passive or shared variable, and raises KeyError for an unknown name or IndexError for an out-of-range index.

Class

Returned by

Description

ZoneList

TecplotReader.zones

Sequence of zones; integer index, slice, or iterate

VariableList

TecplotZoneReader.variables

Sequence of variables; index by position or exact name

See Readers for the full container API.


Meaningful Constants#

Zone types, data types, value locations, and the rest of Tecplot’s enumerated constants are plain Python enums with no dependency on the C library, importable directly from tecio (e.g. tecio.ZoneType).

FileFormat

Binary data format selector.

FileType

Tecplot file type.

ZoneType

Tecplot zone type.

DataType

On-disk storage type for variable data.

ValueLocation

Data value location within a cell.

FaceNeighborMode

Boundary face-sharing mode between zones.

FeCellShape

Unstructured cell shape category.

DataPacking

Zone data packing order for ASCII (.dat) files.

VarStatus

Variable active/passive flag.

Boolean

Boolean flag for C function arguments.

Debug

Debug flag for C function arguments.

See Constants for each constant’s full member listing.


C Function Wrappers#

tecio.libtecio provides the direct Python wrapper for every TecIO C function tecio uses internally, kept public so the library can be called directly, if desired. Importing it never raises, even with no Tecplot installation at all, or an older one missing a newer function, see C Function Wrappers for how that degradation works.

TecioError

Exception for TecIO C library errors.

TecioUnavailableError

Raised when calling a function whose C symbol is unavailable.

TecioAvailabilityWarning

Emitted once at import time if any C function could not be bound.

SZL Read Functions

tec_file_reader_open

Open an SZL file for reading.

tec_file_reader_close

Close an SZL file reader handle and release its resources.

tec_file_get_type

Get the file type for an opened SZL file.

tec_data_set_get_title

Read the dataset title string.

tec_data_set_get_num_vars

Query the number of variables in the dataset.

tec_data_set_get_num_zones

Query the number of zones in the dataset.

tec_zone_get_ijk

Get zone dimensions (ORDERED) or node/element counts (FE).

tec_zone_get_title

Read the title for a zone.

tec_zone_get_type

Query the zone type.

tec_zone_is_enabled

Check whether a zone is enabled.

tec_zone_get_solution_time

Read the solution time for a zone.

tec_zone_get_strand_id

Get the strand ID for a zone.

is_64bit

Check whether a zone's node-map uses 64-bit indices.

tec_zone_node_map_get_64

Read a 64-bit node map for an FE zone.

tec_zone_node_map_get

Read a 32-bit node map for an FE zone.

tec_zone_node_map_get_flat

Read a whole FE zone node map as one flat array.

tec_var_get_name

Get a variable name by index.

tec_var_is_enabled

Check whether a variable is enabled.

tec_zone_var_get_type

Get the data type for a variable in a zone.

tec_zone_var_get_value_location

Get the value location for a zone variable.

tec_zone_var_is_passive

Check whether a zone variable is passive.

tec_zone_var_get_shared_zone

Get the shared zone index for a variable.

tec_zone_var_get_num_values

Query the number of values for a zone variable.

tec_zone_var_get_float_values

Read float32 values for a zone variable.

tec_zone_var_get_double_values

Read float64 values for a zone variable.

tec_zone_var_get_int32_values

Read int32 values for a zone variable.

tec_zone_var_get_int16_values

Read int16 values for a zone variable.

tec_zone_var_get_uint8_values

Read uint8 values for a zone variable.

tec_data_set_aux_data_get_num_items

Get the number of dataset-level auxiliary data items.

tec_data_set_aux_data_get_item

Read a dataset-level auxiliary data item.

tec_var_aux_data_get_num_items

Get the number of auxiliary data items for a variable.

tec_var_aux_data_get_item

Read a variable-level auxiliary data item.

tec_zone_aux_data_get_num_items

Get the number of auxiliary data items for a zone.

tec_zone_aux_data_get_item

Read a zone-level auxiliary data item.

SZL Write Functions

tec_file_writer_open

Open a writer handle for creating SZL files.

tec_file_writer_close

Close a writer handle and finalise the output file.

tec_file_writer_flush

Flush written zone data to a temporary intermediate file.

tec_zone_create_ijk

Create an ordered IJK zone for writing.

tec_zone_create_fe

Create a finite-element zone for writing.

tec_zone_set_unsteady_options

Set time/strand metadata for a zone.

tec_zone_var_write_double_values

Write float64 values for a zone variable.

tec_zone_var_write_float_values

Write float32 values for a zone variable.

tec_zone_var_write_int32_values

Write int32 values for a zone variable.

tec_zone_var_write_int16_values

Write int16 values for a zone variable.

tec_zone_var_write_uint8_values

Write uint8 values for a zone variable.

tec_zone_node_map_write32

Write 32-bit node map entries for an FE zone.

tec_zone_node_map_write64

Write 64-bit node map entries for an FE zone.

tec_zone_face_nbr_write_connections32

Write 32-bit face-neighbor connections for an FE zone.

tec_zone_face_nbr_write_connections64

Write 64-bit face-neighbor connections for an FE zone.

tec_data_set_add_aux_data

Add a dataset-level auxiliary data record.

tec_var_add_aux_data

Add a variable-level auxiliary data record.

tec_zone_add_aux_data

Add a zone-level auxiliary data record.

Classic API Functions

tecini142

Initialise a Tecplot data file (classic API).

tecend142

Finalise and close the active Tecplot data file.

tecflush142

Flush data to disk, optionally retaining zones in memory (SZL only).

tecfil142

Get the file handle for the current output file.

tecforeign142

Set foreign byte order for output.

teczne142

Create a new zone in the active file (classic API).

tecpolyzne142

Create a polygonal or polyhedral zone (classic API).

tecznefemixed142

Create a FEMIXED zone (classic API).

tecdat142

Write field data to the current zone (classic API).

tecnode142

Write node connectivity for an FE zone (classic API).

tecface142

Write face-neighbor connections (classic API).

tecpolyface142

Write face data for polygonal/polyhedral zones (classic API).

tecpolybconn142

Write boundary connections for poly zones (classic API).

tecauxstr142

Add dataset-level auxiliary data (classic API).

tecvauxstr142

Add variable-level auxiliary data (classic API).

teczauxstr142

Add zone-level auxiliary data (classic API).

tecusr142

Write a user-defined data record (classic API).

See C Function Wrappers for the full module page, and SZL Read Functions, SZL Write Functions, Classic API Functions for each function’s full signature and documentation.


Append Handles#

Returned by tecio.open() when using 'a' or 'a+' mode.

Class

Mode

Description

AppendWrite

'a'

Append zones to an existing SZL file

AppendReadWrite

'a+'

Append zones and read existing zones