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 |
|---|---|
|
Read an existing file |
|
Write a new file |
|
Write, failing if the file already exists |
|
Append new zones to an existing file |
|
Append and read in the same session |
Extension |
Format |
|---|---|
|
Tecplot SZL binary (subzone-loadable) |
|
Tecplot PLT binary |
|
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 |
|---|---|
One open file: title, variables, zones, dataset-level aux data |
|
Shared zone interface: title, type, solution time, strand ID, variables, aux data |
|
Adds |
|
Adds |
|
Adds |
|
Adds the face map ( |
|
One variable’s metadata and data within a zone |
|
Read-only, dict-like view of one auxiliary-data mapping |
Writing
Class |
Description |
|---|---|
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.
Reader for Tecplot |
|
Reader for Tecplot |
|
Reader for Tecplot ASCII DAT files. |
|
Write Tecplot SZL ( |
|
Write Tecplot PLT ( |
|
Write Tecplot ASCII ( |
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 |
|---|---|---|
|
Sequence of zones; integer index, slice, or iterate |
|
|
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).
Binary data format selector. |
|
Tecplot file type. |
|
Tecplot zone type. |
|
On-disk storage type for variable data. |
|
Data value location within a cell. |
|
Boundary face-sharing mode between zones. |
|
Unstructured cell shape category. |
|
Zone data packing order for ASCII ( |
|
Variable active/passive flag. |
|
Boolean flag for C function arguments. |
|
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.
Exception for TecIO C library errors. |
|
Raised when calling a function whose C symbol is unavailable. |
|
Emitted once at import time if any C function could not be bound. |
SZL Read Functions
Open an SZL file for reading. |
|
Close an SZL file reader handle and release its resources. |
|
Get the file type for an opened SZL file. |
|
Read the dataset title string. |
|
Query the number of variables in the dataset. |
|
Query the number of zones in the dataset. |
|
Get zone dimensions (ORDERED) or node/element counts (FE). |
|
Read the title for a zone. |
|
Query the zone type. |
|
Check whether a zone is enabled. |
|
Read the solution time for a zone. |
|
Get the strand ID for a zone. |
|
Check whether a zone's node-map uses 64-bit indices. |
|
Read a 64-bit node map for an FE zone. |
|
Read a 32-bit node map for an FE zone. |
|
Read a whole FE zone node map as one flat array. |
|
Get a variable name by index. |
|
Check whether a variable is enabled. |
|
Get the data type for a variable in a zone. |
|
Get the value location for a zone variable. |
|
Check whether a zone variable is passive. |
|
Get the shared zone index for a variable. |
|
Query the number of values for a zone variable. |
|
Read float32 values for a zone variable. |
|
Read float64 values for a zone variable. |
|
Read int32 values for a zone variable. |
|
Read int16 values for a zone variable. |
|
Read uint8 values for a zone variable. |
|
Get the number of dataset-level auxiliary data items. |
|
Read a dataset-level auxiliary data item. |
|
Get the number of auxiliary data items for a variable. |
|
Read a variable-level auxiliary data item. |
|
Get the number of auxiliary data items for a zone. |
|
Read a zone-level auxiliary data item. |
SZL Write Functions
Open a writer handle for creating SZL files. |
|
Close a writer handle and finalise the output file. |
|
Flush written zone data to a temporary intermediate file. |
|
Create an ordered IJK zone for writing. |
|
Create a finite-element zone for writing. |
|
Set time/strand metadata for a zone. |
|
Write float64 values for a zone variable. |
|
Write float32 values for a zone variable. |
|
Write int32 values for a zone variable. |
|
Write int16 values for a zone variable. |
|
Write uint8 values for a zone variable. |
|
Write 32-bit node map entries for an FE zone. |
|
Write 64-bit node map entries for an FE zone. |
|
Write 32-bit face-neighbor connections for an FE zone. |
|
Write 64-bit face-neighbor connections for an FE zone. |
|
Add a dataset-level auxiliary data record. |
|
Add a variable-level auxiliary data record. |
|
Add a zone-level auxiliary data record. |
Classic API Functions
Initialise a Tecplot data file (classic API). |
|
Finalise and close the active Tecplot data file. |
|
Flush data to disk, optionally retaining zones in memory (SZL only). |
|
Get the file handle for the current output file. |
|
Set foreign byte order for output. |
|
Create a new zone in the active file (classic API). |
|
Create a polygonal or polyhedral zone (classic API). |
|
Create a FEMIXED zone (classic API). |
|
Write field data to the current zone (classic API). |
|
Write node connectivity for an FE zone (classic API). |
|
Write face-neighbor connections (classic API). |
|
Write face data for polygonal/polyhedral zones (classic API). |
|
Write boundary connections for poly zones (classic API). |
|
Add dataset-level auxiliary data (classic API). |
|
Add variable-level auxiliary data (classic API). |
|
Add zone-level auxiliary data (classic API). |
|
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 |
|---|---|---|
|
Append zones to an existing SZL file |
|
|
Append zones and read existing zones |