pytecplot 1.5.2__py3-none-any.whl

tecplot/data/query.py

@@ -0,0 +1,334 @@
+from builtins import str
+
+from collections import namedtuple
+from ctypes import byref, c_double, c_int32, c_int64
+
+from ..tecutil import _tecutil
+from ..constant import *
+from ..exception import *
+from .. import layout
+from ..tecutil import Index, IndexSet, lock
+
+
+@lock()
+def 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 to the axis assignments of the `Frame <layout.Frame>`
+        which may be any of the associated variables in the `Dataset <tecplot.data.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. Probe position must be inside the volume of the data
+            being queried, otherwise this will return `None`.
+        starting_cell (3-`tuple` of `integers <int>`, 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 <data_access>`, optional): The first zone to start
+            searching. This is required only when ``starting_cell`` is
+            specified.
+        zones (`list` of `Zones <data_access>`, optional): Limits the search to
+            the given zones. `None` implies searching all zones. (default:
+            `None`)
+        dataset (`Dataset <tecplot.data.Dataset>`, optional): The `Dataset <tecplot.data.Dataset>` to probe. (defaults to
+            the active `Dataset <tecplot.data.Dataset>`.)
+        frame (`Frame <layout.Frame>`, optional): The `Frame <layout.Frame>` which determines the spatial
+            variable assignment ``(X,Y,Z)``. (defaults to the active `Frame <layout.Frame>`.)
+
+    Returns:
+        `namedtuple <collections.namedtuple>`: ``(data, cell, zone)``:
+
+            ``data`` (`list` of `floats <float>`)
+                The values of each variable in the dataset at the given
+                position.
+            ``cell`` (3-`tuple` of `integers <int>`)
+                ``(i,j,k)`` of the cell containing the given position.
+            ``zone`` (`Zone <data_access>`)
+                Zone containing the given position
+
+    .. note:: Returns `None` if the position can't be probed.
+
+        This method will return `None` if the position is outside the volume
+        of the data being queried. This means one should capture the results
+        in a single variable and test it against `None` before proceeding::
+
+            result = tp.data.query.probe_at_position(1.0, 2.0, 3.0)
+            if result is None:
+                print('probe failed.')
+            else:
+                data, cell, zone = result
+
+        Additionally, with Tecplot 360 versions 2018 R1 and later, this
+        function will raise an exception if Tecplot 360 was interrupted via the
+        GUI during the probe operation.
+    """
+    if __debug__:
+        if frame and dataset and frame.dataset != dataset:
+            msg = ('Dataset must be attached to the input Frame: {} != {}'.
+                   format(repr(frame.dataset), repr(dataset)))
+            raise TecplotValueError(msg)
+        if (starting_cell is None) ^ (starting_zone is None):
+            msg = 'starting_cell option requires an associated starting_zone'
+            raise TecplotLogicError(msg)
+
+    if dataset is None:
+        if frame is None:
+            frame = layout.active_frame()
+        dataset = frame.dataset
+    elif frame is None:
+        frame = dataset.frame
+
+    with frame.activated():
+        if starting_cell is None:
+            start_with_local_cell = False
+            i, j, k = 0, 0, 0
+            starting_zone_index = 0
+        else:
+            start_with_local_cell = True
+            i, j, k = (x+1 for x in starting_cell)
+            starting_zone_index = starting_zone.index
+
+        allocd = []
+        if zones is not None:
+            zones = IndexSet(*zones)
+            allocd.append(zones)
+
+        data = (max(3, dataset.num_variables)*c_double)()
+
+        try:
+            result = _tecutil.ProbeAtPosition(
+                x, y, z or 0,
+                i, j, k,
+                IJKPlanes.Volume.value,
+                starting_zone_index+1,
+                start_with_local_cell,
+                data,
+                zones,
+                z is not None,
+                False,
+                nearest)
+            success, i, j, k, plane, zone_index = result
+        except TecplotSystemError as e:
+            if 'Assertion' in str(e):
+                raise
+            success = False
+
+        if not success:
+            if _tecutil.InterruptCheck():
+                raise TecplotInterruptError()
+            return None
+
+        cell = (Index(i-1), Index(j-1), Index(k-1))
+        zone_index = Index(zone_index-1)
+
+        for a in allocd:
+            a.dealloc()
+
+        ProbeResult = namedtuple('ProbeResult', ['data', 'cell', 'zone'])
+        return ProbeResult(data[:], cell, dataset.zone(zone_index))
+
+
+@lock()
+def probe_on_surface(positions=((0,),(0,),(0,)), zones=None, variables=None,
+                     probe_nearest=ProbeNearest.Position, obey_blanking=True,
+                     num_nearest_nodes=20, tolerance=1e-5, dataset=None,
+                     frame=None):
+    """Returns field values at points on a surface closest the points given.
+
+    .. note::
+
+        The positions are processed according to the axis assignments of the
+        `Frame <layout.Frame>` which may be any of the associated variables in the `Dataset <tecplot.data.Dataset>`
+        and not necessarily (but usually) ``(X, Y, Z)``. See:
+        `Cartesian3DFieldAxis.variable`.
+
+    Parameters:
+        positions (2D `float` array): Array of points to probe dimensioned by
+            ``(3, N)`` where the first dimension corresponds to ``(x, y, z)``.
+            A 1D `float` array is accepted for single point probes, however
+            this should be avoided when probing several positions as the
+            internal algorithm is optimized for probing many positions at once.
+        zones (`list` of `Zones <data_access>`, optional): Limits the search to
+            the given zones. `None` implies searching all active relevant
+            surface zones including surfaces of ordered volume zones. To search
+            FE or polygonal volume boundaries, include the volume zones in this
+            list. (default: `None`)
+        variables (`list` of `Variables <Variable>`, optional): The variables
+            within the dataset to probe. `None` implies all variables.
+            (default: `None`)
+        probe_nearest (`ProbeNearest`, optional): Probe at the nodal location
+            (`ProbeNearest.Node`) or interpolate to nearest location on the
+            surface (`ProbeNearest.Position`, default). The return parameter
+            **cells_or_nodes** will be cells if set to `ProbeNearest.Position`
+            (default), or nodes if set to `ProbeNearest.Node`.
+        obey_blanking (`bool`, optional): Do not search blanked cells according
+            the frame's style settings. (default: `True`)
+        num_nearest_nodes (`int`, optional): Only consider surface
+            cells that contain one of the closest ``N`` nodes to the probed
+            position. For highly varying surfaces, the nearest cell may or may
+            not contain the nearest nodes to the probe position and so this
+            value should be increased accordingly, however doing so increases
+            the search-space linearly. (default: 20)
+        tolerance (`float`, optional): The percentage of the longest cartesian
+            ``(x, y, z)`` dimension subtended by the polygons of the surface.
+            This is used in several parts of the algorithm to find the nearest
+            position on the surface zones and should be increased when probing
+            imprecise nodal position data. (default: 1e-5)
+        dataset (`Dataset <tecplot.data.Dataset>`, optional): The `Dataset <tecplot.data.Dataset>` to probe. (defaults to
+            the active `Dataset <tecplot.data.Dataset>`.)
+        frame (`Frame <layout.Frame>`, optional): The `Frame <layout.Frame>` which determines the spatial
+            variable assignment ``(X,Y,Z)``. (defaults to the active `Frame <layout.Frame>`.)
+
+    Returns:
+        `namedtuple <collections.namedtuple>`: ``(data, cells_or_nodes, planes,
+        zone)``:
+
+            ``data`` (`list` of `floats <float>`)
+                Flattened `float` array which can be reshaped to ``(V, N)``
+                where ``V`` is the number of variables returned (either the
+                number of variables in the dataset or the length of
+                **variables** input parameter) and ``N`` is the number of
+                points probed.
+            ``cells_or_nodes`` (`list` of `integers <int>`)
+                The index to the cells (or nodes if `ProbeNearest.Node` was
+                passed in to **probe_nearest**) containing the returned
+                positions.
+            ``planes`` (`list` of `IJKPlanes`)
+                For ordered zones, these are the plane-orientations of the
+                cells for each probed position.
+            ``zones`` (`list` of `Zones <data_access>`)
+                Zones containing the given positions.
+
+    .. versionadded:: 2018.1
+        Probe on surface requires Tecplot 360 2018 R1 or later.
+
+    .. note:: The frame's plot type must be set to `PlotType.Cartesian3D`
+
+        Probe on surface requires the spatial variables to be set according to
+        the frame's style. This can be done by setting the plot type to
+        `PlotType.Cartesian3D`. Example::
+
+            tp.active_frame().plot_type = tp.constant.PlotType.Cartesian3D
+
+        For probing on 2D data, use `probe_at_position()`.
+
+    .. note:: Linear zones will always return nearest nodal values.
+
+        If linear zones, which are ignored by default, are included in the
+        **zones** parameter, the resulting values on that zone will always be
+        nodal and no interpolation on the position will be done.
+
+    .. note:: Irregular or jaggged surfaces may behave poorly.
+
+        For performance reasons, this algorithm has the potential to miss the
+        closest position on highly varying surfaces. This can be addressed by
+        first increasing **num_nearest_nodes** to search more of the zones and
+        then by increasing the **tolerance** to allow for imprecise position
+        data - skewed polygons for example.
+
+        All nodes of each cell considered are checked for co-planarity. This
+        check can be relaxed slightly by increasing the **tolerance**
+        parameter. The nearest position calculation will then be made assuming
+        the cells are planar and the resulting positions may be imprecise.
+
+    Example usage:
+
+    .. code-block:: python
+        :emphasize-lines: 14,28
+
+        from os import path
+        import numpy as np
+
+        import tecplot as tp
+        from tecplot.constant import PlotType
+
+        examples = tp.session.tecplot_examples_directory()
+        datafile = path.join(examples, 'SimpleData', 'F18.plt')
+        ds = tp.data.load_tecplot(datafile)
+        fr = tp.active_frame()
+        fr.plot_type = PlotType.Cartesian3D
+
+        # probe a single point
+        res = tp.data.query.probe_on_surface((13.5, 4.0, 0.6 ))
+
+        '''
+        The following line will print:
+            (13.499723788684996, 3.9922783797612795, 0.49241572276992346,
+            0.0018958827755862578, 0.07313805429221854, 0.997276718375976,
+            0.06335166319722907)
+        '''
+        print(res.data)
+
+        # probe multiple points
+        points = np.array([[13.5,  4.0, 0.6],  # just above starboard wing
+                           [13.5, -4.0, 0.6]]) # just above port wing
+
+        res = tp.data.query.probe_on_surface(points.transpose())
+        values = np.array(res.data).reshape((-1, len(points))).transpose()
+
+        '''
+        The following will print the probed position and the result of the probe
+            [ 13.5   4.    0.6] [  1.34997238e+01   3.99227838e+00   4.92415723e-01
+               1.89588278e-03   7.31380543e-02   9.97276718e-01   6.33516632e-02]
+            [ 13.5  -4.    0.6] [  1.34997238e+01  -3.99227838e+00   4.92415723e-01
+               1.89588278e-03   7.31380543e-02   9.97276718e-01   6.33516632e-02]
+        '''
+        for pt, v in zip(points, values):
+            print(pt, v)
+    """
+    if __debug__:
+        if frame and dataset and frame.dataset != dataset:
+            msg = ('Dataset must be attached to the input Frame: {} != {}'.
+                   format(repr(frame.dataset), repr(dataset)))
+            raise TecplotValueError(msg)
+
+    if dataset is None:
+        if frame is None:
+            frame = layout.active_frame()
+        dataset = frame.dataset
+    elif frame is None:
+        frame = dataset.frame
+
+    if not hasattr(positions[0], '__iter__'):
+        positions = tuple(tuple([p]) for p in positions)
+
+    nvariables = dataset.num_variables if variables is None else len(variables)
+
+    with frame.activated():
+        n = max(len(p) for p in positions)
+        m = n * nvariables
+        x = (c_double * n)(*[float(p) for p in positions[0]])
+        y = (c_double * n)(*[float(p) for p in positions[1]])
+        z = (c_double * n)(*[float(p) for p in positions[2]])
+        v = (c_double * m)()
+        cells_or_nodes = (c_int64 * n)()
+        planes = (c_int32 * n)()
+        zone_indices = (c_int32 * n)()
+
+        zone_set = None if zones is None else IndexSet(zones)
+        var_set = None if variables is None else IndexSet(variables)
+        try:
+            if not _tecutil.ProbeOnSurface(n, x, y, z, zone_set, var_set,
+                                           ProbeNearest(probe_nearest).value,
+                                           obey_blanking, num_nearest_nodes,
+                                           tolerance, v, cells_or_nodes,
+                                           planes, zone_indices):
+                raise TecplotSystemError()
+        finally:
+            if zone_set is not None:
+                zone_set.dealloc()
+            if var_set is not None:
+                var_set.dealloc()
+
+        cells_or_nodes = tuple(cells_or_nodes)
+        planes = tuple(IJKPlanes(i) for i in planes)
+        zones = tuple(dataset.zone(i) for i in zone_indices)
+
+        SurfaceProbeResult = namedtuple('SurfaceProbeResult',
+            ['data', 'cells_or_nodes', 'planes', 'zones'])
+        return SurfaceProbeResult(tuple(v), cells_or_nodes, planes, zones)

tecplot/data/save.py

@@ -0,0 +1,343 @@
+import logging
+
+from ..tecutil import _tecutil
+from ..constant import *
+from ..exception import *
+from .. import layout, macro, tecutil
+from ..tecutil import IndexSet, lock, sv
+
+
+log = logging.getLogger(__name__)
+
+
+@lock()
+def _save_tecplot(binary, frame, dataset, filename, include_text, include_geom,
+                  include_data, include_data_share_linkage,
+                  include_autogen_face_neighbors, use_point_format,
+                  associate_with_layout, zones, variables, precision, version):
+    if dataset is None:
+        if frame is None:
+            frame = layout.active_frame()
+    elif frame is None:
+        frame = dataset.frame
+    elif frame.dataset != dataset:
+        msg = ('Input dataset must be attached to the input Frame: {} != {}'.
+               format(repr(frame.dataset), repr(dataset)))
+        raise TecplotValueError(msg)
+
+    with frame.activated():
+        with tecutil.ArgList() as arglist:
+            alloc_list = []
+            arglist[sv.FNAME] = tecutil.normalize_path(filename)
+            arglist[sv.BINARY] = binary
+
+            if zones is not None:
+                s = IndexSet(zones)
+                alloc_list.append(s)
+                arglist[sv.ZONELIST] = s
+
+            if variables is not None:
+                s = IndexSet(variables)
+                alloc_list.append(s)
+                arglist[sv.VARLIST] = s
+
+            arglist[sv.INCLUDETEXT] = include_text
+            arglist[sv.INCLUDEGEOM] = include_geom
+            arglist[sv.INCLUDEDATA] = include_data
+            arglist[sv.INCLUDEDATASHARELINKAGE] = include_data_share_linkage
+            arglist[sv.INCLUDEAUTOGENFACENEIGHBORS] = \
+                include_autogen_face_neighbors
+            arglist[sv.ASSOCIATELAYOUTWITHDATAFILE] = associate_with_layout
+            if version is not None:
+                arglist[sv.TECPLOTVERSIONTOWRITE] = BinaryFileVersion(version)
+            arglist[sv.PRECISION] = precision
+            arglist[sv.USEPOINTFORMAT] = use_point_format
+
+            try:
+                if not _tecutil.DataSetWriteX(arglist):
+                    raise TecplotSystemError()
+            finally:
+                for a in alloc_list:
+                    a.dealloc()
+
+        return frame.dataset
+
+
+def 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 (`str`): Name of the data file to write. (See note
+            below conerning absolute and relative paths.)
+        frame (`Frame <layout.Frame>`, optional): The `Frame <layout.Frame>` which holds the `Dataset <tecplot.data.Dataset>` to
+            be written. If this option and *dataset* are both `None`, the
+            currently active `Frame <layout.Frame>` is used. (default: `None`)
+        dataset (`Dataset <tecplot.data.Dataset>`, optional): The `Dataset <tecplot.data.Dataset>` to write out. If this
+            and *frame* are both `None`, the `Dataset <tecplot.data.Dataset>` of the currently active
+            `Frame <layout.Frame>` is used. (default: `None`)
+        include_text (`bool`, optional): Write out all text,
+            geometries and custom labels. (default: `True`)
+        include_geom (`bool`, optional): Write out all geometries.
+            (default: `True`)
+        include_data (`bool`, optional): Write out the data. Set
+            this to `False` if you only want to write out annotations.
+            (default: `True`)
+        include_data_share_linkage (`bool`, 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 (`bool`, optional): Save the
+            face neighbor connectivity. This may produce very large data
+            files. (default: `False`)
+        use_point_format (`bool`, optional): Write out point format,
+            otherwise use block format.
+            (default: `False`)
+        zones (`list` of `Zones <data_access>`, optional): `Zones
+            <data_access>` to write out. Use `None` to write out all `Zones
+            <data_access>`. (default: `None`)
+        variables (`list` of `Variables <Variable>`, optional):
+            `Variables <Variable>` to write out. Use `None` to write out all
+            `Variables <Variable>`. (default: `None`)
+        precision (`int`, optional): ASCII decimal precision to use.
+            (default: 12)
+
+    Returns:
+        `Dataset <tecplot.data.Dataset>`: The `Dataset <tecplot.data.Dataset>` read from when saving.
+
+    Raises:
+        `TecplotSystemError`
+        `TecplotLogicError`
+
+    .. note:: **Absolute and relative paths with PyTecplot**
+
+        Relative paths, when used within the PyTecplot API are always from
+        Python's current working directory which can be obtained by calling
+        :func:`os.getcwd()`. This is true for batch and `connected
+        <tecplot.session.connect()>` modes. One exception to this is paths
+        within a macro command or file which will be relative to the |Tecplot
+        Engine|'s home directory, which is typically the |Tecplot 360|
+        installation directory. Finally, when connected to a remote (non-local)
+        instance of Tecplot 360, only absolute paths are allowed.
+
+        Note that backslashes must be escaped which is especially important for
+        windows paths such as ``"C:\\\\Users"`` or ``"\\\\\\\\server\\\\path"``
+        which will resolve to ``"C:\\Users"`` and ``"\\\\server\\path"``
+        respectively. Alternatively, one may use Python's raw strings:
+        ``r"C:\\Users"`` and ``r"\\\\server\\path"``
+
+    Example:
+        In this example, we load sample data and save the data in Tecplot ASCII
+        format:
+
+        .. code-block:: python
+            :emphasize-lines: 12-14
+
+            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])
+    """
+    return _save_tecplot(
+        binary=False, frame=frame, dataset=dataset,
+        filename=filename, include_text=include_text,
+        include_geom=include_geom, include_data=include_data,
+        include_data_share_linkage=include_data_share_linkage,
+        include_autogen_face_neighbors=include_autogen_face_neighbors,
+        use_point_format=use_point_format,
+        associate_with_layout=None,
+        precision=precision,
+        zones=zones, variables=variables,
+        version=None)
+
+
+def save_tecplot_plt(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 PLT data file.
+
+    Parameters:
+        filename (`str`): Name of the data file to write. (See note
+            below conerning absolute and relative paths.)
+        frame (`Frame <layout.Frame>`, optional): The `Frame <layout.Frame>` which holds the `Dataset <tecplot.data.Dataset>` to
+            be written. If this option and *dataset* are both `None`, the
+            currently active `Frame <layout.Frame>` is used. (default: `None`)
+        dataset (`Dataset <tecplot.data.Dataset>`, optional): The `Dataset <tecplot.data.Dataset>` to write out. If this
+            and *frame* are both `None`, the `Dataset <tecplot.data.Dataset>` of the currently active
+            `Frame <layout.Frame>` is used. (default: `None`)
+        zones (`list` of `Zones <data_access>`, optional): `Zones
+            <data_access>` to write out. If `None`, all `Zones <data_access>`
+            will be saved.
+        variables (`list` of `Variables <Variable>`, optional):
+            `Variables <Variable>` to write out. If `None`, all `Variables
+            <Variable>` will be saved.
+        include_text (`bool`, optional): Write out all text,
+            geometries and custom labels. (default: `True`)
+        include_geom (`bool`, optional): Write out all geometries.
+            (default: `True`)
+        include_data (`bool`, optional): Write out the data. Set
+            this to `False` if you only want to write out annotations.
+            (default: `True`)
+        include_data_share_linkage (`bool`, 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: `False`)
+        include_autogen_face_neighbors (`bool`, optional): Save the
+            face neighbor connectivity. This may produce very large data
+            files. (default: `False`)
+        associate_with_layout (`bool`, 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 <tecplot.data.Dataset>`: The `Dataset <tecplot.data.Dataset>` read from when saving.
+
+    Raises:
+        `TecplotSystemError`
+        `TecplotLogicError`
+
+    .. note:: **Absolute and relative paths with PyTecplot**
+
+        Relative paths, when used within the PyTecplot API are always from
+        Python's current working directory which can be obtained by calling
+        :func:`os.getcwd()`. This is true for batch and `connected
+        <tecplot.session.connect()>` modes. One exception to this is paths
+        within a macro command or file which will be relative to the |Tecplot
+        Engine|'s home directory, which is typically the |Tecplot 360|
+        installation directory. Finally, when connected to a remote (non-local)
+        instance of Tecplot 360, only absolute paths are allowed.
+
+        Note that backslashes must be escaped which is especially important for
+        windows paths such as ``"C:\\\\Users"`` or ``"\\\\\\\\server\\\\path"``
+        which will resolve to ``"C:\\Users"`` and ``"\\\\server\\path"``
+        respectively. Alternatively, one may use Python's raw strings:
+        ``r"C:\\Users"`` and ``r"\\\\server\\path"``
+
+    Example:
+        In this example, we load sample data and save the data in Tecplot
+        binary PLT format:
+
+        .. code-block:: python
+            :emphasize-lines: 13-15
+
+            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_plt('wing.plt', dataset=dataset,
+                                            variables=variables_to_save,
+                                            zones=[zone_to_save])
+    """
+    return _save_tecplot(
+        binary=True, frame=frame, dataset=dataset,
+        filename=filename, include_text=include_text,
+        include_geom=include_geom, include_data=include_data,
+        include_data_share_linkage=include_data_share_linkage,
+        include_autogen_face_neighbors=include_autogen_face_neighbors,
+        use_point_format=None,
+        associate_with_layout=associate_with_layout,
+        precision=None,
+        zones=zones, variables=variables,
+        version=version)
+
+
+def save_tecplot_szl(filename, frame=None, dataset=None):
+    """Write Tecplot SZL data file.
+
+    Parameters:
+        filename (`str`): Name of the data file to write. (See note
+            below conerning absolute and relative paths.)
+        frame (`Frame <layout.Frame>`, optional): The `Frame <layout.Frame>` which holds the `Dataset <tecplot.data.Dataset>` to
+            be written. If this option and *dataset* are both `None`, the
+            currently active `Frame <layout.Frame>` is used. (default: `None`)
+        dataset (`Dataset <tecplot.data.Dataset>`, optional): The `Dataset <tecplot.data.Dataset>` to write out. If this
+            and *frame* are both `None`, the `Dataset <tecplot.data.Dataset>` of the currently active
+            `Frame <layout.Frame>` is used. (default: `None`)
+
+    Returns:
+        `Dataset <tecplot.data.Dataset>`: The `Dataset <tecplot.data.Dataset>` read from when saving.
+
+    .. note:: **Absolute and relative paths with PyTecplot**
+
+        Relative paths, when used within the PyTecplot API are always from
+        Python's current working directory which can be obtained by calling
+        :func:`os.getcwd()`. This is true for batch and `connected
+        <tecplot.session.connect()>` modes. One exception to this is paths
+        within a macro command or file which will be relative to the |Tecplot
+        Engine|'s home directory, which is typically the |Tecplot 360|
+        installation directory. Finally, when connected to a remote (non-local)
+        instance of Tecplot 360, only absolute paths are allowed.
+
+        Note that backslashes must be escaped which is especially important for
+        windows paths such as ``"C:\\\\Users"`` or ``"\\\\\\\\server\\\\path"``
+        which will resolve to ``"C:\\Users"`` and ``"\\\\server\\path"``
+        respectively. Alternatively, one may use Python's raw strings:
+        ``r"C:\\Users"`` and ``r"\\\\server\\path"``
+
+    Example:
+        In this example, we load sample data and save it in Tecplot SZL
+        format:
+
+        .. code-block:: python
+            :emphasize-lines: 7
+
+            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)
+            tecplot.data.save_tecplot_szl('wing.szplt')
+    """
+    if dataset is None:
+        if frame is None:
+            frame = layout.active_frame()
+    elif frame is None:
+        frame = dataset.frame
+    elif frame.dataset != dataset:
+        msg = ('Input dataset must be attached to the input Frame: {} != {}'.
+               format(repr(frame.dataset), repr(dataset)))
+        raise TecplotValueError(msg)
+
+    filepath = tecutil.normalize_path(filename)
+    with frame.activated():
+        macro.execute_extended_command(
+            'Tecplot Subzone Data Tools',
+            'WRITEDATASET FILENAME="{}"'.format(filepath))
+        return frame.dataset