tecio.cli.tecaux

tecio.cli.tecaux#

Add, remove, or export dataset, zone, or variable level auxiliary data.

The Tecplot auxiliary data mechanism attaches arbitrary name=value metadata to a dataset, a zone, or a variable (solver name, run date, units, a description, or any other annotation that doesn’t belong in the numerical data itself). Managing this after the fact ordinarily means writing a one-off script against the TecIO API. tecaux does this from the command line, in a single read/write pass, in three mutually exclusive modes:

  • By default (no --strip/--export-json): merges new auxiliary entries (from -d/-z/-v and/or -j) into a copy of the input file. Every zone, variable, and existing sharing relationship is preserved exactly; an existing key with the same name is overwritten.

  • --strip removes every auxiliary entry at all three levels and writes the result to a new file, still preserving sharing.

  • --export-json writes every existing auxiliary entry to a JSON file, in the same format -j reads back – without touching the source file at all, unless combined with --strip.

Usage:

tecaux [-h] [-d KEY=VALUE] ... [-z INDEX KEY=VALUE] ...
       [-v INDEX_OR_NAME KEY=VALUE] ... [-j PATH] [-s] [--export-json]
       [-o PATH] [-f] PATH
Positional Arguments:
PATH

Path to the input Tecplot file (.plt, .szplt, or .dat).

Options:
-d KEY=VALUE, --data KEY=VALUE

A name=value pair to set as dataset-level auxiliary data. Repeat the flag for multiple pairs.

-z INDEX KEY=VALUE, --zone INDEX KEY=VALUE

A name=value pair to set as zone-level auxiliary data on the 0-based zone INDEX, or on every zone if INDEX is the literal word all. Repeat the flag for multiple pairs and/or multiple zones; each occurrence takes exactly one zone and one pair, so -z 0 A=1 -z 0 B=2 sets both A and B on zone 0.

-v INDEX_OR_NAME KEY=VALUE, --variable INDEX_OR_NAME KEY=VALUE

A name=value pair to set as variable-level auxiliary data on the variable given by a 0-based index or a name (case-insensitive), r on every variable if the target is the literal word all. Repeatable, same as -z.

-j PATH, --json PATH

Load bulk auxiliary data from a JSON file (see format below). Applied before any -d/-z/-v flags, which take precedence on a key collision.

-s, --strip

Remove all auxiliary data (dataset, zone, and variable levels) and write the result to <stem>_no_aux<ext> (or -o’s path). Mutually exclusive with -d/-z/-v/-j. Combine with --export-json to keep a JSON copy of what was removed.

--export-json

Write every existing auxiliary entry to <stem>_aux.json, in the same AUXDATASET/AUXZONE/AUXVAR format -j reads, without modifying the source file, unless combined with --strip. Mutually exclusive with -d/-z/-v/-j.

-o PATH, --output PATH

Output file path. The extension controls the output format: .szplt, .plt, or .dat. Defaults to <stem>_aux<ext>, or <stem>_no_aux<ext> with --strip. Not used by --export-json alone which always writes <stem>_aux.json, regardless of -o.

-f, --force

Overwrite the output file(s) if they already exist. Without this flag the command exits with an error rather than silently clobbering an existing file.

JSON Format:
{
  "AUXDATASET": {"Solver": "MyCFD", "Version": "2.1"},
  "AUXZONE": {
    "0": {"Description": "Wing"},
    "all": {"Batch": "2024"}
  },
  "AUXVAR": {
    "Pressure": {"Units": "Pa"},
    "0": {"Source": "Experiment"}
  }
}

All three top-level keys are optional, and match this library’s own attribute/method names for the same three levels exactly (Write.auxdataset/add_auxdataset_dict, Write.auxvar/add_auxvar_dict; AUXZONE is the natural third member of that family even though zone-level aux has no “zone”-prefixed name internally.

In "AUXZONE"/"AUXVAR", a key is either a 0-based index, a variable name ("AUXVAR" only), or the literal string "all" meaning every zone/variable (the same three forms -z/-v accept on the command line). Every JSON key must be a quoted string, including numeric indices ("0", not 0).

--export-json writes this exact format back out, keyed by exact 0-based index (never "all", even if every zone happens to share identical aux content) and omitting any zone/variable/level with nothing to report.

Returns:

In the default mode, a new Tecplot file written to the output path with the requested auxiliary data merged in. With --strip, a new Tecplot file with all auxiliary data removed. With --export-json, a JSON file of everything that was found (and the source file is untouched, unless --strip is also given). Exit code is 0 on success and non-zero if the input file cannot be read, a -z/-v/JSON target cannot be resolved, --strip/--export-json is combined with -d/-z/-v/-j, or an output file already exists and --force is not set.

Examples

Tag a dataset with solver metadata (repeat the flag for multiple pairs):

$ tecaux -d Solver=MyCFD -d Version=2.1 flow.szplt

Two pairs on zone 0, one pair on zone 1:

$ tecaux -z 0 Description=Wing -z 0 Area=120sqm -z 1 Description=Fuselage \
      flow.szplt

Annotate a single variable by name:

$ tecaux -v Pressure Units=Pa flow.szplt

Every zone at once, via the “all” target:

$ tecaux -z all RunDate=2024-01-15 flow.plt

Everything in one pass, written as a bash script would naturally lay it out:

$ tecaux --data Solver=MyCFD \
      --data Version=2.1 \
      --zone 0 Case=A \
      --zone 0 Description=Wing \
      --zone 1 Case=B \
      --variable Pressure Units=Pa \
      -o tagged.szplt flow.szplt

Bulk metadata from a file, with one CLI override on top:

$ tecaux -j metadata.json -d Version=2.2 flow.szplt

Back up everything currently on a file before editing it by hand, without touching the file itself:

$ tecaux --export-json flow.szplt        # writes flow_aux.json

Sanitize a file for external sharing, discarding whatever aux data it had:

$ tecaux --strip flow.szplt               # writes flow_no_aux.szplt

Sanitize a file but keep a record of what was removed, in case it’s needed later (e.g. to reapply with -j after review):

$ tecaux --strip --export-json flow.szplt
# writes flow_no_aux.szplt and flow_aux.json

Call directly from a Python session:

from tecio.cli.tecaux import main as tecaux

tecaux(["-d", "Solver=MyCFD", "flow.szplt"])

See also

  • tecio.cli.tecfix - Rewrite a file with invalid variable arrays set to passive, using the same verbatim zone-copy approach.

  • tecio.cli.teconvert - Convert between formats without modifying auxiliary data.

Functions

main([argv])

Add, remove, or export auxiliary data to a Tecplot file.