Turbmat-Tools - a Matlab library for querying, processing and visualizing data
from the JHU Turbulence Database.
See the end of the file for license conditions.

Written by:

Edo Frederix
The Johns Hopkins University / Eindhoven University of Technology
Department of Mechanical Engineering
edofrederix@jhu.edu, edofrederix@gmail.com

Modified by:

Jason Graham
The Johns Hopkins University
Department of Mechanical Engineering
jgraha8@gmail.com

---- Summary -----------------------------------------------------------------

Turbmat-Tools is a Matlab package with six ready-to-use scripts that make use
of the Turbmat package to fetch, process and visualize data from the Johns
Hopkins Turbulence Database Cluster. The Turbmat package is a Matlab library
for the JHU Turbulence Database Cluster. Turbmat provides a wrapper around
Matlab's intrinsic web service functions for calling the JHU Turbulence
Database Cluster. This package, called Turbmat-Tools, makes use of the Turbmat
library, to connect to the turbulence database.

Turbmat-Tools comes with six ready-to-use example scripts for performing
requests on the JHU Turbulence Database. These scripts do not require any
modification. All input data is obtained from the user by GUI input boxes.

All six scripts make use of the TurbTools class. This class, purposefully
developed for Turbmat-Tools, contains a large set of useful functions to
request, parse and visualize data from the database.

To increase the performance of this package, there has been implemented local
caching functionality. This is accomplished by creating an extra layer between
the Matlab code and the database, called TurbCache. The TurbCache class stores
requests in a uniquely named cache file, and tries to retrieve a request
straight from this cache file if possible. This then avoids the necesity of a
direct expensive request on the Turbulence Database.


---- Credits -----------------------------------------------------------------

All code in this package is written by:

  Edo Frederix
  The Johns Hopkins University / Eindhoven University of Technology
  Department of Mechanical Engineering
  edofrederix@jhu.edu, edofrederix@gmail.com

with modifications and updates provided by:

  Jason Graham
  The Johns Hopkins University
  Department of Mechanical Engineering
  jgraha8@gmail.com

This package is shipped under the terms of the GNU General Public License
version 3 or any later version. A copy of the GNU GPL v3 resides in this
package. A more formal statement can be found at the bottom of this file.

As a sign of appreciation, the names of Charles Meneveau (professor at JHU)
and Jason Graham (PhD student at JHU) have to be mentioned, as they
contributed to this package in many ways. Both through programming related
advise, as well as through tips and ideas on the engineering side of the
spectrum. Thanks!


---- Example Scripts ---------------------------------------------------------

As stated, this package contains a few example scripts. These scripts are:

  * PDFs. By fetching a large cube of data, this script calculates the
    probability density functions (PDF) of quantities such as pressure,
    velocity components and velocity gradient components. The velocity
    gradient components are grouped in transverse and longitudinal sets, and
    logarithmically shown.

  * PDF of Velocity Increments. This scripts fetches a provided number of
    blocks, consisting of 32x128x512 physical grid points, queried by 32x32x32
    points. Within this block, we can calculate velocity increments ranging
    from 1 physical grid point to 256 grid points. This is the equivalent of
    around 2 to 550 Kolmogorov length scales. We can accumulate important
    turbulence statistics from the velocity increments, such as skewness and
    kurtosis. This script presents these statistics in a few graphs. 

    NOTE: The Matlab Statistics Toolbox is required for this script to work.
    
  * 1D Energy Spectrum. This script generates a provided number of randomly
    positioned and oriented lines, crossing the complete simulation domain
    present in the database. For all grid points that are on these lines, the
    inline velocity component is queried. For every single line, we now have a
    signal that can be transformed to the frequency domain, using Matlab's
    standard FFT function. The discrete Fourier transform of the line signals
    can be used to compute the energy spectrum. This energy spectrum is scaled
    and displayed by this script.
    
  * 3D Vorticity. This script allows a user to fetch an arbitrary volume of
    points in a certain time step. From these evenly spaced points, we can
    calculate certain scalar quantities, such as Q-criterion, Lambda-2 or
    Vorticity magnitude, using the velocity gradient tensor components. When
    drawing iso-surfaces for the named quantities, the resulting structures
    will be representative for local vortex structures. This scripts will show
    these iso-surfaces, by using an interpolated 3D scalar field.

  * 2D Velocity. We can extract 2D slices of points with arbitrary dimension,
    orientation and position. On these 2D surfaces, we can show all three
    velocity components by a 2D vector map and a colormap. This script allows
    a user to do so, by asking numerous input values. In addition, a user can
    look at absolute velocity components or to relative velocity components,
    with respect to their average values.

  * 2D Velocity zoom. This script has much resemblance with the 2D Velocity
    script. It applies the same code, using four steps to zoom in from 1024^2
    points to 16^2 points. This allows a user to recognize both large scale
    structures in the 1024^2 surface, as well as small scale structures in the
    16^2 one. This script creates a good picture of how detailed the JHU
    Turbulence Database actually is.


---- Requirements ------------------------------------------------------------

Turbmat-Tools depends on the Turbmat library package. The Turbmat library,
just like this package, can be obtained from the JHU Turbulence Database
Cluster website at http://turbulence.pha.jhu.edu. Read the Getting Started
section in this README file for installation notes.

