.. tflow documentation master file, created by
   sphinx-quickstart on Sat Apr 16 16:42:23 2022.
   You can adapt this file completely to your liking, but it should at least
   contain the root `toctree` directive.

Welcome to tflow documentation!
=================================

tflow: analysis package for experimental 2D PIV/3D PTV data

"tflow" contains modules to process 2D PIV/3D PTV data and analyze various flows (from laminar to turbulent).

**Basic features (velocity module)**

- temporal averaging of energy/enstrophy
- spacial averaging of energy/enstrophy
- computing vorticity, shear, rates, rate-of-strain tensor
- computing streamfunctions (Stokes flow)
- conducting Reynolds decomposition (turbulent flow)
- computing 1D/3D energy spectra and n-th orderstructure functions (turbulent flow)
- computing two-point velocity correlction function (spatial autocorrelation function) (turbulent flow)
- computing quadratic inviscid invariants of hydrodynamics (energy, helicity, linear momentum, and angular momentum)
- slicing an arbitrary plane of a 3D velocity field

**Key modules**

- velocity.py: a core analysis module
- graph.py: a wrapper of matplotlib to efficiently plot the output of velocity.py
- davis2hdf5.py: LaVision Inc. offers a cutting-edge PIV/PTV software called DaVis. This converts their output to a single hdf5 to store a velocity field data.



Philosophy
==================
To make the package compatible for theoretical and experimental studies, the input data is just a numpy array which I refer as ``udata``.

``udata`` has a shape of (dimension, nrows, ncols, (nsteps if applicable), duration).

- ``udata[0, ...]``, ``udata[1, ...]``, ``udata[2, ...]`` represent x-, y-, and  z-component of a velocity field.
- ``udata[0, ..., 100]`` represents the x-component of the velocity field at the 100th frame.
- ``udata`` assumes an evenly spaced grid. The corresponding positional grid can be generated like following:

::

    import numpy as np
    n = 101 # number of points along x and y
    L = np.pi # size of the box
    # 2D grid
    x, y = np.linspace(-L/2., L/2., n), np.linspace(-L/2., L/2., n)
    xx, yy = np.meshgrid(x, y)
    # 3D grid
    z = np.linspace(-L/2., L/2., n)
    xxx, yyy, zzz = np.meshgrid(x, y, z)



Example analysis pipeline
==================

1. Format your PIV-/PTV-extracted velocity field in the format above

   ... For DaVis (ver.10.1-, LaVision Inc.) users, you may use davis2hdf5.py.

2. ``import tflow.velocity as vel``

3. Load your velocity field data like ``udata = vel.get_udata(path2udata)``

4. Run analysis functions such as ``get_energy(udata)``

::

   # Example: Plot an energy field
   import tflow.velocity as vel
   # Load data
   udata = vel.get_udata(path2udata) # Load data
   #udata, xx, yy = vel.get_udata(path2udata, return_xy=True) # 2D velocity field and a grid
   #udata, xx, yy, zz = vel.get_udata(path2udata, return_xy=True) # 3D velocity field

   # Analyze data
   energy = vel.get_energy(udata)

   # Plot
   import matplotlib.pyplot as plt
   fig, ax = plt.subplots(111)
   ax.pcolormesh(xx, yy, energy[..., t]) # plot an energy field at the 100th frame
   plt.show()

Notes
==================

Plans: I will publish this package soon (before the end of May 2022.)
If you cannot wait for the release, clone a repository from my `GitHub <https://github.com/tmatsuzawa/tflow>`_.
I will also add notebooks for tutorials.


Contact
==================

If you have questions or suggestions, contact me on my `GitHub <https://github.com/tmatsuzawa/tflow>`_ or `email <tmatsuzawa@uchicago.edu>`_.


Index
==================

* :ref:`genindex`

..
   * :ref:`modindex`
   * :ref:`search`



.. toctree::
   :maxdepth: 2
   :caption: Contents: