Quickstart#

This page introduces the tecio API with four self-contained examples. For installation and system requirements see Installation.


Examples#

1. Structured IJK Zone (1-D Line)#

The simplest possible file: a single ordered zone containing two variables plotted against each other as a line. Dimensions are inferred from the array shape — a 1-D array of length N produces an (N, 1, 1) zone.

import numpy as np
import tecio

x = np.linspace(0.0, 2.0 * np.pi, 256)
y = np.sin(x)

with tecio.open("line.szplt", "w", title="Sine Curve") as w:
    w.write_ordered_zone(
        title="sin(x)",
        variables=["x", "y"],
        data=[x, y],
    )

Reading the file back follows the same pattern:

with tecio.open("line.szplt", "r") as r:
    print(r.title)  # 'Sine Curve'
    print(r.variables)  # ['x', 'y']

    zone = r.zones[0]
    x_read = zone.variables[0].values  # NumPy array, shape (256, 1, 1)
    y_read = zone.variables[1].values

Note

The tecio Python API is 0-indexed. zones and variables start at 0, and zone_index/var_index properties, and every function or method parameter that takes a zone or variable index all use standard Python (zero-based) indexing: r.zones[0] is the first zone, zone.variables[1] is the second variable.

Tecplot 360 zone and variable numbers start at one. tecio converts between the two conventions automatically when a file is opened for reading or writing, so a zone shown as “Zone 1” in Tecplot 360 is r.zones[0] here, and the first variable in a .dat file’s VARIABLES = "x", "y" line is zone.variables[0]. See Indexing Conventions for mre information.


2. Unstructured Finite-Element Zones#

All five simple finite-element cell types supported by Tecplot are shown below in a single file, one zone per element type. The node_map argument is a (num_cells, nodes_per_cell) integer array of zero-based node indices, each one an index into that zone’s coordinate arrays.

import numpy as np
import tecio
from tecio.libtecio import ZoneType

with tecio.open("fe_cells.szplt", "w") as szlfile:
    # -- Write a FE line segment ---------------------------------------------
    x = np.array([0, 0.5, 1])
    y = np.array([0, 1, 0])
    nodes = np.array([[0, 1], [1, 2]])
    c = np.sin(2 * np.pi * x) * np.cos(2 * np.pi * y)

    szlfile.write_fe_zone(
        zone_type=ZoneType.FELINESEG,
        data=[x, y, c],
        node_map=nodes,
        title="FE_LineSeg",
        variables=["x", "y", "z", "c"],
        passive_vars=[False, False, True, False],
    )

    # --  Write a FE triangle ------------------------------------------------
    x = np.array([0, 1, 0, 1]) + 2
    y = np.array([0, 0, 1, 1])
    nodes = np.array([[0, 1, 2], [1, 3, 2]])
    c = np.sin(2 * np.pi * x) * np.cos(2 * np.pi * y)
    szlfile.write_fe_zone(
        zone_type=ZoneType.FETRIANGLE,
        data=[x, y, c],
        node_map=nodes,
        title="FE_Tri",
        variables=["x", "y", "z", "c"],
        passive_vars=[False, False, True, False],
    )

    #  -- Write a FE quadrilateral -------------------------------------------
    x = np.array([0, 0.5, 1, 0, 0.5, 1]) + 4
    y = np.array([0, 0, 0, 1, 1, 1])
    nodes = np.array([[0, 1, 4, 3], [1, 2, 5, 4]])
    c = np.sin(2 * np.pi * x) * np.cos(2 * np.pi * y)
    szlfile.write_fe_zone(
        zone_type=ZoneType.FEQUADRILATERAL,
        data=[x, y, c],
        node_map=nodes,
        title="FE_Quad",
        variables=["x", "y", "z", "c"],
        passive_vars=[False, False, True, False],
    )

    # -- Write a FE tetrahedron ----------------------------------------------
    x = np.array([0, 1, 0.5, 0.5, 0.5]) + 6
    y = np.array([0, 0, 1, 0.5, 0.5])
    z = np.array([0, 0, 0, 1, -1])
    nodes = np.array([[0, 1, 2, 3], [0, 2, 1, 4]])
    c = np.sin(2 * np.pi * x) * np.cos(2 * np.pi * y) * (1.0 + 0.1 * z)
    szlfile.write_fe_zone(
        zone_type=ZoneType.FETETRAHEDRON,
        data=[x, y, z, c],
        node_map=nodes,
        title="FE_Tet",
        variables=["x", "y", "z", "c"],
    )

    # --  Write a FE pyramid as degenerate FEBRICK ---------------------------
    x = np.array([0, 1, 1, 0, 0.5, 0.5]) + 8
    y = np.array([0, 0, 1, 1, 0.5, 0.5])
    z = np.array([0, 0, 0, 0, 1, -1])
    nodes = np.array([[0, 1, 2, 3, 4, 4, 4, 4], [0, 3, 2, 1, 5, 5, 5, 5]])
    c = np.sin(2 * np.pi * x) * np.cos(2 * np.pi * y) * (1.0 + 0.1 * z)
    szlfile.write_fe_zone(
        zone_type=ZoneType.FEBRICK,
        data=[x, y, z, c],
        node_map=nodes,
        title="FE_Pyramid",
        variables=["x", "y", "z", "c"],
    )

    # -- Write a FE prism as degenerate FEBRICK ------------------------------
    x = np.array([0, 1, 0.5, 0, 1, 0.5, 0, 1, 0.5]) + 10
    y = np.array([0, 0, 1, 0, 0, 1, 0, 0, 1])
    z = np.array([0, 0, 0, 1, 1, 1, -1, -1, -1])
    nodes = np.array([[0, 1, 2, 2, 3, 4, 5, 5], [0, 2, 1, 1, 6, 8, 7, 7]])
    c = np.sin(2 * np.pi * x) * np.cos(2 * np.pi * y) * (1.0 + 0.1 * z)
    szlfile.write_fe_zone(
        zone_type=ZoneType.FEBRICK,
        data=[x, y, z, c],
        node_map=nodes,
        title="FE_Prism",
        variables=["x", "y", "z", "c"],
    )

    # -- Write a FEBRICK -----------------------------------------------------
    x = np.array([0, 1, 1, 0, 0, 1, 1, 0, 0, 1, 1, 0]) + 12
    y = np.array([0, 0, 1, 1, 0, 0, 1, 1, 0, 0, 1, 1])
    z = np.array([0, 0, 0, 0, 1, 1, 1, 1, -1, -1, -1, -1])
    nodes = np.array([[0, 1, 2, 3, 4, 5, 6, 7], [0, 3, 2, 1, 8, 11, 10, 9]])
    c = np.sin(2 * np.pi * x) * np.cos(2 * np.pi * y) * (1.0 + 0.1 * z)
    szlfile.write_fe_zone(
        zone_type=ZoneType.FEBRICK,
        data=[x, y, z, c],
        node_map=nodes,
        title="FE_Brick",
        variables=["x", "y", "z", "c"],
    )

