### Navigation

- ☰
- PyTecplot-0.6 »
- Reference »

# Data

- Loading Data
- Saving Data
- Data Queries
- Data Operations
- Data Access
  - Dataset
  - Variable
  - Zones
  - Array
  - Nodemap
  - Facemap
  - FaceNeighbors
- Auxiliary Data
  - AuxData

`Dataset` access and manipulation.

A `Dataset` consists of a matrix of Zones and `Variables`. Each `Zone <data_access>`-`Variable` pair corresponds to a data object which can always be treated as a 1D array, but which may be interpreted as 2D or 3D in the case of ijk-ordered data. In general, the Zone defines the size, shape and connectivity of the data while the `Variable` defines the underlying data type and whether the data is nodal or cell-centered.

Warning

Zero-based Indexing

It is important to know that all indexing in PyTecplot scripts are zero-based. This is a departure from the macro language which is one-based. This is to keep with the expectations when working in the python language. However, PyTecplot does not modify strings that are passed to the Tecplot Engine. This means that one-based indexing should be used when running macro commands from python or when using `execute_equation()`.

## Loading Data

`tecplot.data.``load_tecplot`(filenames, frame=None, append=True, reset_style=None, initial_plot_first_zone_only=None, initial_plot_type=None, zones=None, variables=None, collapse=None, skip=None, assign_strand_ids=True, add_zones_to_existing_strands=None, include_text=None, include_geom=None, include_custom_labels=None, include_data=None)

  Read a tecplot data file.

  Parameters: | filenames (`string` or `list` of `strings`) – Files to be read. frame (`Frame`, optional) – The `Frame` to attach the resulting `Dataset`. If `None`, the currently active `Frame` is used and the zones are appended by default. append (`boolean`, optional) – Append the data to the existing `Dataset`. If `False`, the existing data attached to the `Frame` is deleted and replaced. (default: `True`) reset_style (`boolean`, optional) – Reset the style for destination `Frame`, if `False`, the `Frame`‘s current style is preserved. (default: `True`) initial_plot_first_zone_only (`boolean`, optional) – Informs the Tecplot Engine that after the data is loaded it only needs to activate the first enabled Zone for the initial plot. This option is particularly useful if you have many Zones and want to get the data into the Tecplot Engine and the first Zone drawn as fast as possible. The inactive Zones can always be activated when needed. (default: `False`) initial_plot_type (`PlotType`, optional) – Forces a specific type of plot upon loading of the data. Only used if resetstyle is `True`. To have Tecplot 360 EX determine the most appropriate plot type for the data, use `PlotType.Automatic`. Possible values are: `PlotType.Automatic` (default), `Cartesian3D`, `Cartesian2D`, `XYLine`, `PlotType.Sketch`, `PolarLine`. zones (`set` of `integers`, optional) – Set of Zones to load. Use `None` to load all zones. (default: `None`) variables (`set` of `strings` or `integers`, optional) – Set of `Variables` to load. Use `None` to load all variables. (default: `None`) collapse (`boolean`, optional) – Reindex Zones and `Variables` if any are disabled. (default: `False`) skip – (3-`tuple` of `integers`, optional) The ijk-skip. A value of (1,1,1) loads every data point in the (i,j,k) directions. A value of (2,2,2) loads every other data point and so forth. This only applies to ordered data. (default: (1,1,1)) assign_strand_ids (`boolean`, optional) – Assign strand ID’s to zones that have a strand ID of -1. (default: `True`) add_zones_to_existing_strands (`boolean`, optional) – Add the Zones to matching strands, if they exist. Otherwise, if the new data specifies strands, new ones will be created beginning after the last strand in the `Dataset`. (default: `False`) include_text (`boolean`, optional) – Load any text, geometries, or custom labels (default: `True`) include_geom (`boolean`, optional) – Load geometries. (default: `True`) include_custom_labels (`boolean`, optional) – (default: `True`) include_data (`boolean`, optional) – Load data. Set this to `False` if you only want annotations such as text or geometries. (default: `True`)
  Returns: | `Dataset` – The `Dataset` holding the loaded data.
  Raises: | `TecplotSystemError` – Internal error when loading data. `TecplotTypeError` – In-valid input.

`tecplot.data.``load_cgns`(filenames, frame=None, append=True, reset_style=None, initial_plot_first_zone_only=None, initial_plot_type=None, zones=None, variables=None, load_convergence_history=None, combine_fe_sections=None, average_to_nodes=None, uniform_grid=None, assign_strand_ids=None, add_zones_to_existing_strands=None, include_boundary_conditions=None)

  Read CGNS data files.

  Parameters: | filenames (`string` or `list` of `strings`) – CGNS data files to be read. Note: Relative paths are considered to be from the running python script’s current working directory which can be obtained via `os.getcwd()`. frame (`Frame`, optional) – The `Frame` to attach the resulting `Dataset`. If `None`, the currently active `Frame` is used and the zones are appended by default. append (`boolean`, optional) – Append the data to the existing `Dataset`. If `False`, the existing data attached to the `Frame` is deleted and replaced. (default: `True`) reset_style (`boolean`, optional) – Reset the style for destination `Frame`, if `False`, the `Frame`‘s current style is preserved. (default: `True`) initial_plot_first_zone_only (`boolean`, optional) – Informs the Tecplot Engine that after the data is loaded it only needs to activate the first enabled Zone for the initial plot. This option is particularly useful if you have many Zones and want to get the data into the Tecplot Engine and the first Zone drawn as fast as possible. The inactive Zones can always be activated when needed. (default: `False`) initial_plot_type (`PlotType`, optional) – Forces a specific type of plot upon loading of the data. Only used if resetstyle is `True`. To have Tecplot 360 EX determine the most appropriate plot type for the data, use `PlotType.Automatic`. Possible values are: `PlotType.Automatic` (default), `Cartesian3D`, `Cartesian2D`, `XYLine`, `PlotType.Sketch`, `PolarLine`. zones (`list` of `integers`, optional) – List of zone indexes to load starting from zero. `None` implies loading all zones. (default: `None`) variables (`list` of `integers`, optional) – List of variable indexes, beyond the first coordinate variables, to load starting from zero. `None` implies loading all variables. The grid will always be loaded and an index of zero indicates the first non-coordinate variable. (default: `None`) load_convergence_history (`boolean`, optional) – Load the global convergence history rather than any grid or solution data. (default: `False`) combine_fe_sections (`boolean`, optional) – Combine all finite-element sections with the zone cell-dimension into one zone. (default: `False`) average_to_nodes (`string`, optional) – Average cell-centered data to grid nodes using the specified method. (Options: `None`, “Arithmetic”, “Laplacian”) uniform_grid (`boolean`, optional) – Indicates the grid structure is the same for all time steps. (default: `True`) assign_strand_ids (`boolean`, optional) – Assign strand ID’s to zones that have a strand ID of -1. (default: `True`) add_zones_to_existing_strands (`boolean`, optional) – Add the Zones to matching strands, if they exist. Otherwise, if the new data specifies strands, new ones will be created beginning after the last strand in the `Dataset`. (default: `False`) include_boundary_conditions (`boolean`, optional) – Load the boundary conditions along with the data. (default: `False`)
  Returns: | `Dataset` – The `Dataset` holding the loaded data.
  Raises: | `TecplotSystemError` – Internal error when loading data. `TecplotTypeError` – Invalid input.

`tecplot.data.``load_fluent`(case_filenames=None, data_filenames=None, frame=None, append=True, reset_style=None, initial_plot_first_zone_only=None, initial_plot_type=None, zones=None, variables=None, all_poly_zones=None, average_to_nodes=None, time_interval=None, assign_strand_ids=True, add_zones_to_existing_strands=None, include_particle_data=None)

  Read Fluent data files.

  Parameters: | case_filenames (`string` or `list` of `strings`, optional) – Case (.cas) files to be read. data_filenames (`string` or `list` of `strings`, optional) – Data (.dat, .xml etc.) files to be read. frame (`Frame`, optional) – The `Frame` to attach the resulting `Dataset`. If `None`, the currently active `Frame` is used and the zones are appended by default. append (`boolean`, optional) – Append the data to the existing `Dataset`. If `False`, the existing data attached to the `Frame` is deleted and replaced. (default: `True`) reset_style (`boolean`, optional) – Reset the style for destination `Frame`, if `False`, the `Frame`‘s current style is preserved. (default: `True`) initial_plot_first_zone_only (`boolean`, optional) – Informs the Tecplot Engine that after the data is loaded it only needs to activate the first enabled Zone for the initial plot. This option is particularly useful if you have many Zones and want to get the data into the Tecplot Engine and the first Zone drawn as fast as possible. The inactive Zones can always be activated when needed. (default: `False`) initial_plot_type (`PlotType`, optional) – Forces a specific type of plot upon loading of the data. Only used if resetstyle is `True`. To have Tecplot 360 EX determine the most appropriate plot type for the data, use `PlotType.Automatic`. Possible values are: `PlotType.Automatic` (default), `Cartesian3D`, `Cartesian2D`, `XYLine`, `PlotType.Sketch`, `PolarLine`. zones (`string` or `list` of `integers`, optional) – List of zone indexes (zero-based) to load or string specifying the type of zones to load. Possible values are: “CellsAndBoundaries”, “CellsOnly” and “BoundariesOnly”. Specifying one of these options is mutually exclusive with the `variables` option. (default: “CellsAndBoundaries”) variables (`list` of `strings`, optional) – List of variable names to load. `None` implies loading all variables. (default: `None`) all_poly_zones (`boolean`, optional) – Converts all zones to Tecplot polytope (polyhedral or polygonal) zones. (default: `False`) average_to_nodes (`string`, optional) – Average cell-centered data to grid nodes using the specified method. (Options: `None`, “Arithmetic”, “Laplacian”) time_interval (`float`, optional) – Use a constant time interval between each .dat file. If `None`, the flow-data parameter of each solution .dat file is used. (default: `None`) assign_strand_ids (`boolean`, optional) – Assign strand ID’s to zones that have a strand ID of -1. (default: `True`) Note assign_strand_ids only applies if you have also provided a time_interval, otherwise it will be ignored. add_zones_to_existing_strands (`boolean`, optional) – Add the Zones to matching strands, if they exist. Otherwise, if the new data specifies strands, new ones will be created beginning after the last strand in the `Dataset`. (default: `False`) include_particle_data (`boolean`, optional) – Load particle data from the .dat files. If loading particle data from an XML file, the XML file should be included in the `data_filenames` list. (default: `False`)
  Returns: | `Dataset` – The `Dataset` holding the loaded data.
  Raises: | `TecplotSystemError` – Internal error when loading data. `TecplotTypeError` – In-valid input.

  Notes

  The `zones` option takes either a `list` of zone indexes to be imported or one of “CellsAndBoundaries”, “CellsOnly” or “BoundariesOnly” to indicate the type of zones the user wants to load, however these options are mutually exclusive with the `variables` option:

      >>> import tecplot
      >>> dataset = tecplot.data.load_fluent(['one.cas', 'two.cas'],
      ...     data_filenames=['one.dat', 'two.dat'],
      ...     variables = ['Pressure','Velocity'],
      ...     zones = [0,1,3])

