pytecplot 1.5.2__py3-none-any.whl

tecplot/data/dataset.py

@@ -0,0 +1,1809 @@
+import collections
+import ctypes
+import fnmatch
+import itertools as it
+import logging
+import re
+import warnings
+
+from collections.abc import Iterable
+from functools import reduce
+from keyword import iskeyword
+from textwrap import dedent, TextWrapper
+
+from ..tecutil import _tecutil, _tecutil_connector
+from ..constant import *
+from ..exception import *
+from .. import layout, macro, session, tecutil, version
+from ..tecutil import (IndexSet, ListWrapper, StringList,
+                       flatten_args, lock, lock_attributes, sv)
+from .variable import Variable
+from .zone import ClassicFEZone, OrderedZone, PolyFEZone, Zone
+
+log = logging.getLogger(__name__)
+
+
+@lock_attributes
+class SolutionTimeClustering(object):
+    """Settings for controlling solution time clustering of solution times.
+
+    By default, a dataset's zones solution times are organized into time steps
+    with the assumption that they are distributed linearly, and are grouped
+    together if they are within the following solution time tolerance::
+
+        (tolerance_factor)*(max_time - min_time) + absolute_tolerance
+
+    Where by default the tolerance_factor is 1.0e-6 and the absolute_tolerance
+    is 0.0.
+    """
+    def __init__(self, dataset):
+        self.dataset = dataset
+
+    def __str__(self):
+        """Brief string representation.
+
+        Returns:
+            `str`: Brief representation of this `SolutionTimeClustering`,
+            showing the options controlling how solution times are grouped into
+            time steps.
+
+        Example::
+
+            >>> dataset = frame.dataset
+            >>> print(dataset.solution_time_clustering)
+            SolutionTimeClustering
+              time_scaling: TimeScaling.Linear
+              absolute_tolerance: 0.0
+              tolerance_factor: 1.0e-6
+        """
+        fmt = dedent('''\
+            SolutionTimeClustering:
+              time_scaling: {}
+              absolute_tolerance: {}
+              tolerance_factor: {}''')
+        return fmt.format(self.time_scaling, self.absolute_tolerance,
+                          self.tolerance_factor)
+
+    @property
+    @lock()
+    def time_scaling(self):
+        """`TimeScaling`: Scaling used to cluster zones by their solution times.
+
+        Identifies if the dataset's zone solution times are distributed linearly
+        or logarithmically. (Default: `TimeScaling.Linear`)
+
+        Possible values: `TimeScaling.Linear`, `TimeScaling.Logarithmic`.
+
+        Example usage::
+
+            >>> from tecplot.constant import TimeScaling
+            >>> dataset.solution_time_clustering.time_scaling = \\
+            ...     TimeScaling.Logarithmic
+
+        .. versionadded:: 2021.2
+            Solution time clustering requires Tecplot 360 2021 R2 or later.
+        """
+        return _tecutil.SolutionTimeGetTimeScaling(self.dataset.uid)
+
+    @time_scaling.setter
+    @lock()
+    def time_scaling(self, time_scaling):
+        value = TimeScaling(time_scaling).value
+        if not _tecutil.SolutionTimeSetTimeScaling(self.dataset.uid, value):
+            raise TecplotSystemError()
+
+    @property
+    @lock()
+    def absolute_tolerance(self):
+        """`float`: Absolute tolerance used to cluster zones by their solution times.
+
+        Absolute tolerance applied to each solution time when clustering with
+        nearby times. (Default: 0.0)
+
+        Example usage::
+
+            >>> dataset.solution_time_clustering.absolute_tolerance = 0.0025
+
+        .. versionadded:: 2021.2
+            Solution time clustering requires Tecplot 360 2021 R2 or later.
+        """
+        return _tecutil.SolutionTimeGetAbsoluteTolerance(self.dataset.uid)
+
+    @absolute_tolerance.setter
+    @lock()
+    def absolute_tolerance(self, absolute_tolerance):
+        uid = self.dataset.uid
+        value = float(absolute_tolerance)
+        if not _tecutil.SolutionTimeSetAbsoluteTolerance(uid, value):
+            raise TecplotSystemError()
+
+    @property
+    @lock()
+    def tolerance_factor(self):
+        """`float`: Tolerance factor used to cluster zones by solution times.
+
+        Tolerance factor, which is multiplied by the overall solution time
+        delta and applied to each solution time when clustering nearby times.
+        (Default: 1.0e-6)
+
+        Example usage::
+
+            >>> dataset.solution_time_clustering.tolerance_factor = 1.0e-4
+
+        .. versionadded:: 2021.2
+            Solution time clustering requires Tecplot 360 2021 R2 or later.
+        """
+        return _tecutil.SolutionTimeGetToleranceFactor(self.dataset.uid)
+
+    @tolerance_factor.setter
+    @lock()
+    def tolerance_factor(self, tolerance_factor):
+        uid = self.dataset.uid
+        value = float(tolerance_factor)
+        if not _tecutil.SolutionTimeSetToleranceFactor(uid, value):
+            raise TecplotSystemError()
+
+
+@lock_attributes
+class Dataset(object):
+    """Table of `Arrays <Array>` identified by `Zone <data_access>` and `Variable`.
+
+    This is the primary data container within the Tecplot Engine. A `Dataset <tecplot.data.Dataset>`
+    can be shared among several `Frames <layout.Frame>`, though any particular
+    `Dataset <tecplot.data.Dataset>` object will have a handle to at least one of them. Any
+    modification of a shared `Dataset <tecplot.data.Dataset>` will be reflected in all `Frames
+    <layout.Frame>` that use it.
+
+    Though a `Dataset <tecplot.data.Dataset>` is usually attached to a `Frame <layout.Frame>` and the plot style
+    associated with that, it can be thought of as independent from any style or
+    plotting representation. Each `Dataset <tecplot.data.Dataset>` consists of a list of `Variables
+    <Variable>` which are used by one or more of a list of `Zones
+    <data_access>`. The `Variable` determines the data type, while the `Zone
+    <data_access>` determines the layout such as shape and ordered vs
+    unordered.
+
+    The actual data are found at the intersection of a `Zone <data_access>` 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 <tecplot.data.Dataset>` is the object returned by most data-loading operations in
+    |PyTecplot|::
+
+        >>> dataset = tecplot.data.load_tecplot('my_data.plt')
+
+    Under `Dataset <tecplot.data.Dataset>`, there are a number methods to create and delete `Zones
+    <data_access>` and `variables <Variable>`.
+    """
+    def __init__(self, uid, frame):
+        self.uid = uid
+        self.frame = frame
+
+    def __repr__(self):
+        """Executable string representation.
+
+        Returns:
+            `str`: Internal representation of this `Dataset <tecplot.data.Dataset>`.
+
+        The string returned can be executed to generate a
+        clone of this `Dataset <tecplot.data.Dataset>` object::
+
+            >>> dataset = frame.dataset
+            >>> print(repr(dataset))
+            Dataset(uid=21, frame=Frame(uid=11, page=Page(uid=1)))
+            >>> exec('dataset_clone = '+repr(dataset))
+            >>> dataset_clone
+            Dataset(uid=21, frame=Frame(uid=11, page=Page(uid=1)))
+            >>> dataset == dataset_clone
+            True
+        """
+        return 'Dataset(uid={uid}, frame={frame})'.format(
+            uid=self.uid, frame=repr(self.frame))
+
+    def __str__(self):
+        """Brief string representation.
+
+        Returns:
+            `str`: Brief representation of this `Dataset <tecplot.data.Dataset>`, showing
+            `Zones <data_access>` and `Variables <Variable>`.
+
+        Example::
+
+            >>> dataset = frame.dataset
+            >>> print(dataset)
+            Dataset: 'My Dataset'
+              Zones: 'Rectangular zone'
+              Variables: 'x', 'y', 'z'
+        """
+        fmt = dedent('''\
+            Dataset: '{}'
+              Zones: {}
+              Variables: {}''')
+        maxwidth = 79
+        wrapper = ListWrapper(initial_width=maxwidth - len('  Zones: '),
+                              subsequent_indent='    ',
+                              subsequent_width=maxwidth)
+        zones = wrapper.fill(self.zone_names)
+        wrapper.initial_width = maxwidth - len('  Variables: ')
+        variables = wrapper.fill(self.variable_names)
+        return fmt.format(self.title, zones, variables)
+
+    def __eq__(self, other):
+        """Checks for equality in the |Tecplot Engine|.
+
+        Returns:
+            `bool`: `True` if the unique ID numbers are the same for both
+            `Datasets <tecplot.data.Dataset>`.
+
+        This can be useful for determining if two `Frames <layout.Frame>`
+        are holding on to the same `Dataset <tecplot.data.Dataset>`::
+
+            >>> frame1.dataset == frame2.dataset
+            True
+        """
+        return self.uid == other.uid
+
+    def __ne__(self, other):
+        return not self.__eq__(other)
+
+    def __contains__(self, obj):
+        if obj.dataset == self:
+            if isinstance(obj, Variable) and obj == self.variable(obj.index):
+                return True
+            elif isinstance(obj, Zone) and obj == self.zone(obj.index):
+                return True
+        return False
+
+    @property
+    def aux_data(self):
+        """Auxiliary data for this dataset.
+
+        Returns:
+            `AuxData`
+
+        This is the auxiliary data attached to the dataset. Such data is
+        written to the layout file by default and can be retrieved later.
+        Example usage::
+
+            >>> frame = tp.active_frame()
+            >>> aux = frame.dataset.aux_data
+            >>> aux['Result'] = '3.14159'
+            >>> print(aux['Result'])
+            3.14159
+        """
+        return session.AuxData(self.frame, AuxDataObjectType.Dataset)
+
+    @property
+    def title(self):
+        """`str`: Title of this `Dataset <tecplot.data.Dataset>`.
+
+        Example usage::
+
+            >>> dataset.title = 'My Data'
+
+        .. versionchanged:: 2017.3 of Tecplot 360
+            The dataset title property requires Tecplot 360 2017 R3 or later.
+        """
+        success, title, _, _ = _tecutil.DataSetGetInfoByUniqueID(self.uid)
+        if not success:
+            raise TecplotSystemError()
+        return title
+
+    @title.setter
+    @lock()
+    def title(self, title):
+        if not _tecutil.DataSetSetTitleByUniqueID(self.uid, title):
+            raise TecplotSystemError()
+
+    @property
+    def solution_time_clustering(self):
+        """`SolutionTimeClustering`: Solution time clustering options.
+
+        Example usage::
+
+            >>> from tecplot.constant import TimeScaling
+            >>> dataset.solution_time_clustering.time_scaling = \\
+            ...     TimeScaling.Logarithmic
+
+        .. versionadded:: 2021.2
+            Solution time clustering requires Tecplot 360 2021 R2 or later.
+        """
+        if __debug__:
+            reqver = (2021, 2)
+            if version.sdk_version_info < reqver:
+                msg = 'Solution time clustering options require 2021 R2 or later.'
+                raise TecplotOutOfDateEngineError(reqver, msg)
+        return SolutionTimeClustering(self)
+
+    @property
+    def num_zones(self):
+        """`int`: Number of `Zones <data_access>` in this `Dataset <tecplot.data.Dataset>`.
+
+        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)
+        """
+        return _tecutil.DataSetGetNumZonesByUniqueID(self.uid)
+
+    def zone(self, pattern):
+        """Returns `Zone <data_access>` by index or string pattern.
+
+        Parameters:
+            pattern (`int`, `str` or `re.Pattern <re.compile>`): Zero-based
+                index, case-insensitive `glob-style pattern string
+                <fnmatch.fnmatch>` or a compiled `regex pattern instance
+                <re.compile>` used to match the zones by name. A negative index
+                is interpreted as counting from the end of the available zones.
+
+        Returns:
+            `OrderedZone`, `ClassicFEZone` or `PolyFEZone` depending on the
+            zone type, `None` no matching `zone <data_access>` name was found.
+
+        Raises:
+            `TecplotIndexError`
+
+        .. note::
+
+            A `Dataset <tecplot.data.Dataset>` can contain `zones <data_access>` with identical names
+            and only the first match found is returned. This is not guaranteed
+            to be deterministic and care should be taken to have only
+            `zones <data_access>` with unique names when this feature is used.
+
+        The `Zone.name <OrderedZone.name>` attribute is used to match the
+        *pattern* to the desired `Zone <data_access>` 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
+
+        .. warning:: **Zone and variable ordering may change between releases**
+
+            Due to possible changes in data loaders or data formats over time,
+            the ordering of zones and variables may be different between
+            versions of Tecplot 360. Therefore it is recommended to always
+            reference zones and variables **by name** instead of by index.
+        """
+        if isinstance(pattern, Zone):
+            return pattern
+        _dispatch = {
+            ZoneType.Ordered: OrderedZone,
+            ZoneType.FELineSeg: ClassicFEZone,
+            ZoneType.FETriangle: ClassicFEZone,
+            ZoneType.FEQuad: ClassicFEZone,
+            ZoneType.FETetra: ClassicFEZone,
+            ZoneType.FEBrick: ClassicFEZone,
+            ZoneType.FEPolygon: PolyFEZone,
+            ZoneType.FEPolyhedron: PolyFEZone}
+        pattern_type = getattr(re, 'Pattern', getattr(re, '_pattern_type', None))
+        if isinstance(pattern, (str, pattern_type)):
+            try:
+                return next(self.zones(pattern))
+            except StopIteration:
+                pass
+        else:
+            if pattern < 0:
+                pattern += self.num_zones
+            try:
+                if __debug__:
+                    # ensure zone is enabled
+                    if not _tecutil.ZoneIsEnabledByDataSetID(self.uid, pattern + 1):
+                        msg = 'zone {} is not enabled'.format(pattern)
+                        raise TecplotIndexError(msg)
+                uid = _tecutil.ZoneGetUniqueIDByDataSetID(self.uid,
+                    pattern + 1)
+                ztype = _tecutil.ZoneGetTypeByDataSetID(self.uid, pattern + 1)
+                return _dispatch[ztype](uid, self)
+            except (TecplotSystemError, TecplotLogicError) as e:
+                raise TecplotIndexError(str(e))
+
+    @property
+    def _zone_indices(self):
+        """Zero-based indices of all enabled zones in the dataset."""
+        success, ptr = _tecutil.ZoneGetEnabledByDataSetID(self.uid)
+        if not success:
+            raise TecplotSystemError()
+        indices = ctypes.cast(ptr, IndexSet)
+        try:
+            return list(indices)
+        finally:
+            indices.dealloc()
+
+    @property
+    def _zone_uids(self):
+        """Unique IDs for all enabled zones in the dataset."""
+        try:
+            success, nuids, uids_ptr = _tecutil.ZoneGetUniqueIDsByDataSetID(self.uid)
+            if not success:
+                raise TecplotSystemError()
+            try:
+                return uids_ptr[:nuids]
+            finally:
+                if not _tecutil_connector.connected:
+                    _tecutil.ArrayDealloc(uids_ptr)
+        except (AttributeError, TecplotSystemError) as err:
+            try:
+                return [_tecutil.ZoneGetUniqueIDByDataSetID(self.uid, zone_index + 1)
+                        for zone_index in self._zone_indices]
+            except:
+                raise err
+
+    @property
+    def _zone_types(self):
+        """`ZoneType`s of all enabled zones in the dataset."""
+        try:
+            success, ntypes, types_ptr = _tecutil.ZoneGetTypesByDataSetID(self.uid)
+            if not success:
+                raise TecplotSystemError()
+            try:
+                return [ZoneType(types_ptr[i]) for i in range(ntypes)]
+            finally:
+                if not _tecutil_connector.connected:
+                    _tecutil.ArrayDealloc(types_ptr)
+        except (AttributeError, TecplotSystemError) as err:
+            try:
+                return [_tecutil.ZoneGetTypeByDataSetID(self.uid, zone_index + 1)
+                        for zone_index in self._zone_indices]
+            except:
+                try:
+                    with self.frame.activated():
+                        return [_tecutil.ZoneGetType(zone_index + 1)
+                                for zone_index in self._zone_indices]
+                except:
+                    raise err
+
+    @property
+    def zone_names(self):
+        """A `list` of names for all zones in the dataset.
+
+        .. warning:: **Newlines in string identifiers may affect performance.**
+
+            When iterating over many items by name, such as must be done when
+            fetching an item via pattern matching, PyTecplot will optimize the
+            search only if there are no newline characters in the searched
+            items. Iterating over strings that contain newlines will be slower
+            and therefore, it is best to avoid using newlines in string
+            identifiers or names of objects such as `Zones <data_access>` or
+            `Variables <Variable>`.
+
+        Example usage::
+
+            >>> print(dataset.zone_names)
+            ['Zone A', 'Zone B', 'Zone C']
+        """
+        try:
+            success, ptr = _tecutil.ZoneGetNamesByDataSetID(self.uid)
+            if not success:
+                raise TecplotSystemError()
+            names = ctypes.cast(ptr, StringList)
+            try:
+                return list(names)
+            finally:
+                names.dealloc()
+        except (AttributeError, TecplotSystemError) as err:
+            try:
+                success, ptr = _tecutil.ZoneGetEnabledNamesByDataSetID(self.uid)
+                if not success:
+                    raise TecplotSystemError()
+                names = ctypes.cast(ptr, StringList)
+                try:
+                    return list(names)
+                finally:
+                    names.dealloc()
+            except:
+                try:
+                    return [z.name for z in self.zones()]
+                except:
+                    raise err
+
+    def zones(self, pattern=None):
+        """Yields all `Zones <data_access>` matching a *pattern*.
+
+        Parameters:
+            pattern (`str` or `re.Pattern <re.compile>`, optional):
+                Case-insensitive `glob-style pattern string <fnmatch.fnmatch>`
+                or a compiled `regex pattern instance <re.compile>` used to
+                match zone names.
+
+        Returns:
+            Generator of `OrderedZones <OrderedZone>`, `ClassicFEZones
+            <ClassicFEZone>` or `PolyFEZones <PolyFEZone>` depending on the
+            zone types. All `zones <data_access>` if *pattern* is not
+            specified.
+
+        If **pattern** is a string, this will be interpreted as a
+        case-insensitive `glob-style pattern <fnmatch.fnmatch>`. Example using
+        glob which will match all zones starting with "A" or "a"::
+
+            >>> for zone in dataset.zones('A*'):
+            ...     x_array = zone.variable('X')
+
+        Alternatively, a regular-expression may be compiled using `re.compile`
+        which will be used directly. This example shows a case-sensitive regex
+        search::
+
+            >>> import re
+            >>> pattern = re.compile('[A-Z]*')
+            >>> for zone in dataset.zones(pattern):
+            ...     x_array = zone.variable('X')
+
+        Use list comprehension to construct a list of all zones with 'Wing'
+        in the zone name. In contrast to the `Dataset.zones()` method, this
+        is case-sensitive::
+
+            >>> wing_zones = [Z for Z in dataset.zones() if 'Wing' in Z.name]
+
+        .. warning:: **Zone and variable ordering may change between releases**
+
+            Due to possible changes in data loaders or data formats over time,
+            the ordering of zones and variables may be different between
+            versions of Tecplot 360. Therefore it is recommended to always
+            reference zones and variables **by name** instead of by index.
+        """
+        _dispatch = {
+            ZoneType.Ordered: OrderedZone,
+            ZoneType.FELineSeg: ClassicFEZone,
+            ZoneType.FETriangle: ClassicFEZone,
+            ZoneType.FEQuad: ClassicFEZone,
+            ZoneType.FETetra: ClassicFEZone,
+            ZoneType.FEBrick: ClassicFEZone,
+            ZoneType.FEPolygon: PolyFEZone,
+            ZoneType.FEPolyhedron: PolyFEZone}
+
+        if pattern:
+            pattern_type = getattr(re, 'Pattern', getattr(re, '_pattern_type', None))
+            if not isinstance(pattern, pattern_type):
+                regex = re.compile(fnmatch.translate(pattern), re.IGNORECASE)
+            else:
+                regex = pattern
+
+            if __debug__:
+                found = False
+            for uid, typ, name in zip(self._zone_uids, self._zone_types, self.zone_names):
+                if regex.match(name):
+                    if __debug__:
+                        found = True
+                    yield _dispatch[typ](uid, self)
+
+            if __debug__:
+                if (
+                    not found and
+                    isinstance(pattern, str) and
+                    any(c in pattern for c in '*?[]')
+                ):
+                    msg = 'no zones found matching: "{}"'.format(pattern)
+                    warning = TecplotPatternMatchWarning(pattern, msg, 'glob')
+                    warnings.warn(warning)
+        else:
+            for uid, typ in zip(self._zone_uids, self._zone_types):
+                yield _dispatch[typ](uid, self)
+
+    @property
+    def num_variables(self):
+        """`int`: Number of `Variables <Variable>` in this `Dataset <tecplot.data.Dataset>`.
+
+        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)
+        """
+        return _tecutil.DataSetGetNumVarsByUniqueID(self.uid)
+
+    def variable(self, pattern):
+        """Returns the `Variable` by index or string pattern.
+
+        Parameters:
+            pattern (`int`, `str` or `re.Pattern <re.compile>`): Zero-based
+                index, case-insensitive `glob-style pattern string
+                <fnmatch.fnmatch>` or a compiled `regex pattern instance
+                <re.compile>` used to match the variable by name. A negative
+                index is interpreted as counting from the end of the available
+                variable.
+
+        Returns:
+            `Variable` or `None` if no matching `Variable` name was found.
+
+        Raises:
+            `TecplotIndexError`
+
+        .. note::
+
+            A `Dataset <tecplot.data.Dataset>` can contain `variables <Variable>` with identical names
+            and only the first match found is returned. This is not guaranteed
+            to be deterministic and care should be taken to have only
+            `variables <Variable>` with unique names when this feature is used.
+
+        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
+
+        .. warning:: **Zone and variable ordering may change between releases**
+
+            Due to possible changes in data loaders or data formats over time,
+            the ordering of zones and variables may be different between
+            versions of Tecplot 360. Therefore it is recommended to always
+            reference zones and variables **by name** instead of by index.
+        """
+        if isinstance(pattern, Variable):
+            return pattern
+        pattern_type = getattr(re, 'Pattern', getattr(re, '_pattern_type', None))
+        if isinstance(pattern, (str, pattern_type)):
+            try:
+                return next(self.variables(pattern))
+            except StopIteration:
+                pass
+        else:
+            if pattern < 0:
+                pattern += self.num_variables
+            if 0 <= pattern < self.num_variables:
+                if __debug__:
+                    if not _tecutil.VarIsEnabledByDataSetID(self.uid, pattern + 1):
+                        msg = 'variable {} is not enabled'.format(pattern)
+                        raise TecplotIndexError(msg)
+                return Variable(_tecutil.VarGetUniqueIDByDataSetID(
+                                self.uid, pattern + 1), self)
+            raise TecplotIndexError
+
+    @property
+    def _variable_indices(self):
+        """Yields zero-based indices for all enabled variables in the dataset."""
+        success, ptr = _tecutil.VarGetEnabledByDataSetID(self.uid)
+        if not success:
+            raise TecplotSystemError()
+        indices = ctypes.cast(ptr, IndexSet)
+        try:
+            for i in indices:
+                yield i
+        finally:
+            indices.dealloc()
+
+    @property
+    def _variable_uids(self):
+        """`list` of Unique IDs for all enabled variables in the dataset."""
+        try:
+            success, nuids, uids_ptr = _tecutil.VarGetUniqueIDsByDataSetID(self.uid)
+            if not success:
+                raise TecplotSystemError()
+            try:
+                return uids_ptr[:nuids]
+            finally:
+                if not _tecutil_connector.connected:
+                    _tecutil.ArrayDealloc(uids_ptr)
+        except (AttributeError, TecplotSystemError) as err:
+            try:
+                return [_tecutil.VarGetUniqueIDByDataSetID(self.uid, variable_index + 1)
+                        for variable_index in self._variable_indices]
+            except:
+                raise err
+
+    @property
+    def variable_names(self):
+        """A `list` of names for all variables in the dataset.
+
+        .. warning:: **Newlines in string identifiers may affect performance.**
+
+            When iterating over many items by name, such as must be done when
+            fetching an item via pattern matching, PyTecplot will optimize the
+            search only if there are no newline characters in the searched
+            items. Iterating over strings that contain newlines will be slower
+            and therefore, it is best to avoid using newlines in string
+            identifiers or names of objects such as `Zones <data_access>` or
+            `Variables <Variable>`.
+
+        Example usage::
+
+            >>> print(dataset.variable_names)
+            ['x', 'y', 'z', 's']
+        """
+        try:
+            success, ptr = _tecutil.VarGetNamesByDataSetID(self.uid)
+            if not success:
+                raise TecplotSystemError()
+            names = ctypes.cast(ptr, StringList)
+            try:
+                return list(names)
+            finally:
+                names.dealloc()
+        except (AttributeError, TecplotSystemError) as err:
+            try:
+                success, ptr = _tecutil.VarGetEnabledNamesByDataSetID(self.uid)
+                if not success:
+                    raise TecplotSystemError()
+                names = ctypes.cast(ptr, StringList)
+                try:
+                    return list(names)
+                finally:
+                    names.dealloc()
+            except:
+                try:
+                    return [z.name for z in self.variables()]
+                except:
+                    raise err
+
+    def variables(self, pattern=None):
+        """Yields all `Variables <Variable>` matching a *pattern*.
+
+        Parameters:
+            pattern (`str` or `re.Pattern <re.compile>`, optional):
+                Case-insensitive `glob-style pattern string <fnmatch.fnmatch>`
+                or a compiled `regex pattern instance <re.compile>` used to
+                match variable names.
+
+        Returns:
+            Generator of `Variables <Variable>`. All `Variables <Variable>` if
+            *pattern* is not specified.
+
+        Example using case-insensitive glob-style matching::
+
+            >>> for variable in dataset.variables('A*'):
+            ...     array = variable.values('My Zone')
+
+        Example using (case-sensitive) regex::
+
+            >>> import re
+            >>> for variable in dataset.variables(re.compile(r'A.*')):
+            ...     array = variable.values('My Zone')
+
+        .. warning:: **Zone and variable ordering may change between releases**
+
+            Due to possible changes in data loaders or data formats over time,
+            the ordering of zones and variables may be different between
+            versions of Tecplot 360. Therefore it is recommended to always
+            reference zones and variables **by name** instead of by index.
+        """
+        if pattern:
+            pattern_type = getattr(re, 'Pattern', getattr(re, '_pattern_type', None))
+            if not isinstance(pattern, pattern_type):
+                regex = re.compile(fnmatch.translate(pattern), re.IGNORECASE)
+            else:
+                regex = pattern
+
+            if __debug__:
+                found = False
+            for uid, name in zip(self._variable_uids, self.variable_names):
+                if regex.match(name):
+                    if __debug__:
+                        found = True
+                    yield Variable(uid, self)
+
+            if __debug__:
+                if (
+                    not found and
+                    isinstance(pattern, str) and
+                    any(c in pattern for c in '*?[]')
+                ):
+                    msg = 'no variables found matching: "{}"'.format(pattern)
+                    warning = TecplotPatternMatchWarning(pattern, msg)
+                    warnings.warn(warning)
+        else:
+            for uid in self._variable_uids:
+                yield Variable(uid, self)
+
+    @property
+    def VariablesNamedTuple(self):
+        r"""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`:
+
+        .. code-block:: python
+
+            from os import path
+            import tecplot as tp
+
+            examples_dir = tp.session.tecplot_examples_directory()
+            datafile = path.join(examples_dir,'SimpleData','DownDraft.plt')
+            dataset = tp.data.load_tecplot(datafile)
+            result = tp.data.query.probe_at_position(0,0.1,0.3)
+            data = dataset.VariablesNamedTuple(*result.data)
+
+            # prints: (RHO, E) = (1.17, 252930.37)
+            msg = '(RHO, E) = ({:.2f}, {:.2f})'
+            print(msg.format(data.RHO, data.E))
+        """
+        # First we clean up variable names
+        # and keep a count of each name used
+        names = []
+        count = {}
+        for vname in self.variable_names:
+            # sub invalid characters with underscores
+            name = re.sub(r'\W|^(?=\d)', r'_', vname)
+            # remove leading underscores
+            name = re.sub(r'^_+', r'', name)
+            # prepend leading number with 'v'
+            name = re.sub(r'^(\d)', r'v\1', name)
+            # append keywords with underscore
+            if iskeyword(name):
+                name = name + '_'
+            # force non-empty variable names using 'v'
+            if name == '':
+                name = 'v'
+            # add name to list
+            names.append(name)
+            # keep track of names to identify duplicates
+            if name not in count:
+                count[name] = 0
+            count[name] += 1
+
+        # append index, with padded zeros
+        numbered = count.copy()
+        for i,name in enumerate(names):
+            if count[name] > 1:
+                names[i] = '{0}{1:0{2}d}'.format(name,
+                    count[name] - numbered[name], len(str(count[name] - 1)))
+                numbered[name] -= 1
+
+        return collections.namedtuple('DatasetVariables', names)
+
+    @lock()
+    def copy_zones(self, *zones, **kwargs):
+        """Copies `Zones <data_access>` within this `Dataset <tecplot.data.Dataset>`.
+
+        Parameters:
+            *zones (`Zone <data_access>`, optional): Specific `Zones
+                <data_access>` to copy. All zones will be copied if none are
+                supplied.
+            shared_variables (`bool` or `list` of `Variables <Variable>`):
+                Share all variables between the original and generated zones if
+                `True` or the list of Variables to be shared. Variable sharing
+                allows you to lower the use of physical memory (RAM).  When
+                sharing a variable the memory used by the source zone is shared
+                with the copied zone.  Alterations to the variable in one zone
+                will affect the other.  See also `Dataset.branch_variables()`.
+                Default: `False`.
+            i_range (`tuple` of `integers <int>`, optional):
+                Range (min, max, step) along the ``i`` dimension for ordered
+                data. Min and max are zero-based indicies where max is
+                inclusive. If step causes max to be skipped, max will be
+                included. If `None` (default), the entire range will be copied.
+            j_range (`tuple` of `integers <int>`, optional):
+                Range (min, max, step) along the ``j`` dimension for ordered
+                data. Min and max are zero-based indicies where max is
+                inclusive. If step causes max to be skipped, max will be
+                included. If `None` (default), the entire range will be copied.
+            k_range (`tuple` of `integers <int>`, optional):
+                Range (min, max, step) along the ``k`` dimension for ordered
+                data. Min and max are zero-based indicies where max is
+                inclusive. If step causes max to be skipped, max will be
+                included. If `None` (default), the entire range will be copied.
+
+        Returns:
+            `list` of the newly created `Zones <data_access>`.
+
+        .. note:: **Performance considerations for data manipulations.**
+
+            When performing many data-manipulation operations including adding
+            zones, adding variables, modifying field data or connectivity, and
+            especially in connected mode, it is recommended to do this all with
+            the `tecplot.session.suspend()`. This will prevent the Tecplot
+            engine from trying to "keep up" with the changes. Tecplot will be
+            notified of all changes made upon exit of this context. This may
+            result in significant performance gains for long operations.
+
+        .. code-block:: python
+
+            import tecplot as tp
+
+            ds = tp.active_page().add_frame().create_dataset('D', ['x','y','z'])
+            z = ds.add_ordered_zone('Z1', (3,3,3))
+            ds.copy_zones(z, i_range=(1, -1, 2), share_variables=True)
+        """
+        share_variables = kwargs.pop('share_variables', False)
+        i_range = kwargs.pop('i_range', None)
+        j_range = kwargs.pop('j_range', None)
+        k_range = kwargs.pop('k_range', None)
+
+        if not share_variables:
+            branch_variables = list(self.variables())
+        elif isinstance(share_variables, Iterable):
+            for idx, var in enumerate(share_variables):
+                if not isinstance(var, Variable):
+                    share_variables[idx]= self.variable(var)
+
+            branch_variables = [v for v in self.variables()
+                                if v not in share_variables]
+        else:
+            branch_variables = []
+
+        num_zones = self.num_zones
+
+        with tecutil.ArgList() as arglist:
+            if not zones:
+                zones = self.zones()
+            with IndexSet(*zones) as zoneset:
+                arglist[sv.SOURCEZONES] = zoneset
+
+                for dim, rng in zip(['I', 'J', 'K'], [i_range, j_range, k_range]):
+                    if rng is not None:
+                        rng = tecutil.IndexRange(*rng)
+                        if rng.min is not None:
+                            arglist[dim + 'MIN'] = tecutil.Index(rng.min)
+                        if rng.max is not None:
+                            arglist[dim + 'MAX'] = tecutil.Index(rng.max)
+                        if rng.step is not None:
+                            step = int(rng.step)
+                            if step > 0:
+                                arglist[dim + 'SKIP'] = step
+                            elif step < 0:
+                                msg = 'Negative step not supported.'
+                                raise TecplotLogicError(msg)
+                _tecutil.ZoneCopyX(arglist)
+
+        new_zones = [self.zone(i) for i in range(num_zones, self.num_zones)]
+
+        for zone in new_zones:
+            for var in branch_variables:
+                self.branch_variables(zone, var, True)
+
+        return new_zones
+
+    def mirror_zones(self, mirror_variables, *zones):
+        """Mirrors `Zones <data_access>` within this `Dataset <tecplot.data.Dataset>`.
+
+        Each mirror zone has a name of the form "Mirror of zone *sourcezone*",
+        where *sourcezone* is the number of the zone from which the mirrored
+        zone was created. The variables in the newly created zones are shared
+        with their corresponding source zones, except for variables to be
+        mirrored as specified.
+
+        Parameters:
+            mirror_variables (`Variable` or `list` of `Variables <Variable>`):
+                Variables in the new zone to be multiplied by :math:`-1` after
+                the zone is copied. the variables may be `Variable` objects,
+                `str` names or `int` indices.
+            *zones (`Zones <data_access>`, optional): Specific `Zones
+                <data_access>` to mirror. All zones will be mirrored if none
+                are supplied. The values may also be `str` names or `int`
+                indices.
+
+        Returns:
+            Generator of mirrored zones.
+
+        This example show how to mirror all zones across the xy-plane in 3D::
+
+            >>> mirrored_zones = dataset.mirror_zones('Z')
+        """
+        if (
+            isinstance(mirror_variables, str) or
+            not isinstance(mirror_variables, Iterable)
+        ):
+            mirror_variables = [mirror_variables]
+
+        mvars = (v if isinstance(v, Variable) else self.variable(v)
+                 for v in mirror_variables)
+        mvars = ','.join([str(v.index + 1) for v in mvars])
+
+        if not zones:
+            mzones = '1-{}'.format(self.num_zones)
+        else:
+            mzones = (z if isinstance(z, Zone) else self.zone(z)
+                      for z in tecutil.flatten_args(*zones))
+            mzones = ','.join([str(z.index + 1) for z in mzones])
+
+        num_zones = self.num_zones
+        cmd = '$!CreateMirrorZones SourceZones = [{0}] MirrorVars = [{1}]'
+        macro.execute_command(cmd.format(mzones, mvars))
+        return (self.zone(i) for i in range(num_zones, self.num_zones))
+
+    @lock()
+    def add_variable(self, name, dtypes=None, locations=None):
+        """Add a single `Variable` to the active `Dataset <tecplot.data.Dataset>`.
+
+        Parameters:
+            name (`str`): 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 <data_access>` in
+                the currently active `Dataset <tecplot.data.Dataset>`. Options are:
+                `FieldDataType.Float`, `Double <FieldDataType.Double>`,
+                `Int32`, `Int16`, `Byte` and `Bit`. If a single value, this
+                will be duplicated for all `Zones <data_access>`. (default:
+                `None`)
+            locations (`ValueLocation` or `list` of `ValueLocation`, optional):
+                Point locations of this `Variable` for each
+                `Zone <data_access>` in the currently active `Dataset <tecplot.data.Dataset>`. Options
+                are: `Nodal` and `CellCentered`. If a single value, this will
+                be duplicated for all `Zones <data_access>`. (default: `None`)
+
+        Returns:
+            `Variable`
+
+        .. note:: **Performance considerations for data manipulations.**
+
+            When performing many data-manipulation operations including adding
+            zones, adding variables, modifying field data or connectivity, and
+            especially in connected mode, it is recommended to do this all with
+            the `tecplot.session.suspend()`. This will prevent the Tecplot
+            engine from trying to "keep up" with the changes. Tecplot will be
+            notified of all changes made upon exit of this context. This may
+            result in significant performance gains for long operations.
+
+        The added `Variable` will be available for use in each `Zone
+        <data_access>` of the dataset. This method should be used in
+        conjunction with other data creation methods such as
+        `Dataset.add_zone`:
+
+        .. code-block:: python
+            :emphasize-lines: 7-8
+
+            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, supersample=3)
+
+        ..  figure:: /_static/images/add_variables.png
+            :width: 300px
+            :figwidth: 300px
+        """
+        assert len(name) <= 128, 'Variable names are limited to 128 characters'
+        with self.frame.activated():
+            dataset = self.frame.dataset
+            new_variable_index = dataset.num_variables
+            with tecutil.ArgList(NAME=name) as arglist:
+                if dtypes is not None:
+                    if not hasattr(dtypes, '__iter__'):
+                        dtypes = [dtypes] * dataset.num_zones
+                    arglist['VARDATATYPE'] = dtypes
+                if locations is not None:
+                    if not hasattr(locations, '__iter__'):
+                        locations = [locations] * dataset.num_zones
+                    arglist['VALUELOCATION'] = locations
+
+                if __debug__:
+                    msg = 'new variable: ' + name
+                    for k, v in arglist.items():
+                        msg += '\n  {} = {}'.format(k, v)
+                    log.debug(msg)
+                if not _tecutil.DataSetAddVarX(arglist):
+                    raise TecplotSystemError()
+            return dataset.variable(new_variable_index)
+
+    @lock()
+    def add_zone(self, zone_type, name, shape, dtypes=None, locations=None,
+                 face_neighbor_mode=None, parent_zone=None, solution_time=None,
+                 strand_id=None, index=None):
+        """Add a single `Zone <data_access>` to this `Dataset <tecplot.data.Dataset>`.
+
+        Parameters:
+            zone_type (`ZoneType`): The type of `Zone <data_access>` to be
+                created. Possible values are: `Ordered`, `FETriangle`,
+                `FEQuad`, `FETetra`, `FEBrick`, `FELineSeg`, `FEPolyhedron` and
+                `FEPolygon`.
+            name (`str`): Name of the new `Zone <data_access>`. This
+                does not have to be unique.
+            shape (`int` or `list` of `integers <int>`): Specifies
+                the length and dimension (up to three) of the new `Zone
+                <data_access>`. A 1D `Zone <data_access>` is assumed if a
+                single `int` is given. This is **(i, j, k)** for ordered `Zones
+                <data_access>`, **(num_points, num_elements)** for
+                finite-element `Zones <data_access>` and **(num_points,
+                num_elements, num_faces)** for polytope `Zones <data_access>`
+                where the number of faces is known.
+            dtypes (`FieldDataType`, `list` of `FieldDataType`, optional): Data
+                types of this `Zone <data_access>` for each `Variable` in the
+                currently active `Dataset <tecplot.data.Dataset>`. Options are: `Float
+                <FieldDataType.Float>`, `Double <FieldDataType.Double>`,
+                `Int32`, `Int16`, `Byte` and `Bit`. If a single value, this
+                will be duplicated for all `Variables <Variable>`. 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 <data_access>` for each
+                `Variable` in the currently active `Dataset <tecplot.data.Dataset>`. Options are:
+                `Nodal` and `CellCentered`. If a single value, this will be
+                duplicated for all `Variables <Variable>`.  If `None` then the
+                type of the first `Variable`, defaulting to `Nodal`, is used
+                for all. (default: `None`)
+            face_neighbor_mode (`FaceNeighborMode`, optional): Specifies the
+                face-neighbor mode for this zone.  Options are:
+                `FaceNeighborMode.LocalOneToOne` (default),
+                `FaceNeighborMode.LocalOneToMany`,
+                `FaceNeighborMode.GlobalOneToOne` or
+                `FaceNeighborMode.GlobalOneToMany`.
+            parent_zone (`Zone <data_access>`, optional): A parent `Zone
+                <data_access>` to be used when generating surface-restricted
+                streamtraces.
+            solution_time (`float`, optional): Solution time for this zone.
+                (default: 0)
+            strand_id (`int`, optional): Associate this new `Zone
+                <data_access>` with a particular strand.
+            index (`int`, 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 <data_access>`
+
+        .. warning:: **Setting connectivity in connected mode.**
+
+            When connected to a running instance of Tecplot 360 using the
+            TecUtil Server, care must be taken to ensure that the GUI does not
+            try to render the data between the creation of the zone and the
+            setting of the connectivity, through the `Facemap` or `Nodemap`
+            objects. This can be achieved by setting the plot type of the
+            frame(s) holding on to the dataset to `PlotType.Sketch` before
+            creating the zone and only going to `PlotType.Cartesian3D` after
+            the connectivity is set. Tecplot 360 may get into a bad state,
+            corrupting loaded data, if it attempts to render (especially
+            polytope) data without connectivity.
+
+        .. note:: **Performance considerations for data manipulations.**
+
+            When performing many data-manipulation operations including adding
+            zones, adding variables, modifying field data or connectivity, and
+            especially in connected mode, it is recommended to do this all with
+            the `tecplot.session.suspend()`. This will prevent the Tecplot
+            engine from trying to "keep up" with the changes. Tecplot will be
+            notified of all changes made upon exit of this context. This may
+            result in significant performance gains for long operations.
+
+        The added `Zone <data_access>` will be able to use all `Variables
+        <Variable>` 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`
+        """
+        if __debug__:
+            if self.num_variables == 0:
+                errmsg = dedent('''\
+                Can not create a zone on a dataset with no variables.
+                    Add at least one variable to this dataset before
+                    creating any zones.''')
+                raise TecplotLogicError(errmsg)
+
+        with self.frame.activated():
+            dataset = self.frame.dataset
+            new_zone_index = dataset.num_zones if index is None else index
+            with tecutil.ArgList(ZONETYPE=zone_type, NAME=name) as arglist:
+                # convert shape to (imax, jmax, kmax)
+                if not hasattr(shape, '__iter__'):
+                    shape = [shape]
+                for k, v in zip([sv.IMAX, sv.JMAX, sv.KMAX], shape):
+                    arglist[k] = v
+
+                # expand data types and locations to length of num_variables
+                for key, val in zip([sv.VARDATATYPE, sv.VALUELOCATION],
+                                    [dtypes, locations]):
+                    if val is not None:
+                        if not hasattr(val, '__iter__'):
+                            val = [val] * dataset.num_variables
+                        arglist[key] = val
+
+                if solution_time is not None:
+                    arglist[sv.SOLUTIONTIME] = float(solution_time)
+
+                if strand_id is not None:
+                    arglist[sv.STRANDID] = int(strand_id)
+
+                if parent_zone is not None:
+                    arglist[sv.PARENTZONE] = parent_zone.index + 1
+
+                if face_neighbor_mode is not None:
+                    arglist[sv.FACENEIGHBORMODE] = FaceNeighborMode(
+                        face_neighbor_mode)
+
+                if index is not None:
+                    arglist[sv.ZONE] = index + 1
+
+                if __debug__:
+                    shp = '({})'.format(','.join(str(s) for s in shape))
+                    msg = 'new dataset shape: ' + shp
+                    for k, v in arglist.items():
+                        msg += '\n  {} = {}'.format(k, v)
+                    log.debug(msg)
+
+                if not _tecutil.DataSetAddZoneX(arglist):
+                    raise TecplotSystemError()
+
+            new_zone = dataset.zone(new_zone_index)
+            session.zone_added(new_zone)
+            return new_zone
+
+    def add_ordered_zone(self, name, shape, **kwargs):
+        """Add a single ordered `Zone <data_access>` to this `Dataset <tecplot.data.Dataset>`.
+
+        Parameters:
+            name (`str`): Name of the new `Zone <data_access>`. This
+                does not have to be unique.
+            shape (`int` or `list` of `integers <int>`): Specifies
+                the length and dimension **(i, j, k)** of the new
+                `Zone <data_access>`. A 1D `Zone <data_access>` is assumed if a
+                single `int` is given.
+            **kwargs: These arguments are passed to `Dataset.add_zone`.
+
+        .. seealso:: `Dataset.add_zone`
+
+            Keyword arguments are passed to the parent zone creation method
+            `Dataset.add_zone`.
+
+        .. note:: **Performance considerations for data manipulations.**
+
+            When performing many data-manipulation operations including adding
+            zones, adding variables, modifying field data or connectivity, and
+            especially in connected mode, it is recommended to do this all with
+            the `tecplot.session.suspend()`. This will prevent the Tecplot
+            engine from trying to "keep up" with the changes. Tecplot will be
+            notified of all changes made upon exit of this context. This may
+            result in significant performance gains for long operations.
+
+        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:
+
+        .. code-block:: python
+            :emphasize-lines: 12,17,22
+
+            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, supersample=3)
+
+        ..  figure:: /_static/images/add_ordered_zones.png
+            :width: 300px
+            :figwidth: 300px
+        """
+        return self.add_zone(ZoneType.Ordered, name, shape, **kwargs)
+
+    def add_fe_zone(self, zone_type, name, num_points, num_elements, **kwargs):
+        r"""Add a single finite-element `Zone <data_access>` to this `Dataset <tecplot.data.Dataset>`.
+
+        Parameters:
+            zone_type (`ZoneType`): The type of `Zone <data_access>` to be
+                created. Possible values are: `FETriangle`, `FEQuad`,
+                `FETetra`, `FEBrick` and `FELineSeg`.
+            name (`str`): Name of the new `Zone <data_access>`. This
+                does not have to be unique.
+            num_points (`int`): Number of points (nodes) in this
+                zone.
+            num_elements (`int`): 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`.
+
+        .. seealso:: `Dataset.add_zone`
+
+            Keyword arguments are passed to the parent zone creation method
+            `Dataset.add_zone`.
+
+        .. warning:: **Setting connectivity in connected mode.**
+
+            When connected to a running instance of Tecplot 360 using the
+            TecUtil Server, care must be taken to ensure that the GUI does not
+            try to render the data between the creation of the zone and the
+            setting of the connectivity, through the `Facemap` or `Nodemap`
+            objects. This can be achieved by setting the plot type of the
+            frame(s) holding on to the dataset to `PlotType.Sketch` before
+            creating the zone and only going to `PlotType.Cartesian3D` after
+            the connectivity is set. Tecplot 360 may get into a bad state,
+            corrupting loaded data, if it attempts to render (especially
+            polytope) data without connectivity.
+
+        .. note:: **Performance considerations for data manipulations.**
+
+            When performing many data-manipulation operations including adding
+            zones, adding variables, modifying field data or connectivity, and
+            especially in connected mode, it is recommended to do this all with
+            the `tecplot.session.suspend()`. This will prevent the Tecplot
+            engine from trying to "keep up" with the changes. Tecplot will be
+            notified of all changes made upon exit of this context. This may
+            result in significant performance gains for long operations.
+
+        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 (:math:`N`):
+
+            ============== ============== ========================
+            Zone Type      Points/Element Nodemap Shape
+            ============== ============== ========================
+            ``FELineSeg``  2              (:math:`N`, :math:`2 N`)
+            ``FETriangle`` 3              (:math:`N`, :math:`3 N`)
+            ``FEQuad``     4              (:math:`N`, :math:`4 N`)
+            ``FETetra``    4              (:math:`N`, :math:`4 N`)
+            ``FEBrick``    8              (:math:`N`, :math:`8 N`)
+            ============== ============== ========================
+
+        For more details, see the "working with datasets" examples shipped with
+        PyTecplot in the Tecplot 360 distribution.
+        """
+        assert zone_type in [ZoneType.FETriangle, ZoneType.FEQuad,
+                             ZoneType.FETetra, ZoneType.FEBrick,
+                             ZoneType.FELineSeg]
+        return self.add_zone(zone_type, name, (num_points, num_elements),
+                             **kwargs)
+
+    def add_poly_zone(self, zone_type, name, num_points, num_elements,
+                      num_faces, **kwargs):
+        """Add a single polygonal `Zone <data_access>` to this `Dataset <tecplot.data.Dataset>`.
+
+        Parameters:
+            zone_type (`ZoneType`): The type of `Zone <data_access>` to be
+                created. Possible values are: `FEPolyhedron` and `FEPolygon`.
+            name (`str`): Name of the new `Zone <data_access>`. This
+                does not have to be unique.
+            num_points (`int`): Number of points in this zone.
+            num_elements (`int`): Number of elements in this zone.
+            num_faces (`int`): Number of faces in this zone.
+            **kwargs: These arguments are passed to `Dataset.add_zone`.
+
+        .. seealso:: `Dataset.add_zone`
+
+            Keyword arguments are passed to the parent zone creation method
+            `Dataset.add_zone`.
+
+        .. warning:: **Setting connectivity in connected mode.**
+
+            When connected to a running instance of Tecplot 360 using the
+            TecUtil Server, care must be taken to ensure that the GUI does not
+            try to render the data between the creation of the zone and the
+            setting of the connectivity, through the `Facemap` or `Nodemap`
+            objects. This can be achieved by setting the plot type of the
+            frame(s) holding on to the dataset to `PlotType.Sketch` before
+            creating the zone and only going to `PlotType.Cartesian3D` after
+            the connectivity is set. Tecplot 360 may get into a bad state,
+            corrupting loaded data, if it attempts to render (especially
+            polytope) data without connectivity.
+
+        .. note:: **Performance considerations for data manipulations.**
+
+            When performing many data-manipulation operations including adding
+            zones, adding variables, modifying field data or connectivity, and
+            especially in connected mode, it is recommended to do this all with
+            the `tecplot.session.suspend()`. This will prevent the Tecplot
+            engine from trying to "keep up" with the changes. Tecplot will be
+            notified of all changes made upon exit of this context. This may
+            result in significant performance gains for long operations.
+
+        .. note:: The **num_faces** is the number of *unique faces*.
+
+            The number of unique faces, given an element map can be obtained
+            using the following function for polygon data::
+
+                def num_unique_faces(elementmap):
+                    return len(set( tuple(sorted([e[i], e[(i+1)%len(e)]]))
+                                for e in elementmap for i in range(len(e)) ))
+
+            This function creates a unique set of node pairs (edges around
+            the polygons) and counts them. For polyhedron data, the following
+            can be used::
+
+                def num_unique_faces(elementmap):
+                    return len(set( tuple(sorted(f)) for e in elementmap
+                                                     for f in e ))
+
+            which merely counts the number of unique faces defined in the
+            element map.
+
+        For more details, see the "working with datasets" examples shipped with
+        PyTecplot in the Tecplot 360 distribution.
+        """
+        assert zone_type in [ZoneType.FEPolyhedron, ZoneType.FEPolygon]
+        return self.add_zone(zone_type, name, (num_points, num_elements,
+                             num_faces), **kwargs)
+
+    @lock()
+    def delete_variables(self, *variables):
+        """Remove `Variables <Variable>` from this `Dataset <tecplot.data.Dataset>`.
+
+        Parameters:
+            *variables (`Variable` or index `int`): Variables to
+                remove from this dataset.
+
+        .. code-block:: python
+            :emphasize-lines: 3
+
+            >>> print(dataset.variable_names)
+            ['X','Y','Z']
+            >>> dataset.delete_variables(dataset.variable('Z'))
+            >>> print(dataset.variable_names)
+            ['X','Y']
+
+        .. Warning::
+            Deleting `Variables <Variable>` invalidates iterators referencing
+            them in the containing `Dataset <tecplot.data.Dataset>` such as those obtained from
+            `Dataset.variables()`. It is recommended to create a list of the
+            `Variables <Variable>` you want to delete and to pass that into a
+            single call to `Dataset.delete_variables()`
+
+        Notes:
+            Multiple `Variables <Variable>` can be deleted at once, though the
+            last `Variable` can not be deleted. The following example deletes
+            all but the first `Variable` in the `Dataset <tecplot.data.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(dataset.variable_names)
+                ['X']
+        """
+        variables = flatten_args(*variables)
+        with self.frame.activated():
+            with IndexSet(*variables) as vlist:
+                _tecutil.DataSetDeleteVar(vlist)
+
+    @lock()
+    def delete_zones(self, *zones):
+        """Remove `Zones <data_access>` from this `Dataset <tecplot.data.Dataset>`.
+
+        Parameters:
+            *zones (`Zones <data_access>` or index `integers <int>`): Zones to
+                remove from this dataset.
+
+        .. code-block:: python
+            :emphasize-lines: 3
+
+            >>> print(dataset.zone_names)
+            ['Zone 1', 'Zone 2']
+            >>> dataset.delete_zones(dataset.zone('Zone 2'))
+            >>> print(dataset.zone_names)
+            ['Zone 1']
+
+        .. Warning::
+            Deleting `Zones <data_access>` invalidates iterators referencing
+            them in the containing `Dataset <tecplot.data.Dataset>` such as those obtained from
+            `Dataset.zones()`. It is recommended to create a list of the `Zones
+            <data_access>` you want to delete and to pass that into a single
+            call to `Dataset.delete_zones()`
+
+        Notes:
+            Multiple `Zones <data_access>` can be deleted at once, though the
+            last `Zone <data_access>` can not be deleted. The following example
+            deletes all but the first `Zone <data_access>` in the `Dataset <tecplot.data.Dataset>`::
+
+                >>> dataset.delete_zones(dataset.zones())
+        """
+        zones = flatten_args(*zones)
+        with self.frame.activated():
+            with IndexSet(*zones) as zlist:
+                _tecutil.DataSetDeleteZone(zlist)
+
+    @property
+    def num_solution_times(self):
+        """`int` (read-only): Number of solution times in the dataset.
+
+        This property is read-only. Solution times are grouped according to the
+        current solution time clustering settings (see
+        `Dataset.solution_time_clustering`). Example usage::
+
+            >>> print(dataset.num_solution_times)
+            10
+
+        .. versionadded:: 2017.3
+            Solution time manipulation requires Tecplot 360 2017 R3 or later.
+        """
+        res = _tecutil.SolutionTimeGetNumTimeStepsByDataSetID(self.uid)
+        success, value = res
+        if not success:
+            raise TecplotSystemError()
+        return value
+
+    @property
+    def solution_times(self):
+        """`list` of `floats <float>`: Solution times in the dataset.
+
+        This property is read-only. Solution times are grouped according to the
+        current solution time clustering settings (see
+        `Dataset.solution_time_clustering`). Example usage::
+
+            >>> print(dataset.solution_times)
+            [0.0, 1.0, 2.0, 3.0, 4.0, 5.0, 6.0, 7.0, 8.0, 9.0]
+
+        .. versionadded:: 2017.3
+            Solution time manipulation requires Tecplot 360 2017 R3 or later.
+        """
+        res = _tecutil.SolutionTimeGetSolutionTimesByDataSetID(self.uid)
+        success, ntimes, times = res
+        if not success:
+            raise TecplotSystemError()
+        ret = list(times[:ntimes])
+        if not _tecutil_connector.connected:
+            _tecutil.ArrayDealloc(times)
+        return ret
+
+    @lock()
+    def branch_variables(self, zones, variables, copy_data=True):
+        """Breaks data sharing between zones.
+
+        Parameters:
+            zones (`list` of `Zones <data_access>`): Zones to be branched.
+            variables (`list` of `Variables <Variable>`): Variables to be
+                branched.
+            copy_data (`bool`, optional): Allocate space for the branched
+                values and copy the data. If `False`, the new variables will
+                be passive. (default: `True`)
+
+        .. seealso:: `Dataset.share_variables()`
+
+        Variable sharing allows you to lower the use of physical memory (RAM).
+        When sharing a variable the memory used by the source zone is shared
+        with the copied zone.  Alterations to the variable in one zone will
+        affect the other. Example usage::
+
+            >>> z = dataset.zone('My Zone')
+            >>> zcopy = z.copy(share_variables=True)
+            >>> print([zn.index for zn in z.values(0).shared_zones])
+            [0,1]
+            >>> dataset.branch_variables(zcopy,dataset.variable(0))
+            >>> print([zn.index for zn in z.values(0).shared_zones])
+            []
+            >>> print([zn.index for zn in z.values(1).shared_zones])
+            [0,1]
+        """
+        if not isinstance(zones, Iterable):
+            zones = [zones]
+        if not isinstance(variables, Iterable):
+            variables = [variables]
+
+        for var in variables:
+            varidx = getattr(var, 'index', self.variable(var).index)
+            for zone in zones:
+                zoneidx = getattr(zone, 'index', self.zone(zone).index)
+                if not _tecutil.DataValueBranchShared(zoneidx + 1, varidx + 1,
+                                                      copy_data):
+                    raise TecplotSystemError()
+
+    @lock()
+    def share_variables(self, source_zone, destination_zones, variables):
+        """Share field data between zones.
+
+        This method links the underlying data `arrays <Array>` of the
+        destination `zones <data_access>` to the data of the source `zone
+        <data_access>`. Modifying the array data of one zone will affect all
+        others in this group.
+
+        Parameters:
+            source_zone (`Zone <data_access>`): Zone which provides data to be
+                shared.
+            destination_zones (`list` of `Zones <data_access>`): Zones
+                where data will be overwritten.
+            variables (`list` of `Variables <Variable>`): Variables to be
+                shared.
+
+        .. seealso:: `Dataset.branch_variables()`
+
+        Example usage::
+
+            >>> z = dataset.zone('My Zone')
+            >>> zcopy = z.copy(share_variables=False)
+            >>> print([zn.index for zn in z.values(0).shared_zones])
+            []
+            >>> dataset.share_variables(zcopy,[z],[dataset.variable(0)])
+            >>> print([zn.index for zn in z.values(0).shared_zones])
+            [0,1]
+            >>> print([zn.index for zn in z.values(1).shared_zones])
+            []
+        """
+        if not isinstance(destination_zones, Iterable):
+            destination_zones = [destination_zones]
+        if not isinstance(variables, Iterable):
+            variables = [variables]
+
+        for var in variables:
+            varidx = getattr(var, 'index', self.variable(var).index)
+            for zone in destination_zones:
+                zoneidx = getattr(zone, 'index', self.zone(zone).index)
+                source_zoneidx = getattr(source_zone, 'index',
+                                         self.zone(source_zone).index)
+                if not _tecutil.DataValueIsSharingOk(source_zoneidx+1,
+                                                     zoneidx+1, varidx+1):
+                    raise TecplotSystemError()
+                _tecutil.DataValueShare(source_zoneidx+1, zoneidx+1, varidx+1)
+
+    @lock()
+    def branch_connectivity(self, zones):
+        """Breaks connectivity sharing between zones.
+
+        Parameters:
+            zones (`list` of `Zones <data_access>`): Zones to be branched.
+
+        .. seealso:: `Dataset.share_connectivity()`
+
+        Example usage::
+
+            >>> z = dataset.zone('My Zone')
+            >>> zcopy = z.copy()
+            >>> print([zn.index for zn in z.shared_connectivity])
+            [0,1]
+            >>> dataset.branch_connectivity(zcopy)
+            >>> print([zn.index for zn in z.shared_connectivity])
+            []
+        """
+        if not isinstance(zones, Iterable):
+            zones = [zones]
+
+        for zone in zones:
+
+            try:
+                zoneidx = getattr(zone, 'index')
+            except:
+                zoneidx = self.zone(zone).index
+            if not _tecutil.DataConnectBranchShared(zoneidx + 1):
+                raise TecplotSystemError()
+
+    @lock()
+    def share_connectivity(self, source_zone, destination_zones):
+        """Share connectivity between zones.
+
+        This method links the connectivity (`nodemap` or `facemap`) of the
+        destination `zones <data_access>` to the connectivity of the source
+        zone. Modifying the connectivity of one zone will affect all others in
+        this group.
+
+        Parameters:
+            source_zone (`Zone <data_access>`): Zone which provides data to be
+                shared.
+            destination_zones (`list` of `Zones <data_access>`): Zones where
+                connectivity list will be overwritten.
+
+        .. seealso:: `Dataset.branch_connectivity()`
+
+        Example usage::
+
+            >>> z = dataset.zone('My Zone')
+            >>> zcopy = z.copy()
+            >>> print([zn.index for zn in z.shared_connectivity])
+            [0,1]
+            >>> dataset.branch_connectivity(zcopy)
+            >>> print([zn.index for zn in z.shared_connectivity])
+            []
+            >>> dataset.share_connectivity(z,zcopy)
+            >>> print([zn.index for zn in z.shared_connectivity])
+            [0,1]
+        """
+        if not isinstance(destination_zones, Iterable):
+            destination_zones = [destination_zones]
+
+        def _index(obj):
+            i = getattr(obj, 'index', None)
+            if i is None:
+                i = self.zone(obj).index
+            return i
+
+        for zone in destination_zones:
+            idst = _index(zone)
+            isrc = _index(source_zone)
+            if not _tecutil.DataConnectIsSharingOk(isrc + 1, idst + 1):
+                raise TecplotSystemError()
+            _tecutil.DataConnectShare(isrc + 1, idst + 1)
+
+
+@property
+@lock()
+def dataset(frame):
+    """`Dataset <tecplot.data.Dataset>` attached to this `Frame <layout.Frame>`.
+
+    Returns:
+        `Dataset <tecplot.data.Dataset>`: The object holding onto the data associated with this
+        `Frame <layout.Frame>`.
+
+    If no `Dataset <tecplot.data.Dataset>` has been created for this `Frame <layout.Frame>`, a new one is created
+    and returned::
+
+        >>> dataset = frame.dataset
+    """
+    if not frame.has_dataset:
+        frame.create_dataset(frame.name + ' Dataset')
+    dataset_uid = _tecutil.FrameGetDataSetUniqueIDByFrameID(frame.uid)
+    return Dataset(dataset_uid, frame)
+
+
+@property
+def has_dataset(frame):
+    """`bool`: Checks to see if the `Frame <layout.Frame>` as an attached `Dataset <tecplot.data.Dataset>`
+
+    Example usage::
+
+        >>> if not frame.has_dataset:
+        ...     dataset = frame.create_dataset('Dataset', ['x','y','z','p'])
+    """
+    return _tecutil.DataSetIsAvailableForFrame(frame.uid)
+
+layout.Frame.dataset = dataset
+layout.Frame.has_dataset = has_dataset