Note

After the first write_fe_zone call the variable list is locked in. Subsequent zones must supply the same set of variables (or a subset via passive_vars). The variables keyword only needs to be passed once — on the first write call, or at tecio.open time.

The seven finite-element zone types supported by tecio are shown below, from left to right: FELINESEG, FETRIANGLE, FEQUADRILATERAL, FETETRAHEDRON, pyramid (degenerate FEBRICK), prism (degenerate FEBRICK), and FEBRICK. Each zone contains two cells.

Node numbering for all supported FE zone types

Node numbering (red) for each FE zone type. Node indices are zero-based and are used directly in the node_map connectivity array passed to write_fe_zone().#

Cell numbering for all supported FE zone types

Cell numbering (blue) for each FE zone type. Cell indices correspond to rows in the node_map array.#


3. Time-Dependent 2-D Field#

Transient datasets are written by assigning each zone a strand_id and solution_time. Zones on the same strand animate together in Tecplot 360. Grid coordinates that do not change between time steps can be shared from the first zone to avoid writing duplicate arrays, which substantially reduces file size for large grids.

import numpy as np
import tecio

# 2-D grid
nx, ny = 128, 128
x = np.linspace(0.0, 1.0, nx)
y = np.linspace(0.0, 1.0, ny)
X, Y = np.meshgrid(x, y, indexing="ij")  # shape (nx, ny)

times = np.linspace(0.0, 4.0 * np.pi, 60)

with tecio.open("transient.szplt", "w", title="Travelling Wave") as w:
    # Set dataset auxiliary data before the first zone. Because the variable
      indices are the aux data values read by Tepclot, use 1-based indices.
    w.add_auxdataset_dict({
        "Common.XVar": 1,
        "Common.YVar": 2,
        "Common.CVar": 3,
    })

    for i, t in enumerate(times):
        phi = np.sin(2.0 * np.pi * X - t) * np.cos(2.0 * np.pi * Y)

        if i == 0:
            # First zone: write grid coordinates and solution
            w.write_ordered_zone(
                title=f"t = {t:.3f}",
                variables=["x", "y", "phi"],
                data=[X, Y, phi],
                strand_id=1,
                solution_time=t,
            )
        else:
            # Subsequent zones: share x and y from zone 0, write phi only
            w.write_ordered_zone(
                title=f"t = {t:.3f}",
                data=[phi],
                var_sharing={"x": 0, "y": 0},
                strand_id=1,
                solution_time=t,
            )