`tecplot.data.``load_plot3d`(grid_filenames=None, solution_filenames=None, function_filenames=None, name_filename=None, frame=None, append=True, reset_style=None, initial_plot_first_zone_only=None, initial_plot_type=None, data_structure=None, is_multi_grid=None, style=None, ascii_is_double=None, ascii_has_blanking=None, uniform_grid=None, assign_strand_ids=True, add_zones_to_existing_strands=True, append_function_variables=None, include_boundaries=True)

  Read Plot3D data files.

  Parameters: | grid_filenames (`string` or `list` of `strings`, optional) – One or more grid file names to be read. solution_filenames (`string` or `list` of `strings`, optional) – One or more solution data file names to be read. function_filenames (`string` or `list` of `strings`, optional) – One or more function file names. name_filename (`string`, optional) – Path to the name file. frame (`Frame`, optional) – The `Frame` to attach the resulting `Dataset`. If `None`, the currently active `Frame` is used and the zones are appended by default. append (`boolean`, optional) – Append the data to the existing `Dataset`. If `False`, the existing data attached to the `Frame` is deleted and replaced. (default: `True`) reset_style (`boolean`, optional) – Reset the style for destination `Frame`, if `False`, the `Frame`‘s current style is preserved. (default: `True`) initial_plot_first_zone_only (`boolean`, optional) – Informs the Tecplot Engine that after the data is loaded it only needs to activate the first enabled Zone for the initial plot. This option is particularly useful if you have many Zones and want to get the data into the Tecplot Engine and the first Zone drawn as fast as possible. The inactive Zones can always be activated when needed. (default: `False`) initial_plot_type (`PlotType`, optional) – Forces a specific type of plot upon loading of the data. Only used if resetstyle is `True`. To have Tecplot 360 EX determine the most appropriate plot type for the data, use `PlotType.Automatic`. Possible values are: `PlotType.Automatic` (default), `Cartesian3D`, `Cartesian2D`, `XYLine`, `PlotType.Sketch`, `PolarLine`. data_structure (`string`, optional) – Specifies the data structure and overrides the automatic detection. Options are: `1D`, `2D`, `3DP`, `3DW`, `UNSTRUCTURED`. Setting this requires `is_multi_grid` and `style` to be set as well. is_multi_grid (`boolean`, optional) – Sets data as multi-grid and overrides the automatic data structure detection. Setting this requires `data_structure` and `style` to be set as well. style (`boolean`, optional) – Specifies the data style and overrides the automatic data structure detection. Options are: `PLOT3DCLASSIC`, `PLOT3DFUNCTION`, `OVERFLOW`. Setting this requires `data_structure` and `is_multi_grid` to be set as well. ascii_is_double (`boolean`, optional) – Indicates that floating-point numbers found in the text data files should be store with 64-bit precision. (default: `False`) ascii_has_blanking (`boolean`, optional) – Indicates that the text data files contain blanking. (default: `False`) uniform_grid (`boolean`, optional) – Indicates the grid structure is the same for all time steps. (default: `True`) assign_strand_ids (`boolean`, optional) – Assign strand ID’s to zones that have a strand ID of -1. (default: `True`) add_zones_to_existing_strands (`boolean`, optional) – Add the Zones to matching strands, if they exist. Otherwise, if the new data specifies strands, new ones will be created beginning after the last strand in the `Dataset`. (default: `True`) append_function_variables (`boolean`, optional) – Append variables in function files to those found in solution files. (default: `False`) include_boundaries (`boolean`, optional) – Loads boundary zones found in the ”.g.fvbnd” file located in the same directory as the grid file, if available. (default: `True`)
  Returns: | `Dataset` – The `Dataset` holding the loaded data.
  Raises: | `TecplotSystemError` – Internal error when loading data. `TecplotValueError` – In-valid input.

  Note

  Data structure is automatically detected by default.

  The options `data_structure`, `is_multi_grid` and `style` must be supplied together or not at all. When all of these are `None`, the data structure is automatically detected.

  The variables from the function files can be appended to the dataset upon loading:

      >>> import tecplot as tp
      >>> dataset = tp.data.load_plot3d(
      ...     grid_filenames = 'data.g',
      ...     solution_filenames = ['t0.q', 't1.q'],
      ...     function_filenames = ['t0.f', 't1.f'],
      ...     append_function_variables = True)

## Saving Data

`tecplot.data.``save_tecplot_binary`(filename, frame=None, dataset=None, zones=None, variables=None, version=None, include_text=None, include_geom=None, include_data=None, include_data_share_linkage=None, include_autogen_face_neighbors=None, associate_with_layout=None)

  Write tecplot binary data file.

  Parameters: | filename (`string`) – Name of the data file to write. frame (`Frame`, optional) – The `Frame` which holds the `Dataset` to be written. If this option and dataset are both `None`, the currently active `Frame` is used. (default: `None`) dataset (`Dataset`, optional) – The `Dataset` to write out. If this and frame are both `None`, the `Dataset` of the currently active `Frame` is used. (default: `None`) zones (`list` of Zones, optional) – Zones to write out. If `None`, all Zones will be saved. variables (`list` of `Variables`, optional) – `Variables` to write out. If `None`, all `Variables` will be saved. include_text (`boolean`, optional) – Write out all text, geometries and custom labels. (default: `True`) include_geom (`boolean`, optional) – Write out all geometries. (default: `True`) include_data (`boolean`, optional) – Write out the data. Set this to `False` if you only want to write out annotations. (default: `True`) include_data_share_linkage (`boolean`, optional) – Conserve space and write the variable and connectivity linkage wherever possible. If `False`, this will write out all data, losing the connectivity sharing linkage for future dataset reads of the file. (default: `True`) include_autogen_face_neighbors (`boolean`, optional) – Save the face neighbor connectivity. This may produce very large data files. (default: `False`) associate_with_layout (`boolean`, optional) – Associate this data file with the current layout. Set to `False` to write the datafile without modifying Tecplot’s current data file to layout association. If version is set to anything other than `BinaryFileVersion.Current`, this association is not possible, and this parameter will be ignored. (default: `True`) version (`BinaryFileVersion`, optional) – Specifies the file version to write. Note that some data may be excluded from the file if it cannot be supported in the specified version. Possible values are: `Tecplot2006`, `Tecplot2008`, `Tecplot2009` and `BinaryFileVersion.Current`. (default: `BinaryFileVersion.Current`)
  Returns: | `Dataset` – The `Dataset` read from when saving.
  Raises: | `TecplotSystemError` `TecplotLogicError`

  Example

  In this example, we load sample data and save the data in Tecplot binary format.

      from os import path
      import tecplot
      examples_directory = tecplot.session.tecplot_examples_directory()
      infile = path.join(examples_directory,
                         'OneraM6wing', 'OneraM6_SU2_RANS.plt')
      dataset = tecplot.data.load_tecplot(infile)
      variables_to_save = [dataset.variable(V)
                           for V in ('x', 'y', 'z', 'Pressure_Coefficient')]

      zone_to_save = dataset.zone('WingSurface')
      # write data out to a binary file
      tecplot.data.save_tecplot_binary('wing.plt', dataset=dataset,
                                      variables=variables_to_save,
                                      zones=[zone_to_save])

