Copyright © 1988-2024 Tecplot, Inc. All rights reserved worldwide. See the complete legal notice in the copyright section of this document.

Table of Contents

Introduction

Tecplot 360 can read data produced in many different formats using the data loaders provided with the product. This manual describes a complementary approach: writing your data in the Tecplot 360 data format so it can be read natively, providing the best experience for Tecplot 360 users. This Data Format Guide includes the following topics:

  • Data Structure Learn about the different types of data structure available in Tecplot 360 and how to use them.

  • Binary Data Refer to this chapter for details on outputting data in Tecplot 360’s binary file format (.plt) or the newer subzone load format (.szplt) using the "classic" APIs in the TecIO library, a collection of routines we provide that you can use to write files in these format from your software.

  • ASCII Data We strongly recommend that you create binary data files. However, we provide the ASCII data format, as it is very convenient for producing small, simple files.

  • Reading SZL Data Files and Writing SZL Data Files (New API) describe using newer TecIO APIs to read and write files in Tecplot’s SZL (.szplt) binary format.

  • Binary Data File Format, documents the .plt binary file format.

  • Glossary Refer to the Glossary for the definitions of terms used throughout the manual.

Before continuing to either the Binary or ASCII chapter, please review this overview of Best Practices.

Subzone Loading

Tecplot 360 introduced a new subzone file format with extension .szplt that is optimized for loading partial zones ("subzones") as individual chunks of data are needed for a plot or for other operations. Subzone loading improves performance substantially for many common operations on large cases while also reducing RAM usage. If your software generates large data files, we strongly encourage you to support this format, as it will significantly improve your user experience. You can use the same API as is used to write .plt files, so if your program already uses TecIO, it is straightforward to upgrade it to write .szplt files instead of, or in addition to, .plt files. For new development, we suggest using the newer API described in Writing SZL Data Files (New API).

Creating Data Files for Tecplot 360 and Focus

For the purposes of this discussion, "polyhedral" refers to either polyhedral or polygonal zones.

If you intend to create data files that will load in both Tecplot 360 and Tecplot Focus, be aware that polyhedral and polygonal zones are not supported by Tecplot Focus. If any of the zones in a given data file are polyhedral, you will not be able to load the data file into Tecplot Focus. To create data files that will load in both products, you must use either ordered zones or "classic" (cell-based) finite element zones (triangular, quadrilateral, tetrahedral or brick elements).

The TecIO library file included with each release of Tecplot Focus is identical to the library file included with the corresponding release of Tecplot 360 and can create polyhedral zones, even though you will not be able to load the data files into Tecplot Focus. Similarly, this guide is largely the same for both products; we have included reminders throughout about this Tecplot Focus limitation.

The subzone load file format (.szplt) is not supported by Tecplot Focus, nor by legacy versions of Tecplot 360 (versions without "EX" in their designation). Current versions of Tecplot Focus (2016 R1 and later), derived from Tecplot 360, also limit the number of data elements in a single data set to 5 million.

Best Practices

Users who wish to generate native Tecplot 360 data files automatically from applications such as complex flow solvers have a number of options for outputting data into Tecplot’s data format. This section outlines a few "best practices" for outputting your data into Tecplot 360 data format.

Create Binary Data Files (.plt or .szplt) instead of ASCII (.dat)

Binary data files are more efficient than ASCII files, in terms of disk space and time to first image. To create binary data files, you may use functions provided in the TecIO library. To create ASCII files, you can write out plain text in the usual manner.

There are some cases where ASCII files are preferred. Create ASCII files when:

  • Your data files are small.

  • Your application runs on a platform for which the TecIO library is not provided. If this is the case, please contact us at support@tecplot.com. There may be a way to resolve this issue.

  • You wish users to be able to view or edit the data in a text editor.

Offer the Option to Write Subzone Load Files (.szplt)

  • Users of Tecplot 360 will appreciate the improved experience provided by these files, especially for large, 3-dimensional, non-Polyhedral cases.

  • Use TECFLUSH142 to reduce memory usage when writing SZL files. TECFLUSH142 must be called after writing a complete zone.

  • Use SZL to allow Read capability.

Use Block Format instead of Point Format

Block format is by far the most efficient format when it comes to loading the file into Tecplot 360. If your data files are small and you can only obtain the data in a point-like format (for example, with a spreadsheet), then using point format is acceptable.

Binary files can only be written in block format. Point format is allowed for ASCII files, but running the preplot utility will convert the data to block format.

Add Auxiliary data to Preset Variable Assignments in Tecplot 360

Zone Auxiliary data can be used to give Tecplot 360 hints about properties of your data. For example, it can be used to set the defaults for which variables to use for certain kinds of plots. Auxiliary data is supported by both binary and ASCII formats. Refer to TECAUXSTR142 or Data Set Auxiliary Data Record for information on working with auxiliary data in binary or ASCII data files, respectively.

Transient Data

  • Data Sharing

  • Share variables whenever possible.

Variable sharing is commonly used for the spatial variables (X, Y, and Z) when you have many sets of data that use the same basic grid. This saves disk space, as well as memory when the data is loaded into Tecplot 360. In addition, the benefits are compounded with scratch data derived from these variables because it is also shared within Tecplot 360. See also TECZNE142 and TECPOLYZNE142 (for binary data) or Variable and Connectivity List Sharing (for ASCII data).

  • Do not share variables between 3D and 2D zones

  • Consider using Grid and Solution files for transient data.

  • Use one object or mesh per StrandID which consists of multiple solution times. See TECZNE142 or TECPOLYZNE142 for more information.

Parallel Output

  • Use TecIO-MPI which writes SZL files in parallel.

  • Be sure to write to a parallel file system.

  • Maximize striping for efficiency.

Passive Variables

Tecplot 360 can manage many data sets at the same time. However, within a given data set you must supply the same number of variables for each zone. In some cases you may have data where there are many variables and, for some of the zones some of those variables are not important or not calculated. You can set selected variables in those zones to be passive. A passive variable is one that will always return the value zero if queried (e.g. in a probe) but will not involve itself in operations such as the calculations of the min and max range. This is very useful when calculating default contour levels.

Use the Native Byte Ordering for the Target Machine

When you create binary data, you can elect to produce these files in either Motorola (big-endian) byte order or Intel (little-endian) byte order. Today’s most popular platforms all use Intel byte order, and generally this is the order you should use when writing binary data. The exceptions involve older platforms no longer supported by Tecplot. If you are using such legacy platforms, it can improve performance to write the binary data in the order native to the platform on which it will be viewed, if this is known, even though Tecplot 360 will load data with either byte order. For See the notes about this option in the User’s Manual for the Preplot flag.

  • SZL doesn’t support big-endian byte ordering and only supports Native Byte Ordering at this time. TECFOREIGN142 has not yet been implemented in the SZL API.

Auxiliary Data Influencing Tecplot 360’s Behavior

Behavior in Tecplot is influenced by the presence of particular auxiliary data assignments:

  • If axis variables X, Y or Z are not assigned, the dataset auxiliary data is searched for "Common.XVar", "Common.YVar", and "Common.ZVar". If found, and one or more of the auxiliary data items contains a valid dataset variable number, it is assigned to the corresponding axis variable.

  • If vector variables, U, V or W are not assigned, the dataset auxiliary data is searched for "Common.UVar", "Common.VVar", and "Common.WVar". If found, and one or more of the auxiliary data items contains a valid dataset variable number, it is assigned to the corresponding vector variable.

  • If the contour variable, C, is not assigned, the dataset auxiliary data is searched for "Common.CVar". If found, and the auxiliary data item contains a valid dataset variable number, it is assigned to the contour variable.

  • Fieldmaps comprised of one or more zones having an auxiliary data item named, "Common.IsBoundaryZone", with a value of "Yes", "Y", "True", "T", or "ON", are deactivated by default, unless the zone’s auxiliary data also contains an item named, "Common.BoundaryCondition", with a value of "Wall".

  • If a transient dataset auxiliary data item of the name "Common.TransientZoneVisibility" is present, it must be located in a dataset and its value is either "ZonesAtOrBeforeSolutionTime" or "ZonesAtSolutionTime". "Common.TransientZoneVisibilitty" determines what is shown when no zones with a given Strand ID exist at the current solution time, within a small time tolerance.

    • ZonesAtOrBeforeSolutionTime: For each strand at a given solution time, the zones shown are those that are at the solution time, within a tolerance. Except for the very last time step, if no zones exist at the given solution time, zones shown are those from the first prior solution time showing zones.

    • ZonesAtSolutionTime: For each strand at a given solution time, the zones shown are those that are at the solution time, within a tolerance.

CFDA Auxiliary Data

A number of aux data values will set values in dialogs available under the Analyze menu.

  • A dataset aux data variable "Common.Incompressible" set to "Yes", "Y", "True", "T", or "ON" will set the Incompressible toggle in the Fluid Properties dialog.

  • For incompressible flow, the density of the flow is taken from the value of data set aux data variable "Common.Density"

  • Several aux data variables may be used to set other values in the Analyze>Fluid Properties dialog. For each of these, a constant value and a data set variable number may be specified. If only a constant value is specified, then that value is used for calculations at all nodes or cells in the data set. If a data set variable number is specified, then the value of that variable is used at each node or cell, and the constant value is used only for reference (free-stream) value calculations.

Name Type Description

Common.SpecificHeat

double

For incompressible flow only, the specific heat of the fluid.

Common.SpecificHeatVar

int

For incompressible flow only, the data set variable that holds the value of specific heat.

Common.GasConstant

double

For compressible flow only, the gas constant of the fluid.

Common.GasConstantVar

int

For compressible flow only, the data set variable that holds the value of the gas constant.

Common.Gamma

double

For compressible flow only, the ratio of specific heats.

Common.GammaVar

int

For compressible flow only, the data set variable that holds the value of the ratio of specific heats.

Common.Viscosity

double

The value of the dynamic viscosity of the fluid.

Common.ViscosityVar

int

The data set variable that holds the value of the fluid dynamic viscosity

Common.Conductivity

double

The value of the fluid thermal conductivity.

Common.ConductivityVar

int

The data set variable that holds the value of the fluid thermal conductivity.

  • Any zones marked with a "Common.IsBoundaryZone" value of "Yes", "Y", "True", "T", or "ON" are also listed as boundaries in the Geometry and Boundaries dialog. The type of each boundary zone is taken from the zone’s value of "Common.BoundaryCondition". Recognized boundary types are "Interzone", "Inflow", "Outflow", "Wall", "Slip Wall", "Symmetry", and "Extrapolated".

  • In addition to the zone aux data mentioned above for boundary assignments, some dataset aux data affects settings in the Analyze>Geometry and Boundaries dialog:

Name Type Available Values Description

Common.Axisymmetric

boolean

"Yes", "Y", "True", "T", or "ON"

Indicates that the solution geometry is axisymmetric.

Common.AxisOfSymmetryVarAssignment

option

"X" or "Y"

For axisymmetric flow, the axis variable used to define the symmetry.

Common.AxisValue

double

any

For axisymmetric flow, the value of the axis variable about which the flow is symmetric.

  • The following data set aux data variables affect settings in the Analyze>Field Variables dialog. Note that only two of Common.PressureVar, Common.TemperatureVar, Common.DensityVar, Common.StagnationEnergyVar and Common.MachNumberVar should be set. Also, Common.DensityVar and Common.MachNumberVar should not be used for incompressible flow:

Name Type Description

Common.VectorVarsAreVelocity

boolean

Set to "Y" to Indicate that the vector vars indicated by Common.UVar, Common.VVar and Common.WVar are velocity. Otherwise, they will be assumed to be or momentum.

Common.PressureVar

double

The data set variable that holds values of pressure.

Common.TemperatureVar

double

The data set variable that holds values of temperature.

Common.DensityVar

double

For compressible flow only, the data set variable that holds values of density.

Common.StagnationEnergyVar

double

The data set variable that holds values of stagnation energy.

Common.MachNumberVar

double

For compressible flow

  • Reference (free-stream) conditions may be set by the following dataset aux data variables, and will be reflected in the Analyze/Reference Values dialog. Note that Common.ReferenceMachNumber, Common.ReferenceDensity and Common.ReferenceSpeedOfSound should not be used for incompressible flow:

Name Type Description

Common.ReferenceU

double

The reference X component of velocity.

Common.ReferenceV

double

The reference Y component of velocity.

Common.ReferenceMachNumber

double

For compressible flow only, the reference Mach number.

Common.AngleOfAttack

double

The reference angle of attack.

Common.ReferencePressure

double

The reference pressure.

Common.ReferenceDensity

double

For compressible flow only, the reference density.

Common.ReferenceTemperature

double

The reference temperature.

Common.ReferenceSpeedOfSound

double

For compressible flow only, the reference speed of sound.

  • The following dataset aux data values may be set to identify dataset variables for turbulent flow calculations. These settings will be reflected in the Analyze>Calculate Turbulence Functions dialog. You should specify only two of these:

Name Type Description

Common.TurbulentKineticEnergyVar

int

The dataset variable that holds turbulent kinetic energy, commonly referred to as "k".

Common.TurbulentDissipationRateVar

int

The dataset variable that holds turbulent dissipation rate, commonly referred to as "ε".

Common.TurbulentFrequencyVar

int

The dataset variable that holds turbulent frequency, commonly referred to as "ω".

Common.TurbulentViscosityVar

int

The dataset variable that holds turbulent kinematic viscosity.

Common.TurbulentDynamicViscosityVar

int

The dataset variable that holds turbulent dynamic viscosity.

Data Structure

Tecplot 360 accommodates two different types of data: Ordered Data and Finite Element Data. Ordered data is a set of points logically stored in a one-, two-, or three-dimensional array, where I, J, and K are the index values within the array. The number of data points is the product of all of the dimensions within the array. Finite-element data is arranged in two arrays, a variable array and a connectivity matrix. The variable array is a collection of points in 2D or 3D space that are connected into polygonal or polyhedral units called elements. The connections between the nodes are defined by the connectivity matrix.

A connectivity list is used to define which nodes are included in each element of an ordered or cell-based finite element zone. You should know your zone type and the number of elements in each zone in order to create your connectivity list.

The number of nodes required for each element is implied by your zone type. For example, if you have a finite element quadrilateral zone, you will have four nodes defined for each element. Likewise, you must provide eight numbers for each cell in a BRICK zone, and three numbers for each element in a TRIANGLE zone. If you have a cell that has a smaller number of nodes than that required by your zone type, simply repeat a node number. For example, if you are working with a finite element quadrilateral zone and you would like to create a triangular element, simply repeat a node in the list (e.g., 1,4,5,5).

In the example below, the zone contains two quadrilateral elements. Therefore, the connectivity list must have eight values. The first four values define the nodes that form Element 1. The second four values define the nodes that form Element 2.

elements.jpg

The connectivity list for this example would appear as follows:

ConnList[8] = {4,5,2,1,       /* nodes for Element 1 */
               5,6,3,2};      /* nodes for Element 2 */
It is important to provide your node list in either a clockwise or counter-clockwise order. Otherwise, your cell will twist, and the element produced will be misshapen.

Ordered Data

Ordered data is defined by one, two, or three-dimensional logical arrays, dimensioned by IMAX, JMAX, and KMAX. These arrays define the interconnections between nodes and cells. The variables can be either nodal or cell-centered. Nodal variables are stored at the nodes; cell-centered values are stored within the cells.

One-dimensional Ordered Data (I-ordered, J-ordered, or K-ordered)

onedvaluelocate.jpg

A single dimensional array where either IMAX, JMAX or KMAX is greater than or equal to one, and the others are equal to one. For nodal data, the number of stored values is equal to IMAX * JMAX * KMAX. For cell-centered I-ordered data (where IMAX is greater than one, and JMAX and KMAX are equal to one), the number of stored values is (IMAX-1) - similarly for J-ordered and K-ordered data.

Two-dimensional Ordered Data (IJ-ordered, JK-ordered, IK-ordered)

twodvaluelocate.jpg

A two-dimensional array where two of the three dimensions (IMAX, JMAX, KMAX) are greater than one, and the other dimension is equal to one. For nodal data, the number of stored values is equal to IMAX * JMAX * KMAX. For cell-centered IJ-ordered data (where IMAX and JMAX are greater than one, and KMAX is equal to one), the number of stored values is (IMAX-1)(JMAX-1) - similarly for JK-ordered and IK-ordered data.

Three-dimensional Ordered Data (IJK-ordered)

threedvaluelocate.jpg

A three-dimensional array where all IMAX, JMAX and KMAX are each greater than one. For nodal ordered data, the number of nodes is the product of the I-, J-, and K-dimensions. For nodal data, the number of stored values is equal to IMAX * JMAX * KMAX. For cell-centered data, the number of stored values is (IMAX-1)(JMAX-1)(KMAX-1).

Finite Element Data

While finite element data is usually associated with numerical analysis for modeling complex problems in 3D structures (heat transfer, fluid dynamics, and electromagnetics), it also provides an effective approach for organizing data points in or around complex geometrical shapes. For example, you may not have the same number of data points on different lines, there may be holes in the middle of the dataset, or the data points may be irregularly (randomly) positioned. For such difficult cases, you may be able to organize your data as a patchwork of elements. Each element can be independent of the other elements, so you can group your elements to fit complex boundaries and leave voids within sets of elements. The figure below shows how finite element data can be used to model a complex boundary.

festruct
Figure 1. This figure shows finite element data used to model a complex boundary.

Finite element data defines a set of points (nodes) and the connected elements of these points. The variables may be defined either at the nodes or at the cell (element) center. Finite element data can be divided into three types:

Line data

This is a set of line segments defining a 2D or 3D line. Unlike I-ordered data, a single finite element line zone may consist of multiple disconnected sections. The values of the variables at each data point (node) are entered in the data file similarly to I-ordered data, where the nodes are numbered with the I-index. This data is followed by another set of data defining connections between nodes. This second section is often referred to as the connectivity list. All elements are lines consisting of two nodes, specified in the connectivity list.

