pytecplot 1.5.2__py3-none-any.whl

tecplot/data/array.py

@@ -0,0 +1,645 @@
+from builtins import range, super
+
+import ctypes
+import logging
+import textwrap
+
+from ctypes import (addressof, byref, cast, c_double, c_float, c_int8, c_int16,
+                    c_int32, c_int64, c_void_p, POINTER)
+
+from ..tecutil import _tecutil, _tecutil_connector
+from ..constant import *
+from ..exception import *
+from .. import session, tecutil
+from . import operate
+
+log = logging.getLogger(__name__)
+
+
+class Array(c_void_p):
+    """Low-level accessor for underlying data within a `Dataset <tecplot.data.Dataset>`.
+
+    This object exposes a list-like interface to the underlying data array.
+    Using it, values can be directly queried and modified. After any
+    modification to the data, the Tecplot Engine will have to be notified of
+    the change. This notification will happen automatically in most cases, but
+    can be turned off using the `suspend context <tecplot.session.suspend>` for
+    a significant performance increase on large data sets.
+
+    Accessing values within an `Array` is done through the standard ``[]``
+    syntax::
+
+        >>> print(array[3])
+        3.1415
+
+    The numbers passed are interpreted just like Python's built-in
+    :py:class:`slice` object::
+
+        >>> # print the values at indices: 5, 7, 9
+        >>> print(array[5:10:2])
+        [1.0, 1.0, 1.0]
+
+    Elements within an array can be manipulated in-place with the assignment
+    operator::
+
+        >>> array[3] = 5.0
+        >>> print(array[3])
+        5.0
+
+    Element-by-element access is *not* guaranteed to be performant and users
+    should avoid writing loops over indices in Python. Instead, whole arrays
+    should be used. This will effectively push the loop down to the underlying
+    native library and will be much faster in virtually all cases.
+
+    Consider this array of 10k elements::
+
+        >>> ds = frame.create_dataset('Dataset', ['x'])
+        >>> zn = ds.add_ordered_zone('Zone', 10000)
+        >>> array = zn.values('x')
+
+    The following loop, which takes the sine of all values in the array will
+    require several Python function calls per element which is a tremendous
+    overhead::
+
+        >>> import math
+        >>> for i in range(len(ar)):
+        ...     ar[i] = math.sin(ar[i])
+
+    An immediate improvement on this can be made by looping over the elements
+    in Python only when reading the values, but assigning them using the
+    whole array. This will be several times faster for even modest arrays::
+
+        >>> ar[:] = [math.sin(x) for x in ar]
+
+    But there is still a large performance penalty for looping over elements
+    directly in Python and PyTecplot supports two solutions for large arrays:
+    `tecplot.data.operate.execute_equation` and `Array.as_numpy_array()`.
+    Please refer to these for details. Continuing with the example above, we
+    could accomplish the same thing with either of the following using
+    `execute_equation()` (assuming the array is identified by the first zone,
+    first variable)::
+
+        >>> from tecplot.data.operate import execute_equation
+        >>> execute_equation('V1 = SIN(V1)', zones=[dataset.zone(0)])
+
+    or by using the `numpy` library::
+
+        >>> import numpy as np
+        >>> ar[:] = np.sin(ar[:])
+
+    In both of these cases, the calculation of the sine and loop over elements
+    is pushed to the low level library and is much faster. Note that only the
+    `execute_equation()` solution does the calculation within Tecplot and does
+    not require the data to copied out to Python so it will typically be the
+    fastest option.
+
+    .. note::
+
+        When modifying data using this class, it may be necessary to update the
+        range of any associated contouring with a call to
+        `ContourLevels.reset()` or similar. This will ensure that the total
+        range of the new values is presented in the plot.
+    """
+    def __init__(self, zone, variable):
+        self.zone = zone
+        self.variable = variable
+        super().__init__(self._native_reference())
+
+    @property
+    def _cache(self):
+        if _tecutil_connector.suspended:
+            _tecutil_connector._delete_caches.append(self._delete_cache)
+            return True
+        else:
+            return False
+
+    def _delete_cache(self):
+        attrs = '''
+            _rnr _wnr _rrp _wrp
+            _location
+            _len
+            _data_type
+        '''.split()
+        for attr in attrs:
+            try:
+                delattr(self, attr)
+            except AttributeError:
+                pass
+
+    def _native_reference(self, writable=False):
+        args = (self.zone.dataset.uid, self.zone.index + 1, self.variable.index + 1)
+        if writable:
+            if self._cache:
+                if not hasattr(self, '_wnr'):
+                    with tecutil.lock():
+                        self._wnr = _tecutil.DataValueGetWritableNativeRefByUniqueID(*args)
+                return self._wnr
+            else:
+                with tecutil.lock():
+                    return _tecutil.DataValueGetWritableNativeRefByUniqueID(*args)
+        else:
+            if self._cache:
+                if not hasattr(self, '_rnr'):
+                    with tecutil.lock():
+                        self._rnr = _tecutil.DataValueGetReadableNativeRefByUniqueID(*args)
+                return self._rnr
+            else:
+                with tecutil.lock():
+                    return _tecutil.DataValueGetReadableNativeRefByUniqueID(*args)
+
+    @tecutil.lock()
+    def _raw_pointer(self, writable=False):
+        if _tecutil_connector.connected:
+            msg = 'raw pointer access only available in batch-mode'
+            raise TecplotLogicError(msg)
+        elif writable:
+            ref = self._native_reference(writable=True)
+            _tecutil.handle.tecUtilDataValueGetWritableRawPtrByRef.restype = \
+                POINTER(self.c_type)
+            wrp = _tecutil.DataValueGetWritableRawPtrByRef(ref)
+            if self._cache:
+                if not hasattr(self, '_wrp'):
+                    self._wrp = wrp
+                return self._wrp
+            else:
+                return wrp
+        else:
+            _tecutil.handle.tecUtilDataValueGetReadableRawPtrByRef.restype = \
+                POINTER(self.c_type)
+            rrp = _tecutil.DataValueGetReadableRawPtrByRef(self)
+            if self._cache:
+                if not hasattr(self, '_rrp'):
+                    self._rrp = rrp
+                return self._rrp
+            else:
+                return rrp
+
+    def __eq__(self, other):
+        self_addr = addressof(cast(self, POINTER(c_int64)).contents)
+        other_addr = addressof(cast(other, POINTER(c_int64)).contents)
+        return self_addr == other_addr
+
+    def __ne__(self, other):
+        return not (self == other)
+
+    def __len__(self):
+        """The number of values in this array.
+
+        :rtype: `integer <int>`
+
+        Example showing size of ordered data::
+
+            >>> x = dataset.zone('Zone').values('X')
+            >>> print(x.shape)
+            (10, 10, 10)
+            >>> print(len(x))
+            1000
+        """
+        if self._cache:
+            if not hasattr(self, '_len'):
+                self._len = _tecutil.DataValueGetCountByRef(self)
+            return self._len
+        else:
+            return _tecutil.DataValueGetCountByRef(self)
+
+    @property
+    def location(self):
+        """`ValueLocation`: Data points location with respect to the elements.
+
+        Possible values are `ValueLocation.CellCentered` and
+        `ValueLocation.Nodal`. Example usage::
+
+            >>> print(dataset.zone(0).values('X').location)
+            ValueLocation.Nodal
+        """
+        if self._cache:
+            if not hasattr(self, '_location'):
+                self._location = _tecutil.DataValueGetLocation(
+                    self.zone.index + 1, self.variable.index + 1)
+            return self._location
+        else:
+            return _tecutil.DataValueGetLocation(self.zone.index + 1,
+                                                 self.variable.index + 1)
+
+    @property
+    def shape(self):
+        """`tuple` of `floats <float>`: ``(i, j, k)`` shape for this array.
+
+        This is defined by the parent zone and can be used to reshape arrays.
+        The following example assumes 32-bit floating point array and copies
+        the Tecplot-owned ``data`` into the `numpy`-owned ``array``::
+
+            >>> import numpy as np
+            >>> data = dataset.zone('Zone').values('X')
+            >>> array = np.empty(data.shape, dtype=np.float32)
+            >>> arr_ptr = array.ctypes.data_as(POINTER(data.c_type))
+            >>> memmove(arr_ptr, data.copy(), sizeof(data.c_type) * len(data))
+
+        The data array presented is normally one-dimensional. For ordered data,
+        you may wish to reshape the array indexing according to the
+        dimensionality given by the ``shape`` attribute:
+
+        .. code-block:: python
+            :emphasize-lines: 30
+
+            import numpy as np
+            import tecplot as tp
+
+            frame = tp.active_frame()
+            dataset = frame.create_dataset('Dataset', ['X'])
+            zone = dataset.add_ordered_zone('Zone', shape=(3,3,3))
+
+            '''
+            the following will print:
+            [ 0.  0.  0.  0.  0.  0.  0.  0.  0.  0.  0.  0.  0.  0.
+              0.  0.  0.  0.  0.  0.  0.  0.  0.  0.  0.  0.  0.]
+            '''
+            x = np.array(zone.values('X')[:])
+            print(x)
+
+            '''
+            the following will print:
+            [[[ 0.  0.  0.]
+              [ 0.  0.  0.]
+              [ 0.  0.  0.]]
+
+             [[ 0.  0.  0.]
+              [ 0.  0.  0.]
+              [ 0.  0.  0.]]
+
+             [[ 0.  0.  0.]
+              [ 0.  0.  0.]
+              [ 0.  0.  0.]]]
+            '''
+            x.shape = zone.values('X').shape
+            print(x)
+
+        """
+        if self.zone.zone_type is ZoneType.Ordered:
+            array_shape = tuple(i for i in self.zone._shape if i > 1)
+        else:
+            array_shape = (self.zone.num_points,)
+        if self.location is ValueLocation.CellCentered:
+            array_shape = tuple(i - 1 for i in array_shape if i > 2)
+        if not array_shape:
+            array_shape = (1,)
+        return array_shape
+
+    @property
+    def c_type(self):
+        """`ctypes` compatible data type of this array.
+
+        This is the `ctypes` equivalent of `Array.data_type` and will return
+        one of the following:
+
+            * `ctypes.c_float`
+            * `ctypes.c_double`
+            * `ctypes.c_int`
+            * `ctypes.c_int16`
+            * `ctypes.c_int8`
+
+        and can be used to create a `ctypes` array to store a copy of the
+        data:
+
+        .. code-block:: python
+
+            import tecplot as tp
+            frame = tp.active_frame()
+            dataset = frame.create_dataset('Dataset', ['x'])
+            dataset.add_ordered_zone('Zone', (3,3,3))
+            x = dataset.zone('Zone').values('x')
+            # allocate array using Python's ctypes
+            x_array = (x.c_type * len(x))()
+            # copy values from Dataset into ctypes array
+            x_array[:] = x[:]
+        """
+        _ctypes = {
+            FieldDataType.Float: ctypes.c_float,
+            FieldDataType.Double: ctypes.c_double,
+            FieldDataType.Int32: ctypes.c_int32,
+            FieldDataType.Int16: ctypes.c_int16,
+            FieldDataType.Byte: ctypes.c_int8}
+        return _ctypes[self.data_type]
+
+    @property
+    def data_type(self):
+        """`FieldDataType`: Indicating the underlying value type of this array.
+
+        Example usage::
+
+            >>> print(dataset.zone('Zone').values('X').data_type)
+            FieldDataType.Float
+        """
+        return _tecutil.DataValueGetRefType(self)
+
+    @tecutil.lock()
+    def as_ctypes_array(self, offset=0, size=None, copy=True):
+        """Present the underlying data array as a `ctypes.Array`.
+
+        If the **copy** parameter is `False`, this method will attempt to return
+        an array pointing to the actual data stored in the Tecplot Engine. This
+        will fail in connected mode or if the loader does not support
+        immediate loading of the entire array into memory. Care should be taken
+        to ensure the validity of the pointers to the data.
+
+        Parameters:
+            offset (`int`, optional): Zero-based offset into the array. This
+                will be the starting point of the resulting data. (default: 0)
+            size (`int`, optional): Number of elements in the resulting array.
+                The default (a value of `None`) is to go to the end of the
+                data.
+            copy (`bool`, optional): Copy the data out from the Tecplot Engine.
+                If `False`, an attempt is made to point to the underlying raw
+                data and an exception is thrown on error. (default: `True`)
+
+        Returns:
+            `ctypes.Array`
+
+        Example usage::
+
+            >>> x = dataset.zone('Zone').values('X').as_ctypes_array()
+        """
+        size = (len(self) - offset) if size is None else size
+        CArray = (self.c_type * size)
+        if copy:
+            arr = CArray()
+            _tecutil.DataValueArrayGetByRef(self, offset + 1, size, arr)
+            return arr
+        else:
+            ptr = self._raw_pointer(True)
+            if offset:
+                vptr = ctypes.cast(ctypes.pointer(ptr),
+                                   ctypes.POINTER(ctypes.c_void_p))
+                vptr.contents.value += ctypes.sizeof(ptr._type_) * offset
+            ptr_addr = ctypes.addressof(ptr.contents)
+            arr = CArray.from_address(ptr_addr)
+            return arr
+
+    def as_numpy_array(self, offset=0, size=None, copy=True):
+        """Present the underlying data array as a `numpy.ndarray`.
+
+        If the **copy** parameter is `False`, this method will attempt to return
+        an array pointing to the actual data stored in the Tecplot Engine. This
+        will fail in connected mode or if the loader does not support
+        immediate loading of the entire array into memory. Care should be taken
+        to ensure the validity of the pointers to the data.
+
+        Parameters:
+            offset (`int`, optional): Zero-based offset into the array. This
+                will be the starting point of the resulting data. (default: 0)
+            size (`int`, optional): Number of elements in the resulting array.
+                The default (a value of `None`) is to go to the end of the
+                data.
+            copy (`bool`, optional): Copy the data out from the Tecplot Engine.
+                If `False`, an attempt is made to point to the underlying raw
+                data and an exception is thrown on error. (default: `True`)
+
+        Returns:
+            `numpy.ndarray`
+
+        Example usage::
+
+            >>> x = dataset.zone('Zone').values('X').as_numpy_array()
+        """
+        import numpy as np
+        carr = self.as_ctypes_array(offset, size, copy)
+        return np.ctypeslib.as_array(carr)
+
+    @tecutil.lock()
+    def copy(self, offset=0, size=None):
+        """Copy the whole or part of the array into a ctypes array.
+
+        Parameters:
+            offset (`int`, optional): Zero-based offset for starting
+                index to copy. (default: 0)
+            size (`int`, optional): Number of values to copy into the
+                resulting array. A value of `None` will copy to the end of the
+                array. (default: `None`)
+
+        Here we will copy out chunks of the data, do some operation and set the
+        values back into the dataset:
+
+        .. code-block:: python
+
+            import tecplot as tp
+
+            tp.new_layout()
+            frame = tp.active_frame()
+            dataset = frame.create_dataset('Dataset', ['x'])
+            dataset.add_ordered_zone('Zone', (2, 2, 2))
+            x = dataset.zone('Zone').values('x')
+
+            # loop over array copying out 4 values at a time
+            for i, offset in enumerate(range(0, len(x), 4)):
+                x_array = x.copy(offset, 4)
+                x_array[:] = [i] * 4
+                x[offset:offset + 4] = x_array
+
+            # will print: [0.0, 0.0, 0.0, 0.0, 1.0, 1.0, 1.0, 1.0]
+            print(x[:])
+        """
+        try:
+            return self.as_numpy_array(offset, size, copy=True)
+        except ImportError:
+            msg = textwrap.dedent('''\
+                Falling back to using basic Python for data operations.
+                If installed, PyTecplot will make use of Numpy where
+                appropriate for significant performance gains.
+            ''')
+            log.warning(msg)
+            return self.as_ctypes_array(offset, size, copy=True)
+
+    def _slice_range(self, s):
+        start = s.start or 0
+        if start < 0:
+            start += len(self)
+        stop = s.stop or len(self)
+        if stop < 0:
+            stop += len(self)
+        step = s.step or 1
+        return range(start, stop, step)
+
+    def __getitem__(self, i):
+        if not isinstance(i, slice):
+            return _tecutil.DataValueGetByRef(self, i + 1)
+        else:
+            s = self._slice_range(i)
+            if s.step > 1:
+                # i is a non-contiguous slice
+                return [_tecutil.DataValueGetByRef(self, ii + 1) for ii in s]
+            else:
+                # i is a contiguous slice
+                return self.copy(s.start, s.stop - s.start)
+
+    @tecutil.lock()
+    def __setitem__(self, i, val):
+        """
+        Developers note:
+            This method avoids using raw pointers which may not be available
+            for different reasons -- backing data does not support it, limited
+            memory resources or we are in connected mode for example.
+        """
+        if not isinstance(i, slice):
+            # i is an index
+            ref = self._native_reference(True)
+            _tecutil.DataValueSetByRef(ref, i + 1, val)
+            session.data_altered(self.zone, self.variable, i)
+        elif isinstance(val, Array) and val == self:
+            # self assignment no-op
+            return
+        else:
+            if callable(getattr(val, 'ravel', None)):
+                val = val.ravel()
+            s = self._slice_range(i)
+            if len(s) != len(val):
+                msg = 'Array length mismatch {} != {}'
+                raise TecplotIndexError(msg.format(len(s), len(val)))
+            if s.step > 1:
+                # i is a non-contiguous slice
+                # the following works, but is slow!
+                for a, b in enumerate(s):
+                    self[b] = val[a]
+            else:
+                # i is a contiguous slice
+                offset = s.start
+                size = s.stop - s.start
+
+                if isinstance(val, Array):
+                    if (
+                        offset == 0 and
+                        size in (None, len(self)) and
+                        val.zone.dataset == self.zone.dataset
+                    ):
+                        # copy whole array
+                        if val.zone == self.zone:
+                            eqn = 'V{0} = V{1}'.format(self.variable.index + 1,
+                                                       val.variable.index + 1)
+                            operate.execute_equation(eqn, self.zone)
+                        else:
+                            src_zone_idx = self.zone.index
+                            tgt_zone_idx = val.zone.index
+                            var_idx = val.variable.index
+                            if not _tecutil.DataValueCopy(src_zone_idx + 1,
+                                                          tgt_zone_idx + 1,
+                                                          var_idx + 1):
+                                raise TecplotSystemError()
+                        return
+                    else:
+                        # either sub array or different datasets
+                        val = val.as_ctypes_array(copy=True)
+
+                ctype = self.c_type
+                if isinstance(val, ctypes.Array) and val._type_ == ctype:
+                    arr = val
+                else:
+                    # coerce val to a ctypes array, using numpy if available
+                    try:
+                        import numpy as np
+                        nparr = np.asarray(val, dtype=ctype)
+                        ptarr = nparr.ctypes.data_as(POINTER(ctype))
+                        ptaddr = addressof(ptarr.contents)
+                        arr = (ctype * size).from_address(ptaddr)
+                    except ImportError:
+                        msg = textwrap.dedent('''\
+                            Falling back to using basic Python for data
+                            operations. If installed, PyTecplot will make use
+                            of Numpy where appropriate for significant
+                            performance gains.
+                        ''')
+                        log.warning(msg)
+                        arr = (ctype * size)(*val)
+
+                ref = self._native_reference(True)
+                _tecutil.DataValueArraySetByRef(ref, offset + 1, size, arr)
+                session.data_altered(self.zone, self.variable)
+
+    def __iter__(self):
+        self.current_index = -1
+        self.current_length = len(self)
+        return self
+
+    def __next__(self):
+        self.current_index += 1
+        if self.current_index < self.current_length:
+            return self.__getitem__(self.current_index)
+        else:
+            del self.current_index
+            del self.current_length
+            raise StopIteration
+
+    def next(self):  # if sys.version_info < (3,)
+        return self.__next__()
+
+    def minmax(self):
+        """Limits of the values stored in this array.
+
+        :rtype: `tuple` of `floats <float>`
+
+        This always returns `floats <float>` regardless of the underlying data
+        type::
+
+            >>> print(dataset.zone('Zone').values('x').minmax())
+            (0, 10)
+        """
+        return _tecutil.DataValueGetMinMaxByRef(self)
+
+    def min(self):
+        """Lower bound of the values stored in this array.
+
+        :rtype: `float`
+
+        This always returns a `float` regardless of the underlying data type::
+
+            >>> print(dataset.zone('Zone').values('x').min())
+            0
+        """
+        return self.minmax()[0]
+
+    def max(self):
+        """Upper bound of the values stored in this array.
+
+        :rtype: `float`
+
+        This always returns a `float` regardless of the underlying data type::
+
+            >>> print(dataset.zone('Zone').values('x').max())
+            10
+        """
+        return self.minmax()[1]
+
+    @property
+    def shared_zones(self):
+        """`list` of `Zones <data_access>`: All `Zones <data_access>` sharing this array.
+
+        Example usage::
+
+            >>> dataset.zone('My Zone').copy(share_variables=True)
+            >>> for z in dataset.zone('My Zone').values(0).shared_zones:
+            ...     print(z.index)
+            0
+            1
+        """
+        indices = _tecutil.DataValueGetShareZoneSet(self.zone.index + 1,
+                                                    self.variable.index + 1)
+        ret = [self.zone.dataset.zone(i) for i in indices]
+        indices.dealloc()
+        return ret
+
+    @property
+    def passive(self):
+        """`bool`: An unallocated zone-variable combination.
+
+        Passive variables are placeholders where no data is defined for a zone
+        variable combination. Passive variables will always return zero when
+        queried:
+
+        .. code-block:: python
+
+            import tecplot as tp
+
+            ds = tp.active_page().add_frame().create_dataset('D', ['x','y'])
+            z = ds.add_ordered_zone('Z1', (3,))
+            assert not z.values(0).passive
+        """
+        return _tecutil.DataValueIsPassive(self.zone.index + 1,
+                                           self.variable.index + 1)

tecplot/data/create.py

@@ -0,0 +1 @@
+