`tecplot.data.``save_tecplot_ascii`(filename, frame=None, dataset=None, zones=None, variables=None, include_text=None, precision=None, include_geom=None, include_data=None, include_data_share_linkage=None, include_autogen_face_neighbors=None, use_point_format=None)

  Write tecplot ASCII data file.

  Parameters: | filename (`string`) – Name of the data file to write. frame (`Frame`, optional) – The `Frame` which holds the `Dataset` to be written. If this option and dataset are both `None`, the currently active `Frame` is used. (default: `None`) dataset (`Dataset`, optional) – The `Dataset` to write out. If this and frame are both `None`, the `Dataset` of the currently active `Frame` is used. (default: `None`) include_text (`boolean`, optional) – Write out all text, geometries and custom labels. (default: `True`) include_geom (`boolean`, optional) – Write out all geometries. (default: `True`) include_data (`boolean`, optional) – Write out the data. Set this to `False` if you only want to write out annotations. (default: `True`) include_data_share_linkage (`boolean`, optional) – Conserve space and write the variable and connectivity linkage wherever possible. If `False`, this will write out all data, losing the connectivity sharing linkage for future dataset reads of the file. (default: `True`) include_autogen_face_neighbors (`boolean`, optional) – Save the face neighbor connectivity. This may produce very large data files. (default: `False`) use_point_format (`boolean`, optional) – Write out point format, otherwise use block format. (default: `False`) zones (`list` of Zones, optional) – Zones to write out. Use `None` to write out all Zones. (default: `None`) variables (`list` of `Variables`, optional) – `Variables` to write out. Use `None` to write out all `Variables`. (default: `None`) precision (`integer`, optional) – ASCII decimal precision to use. (default: 12)
  Returns: | `Dataset` – The `Dataset` read from when saving.
  Raises: | `TecplotSystemError` `TecplotLogicError`

  Example

  In this example, we load sample data and save the data in Tecplot ASCII format.

      from os import path
      import tecplot
      examples_directory = tecplot.session.tecplot_examples_directory()
      infile = path.join(examples_directory,
                         'OneraM6wing', 'OneraM6_SU2_RANS.plt')
      dataset = tecplot.data.load_tecplot(infile)
      variables_to_save = [dataset.variable(V)
                           for V in ('x','y','z','Pressure_Coefficient')]

      zone_to_save = dataset.zone('WingSurface')
      # write data out to an ascii file
      tecplot.data.save_tecplot_ascii('wing.dat', dataset=dataset,
                                      variables=variables_to_save,
                                      zones=[zone_to_save])

## Data Queries

`tecplot.data.query.``probe_at_position`(x, y, z=None, nearest=False, starting_cell=None, starting_zone=None, zones=None, dataset=None, frame=None)

  Returns field values at a point in space.

  Note

  The position is taken according the axis assignments of the `Frame` which may be any of the associated variables in the `Dataset` and not necessarily `(X, Y, Z)`. See: `Cartesian3DFieldAxis.variable`.

  Parameters: | x,y,z (`float`, z is optional) – position to probe for field values. nearest (`bool`) – Returns the values at the nearest node to the given position. starting_cell (3-`tuple` of `integers`, optional) – The `(i,j,k)`-index of the cell to start looking for the given position. This must be used with `starting_zone`. starting_zone (Zone, required only when `starting_cell` is given) – The first zone to start searching. zones (`list` of Zones, optional) – Limits the search to the given zones. `None` implies searching all zones. (default: `None`) dataset (`Dataset`, optional) – The `Dataset` to probe. (defaults to the active `Dataset`.) frame (`Frame`, optional) – The `Frame` which determines the spatial variable assignment `(X,Y,Z)`. (defaults to the active `Frame`.)
  Returns: | `namedtuple` – `(data, cell, zone)`: `data` (`list` of `floats`) The values of each variable in the dataset at the given position. `cell` (3-`tuple` of `integers`) `(i,j,k)` of the cell containing the given position. `zone` (Zone) Zone containing the given position

## Data Operations

`tecplot.data.operate.``Range`(min, max, step)

  Limit the data altered by the `execute_equation` function.

  The Range specification of I,J,K range indices for `execute_equation` follow these rules:

  > - All indices start with 0 and go to some maximum index m.
  > - Negative values represent the indexes starting with the maximum at -1 and continuing back to the beginning of the range.
  > - A step of None, 0 and 1 are all equivalent and mean that no elements are skipped.
  > - A negative step indicates a skip less than the maximum.

  Example

  Add one to variable ‘X’ for a zone ‘Rectangular’ for data points in I Range 1 to max, skipping every three points:

      >>> execute_equation('{X} = {X}+1', i_range=Range(min=1, max=None, step=3),
      ...                  zone_set='Rectangular')

`tecplot.data.operate.``execute_equation`(equation, zones=None, i_range=None, j_range=None, k_range=None, value_location=None, variable_data_type=None, ignore_divide_by_zero=None)

  The execute_equation function operates on a data set within the Tecplot Engine using FORTRAN-like equations.

  Parameters: | equation (`string`) – String containing the equation. Multiple equations can be processed by separating each equation with a newline. See Section 20 - 1 “Data Alteration through Equations” in the Tecplot User’s Manual for more information on using equations. Iterable container of Zone objects to operate on. May be a list, set, tuple, or any iterable container. If `None`, the equation will be applied to all zones. Note In the equation string, variable names should be enclosed in curly braces. For example, ‘{X} = {X} + 1’ zones – (Iterable container of Zone objects, optional): Iterable container of Zone objects to operate on. May be a list, set, tuple, or any iterable container. If `None`, the equation will be applied to all zones. i_range (`Range`, optional) – Tuple of integers for I: (min, max, step). If `None`, then the equation will operate on the entire range. Not used for finite element nodal data. j_range (`Range`, optional) – Tuple of integers for J: (min, max, step). If `None`, then the equation will operate on the entire range. Not used for finite element nodal data. k_range (`Range`, optional) – Tuple of integers for K: (min, max, step). If `None`, then the equation will operate on the entire range. Not used for finite element nodal data. value_location (`ValueLocation`, optional) – Variable `ValueLocation` for the variable on the left hand side. This is used only if this variable is being created for the first time. If `None`, Tecplot Engine will choose the location for you. variable_data_type (`FieldDataType`, optional) – Data type for the variable on the left hand side. This is used only if this variable is being created for the first time. If `None`, Tecplot Engine will choose the type for you. ignore_divide_by_zero (`bool`, optional) – `bool` value which instructs Tecplot Engine to ignore divide by zero errors. The result is clamped such that 0/0 is clamped to zero and (+/-N)/0 where N != 0 clamps to +/-maximum value for the given type.
  Raises: | `TecplotSystemError`

  Warning

  Zero-based Indexing

  It is important to know that all indexing in PyTecplot scripts are zero-based. This is a departure from the macro language which is one-based. This is to keep with the expectations when working in the python language. However, PyTecplot does not modify strings that are passed to the Tecplot Engine. This means that one-based indexing should be used when running macro commands from python or when using `execute_equation()`.

  Add one to variable ‘X’ for zones ‘Rectangular’ and ‘Circular’ for every data point: >>> import tecplot >>> dataset = tecplot.active_frame().dataset >>> execute_equation(‘{X} = {X} + 1’, zones=[dataset.zone(‘Rectangular’), >>> dataset.zone(‘Circular’)])

  Create a new, double precision variable called DIST:

      >>> execute_equation('{DIST} = SQRT({X}**2 + {Y}**2)',
      ...                  variable_data_type=FieldDataType.double)

  Set a variable called P to zero along the boundary of an IJ-ordered zone:

      >>> execute_equation('{P} = 0', i_range=Range(step=-1))
      >>> execute_equation('{P} = 0', j_range=Range(step=-1))

## Data Access

- Dataset
- Variable
- Zones
  - OrderedZone
  - ClassicFEZone
  - PolyFEZone
- Array
- Nodemap
- Facemap
- FaceNeighbors

### Dataset

class `tecplot.data.``Dataset`(uid, frame)

  A table of `Arrays` identified by Zone and `Variable`.

  This is the primary data container within the Tecplot Engine. A `Dataset` can be shared among several `Frames`, though any particular `Dataset` object will have a handle to at least one of them. Any modification of a shared `Dataset` will be reflected in all `Frames` that use it.

  Though a `Dataset` is usually attached to a `Frame` and the plot style associated with that, it can be thought of as independent from any style or plotting representation. Each `Dataset` consists of a list of `Variables` which are used by one or more of a list of Zones. The `Variable` determines the data type while the Zone determines the layout such as shape and ordered vs unordered.

  The actual data are found at the intersection of a Zone and `Variable` and the resulting object is an `Array`. The data array can be obtained using either path:

      >>> # These two lines obtain the same object "x"
      >>> x = dataset.zone('My Zone').values('X')
      >>> x = dataset.variable('X').values('My Zone')

  A `Dataset` is the object returned by most data-loading operations in PyTecplot:

      >>> dataset = tecplot.data.load_tecplot('my_data.plt')

  Under `Dataset`, there are a number methods to create and delete Zones and `variables`.

  Attributes

  `VariablesNamedTuple` | A `collections.namedtuple` object using variable names.
  `num_variables` | Number of `Variables` in this `Dataset`.
  `num_zones` | Number of Zones in this `Dataset`.
  `title` | Title of this `Dataset`.

  Methods

  `add_fe_zone`(zone_type, name, num_points, ...) | Add a single finite-element Zone to this `Dataset`.
  `add_ordered_zone`(name, shape, **kwargs) | Add a single ordered Zone to this `Dataset`.
  `add_poly_zone`(zone_type, name, num_points, ...) | Add a single polygonal Zone to this `Dataset`.
  `add_variable`(name[, dtypes, locations]) | Add a single `Variable` to the active `Dataset`.
  `add_zone`(zone_type, name, shape[, dtypes, ...]) | Add a single Zone to this `Dataset`.
  `copy_zones`(*zones) | Copies Zones within this `Dataset`.
  `delete_variables`(*variables) | Remove `Variables` from this `Dataset`.
  `delete_zones`(*zones) | Remove Zones from this `Dataset`.
  `variable`(pattern) | Returns the `Variable` by index or string pattern.
  `variables`([pattern]) | Yields all `Variables` matching a pattern.
  `zone`(pattern) | Returns Zone by index or string pattern.
  `zones`([pattern]) | Yields all Zones matching a pattern.