Reading a transient file works identically to a steady file — the zones are listed in the order they were written:

with tecio.open("transient.szplt", "r") as r:
    print(r.num_zones)  # 60

    # Solution times across all zones
    times_read = [r.zones[i].solution_time for i in range(r.num_zones)]

    # Grid is only stored in zone 0; later zones return None for shared vars
    phi_t0 = r.zones[0].variables[2].values  # shape (128, 128, 1)
    phi_t1 = r.zones[1].variables[2].values  # shape (128, 128, 1)
    x_shared = r.zones[1].variables[0].values  # None — shared from zone 0

4. Low-Level libtecio API#

The tecio.libtecio module exposes the TecIO C functions directly. Using it gives full control over data types, zone creation options, and the write ordering required by the SZL API. Unlike the rest of tecio, this module is a thin ctypes wrapper with no index translation: zone and variable arguments are passed straight through to TecIO, so they follow TecIO’s own 1-based convention. This example reproduces the 1-D sine curve from Example 1 using the low-level SZL write functions.

import numpy as np
from tecio import libtecio
from tecio.libtecio import DataType, FileType, ValueLocation, ZoneType

x = np.linspace(0.0, 2.0 * np.pi, 256, dtype=np.float32)
y = np.sin(x)

# 1. Open a writer handle (returns an opaque C pointer)
handle = libtecio.tec_file_writer_open(
    filename="line_lowlevel.szplt",
    variables=["x", "y"],
    title="Sine Curve (low-level)",
    file_type=FileType.FULL,
)

# 2. Create a zone and get its 1-based index
izone = libtecio.tec_zone_create_ijk(
    handle,
    zone_title="sin(x)",
    imax=256,
    jmax=1,
    kmax=1,
    var_types=[DataType.FLOAT, DataType.FLOAT],
    value_locations=[ValueLocation.NODAL, ValueLocation.NODAL],
)

# 3. Write each variable by 1-based index (zone=1, var=1 / var=2)
libtecio.tec_zone_var_write_float_values(handle, izone, 1, x)
libtecio.tec_zone_var_write_float_values(handle, izone, 2, y.astype(np.float32))

# 4. Close and flush
libtecio.tec_file_writer_close(handle)

Note

SZL vs. classic API. The SZL functions (tec_file_writer_open, tec_zone_create_ijk, tec_zone_var_write_*) return an explicit file handle and allow variables to be written in any order after zone creation. Multiple files can be open simultaneously.

The classic PLT functions (tecini142, teczne142, tecdat142, tecend142) maintain a single implicit global context: only one file is active at a time and data must be written in strict zone → variable order. Use the SZL API for new code unless PLT format is specifically required.


Indexing Conventions#

Context

Indexing

Example

Python reader/writer objects (zone, variable)

0-based

r.zones[0], zone.variables[2]

zone_index / var_index properties

0-based

r.zones[0].zone_index == 0

get_var_auxdata/get_zone_auxdata arguments

0-based

r.get_var_auxdata(0)

var_sharing mapping values (source zone)

0-based zone number

var_sharing={"x": 0} → share from zone 0

con_sharing argument

0-based zone number, or None

con_sharing=0 → share from zone 0

node_map connectivity arrays

0-based node indices

np.array([[0, 1, 2]])

face_neighbors cell/zone/face references

0-based, including the face ordinal

see Writers

CLI -z/-v arguments (tecextract, tecslice, etc.)

0-based

tecextract -z 0,2 -v 0,1

tecio.libtecio function arguments (zone, var, node, face)

1-based, matches TecIO

tec_zone_var_write_float_values(h, 1, 3, arr)

Tecplot 360 GUI, macro language, and .dat/.tec ASCII text

1-based, Tecplot’s own convention

VARIABLES = "x", "y" → variable 1 is x

tec2mat output (.mat struct fields)

1-based, so it reads naturally in MATLAB

node_map, face_connections, var_shared_from

Everywhere in the Python API, tecio works in zero-based indices, the same convention as NumPy arrays and Python lists. Two boundaries convert to Tecplot’s native one-based convention instead, since that’s what the reader on the other side expects: the raw tecio.libtecio C wrappers and the tec2mat CLI’s .mat output.


Getting Help#

All public classes and functions have docstrings accessible via Python’s built-in help() function:

import tecio

help(tecio.open)  # top-level open function
help(tecio.szl.Write)  # SZL writer class and all its methods
help(tecio.libtecio.ZoneType)  # enum values and descriptions

Full API documentation is available in the API Reference, and runnable demos are provided in the demos/ directory of the repository.