Surface data

This is a set of triangular, quadrilateral, or polygonal elements defining a 2D field or a 3D surface. When using polygonal elements, the number of sides may vary from element to element. In finite element surface data, you can choose (by zone) to arrange your data in three point (triangle), four point (quadrilateral), or variable-point (polygonal) elements. The number of points per node and their arrangement are determined by the element type of the zone. If a mixture of quadrilaterals and triangles is necessary, you may repeat a node in the quadrilateral element type to create a triangle, or you may use polygonal elements.

Remember that Tecplot Focus cannot load face-based (polygonal or polyhedral) data.
Volume data

This is a set of tetrahedral, brick, or polyhedral elements defining a 3D volume field. When using polyhedral elements, the number of sides may vary from element to element. Finite element volume cells may contain four points (tetrahedron), eight points (brick), or variable points (polyhedral).

For cell-based element types (triangular, quadrilateral, tetrahedral, or brick), you can simulate zones with mixed element types by repeating nodes as necessary. For example, a triangle element can be included in a quadrilateral zone by repeating one node in the element’s connectivity list, and tetrahedral, pyramidal, and prismatic elements can be included in a brick zone by repeating nodes appropriately.

Finite Element Data provides detailed information about how to format your FE data in Tecplot’s data file format.

Line Data

Unlike I-ordered data, a single finite element line zone may consist of multiple disconnected sections. The values of the variables at each data point (node) are entered in the data file similarly to I-ordered data, where the nodes are numbered with the I-index. This data is followed by another set of data defining connections between nodes. This second section is often referred to as the connectivity list. All elements are lines consisting of two nodes, specified in the connectivity list.

Surface Data

In finite element surface data, you can choose (by zone) to arrange your data in three point (triangle), four point (quadrilateral), or variable-point (polygonal) elements. The number of points per node and their arrangement are determined by the element type of the zone. If a mixture of quadrilaterals and triangles is necessary, you may repeat a node in the quadrilateral element type to create a triangle or you may use polygonal elements.

Remember that Tecplot Focus cannot load face-based (polygonal or polyhedral) data.

Volume Data

Finite element volume cells may contain four points (tetrahedron), eight points (brick) or a variable number of points (polyhedral). The figures below shows the arrangement of the nodes for tetrahedral and brick elements. The connectivity arrangement for polyhedral data is governed by the method in which the polyhedral facemap data is supplied.

tetrahedral connectivity00040
Figure 2. Tetrahedral connectivity arrangement
ijk ordered block00119
Figure 3. Brick connectivity arrangement

In the brick format, points may be repeated to achieve 4, 5, 6, or 7 point elements. For example, a connectivity list of "n1 n1 n1 n1 n5 n6 n7 n8" (where n1 is repeated four times) results in a quadrilateral-based pyramid element.

Remember that Tecplot Focus cannot load face-based (polygonal or polyhedral) data.

Finite Element Data Limitations

Working with finite element data has some limitations:

  • XY-plots of finite element data treat the data as I-ordered; that is, the connectivity list is ignored. Only nodes are plotted, not elements, and the nodes are plotted in the order in which they appear in the data file.

  • Index skipping in vector and scatter plots treats finite element data as I-ordered; the connectivity list is ignored. Nodes are skipped according to their order in the data file.

Variable Location

Data values can be stored at the nodes or at the cell centers.

  • For finite element meshes, cell-centers are the centers (centroids) of elements.

  • For many types of plots, cell-centered values are interpolated to the nodes internally.

Face Neighbors

For polygonal and polyhedral data, face neighbors are the fundamental means of defining the topology.

A cell is considered a neighbor if one of its faces shares all nodes in common with the selected cell, or if it is identified as a neighbor by face neighbor data in the dataset. The face numbers for cells in the various zone types are defined below.

ijk_ordered_block00046.jpg
Figure 4. Example of node and face neighbors for an FE-brick cell or IJK-ordered cell.
ij_ordered_block.jpg
Figure 5. Example of node and face numbering for an IJ-ordered/ FE-quadrilateral cell.
face_neighbors_tet.jpg
Figure 6. Example of tetrahedron face neighbors.

The implicit connections between elements in a zone may be overridden, or connections between cells in adjacent zones established by specifying face neighbor criteria in the data file. Refer to TECFACE142 for additional information.

Working with Unorganized Data Sets

Tecplot 360 loads unorganized data as a single I-ordered zone and displays them in XY Mode, by default. Tecplot products consider an I-ordered zone irregular if it has more than one dependent variable. An I-ordered data set with one dependent variable (i.e. an XY or polar line) is NOT an irregular zone.

To check for irregular data, you can go to the Data Set Info dialog (accessed via the Data menu). The values assigned to: IMax, JMax, and KMax are displayed in the lower left quadrant of that dialog. If IMax is greater than 1, and JMax and KMax are equal to 1, then your data is irregular.

It is also possible to tell if you have irregular data by looking at the plot. If you are looking at irregular data with the Mesh layer turned on, the data points will be connected by lines in the order the points appear in the data set.

 You can organize your data set for Tecplot 360 in one of the following
ways .
  1. Manually order the data file using a text editor.

  2. Use one of the Data→Interpolation options.

Example - Unorganized Three-Dimensional Volume

To use 3D volume irregular data in field plots, you must interpolate the data onto a regular, IJK-ordered zone. To interpolate your data, perform the following steps:

  1. Place your 3D volume irregular data into an I-ordered zone in a data file.

  2. Read in your data file and create a 3D scatter plot.

  3. From the Data menu, choose Create Zone>Rectangular. (Circular will also work.)

  4. In the Create Rectangular Zone dialog, enter the I-, J-, and K-dimensions for the new zone; at a minimum, you should enter 10 for each dimension. The higher the dimensions, the finer the interpolation grid, but the longer the interpolating and plotting time.

  5. Enter the minimum and maximum X, Y, and Z values for the new zone. The default values are the minimums and maximums of the current (irregular) dataset.

  6. Click [Create] to create the new zone, and [Close] to dismiss the dialog.

  7. From the Data menu, choose Interpolate>Inverse Distance. (Linear or Kriging also works.)

  8. In the Inverse-Distance Interpolation dialog, choose the irregular data zone as the source zone, and the newly created IJK-ordered zone as the destination zone. Set any other parameters as desired.

  9. Select the [Compute] button to perform the interpolation.

Once the interpolation is complete, you can plot the new IJK-ordered zone as any other 3D volume zone. You may plot iso-surfaces, volume streamtraces, and so forth. At this point, you may want to deactivate or delete the original irregular zone so as not to conflict with plots of the new zone.

Figure 7 shows an example of irregular data interpolated into an IJK-ordered zone, with iso-surfaces plotted on the resultant zone.

ito3dijk.jpg
Figure 7. Irregular data interpolated into an IJK-ordered zone.

Time and Date Representation

Tecplot 360 uses floating point numbers to represent times and dates. The integer portion represents the number of days since December 30, 1899. The decimal portion represents a fractional portion of a day. The table below illustrates some examples of this method.

Date Time Floating Point Number

1900-01-01

00:00:00

2.0

1900-01-01

12:00:00

2.5

2008-07-31

00:00:00

39660.0

2008-07-31

12:00:00

39660.5

2008-07-31

12:01:00

39660.5006944444

2008-07-31

13:00:00

39660.5416666667

Tecplot 360 supports dates from 1800-01-01 through 9999-12-31. This formatting matches the representation method used by Microsoft Excel, enabling you to load time/date data easily from Excel into Tecplot 360. However, because Excel software’s original formatting incorrectly calculated 1900 as a leap year, only dates from Mar 1, 1900 forward will import correctly into Tecplot 360.

Binary Data

This chapter is intended for experienced programmers who need to create Tecplot binary data files directly. Support for topics discussed in this chapter is limited to general questions about writing Tecplot binary files. It is beyond the scope of our Technical Support to offer programming advice or to debug programs.

It is easy to write ASCII files in text format, and they have the advantage that you can inspect them using a text editor to make sure they are being written correctly. Their primary disadvantages are that they can consume much more disk space than binary files and are slower to load, which is especially noticeable when they are large. While users can convert them to the binary format with the Preplot utility (see Converting ASCII to Binary for additional information), it is much more efficient to simply write them in binary format to begin with.

To output your data directly into Tecplot’s basic binary file format, .plt, you may use the TecIO library, which is provided at no cost by Tecplot, Inc., or you may write your own binary functions. If you wish to write your own functions, refer to Binary Data File Format for details on the structure of .plt files. If you wish to link with the library provided by Tecplot, begin with Getting Started and use Binary Data File Format only for reference.

If you wish to write files in the newer .szplt format, you must use the TecIO library, as this file format is currently not documented.

You can find source files for most of the examples in this chapter in the util/tecio/examples folder of your Tecplot 360 installation.

New TecIO Writing API

This chapter describes the "classic" TecIO binary file API. If you will be writing SZL (.szplt) files, you may want to use the new API described in Writing SZL Data Files (New API). However, even if you use the new API, you should still read this chapter for background if you are not already familiar with the classic API.

Getting Started

TecIO is a library of utility functions that your application can use to create binary data files directly, bypassing the use of ASCII files. This makes for fewer files to manage, conserves disk space, and saves the time required to convert the files to binary (whether as a separate step or when loading them).

Tecplot products support two binary file formats:

Tecplot Binary (.plt)

The legacy format written by versions of Tecplot 360 and Tecplot Focus prior to Tecplot 360 EX. It is of course also supported by Tecplot 360 EX and can be read by all versions of Tecplot 360, 360 EX, and Focus.

Tecplot Subzone (.szplt)

A newer format introduced with Tecplot 360 EX, optimized for large data sets, that enables substantially improved interactive performance and a reduced memory footprint for common workflows. It can only be read by Tecplot 360 EX. Subzone data does not support Polyhedral data.

We encourage you to support both formats. Users of Tecplot 360 EX will appreciate the improved interactive experience, while users of Tecplot Focus, legacy versions of Tecplot 360, and other programs that read only Tecplot-format binary files will appreciate being able to consume your data with the software they use every day.

Two versions of the TecIO library are available: a standard (single-process) library and a multiprocess library that employs MPI (Message Passing Interface, a standardized, portable message-passing system available on a variety of parallel computing architectures). The MPI version only writes subzone (.szplt) files. Copies of both are installed with your Tecplot 360 installation. The path of the file varies depending on the platform.

Platform Standard TecIO Multiprocess TecIO

Linux

lib/libtecio.so

lib/libteciompi.so

Mac

tecio/libtecio.dylib

tecio/libteciompi.dylib

Windows

lib/tecio.dll

lib/libteciompi.dll

You may also download the latest version of TecIO from the Tecplot Web site. (This may be a newer version than the one described in this document.) Tecplot 360 and Focus both contain precompiled versions of TecIO in their base installation. The download from the website only contains the source files.

Before preparing to output your data in Tecplot’s binary format using the TecIO library, we recommend you proceed as follows:

  1. Review Data Structure for information on how zones and data are structured, Binary Data File Function Calling Sequence and Writing to Multiple Binary Data Files.

  2. Review the example files in the examples/tecio folder. The example programs demonstrate the use of the TecIO utility functions and are provided in both FORTRAN and C/C++:

    • simtest.f, simtest.f90, simtest.cpp - These files demonstrate simple use of the TecIO utility functions.

    • comtest.f, comtest.f90, comtest.cpp - These files demonstrate complex use of TecIO utility functions, such as multiple file generation and transient data.

    Numerous additional, more modern examples included in the TecIO package target specific actions, like writing polyhedral data. Review these examples for additional guidance.

  3. Follow the instructions in Linking with the TecIO Library for information on setting up your project to develop with TecIO and linking with the library.

  4. Begin developing your code.

Be sure to check out the examples located in your installation directory. A brief overview of the types of examples are listed below.

Table 1. TecIO Examples and Descriptions
Example Description

Complex Example

comtest, create multiple plt files containing multiple zones (structured/unstructured/XY Line), also creates geometries and text.

FE (Unstructured) Face Neighbors

faceneighbors, creates plt file of simple squares with face neighbor information.

FE (Unstructured) Partitioned

brickpartitioned, creates an Unstructured .szplt file with partitioned zones, uses TecIO MPI, can be passed flags to output the partitioned zone in grid and solution .szplt files.

Ordered

ij_ordered, creates two, small, 2D, ordered zones with contour variable information.

Ordered Partitioned

ijkpartitioned, creates a .szplt file with an IJK ordered zone in 4 partitions, uses TecIO MPI.

Read/Write Szplt

rewriteszl, creates a utility that reads in a .szplt file and writes it out to another .szplt file

Text

text, creates a text box in a .plt file.

Viewing Your Output

You may load your binary files in Tecplot 360 or Tecplot Focus using the Tecplot Data loader or the Tecplot Subzone Data Loader, as appropriate. Once loaded, you may view information about your data file using any of the following techniques:

Data Set Information dialog

You may use the Data Set Information dialog (accessed via the Data menu) to display information about your file (once it is loaded into Tecplot). Refer to this dialog for a list of the zones, variables, variable ranges, auxiliary data and more. Refer to the User’s Manual for details.

Data Spreadsheet

Use the Data Spreadsheet to view a table of every variable value in your file. Refer to the User’s Manual for details.

Partitioned Data

The TecIO library supports partitioning finite-element and ordered zones when writing .szplt data files. That is, the data does not need to be written all at once, but can be written in sections, and by more than one process. This capability is intended primarily for use with CFD codes that compute large solutions in parallel, with multiple solver processes running on independent nodes in a compute cluster, each solving a subset of the simulation. However, this capability can also be used by a single-process solver running on a desktop workstation if desired.

TecIO writes the partitioned zones into a single Tecplot .szplt file that can later be opened and visualized by Tecplot 360. To enable this functionality on large multiprocessing systems, TecIO utilizes the Message-Passing Interface (MPI) library.

By comparison to non-partitioned zones, only a couple of additional TecIO function calls are required when writing partitioned zones, and only a couple more beyond that when writing in parallel using MPI . Two versions of the TecIO library are provided: tecio and teciompi. The latter requires a compatible MPI library. (Note that non-MPI tecio does support writing partitioned zones, just not in parallel.)

The teciompi library only writes SZL (.szplt) files; it does not write traditional Tecplot binary (.plt) files.

Partitioned solution of large CFD cases typically requires that zone partitions overlap slightly. That is, the nodes or cells on the each side of the boundary between partitions will reside in more than one solver process: in the one that "owns" it according to the partitioning rules, as well as in any processes solving a partition spatially adjacent to it. In processes other than the one that "owns" them, such data are commonly referred to as "ghost cells" and "ghost nodes."

The TecIO library needs information about these overlapping cells and nodes in order to later allow the partitioned data to be joined into a single virtual data set suitable for visualization. For finite-element zones, each solver process must pass a list of its ghost nodes and cells along with the zone data (which should include the ghost nodes and cells). For ordered zones, the solver need pass only the nodes that form non-ghost cells, which provides sufficient information for later reassembling the data.

The code sample brickpartitioned is useful for understanding how to write partitioned zones, and includes the additional function calls needed for writing partitioned data in parallel using MPI. The ijkpartitioned code sample shows this for an IJK-ordered zone, and also demonstrates outputting non-partitioned zones from various MPI ranks.

Binary File Compatibility

A .plt file is compatible with the version of Tecplot 360 EX or Focus tied to the version of the TecIO library that you use and later versions. For example, if you use the TecIO library that was bundled with Tecplot 360 EX 2014 R2, your files can be loaded with Tecplot 360 EX 2014 R2 and newer. A .plt file is also backward compatible to the first version of Tecplot 360 (pre-EX) or Focus that uses the file format version supported by the library being used.

This rule is independent of the version number used for the binary functions (for example, the 142 in TECINI). Even if you use 142 functions with the version of the TecIO library included with this distribution, your .plt file will be compatible with this version of Tecplot 360 EX and newer.

However, older Tecplot products cannot read .szplt files regardless of their version. Subzone data files (SZL or .szplt) can be loaded only in Tecplot 360 EX, not Tecplot 360 (pre-EX) or Tecplot Focus.

The SZL file format was introduced in Tecplot 360 EX 2014 R1 and was revised in Tecplot 360 EX 2016 R1 to support partitioned output. Similar to the situation with the .plt format, newer versions of Tecplot 360 EX can read the format generated with the older TecIO library, but older versions of Tecplot 360 EX may not always be able to read the files generated by the newer versions of TecIO.

Files containing face-based (polygonal or polyhedral) finite-element zones cannot be read by Tecplot Focus. Tecplot Focus 2016 R1 and later can read files containing a maximum of five million data points.

However, the TecIO shipped with Tecplot EX 2014 R2 and later will produce files compatible with older versions dating back to 2009 as long as the file does not contain polyhedral or polygonal zones with more than 2 billion face nodes.

Deprecated Binary Functions

Functions whose names end in an integer less than 142 are deprecated and are provided only for compatibility with older client code. We recommend you use the 142 binary function family with new code and/or if you need to update your application to take advantage of the new functionality provided with version 142. In order to use the 142 family of functions, use the TecIO library included in your Tecplot 360 EX 2024 distribution. If you have existing code using deprecated functions, and want to use any binary function calls from version 142, you must update all your TecIO library calls to 142.