`Dataset.``VariablesNamedTuple`

  A `collections.namedtuple` object using variable names.

  The variable names are transformed to be unique, valid identifiers suitable for use as the key-list for a `collections.namedtuple`. This means that all invalid characters such as spaces and dashes are converted to underscores, Python keywords are appended by an underscore, leading numbers or empty names are prepended with a “v” and duplicate variable names are indexed starting with zero, padded left with zeros variable names duplicated more than nine times. The following table gives some specific examples:

  > Variable names | Resulting namedtuple fields
  > --- | ---
  > `'x', 'y'` | `'x', 'y'`
  > `'x', 'x'` | `'x0', 'x1'`
  > `'X', 'Y=f(X)'` | `'X', 'Y_f_X_'`
  > `'x 2', '_', '_'` | `'x_2', 'v0', 'v1'`
  > `'def', 'if'` | `'def_', 'if_'`
  > `'1', '2', '3'` | `'v1', 'v2', 'v3'`

  This example shows how one can use this n-tuple type with the result from a call to `tecplot.data.query.probe_at_position`:

      >>> from os import path
      >>> import tecplot as tp
      >>> examples_dir = tp.session.tecplot_examples_directory()
      >>> datafile = path.join(examples_dir,'3D_Volume','jetflow.plt')
      >>> dataset = tp.data.load_tecplot(datafile)
      >>> result = tp.data.query.probe_at_position(0,0.1,0.3)
      >>> data = dataset.VariablesNamedTuple(*result.data)
      >>> msg = '(RHO, E) = ({:.2f}, {:.2f})'
      >>> print(msg.format(data.RHO, data.E))
      (RHO, E) = (1.17, 252930.37)

`Dataset.``add_fe_zone`(zone_type, name, num_points, num_elements, **kwargs)

  Add a single finite-element Zone to this `Dataset`.

  Parameters: | zone_type (`ZoneType`) – The type of Zone to be created. Possible values are: `FETriangle`, `FEQuad`, `FETetra`, `FEBrick` and `FELineSeg`. name (`string`) – Name of the new Zone. This does not have to be unique. num_points (`integer`) – Number of points (nodes) in this zone. num_elements (`integer`) – Number of elements in this zone. The nodemap will have the shape (num_points, num_elements). **kwargs – These arguments are passed to `Dataset.add_zone`.

  See also

  `Dataset.add_zone`

  Keyword arguments are passed to the parent zone creation method `Dataset.add_zone`.

  The number of points (also known as nodes) per finite-element is determined from the `zone_type` parameter. The follow table shows the number of points per element for the available zone types along with the resulting shape of the nodemap based on the number of points specified (\(N\)):

  > Zone Type | Points/Element | Nodemap Shape
  > --- | --- | ---
  > `FELineSeg` | 2 | (\(N\), \(2 N\))
  > `FETriangle` | 3 | (\(N\), \(3 N\))
  > `FEQuad` | 4 | (\(N\), \(4 N\))
  > `FETetra` | 4 | (\(N\), \(4 N\))
  > `FEBrick` | 8 | (\(N\), \(8 N\))

`Dataset.``add_ordered_zone`(name, shape, **kwargs)

  Add a single ordered Zone to this `Dataset`.

  Parameters: | name (`string`) – Name of the new Zone. This does not have to be unique. shape (`integer` or `list` of `integers`) – Specifies the length and dimension (i, j, k) of the new Zone. A 1D Zone is assumed if a single `int` is given. **kwargs – These arguments are passed to `Dataset.add_zone`.

  See also

  `Dataset.add_zone`

  Keyword arguments are passed to the parent zone creation method `Dataset.add_zone`.

  This example creates a 10x10x10 ordered zone of double-precision floating-point numbers:

      >>> from tecplot.constant import FieldDataType
      >>> my_zone = dataset.add_zone('My Zone', (10, 10, 10),
      ...                            dtype=FieldDataType.Double)

  Here is a full example:

      import numpy as np
      import tecplot as tp
      from tecplot.constant import PlotType, Color

      # Generate data
      x = np.linspace(-4, 4, 100)

      # Setup Tecplot dataset
      dataset = tp.active_frame().create_dataset('Data', ['x', 'y'])

      # Create a zone
      zone = dataset.add_ordered_zone('sin(x)', len(x))
      zone.values('x')[:] = x
      zone.values('y')[:] = np.sin(x)

      # Create another zone
      zone = dataset.add_ordered_zone('cos(x)', len(x))
      zone.values('x')[:] = x
      zone.values('y')[:] = np.cos(x)

      # And one more zone
      zone = dataset.add_ordered_zone('tan(x)', len(x))
      zone.values('x')[:] = x
      zone.values('y')[:] = np.tan(x)

      # Set plot type to XYLine
      plot = tp.active_frame().plot(PlotType.XYLine)
      plot.activate()

      # Show all linemaps and make the lines a bit thicker
      for lmap in plot.linemaps():
          lmap.show = True
          lmap.line.line_thickness = 0.6

      plot.legend.show = True

      tp.export.save_png('add_ordered_zones.png', 600)

`Dataset.``add_poly_zone`(zone_type, name, num_points, num_elements, num_faces, **kwargs)

  Add a single polygonal Zone to this `Dataset`.

  Parameters: | zone_type (`ZoneType`) – The type of Zone to be created. Possible values are: `FEPolyhedron` and `FEPolygon`. name (`string`) – Name of the new Zone. This does not have to be unique. num_points (`integer`) – Number of points in this zone. num_elements (`integer`) – Number of elements in this zone. num_faces (`integer`) – Number of faces in this zone. **kwargs – These arguments are passed to `Dataset.add_zone`.

  See also

  `Dataset.add_zone`

  Keyword arguments are passed to the parent zone creation method `Dataset.add_zone`.

`Dataset.``add_variable`(name, dtypes=None, locations=None)

  Add a single `Variable` to the active `Dataset`.

  Parameters: | name (`string`) – The name of the new `Variable`. This does not have to be unique. dtypes (`FieldDataType` or `list` of `FieldDataType`, optional) – Data types of this `Variable` for each Zone in the currently active `Dataset`. Options are: `FieldDataType.Float`, `Double`, `Int32`, `Int16`, `Byte` and `Bit`. If a single value, this will be duplicated for all Zones. (default: `None`) locations (`ValueLocation` or `list` of `ValueLocation`, optional) – Point locations of this `Variable` for each Zone in the currently active `Dataset`. Options are: `Nodal` and `CellCentered`. If a single value, this will be duplicated for all Zones. (default: `None`)
  Returns: | `Variable`

  The added `Variable` will be available for use in each Zone of the dataset. This method should be used in conjunction with other data creation methods such as `Dataset.add_zone`:

      import math
      import tecplot as tp
      from tecplot.constant import PlotType

      # Setup Tecplot dataset
      dataset = tp.active_frame().create_dataset('Data')
      dataset.add_variable('x')
      dataset.add_variable('s')
      zone = dataset.add_ordered_zone('Zone', 100)

      # Fill the dataset
      x = [0.1 * i for i in range(100)]
      zone.values('x')[:] = x
      zone.values('s')[:] = [math.sin(i) for i in x]

      # Set plot type to XYLine
      tp.active_frame().plot(PlotType.XYLine).activate()

      tp.export.save_png('add_variables.png', 600)

`Dataset.``add_zone`(zone_type, name, shape, dtypes=None, locations=None, parent_zone=None, solution_time=None, strand_id=None, index=None)

  Add a single Zone to this `Dataset`.

  Parameters: | zone_type (`ZoneType`) – The type of Zone to be created. Possible values are: `Ordered`, `FETriangle`, `FEQuad`, `FETetra`, `FEBrick`, `FELineSeg`, `FEPolyhedron` and `FEPolygon`. name (`string`) – Name of the new Zone. This does not have to be unique. shape (`integer` or `list` of `integers`) – Specifies the length and dimension (up to three) of the new Zone. A 1D Zone is assumed if a single `int` is given. This is (i, j, k) for ordered Zones, (num_points, num_elements) for finite-element Zones and (num_points, num_elements, num_faces) for polytope Zones where the number of faces is known. dtypes (`FieldDataType`, `list` of `FieldDataType`, optional) – Data types of this Zone for each `Variable` in the currently active `Dataset`. Options are: `Float`, `Double`, `Int32`, `Int16`, `Byte` and `Bit`. If a single value, this will be duplicated for all `Variables`. If `None` then the type of the first `Variable`, defaulting to `FieldDataType.Float`, is used for all. (default: `None`) locations (`ValueLocation`, `list` of `ValueLocation`, optional) – Point locations of this Zone for each `Variable` in the currently active `Dataset`. Options are: `Nodal` and `CellCentered`. If a single value, this will be duplicated for all `Variables`. If `None` then the type of the first `Variable`, defaulting to `Nodal`, is used for all. (default: `None`) parent_zone (Zone, optional) – A parent Zone to be used when generating surface-restricted streamtraces. solution_time (`float`, optional) – Solution time for this zone. (default: 0) strand_id (`integer`, optional) – Associate this new Zone with a particular strand. index (`integer`, optional) – Number of the zone to add or replace. If omitted or set to `None`, the new zone will be appended to the dataset. This value can be set to the number of a zone that already exists thereby replacing the existing zone. (default: `None`)

  Returns: Zone

  The added Zone will be able to use all `Variables` defined in the dataset. This method should be used in conjunction with other data creation methods such as `Frame.create_dataset`. Example usage:

      >>> from tecplot.constant import ZoneType
      >>> zone = dataset.add_zone(ZoneType.Ordered, 'Zone', (10, 10, 10))

  Note

  The relationship and meaning of this method’s parameters change depending on the type of zone being created. Therefore, it is recommended to use the more specific zone creation methods:

  > - `Dataset.add_ordered_zone`
  > - `Dataset.add_fe_zone`
  > - `Dataset.add_poly_zone`

