tecio.cli.tecmerge

tecio.cli.tecmerge#

Merge zones from multiple Tecplot data files into a single output file.

Post-processing workflows commonly produce results distributed across multiple files. tecmerge collects all zones from an arbitrary number of input files into a single output, reconciling variable lists across sources by taking their union and writing any variable absent from a given source as passive. Input files may be specified explicitly or via a quoted glob pattern and may be any mix of supported formats. When merging time-step sequences, solution times can be assigned automatically from a start time and either a fixed interval or an end time; each zone also gets a strand ID matching its 1-based position within its source file, so the same physical block (e.g. a wing zone present in every timestep) shares one strand across the whole sequence and can be animated as a single, continuous entity in the Tecplot GUI. Merged zones get SourceFile/SourceFileName aux data record of the source file and path. Grid data can also be detected and shared across zones with matching structure instead of duplicated in every merged zone.

Usage:

tecmerge [-h] -o PATH [-f] [--title STRING] [--assign-time-strands]
         [-s VALUE] [-d VALUE | -e VALUE] [--strand ID] [--strand-offset N]
         [--merge-grid [LIST]] FILE [FILE ...]
Positional Arguments:
FILE [FILE ...]

One or more input Tecplot files (.plt, .szplt, or .dat). Glob patterns are expanded by the tool — quote the pattern to prevent premature shell expansion (e.g. "step_*.szplt"). Files are merged in the order given or matched.

Options:
-o PATH, --output PATH

Output file path. Required. The extension controls the output format: .szplt, .plt, or .dat.

-f, --force

Overwrite the output file if it already exists. Without this flag the command exits with an error rather than silently clobbering an existing file.

--title STRING

Dataset title to write to the output file. Defaults to the title of the first input file.

--assign-time-strands

Assign evenly-spaced solution times to all zones, treating each input file as one time step. By default, each zone also gets a strand ID matching its 1-based position within its source file (the same block from every timestep shares a strand, letting the Tecplot GUI animate them together). Use --strand to force a single strand ID for every zone instead. Requires -s/--start and either -d/--delta or -e/--end.

-s VALUE, --start VALUE

Solution time of the first input file. Used with --assign-time-strands.

-d VALUE, --delta VALUE

Constant time increment between successive input files. Mutually exclusive with -e/--end.

-e VALUE, --end VALUE

Solution time of the last input file. The time step is computed as (end - start) / (N - 1) where N is the number of input files. Mutually exclusive with -d/--delta.

--strand INT

Override: force every zone to this single strand ID instead of the default per-zone-position assignment described under --assign-time-strands. Has no effect without --assign-time-strands.

--strand-offset N

Added to every assigned strand ID (the per-zone-position default, or --strand if given). Lets separate tecmerge runs land on non-overlapping strand ranges, e.g. one run’s zones get strands 1, 2, 3 and a second run with --strand-offset 100 gets 101, 102, 103, so opening both outputs together in Tecplot doesn’t auto-group zones from different merges onto the same strand. Has no effect without --assign-time-strands. Defaults to 0.

--merge-grid [LIST]

Detect and share grid data (coordinate variables, and for FE zones, connectivity) across zones with the same grid, instead of writing it fresh in every merged zone. Zones are first grouped by a (zone_type, num_nodes, num_elements) signature, then compared with every earlier zone of the group that wrote its grid. A zone shares from the first one with the same grid and writes its own grid if there is none, so blocks that only share their size are never mixed up. Grid variables stored in the same order are equal when they agree to within 1e-8 of their largest absolute value, which allows for text files rounding their values.

FE zones whose nodes or cells are stored in another order, for example the same mesh in a PLT and an SZPLT file, share the grid of the earlier zone too. Their nodal and cell-centered variables are put in the order of that zone as they are written. This needs coordinates that are exactly equal, and is not done for a zone with face neighbor connections, which refer to its cells. Ordered zones must match in their stored order. Polygon and polyhedron zones are matched on a hash of their full face map and must also have the same grid variables. Poly zones with boundary face connections cannot be shared because boundary connections must be uniquely defined. A zone whose grid variables are missing or passive can neither share nor be shared from. If a zone only contains grid or passive variables, it cannot be merged because there would be no active data in the zone.

Given with no value, grid variables are found automatically by name (x, X, x-coordinate, xgrid, and similar common names for X/Y/Z). Given a comma-separated list of 1-based indices or exact names into the union variable list instead (e.g. --merge-grid x,y,z or --merge-grid 1,2,3), only those variables are treated as the grid; indices and names cannot be mixed in the same list. Solution variables are never affected either way, only variables explicitly identified as the grid are ever shared.

Returns:

A new Tecplot file written to the output path containing all zones from every input file. Variables absent from a source file are written as passive. Exit code is 0 on success and non-zero if any input file cannot be read, the output file already exists and --force is not set, or conflicting time-strand options are supplied.

Examples

Merge two files explicitly:

$ tecmerge part1.szplt part2.szplt -o combined.szplt

Merge a sequence matched by a glob pattern:

$ tecmerg "results_*.szplt" -o combined.szplt

Merge a time series, each zone getting a strand matching its position within its file (a wing zone present in every timestep shares one strand, so it animates as a single entity):

$ tecmerge --assign-time-strands -s 0.0 -d 0.1 \\
           "step_*.szplt" -o transient.szplt

Same, but force every zone onto a single strand instead:

$ tecmerge --assign-time-strands -s 0.0 -d 0.1 --strand 1 \\
           "step_*.szplt" -o transient.szplt

Merge two separate time series so both can be opened together without the Tecplot GUI auto-grouping their zones onto shared strands:

$ tecmerge --assign-time-strands -s 0.0 -d 0.1 \\
           "groupA_*.szplt" -o groupA.szplt
$ tecmerge --assign-time-strands -s 0.0 -d 0.1 --strand-offset 100 \\
           "groupB_*.szplt" -o groupB.szplt

Merge a multiblock time series, sharing each block’s grid across timesteps instead of duplicating it:

$ tecmerge --assign-time-strands -s 0.0 -d 0.1 --merge-grid \\
           "step_*.szplt" -o transient.szplt

Same, but only “x” and “y” are grid variables (a 2-D case with no “z”):

$ tecmerge --merge-grid x,y "step_*.szplt" -o transient.szplt

Call directly from a Python session:

from tecio.cli.tecmerge import main as tecmerge

tecmerge(["part1.szplt", "part2.szplt", "--output", "combined.szplt"])

See also

  • tecio.cli.tecextract - Extract a zone/variable subset from a single file — the inverse of merging.

  • tecio.cli.tecsplit - Split a file into separate grid and solution files.

  • tecio.cli.tecslice - Extract planar slices from volumetric zone data.

Functions

main([argv])

Merge zones from multiple Tecplot files into one.