Furthermore, this Matlab package is cross operating system (OS) friendly. It
has been tested on Windows 7 and XP, as well as a few popular Linux
distributions ad Mac OSX 10.6.8. Without any guaranties, we are certain that
this package should run perfectly on almost any operating system that has a
working copy of Matlab installed.

For requesting very large datasets, a proper CPU and sufficient memory is
recommended. When retrieving large amounts of data from the database,
depending on your OS, Java might reach its max heap memory space. If your
system can handle it, you can increase the heap memory limit. See
http://www.mathworks.com/support/solutions/en/data/1-18I2C/.


---- Authentication Token ----------------------------------------------------

While our service is open to anyone, we would like to keep track of who is
using the service, and how. To this end, we would like each user or site to
obtain an authorization token from us:
http://turbulence.pha.jhu.edu/help/authtoken.html

If you are just experimenting, the default token included in TurbTools.m
should be sufficient. This token has a max query threshold of 2^12 = 4069
points.

In case you have obtained an authentication token, you may use it by creating
a file called "authtoken.txt" and inserting your key in there. The TurbTools
class will automatically read the contents of this file and use it as a
replacement to the default key. Another way of using your own key is by
editing TurbTools.m.

Turbmat-Tools will automatically detect the use of a testing key. If more than
4096 points are queried, and only a testing key is provided, Turbmat-Tools
will ask the user to insert a valid authentication token. Once again, you may
obtain a token for us at: http://turbulence.pha.jhu.edu/help/authtoken.html.


---- Getting Started ---------------------------------------------------------

A short step-by-step manual to get started using Turbmat-Tools:
  
  * Download Turbmat-Tools. Extract the package to a location of your own
    preference.
    
  * Turbmat-Tools depends on Turbmat. Download Turbmat from the JHU Turbulence
    website: http://turbulence.pha.jhu.edu/. Turbmat-Tools will try to find a
    directory containing the Turbmat library either within its own directory
    or its two parent directories. The Turbmat directory name should contain
    the word 'turbmat' (but not 'turbmat-tools').
    
    For example, a valid installation of Turbmat and Turbmat-Tools on *nix
    type OS would look like:
    
      Turbmat-Tools: /home/user/Turbmat-Tools-<version>/ 
      Turbmat: /home/user/Turbmat-<version>/
    
    And for Windows:
    
      Turbmat-Tools: c:\Users\user\Documents\Turbmat-Tools-<version>\ 
      Turbmat: c:\Users\user\Documents\Turbmat-<version>\
    
    You may leave version numbers in the directory name of both Turbmat and
    Turbmat-Tools. Turbmat-Tools will inform the user if it cannot find the
    Turbmat library. If it can successfully access the TurbulenceService
    class, it will print the path in which Turbmat is installed.

  * If you are in possession of an authentication token, you may create a file
    called "authtoken.txt" in the same directory as TurbTools.m resides in.
    This will override the default key. More info in the "Authentication
    Token" section of this README file.

  * Fire up Matlab

  * Open turbm_velocity2D.m with Matlab.

  * Hit the Run button. Matlab may ask you to change its working directory. If
    so, click "Change Folder". If Turbmat-Tools cannot find Turbmat, it will
    throw an error.

  * Turbmat-Tools will now ask you to flush cache. It will always do this
    before running anything. Hit No.

  * Turbmat-Tools will ask you some parameters for creating a vector map of a
    2D surface. Enter whatever you like.

  * After loading the data from the database, your requested surface will be
    presented.

  * Celebrate, and get going with the other turbm_*.m scripts!


---- Useful Turbulence Database and DNS Properties ---------------------------

For an extended overview of how the JHU Turbulence Database Cluster has been
created and for specifications on the DNS code, please see the published
Journal of Turbulence article, Vol. 9 No 31 (2008), by Yi Li et al.

In this article, Yi Li presents a helpful list of DNS parameters in the
turbulence database:

  * Grid resolution, N: 1024
  * Viscosity, nu: 0.000185
  * Time step of DNS, delta-t: 0.0002
  * Time interval between stored data sets, dt: 0.002
  * Total kinetic energy, E_tot: 0.695
  * Mean dissipation rate, epsilon: 0.0928
  * RMS velocity fluctuation, u': 0.681
  * Taylor micro length scale, lambda: 0.118
  * Taylor micro-scale Reynolds number, Re_lambda: 433
  * Kolmogorov length scale, eta_K: 0.00287
  * Kolmogorov time scale, tau_K: 0.0456
  * Integral length scale, L: 1.376
  * Integral time scale, T: 2.02


---- License -----------------------------------------------------------------

This file is part of Turbmat-Tools.

Turbmat-Tools is free software: you can redistribute it and/or modify it under
the terms of the GNU General Public License as published by the Free Software
Foundation, either version 3 of the License, or (at your option) any later
version.

Turbmat-Tools is distributed in the hope that it will be useful, but WITHOUT
ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS
FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details.

You should have received a copy of the GNU General Public License along with
Turbmat. If not, see <http://www.gnu.org/licenses/>.