`Dataset.``copy_zones`(*zones)

  Copies Zones within this `Dataset`.

  Parameters: | zones (Zone, optional) – Specific Zones to copy. All zones will be copied if none are supplied.

  Returns: `list` of the newly created Zones.

  Example usage:

      >>> new_zones = dataset.copy_zones()

`Dataset.``delete_variables`(*variables)

  Remove `Variables` from this `Dataset`.

  Parameters: | *variables (`Variable` or index `integer`) – Variables to remove from this dataset.

      >>> print([v.name for v in dataset.variables()])
      ['X','Y','Z']
      >>> dataset.delete_variables(dataset.variable('Z'))
      >>> print([v.name for v in dataset.variables()])
      ['X','Y']

  Notes

  Multiple `Variables` can be deleted at once, though the last `Variable` can not be deleted. This command deletes all but the first `Variable` in the `Dataset` (usually `X`):

      >>> # Try to delete all variables:
      >>> dataset.delete_variables(dataset.variables())
      >>> # Dataset requires at least one variable to
      >>> # exist, so it leaves the first one:
      >>> print([v.name for v in dataset.variables()])
      ['X']

`Dataset.``delete_zones`(*zones)

  Remove Zones from this `Dataset`.

  Parameters: | *zones (Zones or index `integers`) – Zones to remove from this dataset.

      >>> print([z.name for z in dataset.zones()])
      ['Zone 1', 'Zone 2']
      >>> dataset.delete_zones(dataset.zone('Zone 2'))
      >>> print([z.name for z in dataset.zones()])
      ['Zone 1']

  Notes

  Multiple Zones can be deleted at once, though the at least one Zone must remain. This command deletes all but the first Zone in the `Dataset`:

      >>> dataset.delete_zones(dataset.zones())

`Dataset.``num_variables`

  Number of `Variables` in this `Dataset`.

  Type: | `integer`

  This count includes disabled variables which were skipped when the data was loaded. Example usage:

      >>> for i in range(dataset.num_variables):
      ...     variable = dataset.variable(i)

`Dataset.``num_zones`

  Number of Zones in this `Dataset`.

  Type: | `integer`

  This count includes disabled zones which were skipped when loading the data. Example usage:

      >>> for i in range(dataset.num_zones):
      ...     zone = dataset.zone(i)

`Dataset.``title`

  Title of this `Dataset`.

  Type: | `string`

  Example usage:

      >>> dataset.title = 'My Data'

`Dataset.``variable`(pattern)

  Returns the `Variable` by index or string pattern.

  Parameters: | pattern (`integer` or `string`) – Zero-based index or `glob-style pattern` in which case, the first match is returned.
  Raises: | `TecplotIndexError`

  The `Variable.name` attribute is used to match the pattern to the desired `Variable` though this is not necessarily unique:

      >>> ds = frame.dataset
      >>> print(ds)
      Dataset:
        Zones: ['Rectangular zone']
        Variables: ['x', 'y', 'z']
      >>> x = ds.variable('x')
      >>> x == ds.variable(0)
      True

`Dataset.``variables`(pattern=None)

  Yields all `Variables` matching a pattern.

  Parameters: | pattern (`string` pattern, optional) – `glob-style pattern` used to match variable names or `None` which will return all variables. (default: `None`)

  Example usage:

      >>> for variable in dataset.variables('A*'):
      ...     array = variable.values('My Zone')

`Dataset.``zone`(pattern)

  Returns Zone by index or string pattern.

  Parameters: | pattern (`integer` or `string`) – Zero-based index or `glob-style pattern` in which case, the first match is returned.
  Returns: | `OrderedZone`, `ClassicFEZone` or `PolyFEZone` depending on the zone type.
  Raises: | `TecplotIndexError`

  The `Zone.name` attribute is used to match the pattern to the desired Zone though this is not necessarily unique:

      >>> ds = frame.dataset
      >>> print(ds)
      Dataset:
        Zones: ['Rectangular zone']
        Variables: ['x', 'y', 'z']
      >>> rectzone = ds.zone('Rectangular zone')
      >>> rectzone == ds.zone(0)
      True

`Dataset.``zones`(pattern=None)

  Yields all Zones matching a pattern.

  Parameters: | pattern (`string` pattern, optional) – `glob-style pattern` used to match zone names or `None` which will return all zones. (default: `None`)
  Yields: | `OrderedZone`, `ClassicFEZone` or `PolyFEZone` depending on the zone type.

  Example usage:

      >>> for zone in dataset.zones('A*'):
      ...     x_array = zone.variable('X')

### Variable

class `tecplot.data.``Variable`(uid, dataset)

  Key value for a data array within a `Dataset`.

  `Variables` can be identified (uniquely) by the index within their parent `Dataset` or (non-uniquely) by name. In general, a Zone must also be selected to access the underlying data array. This object is used by several style controlling classes such as contours and vectors. The following example sets the contour variable for the first contour group to the first variable named ‘S’:

      >>> plot.contour(0).variable = dataset.variable('S')

  Attributes

  `index` | Zero-based position within the parent `Dataset`.
  `name` | Returns or sets the name.
  `num_zones` | Number of Zones in the parent `Dataset`.

  Methods

  `values`(pattern) | Returns `Array` by index or string pattern.

`Variable.``index`

  Zero-based position within the parent `Dataset`.

  Type: | `Index`

  Example usage:

      >>> plot.contour(0).variable_index = dataset.variable('S').index

`Variable.``name`

  Returns or sets the name.

  Type: | `string`

  Example usage:

      >>> print(dataset.variable(0).name)
      X

`Variable.``num_zones`

  Number of Zones in the parent `Dataset`.

  Type: | `integer`

  Example usage, looping over all zones by index:

      >>> for zindex in range(dataset.num_zones):
      ...     zone = dataset.zone(zindex)

`Variable.``values`(pattern)

  Returns `Array` by index or string pattern.

  Parameters: | pattern (`integer` or `string`) – Zero-based index or `glob-style pattern` in which case, the first match is returned.

  The `Zone.name` attribute is used to match the pattern to the desired `Array` though this is not necessarily unique:

      >>> ds = frame.dataset
      >>> print(ds)
      Dataset:
        Zones: ['Rectangular zone']
        Variables: ['x', 'y', 'z']
      >>> x = ds.variable('x')
      >>> rectzone = x.values('Rectangular zone')
      >>> rectzone == x.values(0)
      True

### Zones

- OrderedZone
- ClassicFEZone
- PolyFEZone

#### OrderedZone

class `tecplot.data.``OrderedZone`(uid, dataset)

  An ordered `(i, j, k)` zone within a `Dataset`.

  Ordered zones contain nodal or cell-centered arrays where the connectivity is implied by the dimensions and ordering of the data.

  Zones can be identified (uniquely) by the index with their parent `Dataset` or (non-uniquely) by name. In general, a `Variable` must be selected to access the underlying data array. This object is used by fieldmaps and linemaps to apply style to specific zones. Here we obtain the fieldmap associated with the zone named ‘My Zone’:

      >>> fmap = plot.fieldmap(dataset.zone('My Zone'))

  Attributes

  `dimensions` | Nodal dimensions along `(i, j, k)`.
  `index` | Zero-based position within the parent `Dataset`.
  `name` | The name of the zone.
  `num_elements` | Number of cells in this zone.
  `num_points` | Total number of nodes within this zone.
  `num_points_per_element` | Points per cell for ordered zones.
  `num_variables` | Number of `Variables` in the parent `Dataset`.
  `rank` | Number of dimensions of the data array.
  `solution_time` | The solution time for this zone.
  `strand` | The strand ID number.
  `zone_type` | The `ZoneType` indicating structure of the data contained.

  Methods

  `copy`() | Duplicate this Zone in the parent `Dataset`.
  `values`(pattern) | Returns an `Array` by index or string pattern.

`OrderedZone.``copy`()

  Duplicate this Zone in the parent `Dataset`.

  The name is copied as well but can be set after duplication:

      >>> new_zone = dataset.zone('My Zone').copy()
      >>> print(new_zone.name)
      My Zone
      >>> new_zone.name = 'My Zone Copy'
      >>> print(new_zone.name)
      My Zone Copy

`OrderedZone.``dimensions`

  Nodal dimensions along `(i, j, k)`.

  Returns: | `tuple` of `integers` – `(i, j, k)` for ordered data.

  Example usage:

      >>> print(zone.dimensions)
      (128, 128, 128)