API version 142 or later allows applications to select between the .plt and .szplt file formats at runtime, a feature introduced with Tecplot 360 2014 R2. In Tecplot 360 2014 R1, two versions of the TecIO library were provided, one that wrote .plt files and one that wrote .szplt files. Both had identical APIs; the file format was determined solely by the version of the library you linked with your application. In Tecplot 360 2014 R2 and later, a parameter was added to TECINI to choose the format when opening the file for writing (see TECINI142. The current TecIO library always writes .plt files when using an API version below 142, since there is no way to specify the file format with these older APIs.

Character Strings in FORTRAN

All character string parameters passed to TecIO must use C-style strings: that is, they must terminate with a null character. In FORTRAN, this can be done by concatenating char(0) to the end of a character string.

For example, to send the character string "Hi Mom" to a function called A, use the following syntax:

I=A("Hi Mom"//char(0))

Boolean Flags

Integer parameters identified as "flags" indicate boolean values. Pass 1 for true, and 0 for false.

Binary Data File Function Calling Sequence

The binary data file functions in the TecIO library must be called in a specific order, which varies slightly depending on the type of zone being written and whether you are using the serial version (tecio) or parallel version (teciompi) of the library. Remember, you may write both partitioned and non-partitioned zones with either version of the TecIO library; the MPI version is required only if you want to write files in parallel.

Even if your code generally supports writing partitioned zones, single-partition zones are considered non-partitioned by TecIO, and you should use the non-partitioned zone calling sequence.

A program may, if desired, write both ordinary and partitioned data to up to ten files simultaneously. Writing to Multiple Binary Data Files explains how to use the TECFIL142 function to write to multiple files simultaneously.

Additional Requirement for Parallel Output

For parallel programs using TecIO-MPI, additional routines must be called and some restrictions must be observed:

  • The routine TECMPIINIT142 must be called after each call to TECINI142. TECMPIINIT142 identifies an MPI communicator that includes all MPI ranks (processes) involved in outputting the file, and designates one rank within the communicator group as the main rank. It must be called by all members of the communicator. If more than one file is being output-TECINI142 is called more than once-each file output may use a different communicator and a different main rank within that communicator.

  • Meta-data and other non-zone items may be output from only the main rank for a file. Thus, the routines TECAUXSTR142, TECVAUXSTR142, TECZAUXSTR142, TECLAB142, TECGEO142, and TECTXT142 can be called only from the main rank. TECUSR142 has no effect because TecIO-MPI outputs only .szplt files, and user data is not included in the .szplt file format.

  • For each zone output, TECZNE142 or TECZNEFEMIXED142 must be called by the main rank and all ranks outputting that zone. It is optional for uninvolved ranks to also call TECZNE142 or TECZNEFEMIXED142; it becomes a no-op for these ranks.

  • TECZNEMAP142 must be called immediately after the call to TECZNE142 or TECZNEFEMIXED142 (including any uninvolved ranks that still called TECZNE142 or TECZNEFEMIXED142). For partitioned zones, TECZNEMAP142 indicates how many partitions will be output for the zone, and identifies the MPI rank that will output each partition. For non-partitioned zones, TECZNEMAP142 is called as if the zone had a single partition. This gives a mechanism for your program to designate, for each non-partitioned zone, which rank will output that zone.

Non-partitioned Zones

When writing non-partitioned zones to a file, calls should be made to TecIO in this order:

Remember that Tecplot Focus cannot load face-based (polygonal or polyhedral) data.

Partitioned Zones

Currently, only classic volume finite-element zones and IJK-ordered zones can be written in partitioned fashion. Other zone types are planned for future development.

The calling sequence for writing partitioned zones is as follows:

Writing to Multiple Binary Data Files

Each time TECINI142 is called, it sets up a new file context. For each file context, you must maintain the order of the calls as described earlier. The TECFIL142 function is used to switch between file contexts. Up to 10 files can be written to at a time. TECFIL142 can be called almost anywhere after TECINI142 has been called. The only parameter to TECFIL142, an integer, n, shifts the file context to the nth open file. The files are numbered relative to the order of the calls to TECINI142.

Note that when writing a subzone (.szplt) file, all data written is held in memory and not actually committed to disk until TECEND142 is called, because the order of data stored in a subzone file is usually not the same as the order in which it was provided by the application. Ordinary binary files (.plt) files may be partially written to disk before TECEND142 is called.

Linking with the TecIO Library

Follow the instructions below to link with the TecIO library. The library is provided as a dynamic library on all platforms, meaning that it remains a separate file and must be distributed with your application. If you wish instead to use a static library that will be combined into your application, you may obtain the TecIO or TecIO-MPI source code from my.tecplot.com/portal/product-releases/tecio-library. For TecIO-MPI on Mac or Linux platforms, you should strongly consider building the library from source on your solver machine, since various MPI versions are not binary-compatible.

Linux/Macintosh

To link with the TecIO library, pass the full path to the tecio (or teciompi) library to your compiler or linker along with all other input files needed to compile and link your application. The TecIO library is written in C++, so in addition to linking it, you will likely also need to link in the C++ standard library.

For example, to create an output file my-executable from a C source file of my-prog.c and link in the TecIO library and the C++ standard library:

cc -o my-executable my-prog.c /path/to/libtecio.so -lstdc++ (Linux)
cc -o my-executable my-prog.c /path/to/libtecio.dylib -lstdc++  (Mac)

For TecIO-MPI, instead use /path/to/libteciompi.so or /path/to/libteciompi.dylib depending on platform.

The stdc++ library used to build the tecio library in your Tecplot 360 installation may be newer than the one provided on your platform. If so, link against the version of the stdc++ library provided in your Tecplot 360 installation. See the file util/tecio/examples/base.make inside your Tecplot 360 installation directory for an example of this.

Include the TecIO header file TECIO.h in your source files. It may be found in the include directory of your Tecplot 360 installation.

Fortran programmers: some Fortran 90 compilers do not recognize the .f90 filename extension.

Windows

To link with the TecIO library, list tecio.dll (or, for TecIO-MPI, teciompi.dll) as an additional dependency in your Visual Studio project. Include the TecIO header file TECIO.h in your source files. It may be found in the include directory of your Tecplot 360 installation.

To ensure Windows finds tecio.dll when launching your executable, ensure its location is in your PATH environment variable, or else copy it to your executable’s directory. The latter approach is generally best, as it ensures that the correct version will be used if multiple copies of the library are installed on the machine.

Notes for Windows Programmers using Fortran

Files tecio.f90 and tecio.for, located in the include folder in your installation, contain both Fortran-90 interfaces for all TecIO routines and several compiler-specific directives (the !MS$ATTRIBUTES lines). These direct Microsoft Visual Fortran to use STDCALL calling conventions with by-reference parameter passing. While tecio.f90 is free-formatted, tecio.for uses the traditional column-based formatting. Include the appropriate file in any of your subroutines that call TecIO routines. Both files were developed for Intel Visual Fortran 9.

Users of other compilers may need to adjust the Fortran settings or add other compiler directives to achieve the same effect. In particular, Fortran strings must be null-terminated and passed without a length argument.

Binary Data File Function Reference

This section describes each of the TecIO functions in detail.

TECAUXSTR142

Writes auxiliary data for the data set to the data file. The function may be called at any time between TECINI142 and TECEND142. Auxiliary data may be used by text, macros, equations (if it is numeric) and add-ons. It may be viewed directly in the Aux Data page of the Data Set Information dialog (accessed via the Data menu).

When using TecIO-MPI, may only be called from the main process.

FORTRAN Syntax:
 INTEGER*4 FUNCTION TECAUXSTR142(Name,
&                                Value)
 CHARACTER*(*) Name
 CHARACTER*(*) Value
C Syntax:
#include TECIO.h
INTEGER4 TECAUXSTR142(char *Name,
                      char *Value);
Return Value

0 if successful, -1 if unsuccessful.

Parameters

Parameter Description

Name

The name of the auxiliary data. If this duplicates an existing name, the value will overwrite the existing value. It must be a null-terminated character string and cannot contain spaces.

Value

The value to assign to the named auxiliary data. It must be a null-terminated character string.

Example

For example, to set an Auxiliary Variable called DeformationValue to 0.98:

char DeformationValue[128];
strcpy(DeformationValue,"0.98");

TECAUXSTR142("DeformationValue",
             DeformationValue);

When the data file is loaded into Tecplot, "Deformation Value" will appear on the Aux Page of the Data Set Information dialog when "for Data Set" is selected in Show Auxiliary Data menu.

TECDAT142

Writes an array of data to the data file. Data should not be passed for variables that have been indicated as passive or shared (via TECZNE142 or TECPOLYZNE142 or TECZNEFEMIXED142).

TECDAT142 allows you to write your data in piecemeal fashion in case it is not contained in one contiguous block in your program or is not available all at once. TECDAT142 must be called enough times to ensure that the correct number of values is written for each zone and that the aggregate order for the data is correct.

FORTRAN Syntax:
 INTEGER*4 FUNCTION TECDAT142(N,
&                             Data,
&                             IsDouble)
 INTEGER*4                    N
 REAL or DOUBLE PRECISION     Data(1)
 INTEGER*4                    IsDouble
C Syntax:
#include TECIO.h
INTEGER4 TECDAT142(INTEGER4  *N,
                   void  *Data,
                   INTEGER4  *IsDouble);
Return Value

0 if successful, -1 if unsuccessful.

Parameters

Parameter Description

N

Pointer to an integer value specifying number of values to write.

Data

Array of single or double precision data values. Refer to Table 2 for a description of how to arrange your data.

IsDouble

Pointer to the integer flag stating whether the array Data is single (0) or double (1) precision.

Data Arrangement

The following table describes the order the data must be supplied given different zone types. VarLocation is a parameter supplied to TECZNE142 or TECPOLYZNE142 or TECZNEFEMIXED142.

Table 2. Data Arrangement
Zone Type Var. Location Number of Values Order

Ordered

Nodal

IMax*
JMax*
KMax*
NumVars

I varies fastest, then J, then K, then Vars. That is, the numbers should be supplied in the following order:

for (Var=1;Var<=NumVars;Var++)
  for (K=1;K<=KMax;K++)
    for (J=1;J<=JMax;J++)
      for (I=1;I<=IMax;I++)
        Data[I, J, K, Var] = value;

Ordered

Cell Centered

(IMax-1)*
(JMax-1)*
(KMax-1)*
NumVars

I varies fastest, then J, then K, then Vars. That is, the numbers should be supplied in the following order:

for (Var=1;Var<=NumVars;Var++)
  for (K=1;K<=(KMax-1);K++)
    for (J=1;J<=(JMax-1);J++)
      for (I=1;I<=(IMax-1);I++)
        Data[I, J, K, Var] = value;

Finite element

Nodal

IMax (i.e. NumNodes) * NumVars

N varies fastest, then Vars. That is, the numbers should be supplied in the following order:

for (Var=1;Var<=NumVars;Var++)
  for (N=1;N<=NumNodes;N++)
    Data[N, Var] = value;

Finite element

Cell Centered

JMax (i.e. NumElements) * NumVars

E varies fastest, then Var. That is, the numbers should be supplied in the following order:

for (Var=1;Var<=NumVars;Var++)
  for (E=1;E<=NumElements;E++)
    Data[E, Var] = value;

Refer to Examples for examples using TECDAT142:

TECEND142

Must be called to close the current data file. There must be one call to TECEND142 for each TECINI142 or data may be lost. (When writing .szplt files, all data are held in memory until TECEND142 is called.)

When writing partitioned data, this call will block until all processes involved in writing the data have called it.

FORTRAN Syntax:
INTEGER*4 FUNCTION TECEND142()
C Syntax:
#include TECIO.h
INTEGER4 TECEND142();
Return Value

0 if successful, -1 if unsuccessful.

Parameters

None.

TECFACE142

Writes face connections for the current zone to the file. Face Neighbor Connections are used for ordered or cell-based finite element zones to specify connections that are not explicitly defined by the connectivity list or ordered zone structure. You many use face neighbors to specify connections between zones (global connections) or connections within zones (local connections). Face neighbor connections are used by Tecplot when deriving variables or drawing contour lines. Specifying face neighbors typically leads to smoother connections. NOTE: face neighbors have expensive performance implications. Use face neighbors only to manually specify connections that are not defined via the connectivity list.

Remember that Tecplot Focus cannot load face-based (polygonal or polyhedral) data.

This function must be called after TECNOD142 or TECNODE142, and may only be called if a non-zero value of NumFaceConnections was used in the previous call to TECZNE142 or TECZNEFEMIXED142.

FORTRAN Syntax:
INTEGER*4 FUNCTION TECFACE142(FaceConnections)
INTEGER*4 FACECONNECTIONS(*)
C Syntax:
#include TECIO.h
INTEGER4 TECFACE142(INTEGER4 *FaceConnections);
Return Value

0 if successful, -1 if unsuccessful.

Parameters

Parameter Description

FaceConnections

The array that specifies the face connections. The array must have L values, where L is the sum of the number of values for each face neighbor connection in the data file. The number of values in a face neighbor connection is dependent upon the FaceNeighborMode parameter (set via TECZNE142 or TECZNEFEMIXED142) and is described in the following table.

FaceNeighbor Mode

Number of values

Data

LocalOneToOne

3

cz1,fz,cz2

LocalOneToMany

nz+4

cz1,fz,oz,nz,cz2,cz3,…​,czn

GlobalOneToOne

4

cz, fz, ZZ, CZ

GlobalOneToMany

2*nz+4

cz, fz, oz, nz, ZZ1, CZ1, ZZ2, CZ2, …​,ZZn, CZn

Where:

  • cz = cell in current zone

  • fz = face of cell in current zone

  • oz = face obscuration flag (only applies to one-to-many, 0 = face partially obscured, 1 = face entirely obscured)

  • nz = number of cell or zone/cell associations (only applies to one-to-many)

  • ZZ = remote Zone

  • CZ = cell in remote zone

cz,fz combinations must be unique. Additionally, Tecplot 360 assumes that with the one-to-one face neighbor modes a supplied cell face is entirely obscured by its neighbor. With one-to-many, the obscuration flag must be supplied. Faces that are not supplied with neighbors are run through Tecplot 360’s auto face neighbor generator (FE only).

The face numbers for cells in the various zone types are shown below:

ijk_ordered_block00059.png
Figure 8. Example of node and face neighbors for an FE-brick cell or IJK-ordered cell.
ij_ordered_block00061.png
Figure 9. Example of node and face numbering for an IJ-ordered/ FE-quadrilateral cell.
face_neighbors_tet00063.png
Figure 10. Example of tetrahedron face neighbors.

Example

Refer to Face Neighbors for an example of working with face neighbors. In this example, face neighbors are used to prevent an Edge line from being drawn between the two zones.

TECFEMIXEDPTN142

When writing a partitioned FE-mixed element zone to a .szplt file, TECFEMIXEDPTN142 provides information about the partition about to be written. Must be called after TECZNEFEMIXED142 (and, for TecIO-MPI, TECZNEMAP142) but before calling TECDAT142 and TECNOD142/ TECNODE142 to actually write the data. Should not be called for non-partitioned zones (or equivalently, zones that have only one partition).

A partition may include nodes and cells that overlap other partitions, commonly referred to as "ghost nodes" and "ghost cells." The TECZNEFEMIXED142 function call specifies this ghost data, allowing the partitions to be later reassembled seamlessly into a single zone when loaded for visualization. Each node or cell should be considered to be "owned" by one process, and that process should not report that node or cell as a "ghost." Any other process that has that node or cell in its partition should include it in the list of ghost nodes or cells, respectively, passed to TECZNEFEMIXED142. The array containing the number of cells per section and the number of ghost cells per section must be dimensioned by the number of sections for the zone. All partitions of the zone must deliver both arrays dimensioned by the number of sections for the zone. If a partition does not have cells in a given section it must set the number of cells for that section to zero. The ghostCells array is a flat array containing the ghost cells for each section, back to back, interpreted by looking at the counts in the numGhostCellsPerSection array.

All partitions must include data for the actual "ghost" nodes and cells using the appropriate function calls (e.g. TECDAT142, TECNOD142/ TECNODE142).

FORTRAN Syntax:
 INTEGER*4 FUNCTION TECFEMIXEDPTN142(partition
&                                    numNodes,
&                                    numCellsPerSection,
&                                    numGhostNodes,
&                                    ghostNodes,
&                                    neighborPartitions,
&                                    neighborPartitionNodes,
&                                    numGhostCellsPerSection,
&                                    ghostCells)
 INTEGER*4 partition
 INTEGER*8 numNodes
 INTEGER*8 numCellsPerSection
 INTEGER*8 numGhostNodes
 INTEGER*4 ghostNodes
 INTEGER*4 neighborPartitions
 INTEGER*4 neighborPartitionNodes
 INTEGER*8 numGhostCellsPerSection
 INTEGER*4 ghostCells
C Syntax:
#include "TECIO.h"
INTEGER4 TECFEMIXEDPTN142(INTEGER4 const* partition,
                          INTEGER8 const* numNodes,
                          INTEGER8 const* numCellsPerSection,
                          INTEGER8 const* numGhostNodes,
                          INTEGER4 const* ghostNodes,
                          INTEGER4 const* neighborPartitions,
                          INTEGER4 const* neighborPartitionNodes,
                          INTEGER8 const* numGhostCellsPerSection,
                          INTEGER4 const* ghostCells)
Return Value

0 if successful, -1 if unsuccessful.

Parameters

Parameter Description

partition

The number of the current partition. Partitions are numbered from 1 to the number of partitions (as specified in the TECZNEMAP142 call) inclusive.

numNodes

The number of nodes in the partition, including any ghost nodes.

numCellsPerSection

The number of cells in each section of the partition, including any ghost cells. The array must be dimensioned by the number of sections in the zone and is the same dimension for all partitions. If a partition does not have any cells in a given section a value of zero should be set for that section.

numGhostNodes

The number of ghost nodes in the partition.

ghostNodes

Array of length numGhostNodes specifying the indices of the ghost nodes. Each ghost node must be specified exactly once.

neighborPartitions

Array of length numGhostNodes specifying the owning partition of each ghost node, in the order in which they are specified in ghostNodes.

neighborPartitionNodes

Array of length ngnodes specifying the node index by which each ghost node is known in its owning partition, again in the order specified in ghostNodes.

numGhostCellsPerSection

The number of ghost cells in each section of the partition. The array must be dimensioned by the number of sections in the zone and is the same dimension for all partitions. If a partition does not have any ghost cells in a given section a value of zero should be set for that section.

ghostCells

Flat array of a length that is the sum of the members of the numGhostCellsPerSection array containing the ghost cells for each section of the partition listed back to back.

TECFEPTN142

When writing a partitioned classic finite-element zone to a .szplt file, provides information about the partition about to be written. Must be called after TECZNE142 or TECZNEMAP142(and, for TecIO-MPI, TECZNEMAP142) but before calling TECDAT142 and TECNOD142/TECNODE142 to actually write the data. Should not be called for non-partitioned zones (or equivalently, zones that have only one partition).

A partition may include nodes and cells that overlap other partitions, commonly referred to as "ghost nodes" and "ghost cells." The TECFEPTN142 function call specifies this ghost data, allowing the partitions to be later reassembled seamlessly into a single zone when loaded for visualization. Each node or cell should be considered to be "owned" by one process, and that process should not report that node or cell as a "ghost." Any other process that has that node or cell in its partition should include it in the list of ghost nodes or cells, respectively, passed to TECFEPTN142.

All partitions must include data for the actual "ghost" nodes and cells using the appropriate function calls (e.g. TECDAT142, TECNOD142/TECNODE142).

FORTRAN Syntax:
 INTEGER*4 FUNCTION TECFEPTN142( partition,
&                               numnodes,
&                               numcells,
&                               ngnodes,
&                               gnodes,
&                               gnpartitions,
&                               gnpnodes,
&                               ngcells,
&                               gcells)
INTEGER*4  partition
INTEGER*4  numnodes
INTEGER*4  numcells
INTEGER*4  ngnodes
INTEGER*4  gnodes
INTEGER*4  gnpartitions
INTEGER*4  gnpnodes
INTEGER*4  ngcells
INTEGER*4  gcells
C Syntax:
#include TECIO.h
INTEGER4 TECFEPTN142(INTEGER4 *partition,
                     INTEGER4 *numnodes,
                     INTEGER4 *numcells,
                     INTEGER4 *ngnodes,
                     INTEGER4 *gnodes,
                     INTEGER4 *gnpartitions,
                     INTEGER4 *gnpnodes,
                     INTEGER4 *ngcells,
                     INTEGER4 *gcells);
Return Value

0 if successful, nonzero if unsuccessful.

Parameters

Parameter Description

partition

The number of the current partition. Partitions are numbered from 1 to the number of partitions (as specified in the TECZNEMAP142 call) inclusive.

numnodes

The number of nodes in the partition, including any ghost nodes.

numcells

The number of cells in the partition, including any ghost cells.

ngnodes

The number of ghost nodes in the partition.

gnodes

Array of length ngnodes specifying the indices of the ghost nodes. Each ghost node must be specified exactly once.

gnpartitions

Array of length ngnodes specifying the owning partition of each ghost node, in the order in which they are specified in gnodes.

gnpnodes

Array of length ngnodes specifying the node index by which each ghost node is known in its owning partition, again in the order specified in gnodes.

ngcells

Number of ghost cells.

gcells

Array of length ngcells specifying the indices of the ghost cells. Each ghost cell must be specified exactly once.

TECFIL142

Switch output context to a different file. Each time TECINI142 is called, a new file context is created. This allows you to write multiple data files concurrently. When working with multiple files, be sure to call TECFIL142 each time you wish to write to a file to ensure your data is written to the expected file.

FORTRAN Syntax:
`INTEGER*4 FUNCTION TECFIL142(F)
 INTEGER*4    F
C Syntax:
#include TECIO.h
INTEGER4 TECFIL142(INTEGER4 *F);
Return Value

0 if successful, -1 if unsuccessful.

Parameters

Parameter Description

F

Pointer to integer specifying file number to switch to. A value of 1 indicates a switch to the file opened by the first call to TECINI142.

Examples

Refer to Switching Between Two Files for a simple example of working with TECFIL142.

TECFLUSH142

Optional, implemented for SZL file output only. May be called at any point where the current zone data and connectivity (if any) are complete. This call will append current data to six temporary files (creating the files if they do not already exist), and release associated Tecio memory. The names of these files are the filename supplied to TECINI142, appended with each of six file suffixes: .szhdr, .szdat, .szaux, .sztxt, .szgeo and .szlab. These six files, along with any data not yet flushed to disk, will be assembled into the final .szplt file when TECEND142 is called.

If using TecIO-MPI, this is a collective function - it must be called by all processes in the communicator that was supplied in the call to TECMPIINIT142, and will block until all processes have called it.

This routine is useful for unsteady solvers that write multiple time steps of data to disk and wish to write them all to a single .szplt file. It prevents Tecio from caching all of those time steps in memory, which might exhaust all available memory on the solver machine. It is an alternative to grid/solution files, and should not be used when writing grid/solution files because it adds unnecessary processing overhead for no benefit.

At any time after the first call to TECFLUSH142, the temporary files may be assembled manually using shell utility szcombine. Please see the documentation for SZCOMBINE for more information.

The data can be left in the temporary files, and even appended to in subsequent solver runs, by not calling TECEND142 at the end of the solver run. To append to existing temporary files in a new solver run, pass the same file name to TECINI142 as was used to create the temporary files in the first solver run. Note that the time steps of the new solver run will not be able to share variables or connectivity with any time steps from previous solver runs.

FORTRAN Syntax:
 INTEGER*4 TECFLUSH142(NumZonesToRetain,
&                      ZonesToRetain)
 INTEGER*4 NumZonesToRetain
 INTEGER*4 ZonesToRetain(*)
C Syntax:
INTEGER4 TECFLUSH142(INTEGER4 const* NumZonesToRetain,
                     INTEGER4 const* ZonesToRetain);
Return value:

0 if successful, -1 otherwise.

Parameters

Parameters Description

NumZonesToRetain

The number of zones to retain in Tecio memory for sharing from subsequent zones.

ZonesToRetain

The list of zones to retain in Tecio memory. These zones will be written to the temporary files, but will also be retained in memory so that they are available for variable or connectivity sharing by zones to be output later. These are the only zone numbers that may be referenced by the parameters ShareVarFromZone or ShareConnectivityFromZone in subsequent calls to TECZNE142 or TECZNEFEMIXED142.

TECFOREIGN142

Optional function that sets the byte ordering request for subsequent calls to TECINI142. The byte ordering request will remain in effect until the next call to this function. This has no effect on any files already opened via TECINI142. Use this function to reverse the byte ordering from the format native to your operating system. This function is not much needed today, since current Tecplot products are supported only on Intel-based platforms; however, it may be useful with older versions of TecIO running on legacy UNIX platforms that have non-Intel byte orders.

If the function call is omitted, native byte ordering is used.

FORTRAN Syntax:
 INTEGER*4 FUNCTION TECFOREIGN142(DoForeignByteOrder)
 INTEGER*4                        DoForeignByteOrder
C Syntax:
#include TECIO.h
INTEGER4 TECFOREIGN142(INTEGER4 *DoForeignByteOrder);
Return Value

0 if successful, -1 if unsuccessful.

Parameters

Parameter Description

DoForeignByteOrder

Pointer to boolean value indicating if future files created by TECINI142 should be written out in foreign byte order. 0 indicates native byte order. 1 indicates foreign byte order.#

TECGEO142

Adds a geometry object to the file (e.g. a circle or a square). You cannot set unused parameters to NULL; use dummy values for unused parameters.

When using TecIO-MPI, may only be called from the main process.

FORTRAN Syntax:
 INTEGER*4 FUNCTION TECGEO142(XOrThetaPos,
&                             YOrRPos,
&                             ZPos,
&                             PosCoordMode,
&                             AttachToZone,
&                             Zone,
&                             Color,
&                             FillColor,
&                             IsFilled,
&                             GeomType,
&                             LinePattern,
&                             PatternLength,
&                             LineThicknessness,
&                             NumEllipsePts,
&                             ArrowheadStyle,
&                             ArrowheadAttachment,
&                             ArrowheadSize,
&                             ArrowheadAngle,
&                             Scope,
&                             Clipping,
&                             NumSegments,
&                             NumSegPts,
&                             XOrThetaGeomData,
&                             YOrRGeomData,
&                             ZGeomData,
&                             MFC)
DOUBLE PRECISION              XOrThetaPos
DOUBLE PRECISION              YOrRPos
DOUBLE PRECISION              ZPos
INTEGER*4                     PosCoordMode
INTEGER*4                     AttachToZone
INTEGER*4                     Zone
INTEGER*4                     Color
INTEGER*4                     FillColor
INTEGER*4                     IsFilled
INTEGER*4                     GeomType
INTEGER*4                     LinePattern
DOUBLE PRECISION              PatternLength
DOUBLE PRECISION              LineThicknessness
INTEGER*4                     NumEllipsePts
INTEGER*4                     ArrowheadStyle
INTEGER*4                     ArrowheadAttachment
DOUBLE PRECISION              ArrowheadSize
DOUBLE PRECISION              ArrowheadAngle
INTEGER*4                     Scope
INTEGER*4                     Clipping
INTEGER*4                     NumSegments
INTEGER*4                     NumSegPts
REAL*4                        XOrThetaGeomData
REAL*4                        YOrRGeomData
REAL*4                        ZGeomData
CHARACTER*(*)                 MFC
C Syntax:
#include TECIO.h
INTEGER4 TECGEO142(double *XOrThetaPos,
                   double  *YOrRPos,
                   double  *ZPos,
                   INTEGER4 *PosCoordMode,
                   INTEGER4 *AttachToZone,
                   INTEGER4 *Zone,
                   INTEGER4 *Color,
                   INTEGER4 *FillColor,
                   INTEGER4 *IsFilled,
                   INTEGER4 *GeomType,
                   INTEGER4 *LinePattern,
                   double  *PatternLength,
                   double    *LineThicknessness,
                   INTEGER4 *NumEllipsePts,
                   INTEGER4 *ArrowheadStyle,
                   INTEGER4 *ArrowheadAttachment,
                   double  *ArrowheadSize,
                   double  *ArrowheadAngle,
                   INTEGER4 *Scope,
                   INTEGER4 *Clipping,
                   INTEGER4 *NumSegments,
                   INTEGER4 *NumSegPts,
                   float  *XOrThetaGeomData,
                   float  *YOrRGeomData,
                   float  *ZGeomData,
                   char  *MFC)
Return Value

0 if successful, -1 if unsuccessful.

Parameters

Parameter Description

XPos or ThetaPos

Pointer to double value specifying the X- position or, for polar line plots, the Theta-position of the geometry.

YPos or RPos

Pointer to double value specifying the Y-position or, for polar line plots, the R-position of the geometry.

ZPos

Pointer to double value specifying the Z-position of the geometry.

PosCoordMode

Pointer to integer value specifying the position coordinate system.

0=Grid

1=Frame

6=Grid3D

Grid3D is available only when the GeomType is equal to 3D Line Segments.

AttachToZone

Pointer to integer flag to signal that the geometry is "attached" to a zone. When a geometry is attached to a zone, it will be visible only when that zone is visible.

1 = Yes

0 = No

Zone

Pointer to integer value specifying the number of the zone to attach to. Must be greater than or equal to one.

Color

Pointer to integer value specifying the color to assign to the geometry.

0=Black
1=Red
2=Green
3=Blue
4=Cyan
5=Yellow
6=Purple
7=White

8=Custom1
9=Custom2
10=Custom3
11=Custom4
12=Custom5
13=Custom6
14=Custom7
15=Custom8

FillColor

Pointer to integer value specifying the color used to fill the geometry. Refer to Color for a list of available values.

IsFilled

Pointer to integer flag to specify if geometry is to be filled.

1 = Yes

0 = No

GeomType

Pointer to integer value specifying the geometry type.

0=2D Line Segments
1=Rectangle
2=Square

3=Circle
4=Ellipse
5=3D Line Segments

LinePattern

Pointer to integer value specifying the line pattern.

0=Solid
1=Dashed
2=DashDot

3=Dotted
4=LongDash
5=DashDotDot

PatternLength

Pointer to double value specifying the pattern length in frame units (from 0.01 and less than 100).

LineThicknessness

Pointer to double value specifying the line thickness in frame units. The value must be greater than 0.0001 and less than 100.

NumEllipsePts

Pointer to integer value specifying the number of points to use for circles and ellipses. The value must be between 2 and 720.

ArrowheadStyle

Pointer to integer value specifying the arrowhead style.

0=Plain

2=Hollow

1=Filled

ArrowheadAttachment

Pointer to integer value specifying where to attach arrowheads.

0=None
1=Beginning

2=End
3=Both

ArrowheadSize

Pointer to double value specifying the arrowhead size in frame units (from 0 to 100).

ArrowheadAngle

Pointer to double value specifying the arrowhead angle in degrees.

Scope

Pointer to integer value specifying the scope with respect to frames. A local scope places the object in the active frame. A global scope places the object in all frames that contain the active frame’s data set.

0=Global

1=Local.

Clipping

Specifies whether to clip the geometry (that is, only plot the geometry within the viewport or the frame).

0=ClipToViewport

1=ClipToFrame

NumSegments

Pointer to integer value specifying the number of polyline segments.

NumSegPts

Array of integer values specifying the number of points in each of the NumSegments segments.

XGeomData

Array of floating-point values specifying the X-, Y- and Z-coordinates. Refer to Data Values for information regarding the values required for each GeomType.

ThetaGeomData

YGeomData

RGeomData

ZGeomData

MFC

Macro function command. Must be null terminated.

Origin positions

The origin (XOrThetaPos, YOrRPos, ZPos) of each geometry type is listed below:

  • SQUARE- lower left corner at XOrThetaPos, YOrRPos.

  • RECTANGLE- lower left corner at XOrThetaPos, YOrRPos.

  • CIRCLE - centered at XOrThetaPos, YOrRPos.

  • ELLIPSE- centered at XOrThetaPos, YOrRPos.

  • LINE - anchored at XOrThetaPos, YOrRPos.

  • LINE3D- anchored at XOrThetaPos, YOrRPos, ZPos.

Data Values

The origin (XOrThetaGeomData, YOrRGeomData, ZGeomData) of each geometry type is listed below:

  • SQUARE- set XOrThetaGeomData equal to the desired length.

  • RECTANGLE- set XOrThetaGeomData equal to the desired width and YOrThetaGeomData equal to the desired height.

  • CIRCLE - set XOrThetaGeomData equal to the desired radius.

  • ELLIPSE- set XOrThetaGeomData equal to the desired width along the x-axis and YOrThetaGeomData equal to the desired width along the y-axis.

  • LINE - specify the coordinate positions for the data points in each line segment with *XOrThetaGeomData * and YOrRGeomData.

  • LINE3D- specify the coordinate positions for the data points in each line segment with XOrThetaGeomData, YOrRGeomData and ZGeomData.

TECIJKPTN142

When writing a partitioned IJK-ordered zone to a .szplt file, TECIJKPTN142 provides information about the partition about to be written. Must be called after TECZNE142 (and, for TecIO-MPI, TECZNEMAP142) but before calling TECDAT142 to actually write the data. Should not be called for non-partitioned zones (or equivalently, zones that have only one partition).

The TECIJKPTN142 function specifies the I, J, and K indices of the partition (excluding any "ghost" cells), allowing the partitions to be later reassembled seamlessly into a single zone when loaded for visualization. The indices passed refer to indices of the entire IJK-ordered zone. Therefore, the I dimension (for example) of a partition is imax - imin + 1.

Index ranges of neighboring partitions must exactly coincide: for example, if one zone’s imax is 25, the imin of the partition immediately to the right must be 25.

Data subsequently written using TECDAT142 must output only the data corresponding to the nodes and cells indicated by this range.

FORTRAN Syntax:
 INTEGER*4 FUNCTION TECIJKPTN142(partition,
&                                imin,
&                                jmin,
&                                kmin,
&                                imax,
&                                jmax,
&                                kmax)
 INTEGER*4                       partition
 INTEGER*4                       imin
 INTEGER*4                       jmin
 INTEGER*4                       kmin
 INTEGER*4                       imax
 INTEGER*4                       jmax
 INTEGER*4                       kmax
C Syntax:
#include TECIO.h
INTEGER4 TECIJKPTN(INTEGER4 *partition,
                   INTEGER4 *imin,
                   INTEGER4 *jmin,
                   INTEGER4 *kmin,
                   INTEGER4 *imax,
                   INTEGER4 *jmax,
                   INTEGER4 *kmax);
Return Value

0 if successful, nonzero if unsuccessful.

Parameters

Parameter Description

partition

The number of the current partition. Partitions are numbered from 1 to the number of partitions (as specified in the TECZNEMAP142 call inclusive).

imin

The smallest I index in the partition.

jmin

The smallest J index in the partition.

kmin

The smallest K index in the partition.

imax

The largest I index in the partition.

jmax

The largest J index in the partition.

kmax

The largest K index in the partition.

TECINI142

Initializes the process of writing a binary data file. This function must be called first before any other TecIO calls are made (except TECFOREIGN142).

You may write to multiple files by calling TECINI142 more than once. Each time TECINI142 is called, a new file is created and a new context established for it. Use TECFIL142 to switch between files. For each call to TECINI142, there must be a corresponding call to TECEND142.

If using TecIO-MPI, the TECINI142 call must be followed immediately by a call to TECMPIINIT142.

FORTRAN Syntax:
 INTEGER*4 FUNCTION TECINI142(Title,
&                             Variables,
&                             FName,
&                             ScratchDir,
&                             FileFormat,
&                             FileType,
&                             Debug,
&                             VIsDouble)
 CHARACTER*(*)                Title
 CHARACTER*(*)                Variables
 CHARACTER*(*)                ScratchDir
 CHARACTER*(*)                FName
 INTEGER*4                    FileFormat
 INTEGER*4                    FileType
 INTEGER*4                    Debug
 INTEGER*4                    VIsDouble
C Syntax:
#include TECIO.h
INTEGER4 TECINI142(char  *Title,
                   char  *Variables,
                   char  *FName,
                   char *ScratchDir,
                   INTEGER4 *FileFormat,
                   INTEGER4 *FileType,
                   INTEGER4 *Debug
                   INTEGER4 *VIsDouble);
Return Value

0 if successful, -1 if unsuccessful.

Parameters

Parameter Description

Title

Title of the data set. Must be null terminated.

Variables

List of variable names. If a comma appears in the string it will be used as the separator between variable names, otherwise a space is used. Must be null terminated.

FName

Name of the file to create. Must be null terminated.

ScratchDir

Name of the directory to put the scratch file. Must be null terminated.

FileFormat

Specifies the file format to be used. Ignored by TecIO-MPI, which always writes .szplt files.

0=Tecplot binary (.plt)

1=Tecplot subzone (.szplt)

FileType

Specify whether the file is a full data file (containing both grid and solution data), a grid file or a solution file.

0=Full

1=Grid

2=Solution

Debug

Pointer to the integer flag for debugging. Set to 0 for no debugging or 1 to debug. When set to 1, the debug messages will be sent to the standard output (stdout).

VIsDouble

Pointer to the integer flag for specifying whether field data generated in future calls to TECDAT142 are to be written in single or double precision.

0=Single

1=Double

Examples

Each example in Examples calls TECINI142 at least once. Refer to this section for details.

TECLAB142

Adds custom labels to the data file. Custom Labels can be used for axis labels, legend text, and tick mark labels. The first custom label string corresponds to a value of one on the axis, the next to a value of two, the next to a value of three, and so forth. You must have at least one zone in your data set.

A custom label set is added to your file each time you call TECLAB142. You may have up to sixty labels in a set and up to ten sets in a file. Each label must be surrounded by double-quotes, e.g. "Mon" "Tues" "Wed", etc. The \n escape sequence may be used to indicate a line break.

Custom labels are assigned to an object via the Tecplot interface. Refer to User’s Manual for details.

When using TecIO-MPI, may only be called from the main process.

FORTRAN Syntax:
 INTEGER*4 FUNCTION TECLAB142(Labels)
 CHARACTER*(*)                Labels
C Syntax:
#include TECIO.h
INTEGER4 TECLAB142(char *Labels);
Return Value

0 if successful, -1 if unsuccessful.

Parameters

Parameter Description

Labels

Character string of custom labels. Each label must be surrounded by double-quotes. Separate labels by a comma or space. You may have up to sixty labels in each call to TECLAB142.

Examples

To add the days of the week to your data file, to be displayed along the x-axis:

char Labels[60] = "\"Mon\", \"Tues\",\"Wed\",\"Thurs\", \"Fri\"";
TECLAB142(&Labels[0]);

TECMPIINIT142

Initializes MPI and joins a specified MPI communicator. This is a collective function. Must be called immediately after TECINI142 by all processes in the supplied communicator, and will block until all processes have called it. If processes call TECINI142 multiple times to create multiple files, TECMPIINIT142 must be called immediately after each call to TECINI142. All processes may then switch output among the open files by calling TECFIL142 as usual.

The mainrank process is the only process that may output non-zone data, such as text, geometries and aux data.

For TecIO-MPI only; does not exist in standard TecIO library.

FORTRAN Syntax:
 INTEGER*4 FUNCTION TECMPIINIT142(communicator, mainrank)
 INTEGER*4 communicator
 INTEGER*4 mainrank
C Syntax:
#include TECIO.h
INTEGER4 TECMPIINIT142(void* communicator,
                       INTEGER4 const* mainrank);
Return Value

0 if successful, nonzero if error.

Parameters

Parameter Description

communicator

Pointer to MPI communicator. May be MPI_COMM_WORLD or any other MPI_Comm that includes all MPI processes involved in output.

mainrank

The ID of the process (rank) within the communicator designated as the main process. Must be the same for all calling processes.

TECNOD142

Writes an array of node data to the binary data file. This is the connectivity list for cell-based finite element zones (line segment, triangle, quadrilateral, brick, and tetrahedral zones). The connectivity list for face-based finite element zones (polygonal and polyhedral) is specified via TECPOLYFACE142.

Remember that Tecplot Focus cannot load face-based (polygonal or polyhedral) data.

Note that node data are not stored in solution files, so do not call TECNOD142 if the file type specified in TECINI142 was SOLUTION.

See also TECNODE142, which allows you to provide connectivity information in arbitrarily-sized chunks rather than requiring it all at once.

FORTRAN Syntax:
 INTEGER*4 FUNCTION TECNOD142(NData)
 INTEGER*4 NData (T, M)
C Syntax:
#include TECIO.h
INTEGER4 TECNOD142(INTEGER4 *NData);
Return Value

0 if successful, -1 if unsuccessful.

Parameters

Parameter Description

NData

Array of integers listing the nodes for each element. This is the connectivity list, dimensioned (T, M) (T moving fastest), where M is the number of elements in the zone and T is set according to the following list:

2=Line Segment
3=Triangle
4=Quadrilateral

4=Tetrahedral
8=Brick

Examples:

Refer to Face Neighbors for examples using TECNOD142.

TECNODE142

Writes a chunk of node data to the binary data file. This is the connectivity list for cell-based finite element zones (line segment, triangle, quadrilateral, brick, and tetrahedral zones). The connectivity list for face-based finite element zones (polygonal and polyhedral) is specified via TECPOLYFACE142.

Remember that Tecplot Focus cannot load face-based (polygonal or polyhedral) data.

Note that node data are not stored in solution files, so do not call TECNODE142 if the file type specified in TECINI142 was SOLUTION.

This function is similar to TECNOD142 but does not require that the entire connectivity list be provided at once. Rather, you may call TECNODE142 as many times as you like, providing connectivity information for as many elements as you like each time, so long as you eventually provide connectivity information for all elements in the zone.

FORTRAN Syntax:
 INTEGER*4 FUNCTION TECNODE142(N, NData)
 INTEGER*4 N
 INTEGER*4 NData (T, M)
C Syntax:
#include TECIO.h
INTEGER4 TECNODE142(INTEGER4 *N,
                    INTEGER4 *NData);
Return Value

0 if successful, -1 if unsuccessful.

Parameters

Parameter Description

N

Pointer to an integer indicating the number of values to write.

NData

Array of integers listing the nodes for each element. This is the connectivity list, dimensioned (T, N) (T moving fastest), where N is the number of elements provided in this call to TECNODE142 and T is set according to the following list:

2=Line Segment
3=Triangle
4=Quadrilateral

4=Tetrahedral
8=Brick

TECPOLYFACE142

Writes the face nodes of the face map for polygonal and polyhedral zones. All numbering schemes are one-based. The first node is Node 1, the first Face is Face 1, and so forth. Refer to Defining Polyhedral and Polygonal Data for additional information.

Remember that Tecplot Focus cannot load face-based (polygonal or polyhedral) data.

This function may be called any number of times, with any number of face nodes each time, so long as face nodes for all faces are eventually written. You must also, at some point, call TECPOLYBCONN142 to specify any boundary connections in the zone; this can be done in any order, even to the point of interleaving calls to specify boundary connections and face nodes.

Note that face data are not stored in solution files, so do not call TECPOLYFACE142 if the file type specified in TECINI142 was SOLUTION.

Avoid creating concave objects (or bad meshes), as they will not look good when plotted.

FORTRAN Syntax:
 INTEGER*4 FUNCTION TECPOLYFACE142(
&                                  NumFaces,
&                                  FaceNodeCounts,
&                                  FaceNodes,
&                                  FaceLeftElems,
&                                  FaceRightElems)
 INTEGER*4                         NumFaces(*)
 INTEGER*4                         FaceNodeCounts(*)
 INTEGER*4                         FaceNodes(*)
 INTEGER*4                         FaceLeftElems(*)
 INTEGER*4                         FaceRightElems(*)
C Syntax:
#include TECIO.h
INTEGER4
TECPOLYFACE142(INTEGER4 *NumFaces,
               INTEGER4 *FaceNodeCounts,
               INTEGER4 *FaceNodes,
               INTEGER4 *FaceLeftElems,
               INTEGER4 *FaceRightElems);
Return Value

0 if successful; -1 if unsuccessful.

Parameters

Parameter Description

NumFaces

The number of faces being defined in this call. TECPOLYFACE142 may be called any number of times with any number of faces in each call, so long as all faces in the zone are eventually defined.

FaceNodeCounts

An array used to define the number of nodes in each face. The array is dimensioned by NumFaces. This is NULL for polygonal zones, as each face in a polygonal zone is already known to have exactly two nodes.

FaceNodes

An array used to specify the nodes belonging to each face. The array is dimensioned by the sum of the FaceNodeCounts array for polyhedral zones or, for polygonal zones, twice NumFaces.

FaceLeftElems

An array used to define the left neighboring element for each face. The array is dimensioned by NumFaces.

FaceRightElems

An array used to define the right neighboring element for each face. The array is dimensioned by NumFaces.

Examples

Refer to the following sections for examples using TECPOLYFACE142:

TECPOLYBCONN142

Writes the boundary connections of the face map for polygonal and polyhedral zones. Boundary faces are faces that either have more than one neighboring cell on a side or have at least one neighboring cell in another zone. (Refer to Boundary Faces and Boundary Connections for a simple example.)

Remember that Tecplot Focus cannot load face-based (polygonal or polyhedral) data.

All numbering schemes are one-based. The first node is Node 1, the first face is Face 1, and so forth. Refer to Defining Polyhedral and Polygonal Data for additional information.

This function may be called any number of times, with any number of boundary connections each time, so long as boundary connections for all faces are eventually written. You must also, at some point, call TECPOLYFACE142 at least once to specify the face nodes. This can be done in any order, even to the point of interleaving calls to specify boundary connections and face nodes.

Note that connection data are not stored in solution files, so do not call TECPOLYBCONN142 if the file type specified in TECINI142 was SOLUTION.

Avoid creating concave objects (or bad meshes), as they will not look good when plotted.

FORTRAN Syntax:
 INTEGER*4 FUNCTION TECPOLYBCONN142(
&                                   NumBndryFaces,
&                                   FaceBndryConnectionCounts,
&                                   FaceBndryConnectionElems,
&                                   FaceBndryConnectionZones)
 INTEGER*4                          NumBndryFaces(*)
 INTEGER*4                          FaceBndryConnectionCounts(*)
 INTEGER*4                          FaceBndryConnectionElems(*)
 INTEGER*2                          FaceBndryConnectionZones(*)
C Syntax:
#include TECIO.h
INTEGER4 TECPOLYBCONN142(INTEGER4 *NumBndryFaces,
                         INTEGER4 *FaceBndryConnectionCounts,
                         INTEGER4 *FaceBndryConnectionElems,
                         INTEGER4 *FaceBndryConnectionZones);
Return Value

0 if successful, -1 if unsuccessful.

Parameters

Parameter Description

NumBndryFaces

The number of boundary faces being defined in this call. Each call to TECPOLYBCONN142 may define any number of boundary faces, so long as all boundary faces (i.e., NumConnectedBoundaryFaces in TECZNE142 or TECPOLYZNE142) are eventually defined.

FaceBndryConnectionCounts

An array used to define the number of boundary connections for each boundary face. The array is dimensioned by NumBndryFaces.

FaceBndryConnectionElems

An array used to define the boundary element(s) to which each boundary face is connected.

FaceBndryConnectionZones

An array used to define the zone(s) to which each boundary element belongs.

Examples

Refer to the following sections for examples using TECPOLYBCONN142:

TECPOLYZNE142

This function is provided as an alternative to calling TECZNE142 for face-based finite-element zones (FEPOLYGON or FEPOLYHEDRON). You are encouraged to use this function instead of TECZNE142or such zone. This function contains only parameters relevant to face-based zones and also supports zones with number of faces or number of face nodes exceeding 32-bit limitations (beyond about two billion). TECPOLYZNE142 writes header information about the next face-based zone to be added to the data file. This function is not currently available in TecIO-MPI, because face-based zones are not currently supported by the .szplt file format. After TECPOLYZNE142 is called, you must call TECDAT142 one or more times, then call TECPOLYFACE142 one or more times, and call TECPOLYBCONN142 one or more times if NumConnectedBoundaryFaces is non-zero..

Remember that Tecplot Focus cannot load face-based (polygonal or polyhedral) data.
FORTRAN Syntax:
 INTEGER*4 FUNCTION TECPOLYZNE142(ZoneTitle,
&                                 ZoneType,
&                                 NumNodes,
&                                 NumCells,
&                                 NumFaces,
&                                 TotalNumFaceNodes,
&                                 SolutionTime,
&                                 StrandID,
&                                 ParentZone,
&                                 NumConnectedBoundaryFaces,
&                                 TotalNumBoundaryConnections,
&                                 PassiveVarList,
&                                 ValueLocation,
&                                 ShareVarFromZone,
&                                 ShareConnectivityFromZone)
 CHARACTER*(*)                    ZoneTitle
 INTEGER*4                        ZoneType
 INTEGER*4                        NumNodes
 INTEGER*4                        NumCells
 INTEGER*8                        NumFaces
 INTEGER*8                        TotalNumFaceNodes
 DOUBLE PRECISION                 SolutionTime
 INTEGER*4                        StrandID
 INTEGER*4                        ParentZone
 INTEGER*4                        NumConnectedBoundaryFaces
 INTEGER*4                        TotalNumBoundaryConnections
 INTEGER*4                        PassiveVarList(*)
 INTEGER*4                        ValueLocation(*)
 INTEGER*4                        ShareVarFromZone(*)
 INTEGER*4                        ShareConnectivityFromZone
C Syntax:
#include TECIO.h
INTEGER4 TECPOLYZNE142(char  *ZoneTitle,
                       INTEGER4 *ZoneType,
                       INTEGER4 *NumNodes,
                       INTEGER4 *NumCells,
                       INTEGER8 *NumFaces,
                       INTEGER8 *TotalNumFaceNodes,
                       double  *SolutionTime,
                       INTEGER4 *StrandID,
                       INTEGER4 *ParentZone,
                       INTEGER4 *NumConnectedBoundaryFaces,
                       INTEGER4 *TotalNumBoundaryConnections,
                       INTEGER4 *PassiveVarList,
                       INTEGER4 *ValueLocation,
                       INTEGER4 *ShareVarFromZone,
                       INTEGER4 *ShareConnectivityFromZone)
Return Value

0 if successful; -1 if unsuccessful.

Parameters

Parameter Notes

ZoneTitle

The title of the zone. Must be null-terminated.

ZoneType

The type of the zone:

6=FEPOLYGON

7=FEPOLYHEDRON

NumNodes

The number of nodes.

NumCells

The number of elements.

NumFaces

The number of faces.

SolutionTime

Scalar double precision value specifying the time associated with the zone. Refer to User’s Manual for additional information on working with transient data.

StrandID

Scalar integer value specifying the strand to which the zone is associated.

0 = static zone, not associated with a strand.
Values greater than 0 indicate a zone is assigned to a given strand.

Refer to User’s Manual for additional information on strands.

If you are converting your function calls from function calls 109 or older, use "0" for StrandID.

ParentZone

ParentZone is no longer used. Enter 0 for this value.

TotalNumFaceNodes

Total number of nodes for all faces. It is also the sum of the FaceNodeCounts array (defined in TECPOLYFACE142). For polygonal zones this value is equivalent to 2 * NumFaces. NumFaces = the number of faces in the zone. Refer to FaceNodeCounts and FaceNodes for simple example.

NumConnectedBoundaryFaces

Total number of boundary faces, where boundary faces are faces that either have more than one neighboring cell on a side or have a neighboring cell from another zone. Refer to Boundary Faces and Boundary Connections for simple example.

TotalNumBoundaryConnections

Total number of boundary connections for all faces. In general, TotalNumBoundaryConnections will be equal to NumConnectedBoundaryFaces. However, TotalNumBoundaryConnections must be greater than or equal to NumConnectedBoundaryFaces. Refer to Boundary Faces and Boundary Connections for simple example.

PassiveVarList

Array, dimensioned by the number of variables, of 4 byte integer values specifying the active/passive nature of each variable. A value of 0 indicates the associated variable is active while a value of 1 indicates that it is passive. If all variables are active, you may pass NULL rather than an array of zeroes. Refer to [introduction/best-practices/passive-variables] for additional information.

ValueLocation

The location of each variable in the data set. ValueLocation(I) indicates the location of variable I for this zone. 0=cell-centered, 1=node-centered. Pass null to indicate that all variables are node-centered.

ShareVarFromZone

Indicates variable sharing. Array, dimensioned by the number of variables. ShareVarFromZone(I) indicates the zone number with which variable I will be shared. This reduces the amount of data to be passed via TECDAT142. A value of 0 indicates that the variable is not shared. Pass null to indicate no variable sharing for this zone. You must pass null for the first zone in a data set (there is no data available to share).

ShareConnectivityFromZone

Indicates the zone number with which connectivity is shared. Pass 0 to indicate no connectivity sharing. You must pass 0 for the first zone in a data set. NOTE: Connectivity cannot be shared between cell-based and face-based finite element zones.

Examples

Refer to the following sections for examples using TECPOLYZNE142:

TECTXT142

Adds a text box to the file. When using TecIO-MPI, may only be called from the main process.

FORTRAN Syntax:
 INTEGER*4 FUNCTION TECTXT142(XOrThetaPos,
&                             YOrRPos,
&                             ZOrUnusedPos,
&                             PosCoordMode,
&                             AttachToZone,
&                             Zone,
&                             Font,
&                             FontHeightUnits,
&                             FontHeight,
&                             BoxType,
&                             BoxMargin,
&                             BoxLineThickness,
&                             BoxColor,
&                             BoxFillColor,
&                             Angle,
&                             Anchor,
&                             LineSpacing,
&                             TextColor,
&                             Scope,
&                             Clipping,
&                             Text,
&                             MFC)
 DOUBLE PRECISION             XOrThetaPos
 DOUBLE PRECISION             YOrRPos
 DOUBLE PRECISION             ZOrUnusedPos
 INTEGER*4                    PosCoordMode
 INTEGER*4                    AttachToZone
 INTEGER*4                    Zone
 INTEGER*4                    Font
 INTEGER*4                    FontHeightUnits
 DOUBLE PRECISION             FontHeight
 INTEGER*4                    BoxType
 DOUBLE PRECISION             BoxMargin
 DOUBLE PRECISION             BoxLineThickness
 INTEGER*4                    BoxColor
 INTEGER*4                    BoxFillColor
 DOUBLE PRECISION             Angle
 INTEGER*4                    Anchor
 DOUBLE PRECISION             LineSpacing
 INTEGER*4                    TextColor
 INTEGER*4                    Scope
 INTEGER*4                    Clipping
 CHARACTER*(*)                Text
 CHARACTER*(*)                MFC
C Syntax:
#include TECIO.h
INTEGER4 TECTXT142(double  *XOrThetaPos,
                   double  *YOrRPos,
                   double  *ZOrUnusedPos,
                   INTEGER4 *PosCoordMode,
                   INTEGER4 *AttachToZone,
                   INTEGER4 *Zone,
                   INTEGER4 *Font,
                   INTEGER4 *FontHeightUnits,
                   double *FontHeight,
                   INTEGER4 *BoxType,
                   double *BoxMargin,
                   double *BoxLineThickness,
                   INTEGER4 *BoxColor,
                   INTEGER4 *BoxFillColor,
                   double *Angle,
                   INTEGER4 *Anchor,
                   double *LineSpacing,
                   INTEGER4 *TextColor,
                   INTEGER4 *Scope,
                   INTEGER4 *Clipping,
                   char *Text,
                   char *MFC)
Return Value

0 if successful, -1 if unsuccessful.

Parameters

Parameter Description

XOrThetaPos

Pointer to double value specifying the X-position or Theta-position (polar plots only) of the text.

YOrRPos

Pointer to double value specifying the Y-position or R-position (polar plots only) of the text.

ZOrUnusedPos

Pointer to double value specifying the Z-position of the text.

PosCoordMode

Pointer to integer value specifying the position coordinate system.

0=Grid

1=Frame

6=Grid3D

If you use Grid3D, the plot type must be set to 3D Cartesian to view your text box.

AttachToZone

Pointer to integer flag to signal that the text is "attached" to a zone.

Zone

Pointer to integer value specifying the zone number to attach to.

Font

Pointer to integer value specifying the font.

0=Helvetica
1=Helvetica Bold
2=Greek
3=Math
4=User-Defined
5=Times

6=Times Italic
7=Times Bold
8=Times Italic Bold
9=Courier
10=Courier Bold

FontHeightUnits

Pointer to integer value specifying the font height units.

0=Grid

1=Frame

2=Point

FontHeight

Pointer to double value specifying the font height. If PosCoordMode is set to FRAME, the value range is zero to 100.

BoxType

Pointer to integer value specifying the box type.

0=None

1=Filled

2=Hollow

BoxMargin

Pointer to double value specifying the box margin (in frame units ranging from 0 to 100).

BoxLineThickness

Pointer to double value specifying the box line thickness (in frame units ranging from 0.0001 to 100).

BoxColor

Pointer to integer value specifying the color to assign to the box.

0=Black
1=Red
2=Green
3=Blue
4=Cyan
5=Yellow
6=Purple
7=White
8=Custom1

9=Custom2
10=Custom3
11=Custom4
12=Custom5
13=Custom6
14=Custom7
15=Custom8

BoxFillColor

Pointer to integer value specifying the fill color to assign to the box. (See BoxColor)

Angle

Pointer to double value specifying the text angle in degrees.

Anchor

Pointer to integer value specifying where to anchor the text.

0=Left
1=Center
2=Right
3=MidLeft
4=MidCenter

5=MidRight
6=HeadLeft
7=HeadCenter
8=HeadRight

LineSpacing

Pointer to double value specifying the text line spacing.

TextColor

Pointer to integer value specifying the color to assign to the text. (See BoxColor)

Scope

Pointer to integer value specifying the scope with respect to frames. A local scope places the object in the active frame. A global scope places the object in all frames that contain the active frame’s data set.

0=Global

1=Local

Clipping

Specifies whether to clip the text (that is, only plot the text within the viewport or the frame).

0=ClipToViewport

1=ClipToFrame.

Text

Character string representing text to display. Must be null terminated.

MFC

Macro function command. Must be null terminated.

Examples

Refer to Text Example for an example of working with TECTXT142.

TECUSR142

Writes a character string to the data file in a USERREC record. USERREC records are ignored by Tecplot 360, but may be used by add-ons.

When using TecIO-MPI, may only be called from the main process.

FORTRAN Syntax:
 INTEGER*4 FUNCTION TECUSR142(S)
 CHARACTER*(*) S
C Syntax:
#include TECIO.h
INTEGER4 TECUSR142(CHAR *S);
Return Value

0 if successful, -1 if unsuccessful.

Parameters

Parameter Description

S

The character string to write to the data file. Must be null-terminated.

TECVAUXSTR142

Writes an auxiliary data item to the data file for the specified variable. Must be called after TECINI142 and before TECEND142. Auxiliary data may be used by text, macros, equations (if the data is numeric) and add-ons. It may be viewed directly in the Aux Data page of the Data Set Information dialog (accessed via the Data menu). The value can be verified by selecting "Variable" from the "Show Auxiliary Data" menu and selecting the corresponding variable number from the menu.

When using TecIO-MPI, may only be called from the main process.

FORTRAN Syntax:
 INTEGER*4 FUNCTION TECVAUXSTR142(Var, Name, Value)
 INTEGER*4          Var
 CHARACTER*(*)      Name
 CHARACTER*(*)      Value
C Syntax:
#include TECIO.h
INTEGER4 TECAUXSTR142(INTEGER4 *Var,
                      char *Name,
                      char *Value);
Return Value

0 if successful, -1 if unsuccessful.

Parameters

Parameter Description

Var

The variable number for which to set the auxiliary data. Variable numbers start at one.

Name

The name of the auxiliary data item. If a data item with this name already exists, its value will be overwritten. Must be a null-terminated character string and cannot contain spaces.

Value

The auxiliary data value to be written to the data file. Must be a null-terminated character string.

Example:

The following example illustrates adding auxiliary data to the pressure variable in the data file. In this case, pressure is the third variable.

INTEGER4 Var                    = 3;
char     PressureUnitsName[16]  = "PressureUnits";
char     PressureUnitsValue[16] = "Pascal (Pa)";

TECVAUXSTR142(&Var,
              &PressureUnitsName[0],
              &PressureUnitsValue[0]);

TECZAUXSTR142

Writes an auxiliary data item for the current zone to the data file. Must be called immediately after TECZNE142 or TECPOLYZNE142 or TECZNEFEMIXED142for the desired zone. Auxiliary data may be used by text, macros, equations (if it is numeric) and add-ons. It may be viewed directly in the Aux Data page of the Data Set Information dialog (accessed via the Data menu). The value can be verified by selecting "Zone" from the "Show Auxiliary Data" menu and selecting the corresponding zone number.

When using TecIO-MPI, may only be called from the main process.

FORTRAN Syntax:
 INTEGER*4 FUNCTION TECZAUXSTR142(Name, Value)
 CHARACTER*(*)      Name
 CHARACTER*(*)      Value
C Syntax:
#include TECIO.h
INTEGER4 TECZAUXSTR142(char *Name,
                       char *Value);
Return Value

0 if successful, -1 if unsuccessful.

Parameters

Parameter Description

Name

The name of the auxiliary data item. If a data item with this name already exists, its value will be overwritten. Must be a null-terminated character string and cannot contain spaces.

Value

The auxiliary data value to be written to the data file. Must be a null-terminated character string.

Example:

The following example code adds auxiliary data to the zone. NOTE: TECZAUXSTR142 must be called immediately after TECZNE142 or TECPOLYZNE142 or TECZNEFEMIXED142for the desired zone.

char  CreatedByName[16]   = "CreatedBy";
char  CreatedByValue[16]  = "My Company";

TECZAUXSTR142(&CreatedByName[0],
              &CreatedByValue[0]);

TECZNE142

Writes header information about the next zone to be added to the data file. For face-based finite-element zones, you are encouraged to use TECPOLYZNE142 instead because that function is specifically designed for those zones and has features that TECZNE142 does not support (specifically support for more than two-billion faces and/or face nodes). For writing mixed-element or higher-order-element zones, you must instead call TECZNEFEMIXED142. When using TecIO-MPI, TECZNE142 should be immediately followed by a call to TECZNEMAP142.

After TECZNE142 (and TECZNEMAP142, if necessary) is called, you must call TECDAT142 one or more times. If the zone is a finite element zone, call TECNOD142/ TECNODE142 (cell-based zones) or TECPOLYFACE142/TECPOLYBCONN142 (face-based zones) after calling TECDAT142.

Remember that Tecplot Focus cannot load face-based (polygonal or polyhedral) data.
FORTRAN Syntax:
 INTEGER*4 FUNCTION TECZNE142(ZoneTitle,
&                             ZoneType,
&                             IMxOrNumPts,
&                             JMxOrNumElements,
&                             KMxOrNumFaces,
&                             ICellMax,
&                             JCellMax,
&                             KCellMax,
&                             SolutionTime,
&                             StrandID,
&                             ParentZone,
&                             IsBlock,
&                             NumFaceConnections,
&                             FaceNeighborMode,
&                             TotalNumFaceNodes,
&                             NumConnectedBoundaryFaces,
&                             TotalNumBoundaryConnections,
&                             PassiveVarList,
&                             ValueLocation,
&                             ShareVarFromZone,
&                             ShareConnectivityFromZone)
 CHARACTER*(*)                ZoneTitle
 INTEGER*4                    ZoneType
 INTEGER*4                    IMxOrNumPts
 INTEGER*4                    JMxOrNumElements
 INTEGER*4                    KMxOrNumFaces
 INTEGER*4                    ICellMax
 INTEGER*4                    JCellMax
 INTEGER*4                    KCellMax
 DOUBLE PRECISION             Solution Time
 INTEGER*4                    StrandID
 INTEGER*4                    ParentZone
 INTEGER*4                    IsBlock
 INTEGER*4                    NumFaceConnections
 INTEGER*4                    FaceNeighborMode
 INTEGER*4                    TotalNumFaceNodes,
 INTEGER*4                    NumConnectedBoundaryFaces
 INTEGER*4                    TotalNumBoundaryConnections
 INTEGER*4                    PassiveVarList(*)
 INTEGER*4                    ValueLocation(*)
 INTEGER*4                    ShareVarFromZone(*)
 INTEGER*4                    ShareConnectivityFromZone
C Syntax:
#include TECIO.h
##INTEGER4  TECZNE142(char  *ZoneTitle,
                      INTEGER4 *ZoneType,
                      INTEGER4 *IMxOrNumPts,
                      INTEGER4 *JMxOrNumElements,
                      INTEGER4 *KMxOrNumFaces,
                      INTEGER4 *ICellMax,
                      INTEGER4 *JCellMax,
                      INTEGER4 *KCellMax,
                      double  *SolutionTime,
                      INTEGER4 *StrandID,
                      INTEGER4 *ParentZone,
                      INTEGER4 *IsBlock,
                      INTEGER4 *NumFaceConnections,
                      INTEGER4 *FaceNeighborMode,
                      INTEGER4 *TotalNumFaceNodes,
                      INTEGER4 *NumConnectedBoundaryFaces,
                      INTEGER4 *TotalNumBoundaryConnections,
                      INTEGER4 *PassiveVarList,
                      INTEGER4 *ValueLocation,
                      INTEGER4 *ShareVarFromZone,
                      INTEGER4 *ShareConnectivityFromZone)
Return Value

0 if successful, -1 if unsuccessful.

Parameters

Parameter Applies to Zone Type(s) Notes

ZoneTitle

ALL

The title of the zone. Must be null-terminated.

ZoneType

ALL

The type of the zone:

0=ORDERED 1=FELINESEG 2=FETRIANGLE 3=FEQUADRILATERAL

4=FETETRAHEDRON 5=FEBRICK 6=FEPOLYGON 7=FEPOLYHEDRON

IMax or NumPts

ALL

For ordered zones, the number of nodes in the I-index direction. For finite element zones (cell-based and face-based), the number of nodes.

JMax or NumElements

ALL

For ordered zones, the number of nodes in the J index direction. For finite element zones (cell-based and face-based), the number of elements.

KMax or NumFaces

ORDERED
FEPOLYGON
FEPOLYHEDRON

For ordered zones, the number of nodes in the K index direction. For polyhedral and polygonal finite element zones, the number of faces. Not used for all other finite element zone types.

ICellMax

N/A

Reserved for future use. Set to zero.

JCellMax

N/A

Reserved for future use. Set to zero.

KCellMax

N/A

Reserved for future use. Set to zero.

SolutionTime

ALL

Scalar double precision value specifying the time associated with the zone. Refer to User’s Manual for additional information on working with transient data.

StrandID

ALL

Scalar integer value specifying the strand to which the zone is associated.

0 = static zone, not associated with a strand.
Values greater than 0 indicate a zone is assigned to a given strand.

Refer to User’s Manual for additional information on strands.

If you are converting your function calls from function calls 109 or older, use "0" for StrandID.

ParentZone

ALL

ParentZone is no longer used. Enter 0 for this value.

IsBlock

ALL

Deprecated field. Always set to 1.

NumFaceConnections

ORDERED
FELINESEG
FETRIANGLE
FEQUADRILATERAL
FETETRAHEDRON
FEBRICK

Used for cell-based finite element and ordered zones only. The number of face connections that will be passed in routine TECFACE142.

FaceNeighborMode

Used for cell-based1 finite element and ordered zones only. The type of face connections that will be passed in routine TECFACE142.

0=LocalOneToOne
1=LocalOneToMany
2=GlobalOneToOne
3=GlobalOneToMany

TotalNumFaceNodes

FEPOLYGON
FEPOLYHEDRON

Used for face-based2 finite element zones Total number of nodes for all faces. It is also the sum of the FaceNodeCounts array (defined in TECPOLYFACE142). For polygonal zones this value is equivalent to 2 * NumFaces. NumFaces = the number of faces in the zone. Refer to FaceNodeCounts and FaceNodes for simple example.

NumConnectedBoundaryFaces

FEPOLYGON
FEPOLYHEDRON

Used for face-based2 finite element zones. Total number of boundary faces, where boundary faces are faces that either have more than one neighboring cell on a side or have a neighboring cell from another zone. Refer to Boundary Faces and Boundary Connections for simple example.

TotalNumBoundaryConnections

FEPOLYGON
FEPOLYHEDRON

Used for face-based2 finite element zones. Total number of boundary connections for all faces. In general, TotalNumBoundaryConnections will be equal to NumConnectedBoundaryFaces However, TotalNumBoundaryConnections must be greater than or equal to equal to NumConnectedBoundaryFaces. Refer to Boundary Faces and Boundary Connections for simple example.

PassiveVarList

ALL

Array, dimensioned by the number of variables, of 4 byte integer values specifying the active/passive nature of each variable. A value of 0 indicates the associated variable is active while a value of 1 indicates that it is passive. If all variables are active, you may pass NULL rather than an array of zeroes. Refer to [introduction/best-practices/passive-variables] for additional information.

ValueLocation

ALL

The location of each variable in the data set. ValueLocation(I) indicates the location of variable I for this zone. 0=cell-centered, 1=node-centered. Pass null to indicate that all variables are node-centered.

ShareVarFromZone

ALL

Indicates variable sharing. Array, dimensioned by the number of variables. ShareVarFromZone(I) indicates the zone number with which variable I will be shared. This reduces the amount of data to be passed via TECDAT142. A value of 0 indicates that the variable is not shared. Pass null to indicate no variable sharing for this zone. You must pass null for the first zone in a data set (there is no data available to share).

ShareConnectivityFromZone

ALL

Indicates the zone number with which connectivity is shared. Pass 0 to indicate no connectivity sharing. You must pass 0 for the first zone in a data set.
NOTE: Connectivity and/or face neighbors cannot be shared when the face neighbor mode is set to Global. Connectivity cannot be shared between cell-based and face-based finite element zones.

1 Cell-based finite element zones: FELINESEG, FETRIANGLE, FEQUADRILATERAL, FETETRAHEDRON, and FEBRICK.
2 Face-based finite element zones: FEPOLYGON and FEPOLYHEDRON. For these consider using TECPOLYZNE142 instead.

Examples:

Refer to the following examples for illustrations of working with TECZNE142:

TECZNEFEMIXED142

Writes header information about the next zone to be added to the data file. TECZNEFEMIXED142 specifies that the next zone is a finite element zone with one or more linear or high order sections. A mixed element zone can have between 1 and 16 sections. All cells within a section have a the same cell type, grid order, and basis function. The cell types of all sections within a zone must have the same spatial dimensionality, or in other words, all sections of a zone must either be all line, surface, or volume cell types. When using TecIO-MPI, TECZNEFEMIXED142 should be immediately followed by a call to TECZNEMAP142. After TECZNEFEMIXED142 and TECZNEMAP142 are called, you must call TECDAT142 one or more times and then TECNOD142 (after calling TECDAT142).

FORTRAN Syntax:
 INTEGER*4 FUNCTION TECZNEFEMIXED142(ZoneTitle,
&                                    NumNodes,
&                                    NumSections,
&                                    CellShapePerSection,
&                                    GridOrderPerSection,
&                                    BasisFnPerSection,
&                                    NumElementsPerSection,
&                                    SolutionTime,
&                                    StrandID,
&                                    NumFaceConnections,
&                                    FaceNeighborMode,
&                                    PassiveVarList,
&                                    ValueLocation,
&                                    ShareVarFromZone,
&                                    ShareConnectivityFromZone)
 CHARACTER*(*)                       ZoneTitle
 INTEGER*8                           NumNodes
 INTEGER*4                           NumSections
 INTEGER*4                           CellShapePerSection
 INTEGER*4                           GridOrderPerSection
 INTEGER*4                           BasisFnPerSection
 INTEGER*8                           NumElementsPerSection
 DOUBLE PRECISION                    SolutionTime
 INTEGER*4                           StrandID
 INTEGER*4                           NumFaceConnections
 INTEGER*4                           FaceNeighborMode
 INTEGER*4                           PassiveVarList
 INTEGER*4                           ValueLocation
 INTEGER*4                           ShareVarFromZone
 INTEGER*4                           ShareConnectivityFromZone
C Syntax:
#include "TECIO.h"
INTEGER4 TECZNEFEMIXED142(char const*  ZoneTitle,
                          INTEGER8 const* NumNodes,
                          INTEGER4 const* NumSections,
                          INTEGER4 const* CellShapePerSection,
                          INTEGER4 const* GridOrderPerSection,
                          INTEGER4 const* BasisFnPerSection,
                          INTEGER8 const* NumElementsPerSection,
                          double  const* SolutionTime,
                          INTEGER4 const* StrandID,
                          INTEGER4 const* NumFaceConnections,
                          INTEGER4 const* FaceNeighborMode,
                          INTEGER4 const* PassiveVarList,
                          INTEGER4 const* ValueLocation,
                          INTEGER4 const* ShareVarFromZone,
                          INTEGER4 const* ShareConnectivityFromZone)
Return Value

0 if successful, -1 if unsuccessful.

Parameters

Parameter Description

ZoneTitle

The title of the zone. Must be null-terminated.

NumNodes

Total number of nodes for the zone.

NumSections

Number of FE mixed element sections for the zone. Must be between 1 and 16, inclusive.

CellShapePerSection

Array containing the cell shape for each section. Must be between 0 and 6, inclusive.

0=FECellShape_Bar
1=FECellShape_Triangle
2=FECellShape_Quadrilateral
3=FECellShape_Tetrahedron

4=FECellShape_Hexahedron
5=FECellShape_Pyramid
6=FECellShape_Prism

GridOrderPerSection

Array containing the grid order for each section. Grid orders must be between 1 and 4, inclusive.

BasisFnPerSection

Array containing the basis function for each section. Must be 0 for each section.

SolutionTime

Scalar double precision value specifying the time associated with the zone. Refer to User’s Manual for additional information on working with transient data.

StrandID

Scalar integer value specifying the strand to which the zone is associated.

0 = static zone, not associated with a strand.
Values greater than 0 indicate a zone is assigned to a given strand.

Refer to User’s Manual for additional information on strands.

If you are converting your function calls from function calls 109 or older, use "0" for StrandID.

NumFaceConnections

The number of face connections that will be passed in routine TECFACE142.

FaceNeighborMode

The type of face connections that will be passed in routine TECFACE142.

0=LocalOneToOne
1=LocalOneToMany

2=GlobalOneToOne
3=GlobalOneToMany

PassiveVarList

Array, dimensioned by the number of variables, of 4 byte integer values specifying the active/passive nature of each variable. A value of 0 indicates the associated variable is active while a value of 1 indicates that it is passive. If all variables are active, you may pass NULL rather than an array of zeroes. Refer to [introduction/best-practices/passive-variables] for additional information.

ValueLocation

The location of each variable in the data set. ValueLocation(I) indicates the location of variable I for this zone. 0=cell-centered, 1=node-centered. Pass null to indicate that all variables are node-centered.

ShareVarFromZone

Indicates variable sharing. Array, dimensioned by the number of variables. ShareVarFromZone(I) indicates the zone number with which variable I will be shared. This reduces the amount of data to be passed via TECDAT142. A value of 0 indicates that the variable is not shared. Pass null to indicate no variable sharing for this zone. You must pass null for the first zone in a data set (there is no data available to share).

ShareConnectivityFromZone

Indicates the zone number with which connectivity is shared. Pass 0 to indicate no connectivity sharing. You must pass 0 for the first zone in a data set. NOTE: Connectivity and/or face neighbors cannot be shared when the face neighbor mode is set to Global. Connectivity cannot be shared between cell-based and face-based finite element zones.

TECZNEMAP142

When using TecIO-MPI, must be called immediately after calling TECZNE142, or TECZNEFEMIXED142 and must be called by the main process and by each process that will write a zone to indicate which processes will output each partition of the zone. A zone may be written in non-partitioned fashion (that is, as in the standard TecIO library) by indicating that a single process will output it (npartitions of 1, and a one-element ptnranks array). When outputting a partitioned zone, each rank outputting this zone should then call TECFEPTN142 or TECIJKPTN142 followed by data output calls for each partition it will output.

FORTRAN Syntax:
 INTEGER*4 FUNCTION TECZNEMAP142(npartitions, ptnranks)
 INTEGER*4          npartitions
 INTEGER*4          ptnranks
C Syntax:
#include TECIO.h
INTEGER4 TECZNEMAP142(INTEGER4 *npartitions,
                      INTEGER4 *ptnranks);
Return Value

0 if successful, nonzero if unsuccessful.

Parameters

Parameter Description

npartitions

The number of partitions for this zone (1 for a non-partitioned zone).

ptnranks

An array of MPI ranks (processes) that indicates the process that will output that partition. The array may include the main process. For non-partitioned zones, contains a single entry.

Defining Polyhedral and Polygonal Data

Polyhedral data is defined using TECPOLYZNE142 (or TECZNE142), TECPOLYFACE142, and TECPOLYBCONN142. Via TECPOLYZNE142 the number of nodes, faces, elements, boundary faces, and boundary connections are specified. TECPOLYFACE142 is used to specify the face mapping. If the zone is connected to neighboring zones, TECPOLYBCONN142 is then used to specify those connections.

Remember that Tecplot Focus cannot load face-based (polygonal or polyhedral) data.

Before defining your polyhedral or polygonal data, you should determine the numbering scheme for the nodes, faces and elements in each zone of your data set. The numbering scheme is communicated to Tecplot implicitly by the order in which you supply the data. For example, the first nodal value supplied is for Node 1, followed by the value for Node 2, continuing to node N (where N is the total number of nodes). Similarly, for faces and elements.

The remainder of this section provides simple examples illustrating how to define polygonal and polyhedral data.

Boundary Faces and Boundary Connections

A "Connected Boundary Face" is a face with at least one neighboring element that belongs to another zone. Each "Connected Boundary Face" has one or more "Boundary Connections". A "Boundary Connection" is defined as the element-zone tuple used to identify the neighboring element when the element is part of another zone.

Consider the following picture:

SimpleExample.png

In the figure shown above, Zone 1 contains a single element (e1) and Zone 2 contains two elements (e1 and e2). The boundary faces and boundary connections for each zone are as follows:

Zone 1

In Zone 1, Face 1 (f1) is the sole connected boundary face. It has two boundary connections. The first boundary connection is Element 1 in Zone 2. The second boundary connection is Element 2 in Zone 2.

  • NumConnectedBoundaryFaces = 1

  • TotalNumBndryConnections = 2

Zone 2

In Zone 2, both Face 1 and Face 2 are connected boundary faces. There is a total of two boundary connections. The boundary connection for each boundary face in Zone 2 is Element 1 in Zone 1.

  • NumConnectedBoundaryFaces = 2

  • TotalNumBndryConnections = 2

FaceNodeCounts and FaceNodes

For illustration purposes, consider a zone composed of a single pyramidal element. The pyramid is composed of five nodes and five faces.

Pyramid.png
Figure 11. A simple pyramid. The remaining triangular faces are Faces 2 and 3. The bottom rectangular face is Face 5. Node 4 is obscured from view.

The FaceNodeCounts array is used to specify the number of nodes that compose each face. The values in the array are arranged as follows:

FaceNodeCounts = [NumNodesInFace1,
                  NumNodesInFace2,
                  ...
                  NumNodesInFaceF]

where F is the total number of faces in the zone.

In this example, the FaceNodeCounts array is: [3 3 3 3 4]. The first four faces are composed of three nodes and the last face is composed of four nodes.

The FaceNodes array is used to specify which nodes belong to which face. The array is dimensioned by the total number of face nodes in the zone (specified via TECPOLYZNE142. The total number of face nodes is defined as the sum of the number of nodes in each face.

The first K values in the FaceNodes array are the node numbers for Face 1, where K is the first value in the FaceNodeCounts array. The next L values are the node numbers for Face 2, where L is the second value in the FaceNodeCounts array.

When supplying the node numbers for each face, you must supply the numbers in either a clockwise or counter-clockwise configuration around the face. Otherwise, the faces will be contorted when the data is plotted.

It is not important to be consistent when choosing between clockwise or counter-clockwise ordering. The key is to present the numbers consistently within the numbering scheme. For example, you may present the node numbers for face 1 in a clockwise order and the node numbers for the remaining faces in counter-clockwise order.

Consider the pyramid used above. Using the FaceNodeCounts array we have already defined and the figure, we can create the FaceNodes array for the pyramid.

FaceNodes = [1, 2, 3
             3, 2, 4,
             5, 2, 4,
             5, 1, 2,
             1, 5, 4, 3]

FaceRightElems and FaceLeftElems

After specifying the face map data (using the FaceNodeCounts and FaceNodes array), the next step is to identify the element on either side of each face. To illustrate this, we will switch from the single element zone to the following data set:

MultiPolygonalCells.jpg

The neighboring elements can be determined using the right-hand rule:

2D Data

For each face, place your right-hand along the face with your fingers pointing in the direction of incrementing node numbers (i.e. from Node 1 to Node 2). The right side of your hand will indicate the right element, and the left side of your hand will indicate the left element.

3D Data

For each face, curl the fingers of your right-hand following the order that the nodes were presented in the FaceNodes array. Your thumb will point to the right element. The left element is the other adjacent element. If the face has more than one neighboring element on a single side, you will need to use the FaceBoundaryConnectionCounts, FaceBoundaryConnectionElems and FaceBoundaryConnectionZones array.

The neighboring elements for each face are stored in the FaceRightElems and FaceLeftElems array. Each array is dimensioned by the total number of faces in the zone. The first value in each array is the right or left neighboring element for Face 1, followed by the neighboring element for Face 2, and so forth.

FaceRightElems = [RightNeighborToFace1,
                  RightNeighborToFace2,
                  ...
                  RightNeighborToFaceF]
FaceLeftElems = [LeftNeighborToFace1,
                 LeftNeighborToFace2,
                 ...
                 LeftNeighborToFaceF]

where F is the total number of faces

In the above plot, the face neighbors are as follows:

Face Number Right
Neighboring
Element
Left
Neighboring
Element

Face 1

1

0

Face 2

1

0

Face 3

1

2

Face 4

1

3

Face 5

1

4

Face 6

1

0

Face 7

2

0

Face 8

2

0

Face 9

2

0

Face 10

2

3

Face 11

3

0

Face 12

3

4

Face 13

4

0

Face 14

4

0

Face 15

4

0

The number zero is used to indicate that the face is on the edge of the data (i.e. has "no neighboring element").

FaceBoundaryConnectionElements and Zones

When working with multiple zones, an additional aspect is folded into the FaceLeftElems and FaceRightElems arrays. When the neighboring element is not within the current zone, you cannot identify the element by its element number alone. Instead you need to specify both the element number and its zone number. This is accomplished using the FaceBoundaryConnectionElements and FaceBoundaryConnectionZones arrays. For each boundary connection, the element number of the boundary connection is stored in the FaceBoundaryConnectionElements array while its zone number is stored in the FaceBoundaryConnectionZones array.

A negative value in the FaceLeftElems or FaceRightElems array is used to indicate that the neighboring element belongs to another zone. The magnitude of the negative number is a pointer to a value in the FaceBoundaryConnectionElements and FaceBoundaryConnectionZones arrays. For example, given the following FaceBoundaryConnectionElements and FaceBoundaryConnectionZones arrays:

FaceBoundaryConnectionElements = [ 1 1 3 4 ]

FaceBoundaryConnectionZones = [ 2 2 3 3 ]

A value of -4 in the FaceLeftElems indicates that the left neighboring element for that face is element four in zone three.

Partially Obscured Boundary Faces

A face on the boundary of a zone may be partially obscured by its boundary connections (neighboring elements). While Tecplot 360 does not draw fully obscured boundary faces (because it treats those faces as internal faces), Tecplot 360 does draw partially obscured boundary faces. Thus, Tecplot 360 requires definition of partially obscured boundary faces.

To indicate a partially obscured face, indicate the appropriate neighboring element as zero in the FaceBndryConnectionElems and FaceBndryConnectionZones arrays, followed by the actual neighboring elements. When Tecplot 360 sees a list of neighboring elements for a boundary face that begin with element zero, it marks that boundary face as partially obscured.

If Tecplot 360 sees a zero in FaceBndryConnectionElems that is not the first boundary element listed for a face, an error message will appear, indicating that either the partially obscured boundary face was not indicated correctly, or FaceBndryConnectionsElems and/or FaceBndryConnectionsZones was not completely filled out.

Examples

Source code for example programs that use the TecIO library is provided with your Tecplot 360 installation in the util/tecio/examples folder in the installation directory. See the readme.txt file in that folder for additional information on building the examples.

The examples (written in C) provide a basic illustration of creating a *.plt file using the TecIO library. If you plan to compile the examples, be sure to review the instructions in Linking with the TecIO Library first.

In order to keep the examples as simple as possible, error checking is not included. For complete details on the parameters used and the function syntax for each TecIO function, refer to Binary Data File Function Reference. When creating a binary data file using the TecIO library, the functions must be called in a specific order. Refer to Binary Data File Function Calling Sequence for details.

Face Neighbors

This example illustrates how to (1) create two simple FE-quadrilateral zones and (2) create a face neighbor connection between the two zones. In order to keep the example as simple as possible, error checking is not included. If you plan to compile this example, be sure to include TECIO.h.

For complete details on the parameters used and the function syntax for each TecIO function, refer to Binary Data File Function Reference. When creating a binary data file using the TecIO library, the functions must be called in a specific order. Refer to Binary Data File Function Calling Sequence for details.

Step 1 Initialize the data file using TECINI

TECINI is required for all data files. It is used to open the data file and initialize the file header information (name the data file, the variables for the data file, and the file type).

INTEGER4 Debug  = 1;
INTEGER4 VIsDouble  = 0;
INTEGER4 FileType  = 0;
INTEGER4 FileFormat = 0; // 0 == PLT, 1 == SZPLT
INTEGER4 I  = 0;  /* Used to track return codes */

I = TECINI142((char*)"Face Neighbors Example", /* Specifies the name
                                                * of the entire
                                                * dataset
                                                */
              (char*)"X Y P",                  /* Defines the
                                                * variables for the
                                                * data file.  Each
                                                * zone must contain
                                                * each of the vars
                                                * listed.  The order
                                                * of the variables in
                                                * the list is used to
                                                * define the variable
                                                * number (e.g. X is
                                                * Var 1.)
                                                */
              (char*)"FaceNeighbors.plt",      /* Specifies the
                                                * file name.
                                                */
              (char*)".",
              &FileFormat,
              &FileType,                       /* The FileType is set to
                                                * zero, indicating it is
                                                * a full file containing
                                                * both grid and solution
                                                * data).
                                                */
              &Debug,
              &VIsDouble);
Step 2 Create Zone 1

After TECINI is called, call `TECZNE to create one or more zones for your data file.

INTEGER4 ZoneType  = 3;  /* set the zone type to
                          * FEQuadrilateral
                          */
INTEGER4 NumPts    = 6;
INTEGER4 NumElems  = 2;
INTEGER4 NumFaces  = 8;
INTEGER4 ICellMax  = 0;  /* not used */
INTEGER4 JCellMax  = 0;  /* not used */
INTEGER4 KCellMax  = 0;  /* not used */
double  SolTime    = 360.0;
INTEGER4 StrandID  = 0;  /* StaticZone */
INTEGER4 unused    = 0;  // ParentZone is no longer used
INTEGER4 IsBlock   = 1;  /* Block */
INTEGER4 NFConns   = 1;  /* Specify the number of Face
                          * Neighbor Connections in the
                          * Zone.  When this value is
                          * greater than zero, TECFACE must
                          * be called prior to creating the
                          * next zone or ending the file.
                          */

/* Specify the Face Neighbor Mode.
 * A value of 2 indicated that the face neighbor mode is global
 * one-to-one.  The scope of the face neighbors (local or
 * global) is with respect to the zones. A value of global
 * indicates that the face neighbor(s) is/are shared aross zones;
 * a value of local indicates that the face neighbor(s) are
 * shared within the current zone.  The terms one-to-one and
 * one-to-many are used to indicate whether the face in question
 * is shared with one cell or several cells.
 * For example, if your data is arranged as follows:
 *
 *             +-----+-----+-----+
 *             |     |     |     |
 *             |  1  |  2  |  3  |
 *             |     |     |     |
 *             +-----+-----+-----+
 *             |     |           |
 *             |  4  |     5     |
 *             |     |           |
 *             +-----+-----------+
 *
 * The face between 1 & 4 is local-one-to-one. The face between
 * 5 and (2 & 3) is local one-to-many.
 */

INTEGER4 FNMode  = 2;
INTEGER4 TotalNumFaceNodes  = 1;           /* Not used for FEQuad zones*/
INTEGER4 NumConnectedBoundaryFaces  = 1;   /* Not used for FEQuad zones*/
INTEGER4 TotalNumBoundaryConnections  = 1; /* Not used for FEQuad zones*/
INTEGER4 ShrConn  = 0;

INTEGER4 ValueLocation[3] = {1, 1, 1};  /* Specify the variable
                                         * values at the nodes.
                                         * NOTE:  Because all of
                                         * the variables are
                                         * defined at the nodes,
                                         * we can just pass
                                         * NULL for this array.
                                         * We are providing the
                                         * array for illustration
                                         * purposes.
                                         */

I = TECZNE142((char*)"Zone 1",
              &ZoneType,
              &NumPts,
              &NumElems,
              &NumFaces,
              &ICellMax,
              &JCellMax,
              &KCellMax,
              &SolTime,
              &StrandID,
              &unused,
              &IsBlock,
              &NFConns,
              &FNMode,
              &TotalNumFaceNodes,
              &NumConnectedBoundaryFaces,
              &TotalNumBoundaryConnections,
              NULL,
              ValueLocation,
              NULL,
              &ShrConn);
Step 3 Define the node numbering for Zone 1

For this example, we will create 2 rectangular cells in Zone 1. Before defining your variables, you must establish a consistent node numbering scheme for your data. Once the node numbers are defined, supply the variable values in the node numbering order. In this example, Node 1 is defined at X = 0 and Y = 0. As such, the first value supplied for X (i.e. X[0]) is 0. Similarly, the first value supplied for Y is 0.

It is important that you refer to node numbers consistently. The node numbers will be used later to define the connectivity for each element.

For this example, we will create two quadrilateral elements. The node numbering for the elements is defined in the following picture.

Zone1_NodeLabels.jpg
Step 4 Set up the variable values

The variable values will be written to the file using TECDAT. Because we are specifying nodal variables (as specified via the ValueLocation parameter in TECZNE), each variable is dimensioned by the number of points (NumPts) in the Zone. You have the option to specify some variables with nodal values and some with cell-centered values. Refer to TECZNE142 or TECZNEFEMIXED142 for details.

float *X = new float[NumPts];
float *Y = new float[NumPts];
float *P = new float[NumPts];

/* For this example, we will create 2 rectangular cells in Zone
 * 1.  Before defining your variables, you must establish a
 * consistent node numbering scheme for your data.  Once the
 * node numbers are defined, supply the variable values in the
 * node numbering order.  In this example, node 1 is defined at
 * X = 0 and Y = 0.  As such, the first value supplied for X
 * (i.e. X[0]) is 0.  Similarly, the first value supplied for Y
 * is 0.
 *
 * It is important that you refer to node numbers consistently.
 * The node numbers will be used later to define the
 * connectivity for each element.
 */

X[0] = 0;
X[1] = 0;
X[2] = 1;
X[3] = 1;
X[4] = 2;
X[5] = 2;

Y[0] = 0;
Y[1] = 1;
Y[2] = 0;
Y[3] = 1;
Y[4] = 0;
Y[5] = 1;

for (INTEGER4 ii = 0; ii < NumPts; ii++)
 P[ii] = (float)(NumPts - ii);

INTEGER4 DIsDouble =  0;  /* Set DIsDouble to zero to use
                           * variables in float format.
                           */

/* Call TECDAT once for each variable */
I  = TECDAT142(&NumPts, &X[0], &DIsDouble);
I  = TECDAT142(&NumPts, &Y[0], &DIsDouble);
I  = TECDAT142(&NumPts, &P[0], &DIsDouble);
Step 5 Define the connectivity list for Zone 1

The Connectivity List is used to specify the nodes that compose each element. When working with nodal variables, the numbering of the nodes is implicitly defined when the variables are declared. The first value of each variable is for node one, the second value for node two, and so on.

Because this zone contains two quadrilateral elements, we must supply 8 values in the connectivity list. The first four values define the nodes that form Element 1. Similarly, the second four values define the nodes that form Element 2.

INTEGER4 ConnList[8] = {1, 3, 4, 2,
                        3, 5, 6, 4 };
I  = TECNOD142(ConnList);
It is important to provide the node list in either a clockwise or counter-clockwise order. Otherwise, your elements will be misshapen. For example, if the first two numbers in the above connectivity list were switched, the zone would appear as follows:
Zone1_NodeLabelsContort.jpg
Step 6 Define the face neighbor connections for Zone 1

Now that TECNOD or TECNODE has been called, the creation of Zone 1 is complete. However, in this example, we will define a face neighbor between Zone 1 and Zone 2 (to be created later in the example). Face Neighbor connections are used to define connections that are not created via the connectivity list. For example, local face neighbors may need to be defined when a zone wraps onto itself and global face neighbors may need to be defined to smooth edges across zones. Face Neighbors are used when deriving variables and drawing contours.

In this example, we are creating a face neighbor connection between Cell 2 in Zone 1 and Cell 1 in Zone 2. The information required when specifying face neighbors depends upon the type of connection. Refer to TECFACE142 for details.

In this case, we must supply the following information (in the order provided):

  • the cell number in the current zone that contains the face neighbor

  • the number of the face in that cell that contains the face neighbor

  • the number of the other zone to which the face is connected

  • the number of the cell in the other zone to which the face is connected

In this example, Face 2 in Cell 2 in the current zone is connected to Cell 1 in Zone 2.

Zone1_FaceNeighbor.jpg
INTEGER4 FaceConn[4] = {2, 2, 2, 1};
I  = TECFACE142(FaceConn);
Step 7 Create Zone 2

The creation of Zone 1 is complete. We are ready to create Zone 2. For simplicity, Zone 2 is a copy of Zone 1 shifted along the X-axis. As such, many of the variables used to create Zone 1 are re-used here.

/* Call TECZNE to create Zone 2 */
I = TECZNE142((char*)"Zone 2",
              &ZoneType,
              &NumPts,
              &NumElems,
              &NumFaces,
              &ICellMax,
              &JCellMax,
              &KCellMax,
              &SolTime,
              &StrandID,
              &unused,
              &IsBlock,
              &NFConns,
              &FNMode,
              &TotalNumFaceNodes,
              &NumConnectedBoundaryFaces,
              &TotalNumBoundaryConnections,
              NULL,
              ValueLocation,
              NULL,
              &ShrConn);
Step 8 Define the variables for Zone 2

Because Zone 2 is a copy of Zone 1, shifted along the X-axis, we can share the Y variable definition used to Zone. We will also create a second pressure variable for Zone 2 (P2).

float *X2 = new float[NumPts];
float *P2 = new float[NumPts];

for (INTEGER4 ii = 0; ii < NumPts; ii++)
{
 X2[ii] = X[ii] + 2;
 P2[ii] = 2 * (float)ii;
}

I  = TECDAT142(&NumPts, &X2[0], &DIsDouble);
I  = TECDAT142(&NumPts, &Y[0], &DIsDouble);
I  = TECDAT142(&NumPts, &P2[0], &DIsDouble);

delete X;
delete Y;
delete P;
delete X2;
delete P2;
Step 9 Define the connectivity list for Zone 2

As with Zone 1, we must define the connectivity list for Zone 2. Because, the node numbering restarts at one for each new zone and the nodal arrangement is identical between the two zones, we may reuse the connectivity list from Zone 1.

I  = TECNOD142(ConnList);
Step 10 Define the face neighbor connections for Zone 2

We will now specify the face neighbor connection with respect to our new current zone of Zone 2.

Zone2_FaceNeighbor.jpg
INTEGER4 FaceConn2[4] = {1, 4, 1, 2};  /* cell 1, face 4 in
                                        * current zone is a
                                        * neighbor to cell 2 in
                                        * zone 1.
                                        */
I  = TECFACE142(FaceConn2);
Step 11 Close the file

Call TECEND to close the file.

I = TECEND142();

Summary

When the preceding code is compiled and built, the data file will look as follows (with the Mesh and Edge layers turned-on):

FinalDataFile.jpg

With the Mesh layer deactivated, the data set will look as follows:

FinalDataFile_NoMesh.jpg

If we had not included face neighbor connections, an Edge line would be drawn in between the two zones.

Polygonal Example

The following example (written in C++) illustrates how to create a single octagonal cell using the TecIO library.

Octagon.jpg

In order to keep the example as simple as possible, error checking is not included. If you plan to compile this example, be sure to include TECIO.h.

For complete details on the parameters used and the function syntax for each TecIO function, refer to Binary Data File Function Reference. When creating a binary data file using the TecIO library, the functions must be called in a specific order. Refer to Binary Data File Function Calling Sequence for details.

Remember that Tecplot Focus cannot load face-based (polygonal or polyhedral) data.
Step 1 Initialize the data file using TECINI

TECINI is required for all data files. It is used to: open the data file and initialize the file header information (name the data file, the variables for the data file, and the file type).

INTEGER4 Debug  = 1;
INTEGER4 VIsDouble  = 0;
INTEGER4 FileType  = 0;
INTEGER4 FileFormat = 0; // 0 == PLT, 1 == SZPLT; Only PLT is currently
                         // supported for polygonal zones.
INTEGER4 I;              // used to check return codes

/*
 * Open the file and write the Tecplot datafile
 * header information
 */

I = TECINI142((char*)"Octagon",
              (char*)"X Y P",  /* Defines the variables for the data
                                * file. Each zone must contain each
                                * of the vars listed here. The order
                                * of the variables in the list is
                                * used to define the variable number
                                * (e.g. X is Variable 1). When
                                * referring to variables in other
                                * TecIO functions, you will refer to
                                * thevariable by its number.
                                */
              (char*)"octagon.plt",
              (char*)".",       /* scratch directory */
              &FileFormat,
              &FileType,
              &Debug,
              &VIsDouble);
Step 2 Create Zone 1

After TECINI is called, call TECPOLYZNE to create one or more zones for your data file.

/* In this example, we will create a single octagonal cell in
 * Tecplot 360’s polyhedral file format.
 */
INTEGER4 ZoneType  = 6;  /* FEPolygon */
INTEGER4 NumNodes  = 8;  /* Number of nodes in the octagon.*/
INTEGER4 NumElems  = 1;  /* Number of octagonal elements. */
INTEGER8 NumFaces  = 8;  /* Number of faces in the octagon.*/
double  SolTime    = 360.0;
INTEGER4 StrandID  = 0;  /* Static Zone */
INTEGER4 unused  = 0;  // ParentZone is no longer used


/* For polygonal zones, the total number of face nodes is equal
 * to twice the number of nodes.  This is because, each face
 * has exactly two nodes.
 */
INTEGER8 NumFaceNodes  = 2 * NumNodes;
/* Boundary Faces and Boundary Connections are not used in this
 * example.
 */
INTEGER4 NumBFaces  = 0;
INTEGER4 NumBConnections = 0;

INTEGER4 ShrConn  = 0;

I = TECPOLYZNE142((char*)"Octagonal Zone",
                   &ZoneType,
                   &NumNodes,
                   &NumElems,
                   &NumFaces,
                   &NumFaceNodes,
                   &SolTime,
                   &StrandID,
                   &unused,
                   &NumBFaces,
                   &NumBConnections,
                   NULL,
                   NULL,  /* When Value Location is not specified,
                           * Tecplot will treat all variables as
                           * nodal variables.
                           */
                   NULL,
                   &ShrConn);
Step 3 Define node numbering

For this example, we will create a single octagonal cell. Before defining your variables, you must establish a consistent node numbering scheme for your data. Once the node numbers are defined, supply the variable values in the node numbering order. In this example, Node 1 is defined at X = .25 and Y = 0. As such, the first value supplied for X (i.e. X[0]) is .25. Similarly, the first value supplied for Y is 0.

It is important that you refer to node numbers consistently. The node numbers will be used later to define the connectivity for each element.

NodeNumbering.jpg
Step 4 Set up the variable values

Write the variable values to the file using TECDAT. Because we are specifying nodal variables (as specified via the ValueLocation parameter in TECPOLYZNE), each variable is dimensioned by the number of points (NumPts) in the Zone. You have the option to specify some variables with nodal values and some with cell-centered values. Refer to TECPOLYZNE142 for details.

The order of the values supplied for each nodal variable is determined by the node numbering established in Step 3. The first value for each variable is for Node 1, the second value for each variable is for Node 2 and so forth.

V1 = {ValueAtNode1, ValueAtNode2, …​, ValueAtNodeN}

where N is the total number of nodes

float *X = new float[NumNodes];
float *Y = new float[NumNodes];
float *P = new float[NumNodes];

//Define the grid values.
X[0] = 0.25;
Y[0] = 0.0;

X[1] = 0.75;
Y[1] = 0.0;

X[2] = 1.0;
Y[2] = 0.25;

X[3] = 1.0;
Y[3] = 0.75;

X[4] = 0.75;
Y[4] = 1.0;

X[5] = 0.25;
Y[5] = 1.0;

X[6] = 0.0;
Y[6] = 0.75;

X[7] = 0.0;
Y[7] = 0.25;

for (INTEGER4 ii = 0; ii < 8; ii++)
 P[ii] = .5;

/* Write out the field data using TECDAT */
INTEGER4 DIsDouble = 0;  /* set IsDouble to 0 to use float
                          * variables. */

I  = TECDAT142(&NumNodes,  X,  &DIsDouble);
I  = TECDAT142(&NumNodes,  Y,  &DIsDouble);
I  = TECDAT142(&NumNodes,  P,  &DIsDouble);

delete X;
delete Y;
delete P;
Step 5 Define the Face Nodes

The FaceNodes array is used to indicate which nodes define which face. As mentioned earlier, the number of the nodes is implicitly defined by the order in which the nodal data is provided. The first value of each nodal variable describes Node 1, the second value describes Node 2, and so on.

The face numbering is also implicitly defined. Because there are two nodes in each face of any polygonal zone, the first two nodes provided define Face 1, the next two define Face 2 and so on. If there was a variable number of nodes used to define the faces, the array would be more complicated. Refer to Multiple Polygonal Zones for an example.

The following picture describes the face numbering for this example:

FaceNumbering.png

As you can see, Face 1 is defined by Nodes 1 and 2, Face 2 is defined by Nodes 2 and 3, and so forth. Because of this simple arrangement, we can use a for-loop to define all but the end points of the face nodes array.

INTEGER4 *FaceNodes = new INTEGER4[NumFaceNodes];

/*
 * Loop over number of sides, and set each side to two
 * consecutive nodes.
 */
for (INTEGER4 ii = 0; ii < 8; ii++)
{
  FaceNodes[2*ii] = ii + 1;
  FaceNodes[2*ii+1] = ii + 2;
}
FaceNodes[15] = 1;
Step 6 Define the right and left elements of each face

The last step for writing out the polygonal data is to define the right and left neighboring elements for each face. The neighboring elements can be determined using the right-hand rule. For each face, place your right-hand along the face with your fingers pointing the direction of incrementing node numbers (i.e. from Node 1 to Node 2). The right side of your hand will indicate the right element, and the left side of your hand will indicate the left element. Refer to FaceRightElems and FaceLeftElems for details.

The number zero is used to indicate that there isn’t an element on that side of the face (i.e. the face is on the edge of the data set). This is referred to as "no neighboring element".

Because of the way we numbered the nodes and faces, the right element for every face is the element itself (Element 1) and the left element is "no-neighboring element" (Element 0).

INTEGER4 *FaceLeftElems  = new INTEGER4[NumFaces];
INTEGER4 *FaceRightElems = new INTEGER4[NumFaces];

for (INTEGER8 ii = 0; ii < NumFaces; ii++)
{
 FaceLeftElems[ii]  = 0;
 FaceRightElems[ii]  = 1;
}
Step 7 Write the face nodes to the file

We can now call TECPOLYFACE142 to write the face nodes to the file. Since we do not have any boundary connections in this data set, there is no need to call TECPOLYBCONN142.

INTEGER4 NumFaces32 = (INTEGER4)NumFaces;
I = TECPOLYFACE142(&NumFaces32,
                   NULL,
                   FaceNodes,
                   FaceLeftElems,
                   FaceRightElems);

delete FaceNodes;
delete FaceLeftElems;
delete FaceRightElems;
Step 8 Close the file

Call TECEND to close the file.

I = TECEND142();

Multiple Polyhedral Zones

The following example demonstrates how to create two polyhedral zones, a rectangular solid and a prism. The resulting image is a three-dimensional arrow (shown below).

Arrow_ShadeLayer.jpg

This example covers the following topics: polyhedral data, working with multiple zones, and specifying partially obscured faces. In order to keep the example as simple as possible, error checking is not included. If you plan to compile this example, be sure to include: TECIO.h.

For complete details on the parameters used and the function syntax for each TecIO function, refer to Binary Data File Function Reference. When creating a binary data file using the TecIO library, the functions must be called in a specific order. Refer to Binary Data File Function Calling Sequence for details.

Remember that Tecplot Focus cannot load face-based (polygonal or polyhedral) data.
Step 1 Initialize the data file using TECINI

TECINI is required for all data files. This function opens the data file and initializes the file header information (names the data file, the variables for the data file, and the file type).

INTEGER4 Debug  = 1;
INTEGER4 VIsDouble = 1;
INTEGER4 FileFormat = 0; // 0 == PLT, 1 == SZPLT; Only PLT is currently
                         // supported for ployhedral zones
INTEGER4 FileType  = 0;
INTEGER4 I;

/* Open the file and write the Tecplot datafile
 * header information
 */
I = TECINI142((char*)"Multiple polyhedral zones", /* Name of the entire
                                                   * dataset.
                                                   */
              (char*)"X Y Z P",  /* Defines the variables for the data
                                  * file. Each zone must contain each of
                                  * the variables listed here. The order
                                  * of the variables in the list is used
                                  * to define the variable number (e.g.
                                  * X is Var 1).
                                  */
              (char*)"Arrow.plt",
              (char*)".",         /* Scratch Directory */
              &FileFormat,
              &FileType,
              &Debug,
              &VIsDouble);
Step 2 Create Zone 1 (rectangle)

After TECINI is called, call TECPOLYZNE to create one or more zones for your data file. In this example, Zone 1 contains a single rectangular solid created as a face-based finite element (i.e. polyhedral zone). The zone has eight points (or nodes), six faces and one element.