(quickstart)=
# Quickstart

This page introduces the `tecio` API with four self-contained examples.  For
installation and system requirements see {ref}`Installation <installation>`.

---

(qs-examples)=
## 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.

```python
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:

```python
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 {ref}`Indexing Conventions <qs-index-convention>` 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.

```python
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.

```{figure} _static/fe_nodes.png
:alt: Node numbering for all supported FE zone types
:width: 100%

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
{meth}`~tecio.szl.Write.write_fe_zone`.
```

```{figure} _static/fe_cells.png
:alt: Cell numbering for all supported FE zone types
:width: 100%

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.

```python
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:

```python
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.

```python
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.
:::

---

(qs-index-convention)=
## 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 {doc}`api/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.

---

(qs-getting-help)=
## Getting Help

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

```python
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 {doc}`API Reference </api/index>`,
and runnable demos are provided in the `demos/` directory of the repository.