`OrderedZone.``index`

  Zero-based position within the parent `Dataset`.

  Type: | `Index`

  This is the value used to obtain a specific zone if you have duplicately named zones in the dataset:

      >>> tp.new_layout()
      >>> frame = tp.active_frame()
      >>> dataset = frame.create_dataset('Dataset', ['x', 'y'])
      >>> dataset.add_ordered_zone('Zone', (10,10,10))
      >>> dataset.add_ordered_zone('Zone', (3,3,3))
      >>> # getting zone by name always returns first match
      >>> print(dataset.zone('Zone').index)
      0
      >>> # use index to get specific zone
      >>> print(dataset.zone(1).dimensions)
      (3, 3, 3)

`OrderedZone.``name`

  The name of the zone.

  Type: | `string`

  Example usage:

      >>> dataset.zone(0).name = 'Zone 0'

`OrderedZone.``num_elements`

  Number of cells in this zone.

  Type: | `integer`

  Example usage:

      >>> zone = dataset.zone('My Zone')
      >>> print(zone.dimensions)
      (128, 128, 128)
      >>> print(zone.num_elements)
      2048383

`OrderedZone.``num_points`

  Total number of nodes within this zone.

  Type: | `integer`

  This is number of nodes within the zone and is equivalent to the product of the values in `OrderedZone.dimensions`. Example usage:

      >>> zone = dataset.zone('My Zone')
      >>> print(zone.dimensions)
      (128, 128, 128)
      >>> print(zone.num_points)
      2097152

`OrderedZone.``num_points_per_element`

  Points per cell for ordered zones.

  Type: | `integer`

  For ordered zones, this is \(2^{d}\) where \(d\) is the number of dimensions:

      >>> zone = dataset.zone('My Zone')
      >>> print(zone.dimensions)
      (10, 10, 1)
      >>> print(zone.rank)
      2
      >>> print(zone.num_points_per_element)
      4

`OrderedZone.``num_variables`

  Number of `Variables` in the parent `Dataset`.

  Type: | `integer`

  Example usage, iterating over all variables by index:

      >>> for i in range(dataset.num_variables):
      ...     variable = dataset.variable(i)

`OrderedZone.``rank`

  Number of dimensions of the data array.

  Type: | `integer`

  This will return the number of dimensions which contain more than one value:

      >>> zone = dataset.zone('My Zone')
      >>> print(zone.dimensions)
      (10, 10, 1)
      >>> print(zone.rank)
      2

`OrderedZone.``solution_time`

  The solution time for this zone.

  Type: | `float`

  Example usage:

      >>> dataset.zone('My Zone').solution_time = 3.14

`OrderedZone.``strand`

  The strand ID number.

  Type: | `integer`

  Example usage:

      >>> dataset.zone('My Zone').strand = 2

`OrderedZone.``values`(pattern)

  Returns an `Array` by index or string pattern.

  Parameters: | pattern (`integer` or `string`) – Zero-based index or `glob-style pattern` in which case, the first match is returned.

  The `Variable.name` attribute is used to match the pattern to the desired `Array` though this is not necessarily unique:

      >>> ds = frame.dataset
      >>> print(ds)
      Dataset:
        Zones: ['Rectangular zone']
        Variables: ['x', 'y', 'z']
      >>> zone = ds.zone('Rectangular zone')
      >>> x = zone.values('x')
      >>> x == zone.values(0)
      True

`OrderedZone.``zone_type`

  The `ZoneType` indicating structure of the data contained.

  Type: | `ZoneType`

  The specific type of zone this object represents:

      >>> print(dataset.zone(0).zone_type)
      ZoneType.Ordered

#### ClassicFEZone

class `tecplot.data.``ClassicFEZone`(uid, dataset)

  A classic finite-element zone within a `Dataset`.

  Classic finite-element zones are arrays of nodes that are connected explicitly into pre-defined geometric shapes called “elements.” The geometry is consistent across the whole zone so that the number of nodes per element is constant.

  Zones can be identified (uniquely) by the index with their parent `Dataset` or (non-uniquely) by name. In general, a `Variable` must be selected to access the underlying data array. This object is used by fieldmaps and linemaps to apply style to specific zones. Here we obtain the fieldmap associated with the zone named ‘My Zone’:

      >>> fmap = plot.fieldmap(dataset.zone('My Zone'))

  Attributes

  `index` | Zero-based position within the parent `Dataset`.
  `name` | The name of the zone.
  `nodemap` | The connectivity `Nodemap` for this classic finite-element zone.
  `num_elements` | Number of cells in this finite-element zone.
  `num_points` | Total number of nodes within this zone.
  `num_points_per_element` | Points per element for classic finite-element zones.
  `num_variables` | Number of `Variables` in the parent `Dataset`.
  `rank` | Number of dimensions of the data array.
  `solution_time` | The solution time for this zone.
  `strand` | The strand ID number.
  `zone_type` | The `ZoneType` indicating structure of the data contained.

  Methods

  `copy`() | Duplicate this Zone in the parent `Dataset`.
  `values`(pattern) | Returns an `Array` by index or string pattern.

`ClassicFEZone.``copy`()

  Duplicate this Zone in the parent `Dataset`.

  The name is copied as well but can be set after duplication:

      >>> new_zone = dataset.zone('My Zone').copy()
      >>> print(new_zone.name)
      My Zone
      >>> new_zone.name = 'My Zone Copy'
      >>> print(new_zone.name)
      My Zone Copy

`ClassicFEZone.``index`

  Zero-based position within the parent `Dataset`.

  Type: | `Index`

  This is the value used to obtain a specific zone if you have duplicately named zones in the dataset:

      >>> tp.new_layout()
      >>> frame = tp.active_frame()
      >>> dataset = frame.create_dataset('Dataset', ['x', 'y'])
      >>> dataset.add_ordered_zone('Zone', (10,10,10))
      >>> dataset.add_ordered_zone('Zone', (3,3,3))
      >>> # getting zone by name always returns first match
      >>> print(dataset.zone('Zone').index)
      0
      >>> # use index to get specific zone
      >>> print(dataset.zone(1).dimensions)
      (3, 3, 3)

`ClassicFEZone.``name`

  The name of the zone.

  Type: | `string`

  Example usage:

      >>> dataset.zone(0).name = 'Zone 0'

`ClassicFEZone.``nodemap`

  The connectivity `Nodemap` for this classic finite-element zone.

  Type: | `Nodemap`

  Example usage:

      >>> zone = dataset.zone(0)
      >>> print(zone.nodemap.num_points_per_element)
      4

`ClassicFEZone.``num_elements`

  Number of cells in this finite-element zone.

  Type: | `integer`

  Example usage:

      >>> print(dataset.zone('My Zone').num_elements)
      1048576

`ClassicFEZone.``num_points`

  Total number of nodes within this zone.

  Type: | `integer`

  This is the total number of nodes in the zone. Example usage:

      >>> print(dataset.zone('My Zone').num_points)
      2048

`ClassicFEZone.``num_points_per_element`

  Points per element for classic finite-element zones.

  Type: | `integer`

  The number of points (also known as nodes) per finite-element is determined from the `zone_type` parameter. The follow table shows the number of points per element for the available zone types along with the resulting shape of the nodemap based on the number of points specified (\(N\)):

  > Zone Type | Points/Element | Nodemap Shape
  > --- | --- | ---
  > `FELineSeg` | 2 | (\(N\), \(2 N\))
  > `FETriangle` | 3 | (\(N\), \(3 N\))
  > `FEQuad` | 4 | (\(N\), \(4 N\))
  > `FETetra` | 4 | (\(N\), \(4 N\))
  > `FEBrick` | 8 | (\(N\), \(8 N\))

  Example usage:

      >>> zone = dataset.zone('My Zone')
      >>> print(zone.zone_type)
      ZoneType.FETriangle
      >>> print(zone.num_points_per_element)
      3

`ClassicFEZone.``num_variables`

  Number of `Variables` in the parent `Dataset`.

  Type: | `integer`

  Example usage, iterating over all variables by index:

      >>> for i in range(dataset.num_variables):
      ...     variable = dataset.variable(i)

`ClassicFEZone.``rank`

  Number of dimensions of the data array.

  Type: | `integer`

  This indicates the dimensionality of the data and is dependent on the type of element this zone contains:

  > Zone Type | Rank
  > --- | ---
  > `FELineSeg` | 1
  > `FETriangle` | 2
  > `FEQuad` | 2
  > `FETetra` | 3
  > `FEBrick` | 3

  Example usage:

      >>> zone = dataset.zone('My Zone')
      >>> print(zone.zone_type)
      ZoneType.FEBrick
      >>> print(zone.rank)
      3

`ClassicFEZone.``solution_time`

  The solution time for this zone.

  Type: | `float`

  Example usage:

      >>> dataset.zone('My Zone').solution_time = 3.14

`ClassicFEZone.``strand`

  The strand ID number.

  Type: | `integer`

  Example usage:

      >>> dataset.zone('My Zone').strand = 2

`ClassicFEZone.``values`(pattern)

  Returns an `Array` by index or string pattern.

  Parameters: | pattern (`integer` or `string`) – Zero-based index or `glob-style pattern` in which case, the first match is returned.

  The `Variable.name` attribute is used to match the pattern to the desired `Array` though this is not necessarily unique:

      >>> ds = frame.dataset
      >>> print(ds)
      Dataset:
        Zones: ['Rectangular zone']
        Variables: ['x', 'y', 'z']
      >>> zone = ds.zone('Rectangular zone')
      >>> x = zone.values('x')
      >>> x == zone.values(0)
      True

`ClassicFEZone.``zone_type`

  The `ZoneType` indicating structure of the data contained.

  Type: | `ZoneType`

  The specific type of zone this object represents:

      >>> print(dataset.zone(0).zone_type)
      ZoneType.FEBrick

#### PolyFEZone

class `tecplot.data.``PolyFEZone`(uid, dataset)

  A polygonal finite-element zone within a `Dataset`.

  A polygonal zone consists of arrays of nodes which are connected explicitly into arbitrary and varying geometric elements. These elements are 2D or 3D in nature and have a number of faces (connections between nodes) which hold the concept of a left and right neighbor.

  Zones can be identified (uniquely) by the index with their parent `Dataset` or (non-uniquely) by name. In general, a `Variable` must be selected to access the underlying data array. This object is used by fieldmaps and linemaps to apply style to specific zones. Here we obtain the fieldmap associated with the zone named ‘My Zone’:

      >>> fmap = plot.fieldmap(dataset.zone('My Zone'))

  Attributes

  `face_neighbors` | The face neighbor list for this polygonal finite-element zone.
  `facemap` | The connectivity `Facemap` for this polygonal finite-element zone.
  `index` | Zero-based position within the parent `Dataset`.
  `name` | The name of the zone.
  `num_elements` | Number of cells in this finite-element zone.
  `num_faces` | Number of faces in this finite-element zone.
  `num_points` | Total number of nodes within this zone.
  `num_variables` | Number of `Variables` in the parent `Dataset`.
  `rank` | Number of dimensions of the data array.
  `solution_time` | The solution time for this zone.
  `strand` | The strand ID number.
  `zone_type` | The `ZoneType` indicating structure of the data contained.

  Methods

  `copy`() | Duplicate this Zone in the parent `Dataset`.
  `create_facemap`(face_nodes, boundary_faces, ...) | Allocate space for the facemap.
  `values`(pattern) | Returns an `Array` by index or string pattern.

`PolyFEZone.``copy`()

  Duplicate this Zone in the parent `Dataset`.

  The name is copied as well but can be set after duplication:

      >>> new_zone = dataset.zone('My Zone').copy()
      >>> print(new_zone.name)
      My Zone
      >>> new_zone.name = 'My Zone Copy'
      >>> print(new_zone.name)
      My Zone Copy

`PolyFEZone.``create_facemap`(face_nodes, boundary_faces, boundary_connections)

  Allocate space for the facemap.

  Parameters: | face_nodes (`int`) – Total number of nodes for all faces. This is not the number of unique nodes but the total number. For example if a facemap defines two triangle polygons that share a common face, `faces` would be 5 and `face_nodes` would be 6, not 4. boundary_faces (`int`) – Total number of boundary faces. boundary_connections (`int`) – Total number of boundary face elements or boundary face element/zone pairs.

  If the zone does not already have space allocated for a facemap, then this must be called before accessing it:

      >>> zone.create_facemap(400, 25, 50)
      >>> facemap = zone.facemap

`PolyFEZone.``face_neighbors`

  The face neighbor list for this polygonal finite-element zone.

  Type: | `FaceNeighbors`

  Example usage:

      >>> zone = dataset.zone(0)
      >>> print(zone.face_neighbors.mode)
      FaceNeighborMode.LocalOneToMany

`PolyFEZone.``facemap`

  The connectivity `Facemap` for this polygonal finite-element zone.

  Type: | `Facemap`

  Example usage:

      >>> zone = dataset.zone(0)
      >>> print(zone.facemap.num_faces)
      4500

`PolyFEZone.``index`

  Zero-based position within the parent `Dataset`.

  Type: | `Index`

  This is the value used to obtain a specific zone if you have duplicately named zones in the dataset:

      >>> tp.new_layout()
      >>> frame = tp.active_frame()
      >>> dataset = frame.create_dataset('Dataset', ['x', 'y'])
      >>> dataset.add_ordered_zone('Zone', (10,10,10))
      >>> dataset.add_ordered_zone('Zone', (3,3,3))
      >>> # getting zone by name always returns first match
      >>> print(dataset.zone('Zone').index)
      0
      >>> # use index to get specific zone
      >>> print(dataset.zone(1).dimensions)
      (3, 3, 3)

`PolyFEZone.``name`

  The name of the zone.

  Type: | `string`

  Example usage:

      >>> dataset.zone(0).name = 'Zone 0'

`PolyFEZone.``num_elements`

  Number of cells in this finite-element zone.

  Type: | `integer`

  Example usage:

      >>> print(dataset.zone('My Zone').num_elements)
      1048576

`PolyFEZone.``num_faces`

  Number of faces in this finite-element zone.

  Type: | `integer`

  The number of faces may be `0` if unknown or facemap creation is deferred. Example usage:

      >>> print(dataset.zone('My Zone').num_faces)
      1048576

`PolyFEZone.``num_points`

  Total number of nodes within this zone.

  Type: | `integer`

  This is the total number of nodes in the zone. Example usage:

      >>> print(dataset.zone('My Zone').num_points)
      2048

`PolyFEZone.``num_variables`

  Number of `Variables` in the parent `Dataset`.

  Type: | `integer`

  Example usage, iterating over all variables by index:

      >>> for i in range(dataset.num_variables):
      ...     variable = dataset.variable(i)

`PolyFEZone.``rank`

  Number of dimensions of the data array.

  Type: | `integer`

  This indicates the dimensionality of the data and is dependent on the type of element this zone contains:

  > Zone Type | Rank
  > --- | ---
  > `FEPolygon` | 2
  > `FEPolyhedron` | 3

  Example usage:

      >>> zone = dataset.zone('My Zone')
      >>> print(zone.zone_type)
      ZoneType.FEPolygon
      >>> print(zone.rank)
      2

`PolyFEZone.``solution_time`

  The solution time for this zone.

  Type: | `float`

  Example usage:

      >>> dataset.zone('My Zone').solution_time = 3.14

`PolyFEZone.``strand`

  The strand ID number.

  Type: | `integer`

  Example usage:

      >>> dataset.zone('My Zone').strand = 2

`PolyFEZone.``values`(pattern)

  Returns an `Array` by index or string pattern.

  Parameters: | pattern (`integer` or `string`) – Zero-based index or `glob-style pattern` in which case, the first match is returned.

  The `Variable.name` attribute is used to match the pattern to the desired `Array` though this is not necessarily unique:

      >>> ds = frame.dataset
      >>> print(ds)
      Dataset:
        Zones: ['Rectangular zone']
        Variables: ['x', 'y', 'z']
      >>> zone = ds.zone('Rectangular zone')
      >>> x = zone.values('x')
      >>> x == zone.values(0)
      True

`PolyFEZone.``zone_type`

  The `ZoneType` indicating structure of the data contained.

  Type: | `ZoneType`

  The specific type of zone this object represents:

      >>> print(dataset.zone(0).zone_type)
      ZoneType.FEPolygon

### Array

class `tecplot.data.``Array`(zone, variable)

  Low-level accessor for underlying data within a `Dataset`.

  Note

  The data manipulation context referred to below is currently being developed and should show up in an up-coming revision.

  This object exposes a list-like interface to the underlying data array. Using it, values can be directly queried and modified. After any modification to the data, the Tecplot Engine will have to be notified of the change. This notification will happen automatically in most cases, but can be turned off using the data manipulation context for a significant performance increase on large datasets.

  Accessing values within an `Array` is done through the standard `[]` syntax:

      >>> print(array[3])
      3.1415

  The numbers passed are interpreted just like Python’s built-in `slice` object:

      >>> # print the values at indices: 5, 7, 9
      >>> print(array[5:10:2])
      [1.0, 1.0, 1.0]

  Elements within an array can be manipulated in-place with the assignment operator:

      >>> array[3] = 5.0
      >>> print(array[3])
      5.0

  Element-by-element access is not guaranteed to be performant and users should avoid writing loops over indices in Python. Instead, whole arrays should be used. This will effectively push the loop down to the underlying native library and will be much faster in virtually all cases.

  Consider this array of 10k elements:

      >>> import tecplot as tp
      >>> ds = tp.active_frame().create_dataset('Dataset', ['x'])
      >>> zn = ds.add_ordered_zone('Zone', 10000)
      >>> array = zn.values('x')

  The following loop, which takes the sine of all values in the array will require several Python function calls per element which is a tremendous overhead:

      >>> import math
      >>> for i in range(len(ar)):
      ...     ar[i] = math.sin(ar[i])

  An immediate improvement on this can be made by looping over the elements in Python only when reading the values, but assigning them using the whole array. This will be several times faster for even modest arrays:

      >>> ar[:] = [math.sin(x) for x in ar]

  But there is still a large performance penalty for looping over elements directly in Python and PyTecplot supports two solutions for large arrays: `tecplot.data.operate.execute_equation` and `tecplot.extension.numpy`. Please refer to these for details. Continuing with the example above, we could accomplish the same thing with either of the following using `execute_equation` (assuming the array is identified by the first zone, first variable):

      >>> from tecplot.data.operate import execute_equation
      >>> execute_equaion('V1 = SIN(V1)', zones=[dataset.zone(0)])

  or by using the `numpy` library:

      >>> import numpy as np
      >>> ar[:] = np.sin(ar[:])

  In both of these cases, the calculation of the sine and loop over elements is pushed to the low level library and is much faster.

  Attributes

  `c_type` | `ctypes` compatible data type of this array.
  `data_type` | `FieldDataType` indicating the underlying value type of this array.
  `location` | The location of the data points with respect to the elements.
  `max` | Upper bound of the values stored in this array.
  `min` | Lower bound of the values stored in this array.
  `minmax` | Limits of the values stored in this array.
  `shape` | `(i, j, k)` shape for this array.
  `size` | The number of values in this array.

  Methods

  `as_numpy_array`(arr) |
  `copy`([offset, size]) | Copy the whole or part of the array into a ctypes array.

`Array.``as_numpy_array`(arr)

`Array.``c_type`

  `ctypes` compatible data type of this array.

  This is the `ctypes` equivalent of `Array.data_type` and will return one of the following:

  > - `ctypes.c_float`
  > - `ctypes.c_double`
  > - `ctypes.c_int`
  > - `ctypes.c_int16`
  > - `ctypes.c_int8`

  and can be used to create a `ctypes` array to store a copy of the data:

      import tecplot as tp
      frame = tp.active_frame()
      dataset = frame.create_dataset('Dataset', ['x'])
      dataset.add_ordered_zone('Zone', (3,3,3))
      x = dataset.zone('Zone').values('x')
      # allocate array using Python's ctypes
      x_array = (x.c_type * x.size)()
      # copy values from Dataset into ctypes array
      x_array[:] = x[:]

`Array.``copy`(offset=0, size=None)

  Copy the whole or part of the array into a ctypes array.

  Parameters: | offset (`integer`, optional) – Zero-based offset for starting index to copy. (default: 0) size (`integer`, optional) – Number of values to copy into the resulting array. A value of `None` will copy to the end of the array. (default: `None`)

  Here we will copy out chunks of the data, do some operation and set the values back into the dataset:

      >>> import tecplot as tp
      >>> tp.new_layout()
      >>> frame = tp.active_frame()
      >>> dataset = frame.create_dataset('Dataset', ['x'])
      >>> dataset.add_ordered_zone('Zone', (2, 2, 2))
      >>> x = dataset.zone('Zone').values('x')
      >>> # loop over array copying out 4 values at a time
      >>> for i, offset in enumerate(range(0, x.size, 4)):
      ...     x_array = x.copy(offset, 4)
      ...     x_array[:] = [i] * 4
      ...     x[offset:offset + 4] = x_array
      >>> print(x[:])
      [0.0, 0.0, 0.0, 0.0, 1.0, 1.0, 1.0, 1.0]

`Array.``data_type`

  `FieldDataType` indicating the underlying value type of this array.

  Type: | `FieldDataType`

  Example usage:

      >>> print(dataset.zone('Zone').values('X').data_type)
      FieldDataType.Float

`Array.``location`

  The location of the data points with respect to the elements.

  Type: | `ValueLocation`

  Possible values are `ValueLocation.CellCentered` and `ValueLocation.Nodal`. Example usage:

      >>> print(dataset.variable('X').zone(0).location)
      ValueLocation.Nodal

`Array.``max`

  Upper bound of the values stored in this array.

  Type: | `float`

  This always returns a `float` regardless of the underlying data type:

      >>> print(dataset.zone('Zone').values('x').max)
      10

`Array.``min`

  Lower bound of the values stored in this array.

  Type: | `float`

  This always returns a `float` regardless of the underlying data type:

      >>> print(dataset.zone('Zone').values('x').min)
      0

`Array.``minmax`

  Limits of the values stored in this array.

  Type: | 2-tuple of `floats`

  This always returns `floats` regardless of the underlying data type:

      >>> print(dataset.zone('Zone').values('x').minmax)
      (0, 10)

`Array.``shape`

  `(i, j, k)` shape for this array.

  Type: | `tuple` of `floats`

  This is defined by the parent zone and can be used to reshape arrays. The following example assumes 32-bit floating point array and copies the Tecplot-owned `data` into the `numpy`-owned `array`:

      >>> import numpy as np
      >>> data = dataset.zone('Zone').values('X')
      >>> array = np.empty(data.shape, dtype=np.float32)
      >>> arr_ptr = array.ctypes.data_as(POINTER(data.c_type))
      >>> memmove(arr_ptr, data.copy(), sizeof(data.c_type) * data.size)

  The data array presented is normally one-dimensional. For ordered data, you may wish to reshape the array indexing according to the dimensionality given by the `shape` attribute:

      >>> import numpy as np
      >>> import tecplot as tp
      >>> frame = tp.active_frame()
      >>> dataset = frame.create_dataset('Dataset', ['x'])
      >>> zone = dataset.add_ordered_zone('Zone', shape=(3,3,3))
      >>> x = np.array(zone.values('X')[:])
      >>> print(x)
      [ 0.  0.  0.  0.  0.  0.  0.  0.  0.  0.  0.  0.  0.  0.
        0.  0.  0.  0.  0.  0.  0.  0.  0.  0.  0.  0.  0.]
      >>> x.shape = zone.values('X').shape
      >>> print(x)
      [[[ 0.  0.  0.]
        [ 0.  0.  0.]
        [ 0.  0.  0.]]

       [[ 0.  0.  0.]
        [ 0.  0.  0.]
        [ 0.  0.  0.]]

       [[ 0.  0.  0.]
        [ 0.  0.  0.]
        [ 0.  0.  0.]]]

`Array.``size`

  The number of values in this array.

  Type: | `integer`

  Example showing size of ordered data:

      >>> x = dataset.zone('Zone').values('X')
      >>> print(x.shape)
      (10, 10, 10)
      >>> print(x.size)
      1000

### Nodemap

class `tecplot.data.``Nodemap`(zone)

  Connectivity list definition and control.

  Nodemap access in PyTecplot is a work in progress. While we provide some functionality, it sould be considered “beta” quality at best.

  Attributes

  `c_type` |
  `num_points_per_element` | Points per element for classic finite-element zones.
  `shape` |

  Methods

  `copy`() |

`Nodemap.``c_type`

`Nodemap.``copy`()

`Nodemap.``num_points_per_element`

  Points per element for classic finite-element zones.

  Type: | `integer`

  The number of points (also known as nodes) per finite-element is determined from the `zone_type` parameter. The following table shows the number of points per element for the available zone types along with the resulting shape of the nodemap based on the number of points specified (\(N\)):

  > Zone Type | Points/Element | Nodemap Shape
  > --- | --- | ---
  > `FELineSeg` | 2 | (\(N\), \(2 N\))
  > `FETriangle` | 3 | (\(N\), \(3 N\))
  > `FEQuad` | 4 | (\(N\), \(4 N\))
  > `FETetra` | 4 | (\(N\), \(4 N\))
  > `FEBrick` | 8 | (\(N\), \(8 N\))

  Example usage:

      >>> zone = dataset.zone('My Zone')
      >>> print(zone.zone_type)
      ZoneType.FETriangle
      >>> print(zone.nodemap.num_points_per_element)
      3

`Nodemap.``shape`

### Facemap

class `tecplot.data.``Facemap`(zone)

  Connectivity list definition and control.

  Facemap access in PyTecplot is a work in progress. While we provide some functionality, it sould be considered “beta” quality at best.

  Attributes

  `element_c_type` |
  `node_c_type` |
  `num_faces` |

  Methods

  `assign_mapping`(facemap, elements) |

`Facemap.``assign_mapping`(facemap, elements)

`Facemap.``element_c_type`

`Facemap.``node_c_type`

`Facemap.``num_faces`

### FaceNeighbors

class `tecplot.data.``FaceNeighbors`(zone)

  Face neighbor definition and control.

  Face neighbor access in PyTecplot is a work in progress. While we provide some functionality, it sould be considered “beta” quality at best.

  Attributes

  `c_type` |
  `mode` | Face neighbor mode.

  Methods

  `set_connection`(element, face, neighbors[, ...]) | Connect boundary of an element’s face to a neighboring face.

`FaceNeighbors.``c_type`

`FaceNeighbors.``mode`

  Face neighbor mode.

  Type: | `FaceNeighborMode`

  Possible values: `FaceNeighborMode.LocalOneToOne`,
    `FaceNeighborMode.LocalOneToMany`, `FaceNeighborMode.GlobalOneToOne`, `FaceNeighborMode.GlobalOneToMany`.

  Example usage:

      >>> print(zone.face_neighbors.mode)
      FaceNeighborMode.LocalOneToMany

`FaceNeighbors.``set_connection`(element, face, neighbors, zones=None, obscure=False)

  Connect boundary of an element’s face to a neighboring face.

  This sets the boundary connection face neighbors within an open face neighbor assignment sequence for the specified element and face.

  Parameters: | element (`int`) – The element number (zero-based). face (`int`) – The face number on the element (zero-based). neighbors (`list` of `integers`) – List of zero-based indices of the neighboring faces. zones (`list` of `PolyFEZone` objects, optional) – List of zones for global neighbors. This must be the same length as `neighbors`. Use `None` to indicate these are local neighbors. (default: `None`) obscure (`boolean`, optional) – Indicates that the neighbors completely obscure the face. (default: `False`)

## Auxiliary Data

### AuxData

class `tecplot.data.``AuxData`(frame)

  Methods

  `item`(i) | item by number

`AuxData.``item`(i)

  item by number

### Navigation

- index
- modules |
- next |
- previous |