 |
valib
Vortex Analysis LIBrary
|
|
valib
Vortex Analysis LIBrary
|
VALIB is a collection of functions intended for computing local vortex identification criteria out of the velocity gradient at a point in 3D. The project contains some established methods as well as some recently developed methods. Functions have a common interface based on the velocity gradient at a point in 3D, which is a 3x3 matrix stored in a column-major format. The 3x3 matrix of derivatives of the velocity components u, v, w by x, y, z,
[ du/dx du/dy du/dz ] [ dv/dx dv/dy dv/dz ] [ dw/dx dw/dy dw/dz ]
is stored as an array of length 9 as
[ du/dx dv/dx dw/dx du/dy dv/dy dw/dy du/dz dv/dz dw/dz ]
On the output from each function, there is the demanded quantity - one or more scalars, a vector of length 3, or a 3x3 matrix, depending on the nature of the quantity.
The intended use of the library is to evaluate a vortex identification quantity for each point in a 3-D flow field by calling a VALIB function at each of these points and storing the result. These values can be then used for postprocessing, e.g. by plotting isosurfaces of the scalar quantities.
Some widely used methods in the collection include
Some recent methods include
The functions are implemented as C-header files and can be used as such from C/C++ codes. There is an auxiliary file src/va.c which just includes all the headeres and can be compiled to a library, libva.a.
The testing program test/test_libva is written in C and shows basic usage of the library at a local point.
This design gives the flexibility of usage in a variety of languages, including seamless use by CUDA and OpenCL kernels.
VALIB documentation generated by Doxygen is available at http://users.math.cas.cz/~sistek/software/valib/
You can download a particular released version of VALIB from the list below
The latest version under development can be downloaded from the git repository of VALIB at https://bitbucket.org/jakub_sistek/valib
For example, you can simply clone the repository by
git clone https://bitbucket.org/jakub_sistek/valib
Using header files. Include the correct header file into your code and call the corresponding function. The VALIB library need not be even compiled in this mode of use. In C++, the header should be included in the extern "C" { } clause, e.g.
extern "C" {
#include "lambda2.h"
}
This mode is similar to generic programming with templates in C++.
Using a precompiled library. Use just the common header valib.h, i.e.
#include "valib.h"
This file does not contain implementations of the functions, it only provides their signatures. After compiling your code, link to the precompiled library libvalib.a, i.e.
-LPATH_TO_VALIB/lib -lvalib
This mode can be seen as the standard usage of a precompiled library in C.
VALIB comes with a simple interface of the user-level C functions. You will need to build the VALIB library and the Fortran module first (see below). For using it, follow these three steps:
In your application, use this module
use valib_mod
When compiling your application, add the path
-IPATH_TO_VALIB/include
to tell the Fortran compiler where to look for the module.
Link to the precompiled library libvalib.a, i.e.
-LPATH_TO_VALIB/lib -lvalib
You may want to use these functions from CUDA kernels. This can be important for accelerating evaluation of the more time consuming methods, such as the triple decomposition method with a high resolution.
This corresponds to the 1st mode of use described for C/C++:
define preprocessor variable "CUDA" in your code
#define CUDA
or on the command line by adding on the compile line
-DCUDA
This corresponds to the 1st mode of use described for C/C++:
define preprocessor variable "OPENCL" in your code
#define OPENCL
or on the command line by adding on the compile line
-DOPENCL
This is really needed only for Fortran users. For C/C++/CUDA/OpenCL users, it is simpler to use just the header files, i.e. the 1st way of use described at C/C++ section.
make.inc file with your setting of the C compiler and flags in the top section. Use the make.inc.example as the template. This file is automatically included into the Makefile, which should not be edited.Open the include/common_defs.h file and check if you need to change some settings here. In particular, the type of real numbers can be changed from "double" to "float" on the line by un/commenting the correct line.
#define VA_REAL double
or
#define VA_REAL float
The double precision version is the default.
make
test/test_valib
Optional. Create the Doxygen documentation by
make doxy
You will need the Doxygen and BibTeX tools for this.
Optional. Browse the documentation by opening the file
doc/doxy/valib/html/index.html
in your favourite browser.
Optional. If you want to use VALIB from Fortran, precompile the module file with the interface. Open file include/valib_mod.F90 and check if you need to change the type of real numbers from "c_double" to "c_float" on the line by un/commenting the line
#define VA_REAL_F c_double
or
#define VA_REAL_F c_float
The double precision version is the default. Make sure your type here matches the type used for VALIB (see step 2). Use c_double for double, and c_float for float.
Then run
make fortran
This generates the module include/valib_mod.mod with the VALIB interface to be used in Fortran applications.
The VALIB library has been developed by Jakub Šístek (Institute of Mathematics of the Czech Academy of Sciences, Prague), with a lot of help, consulting, and support provided by Václav Kolář (Institute of Hydrodynamics of the Czech Academy of Sciences, Prague).
Development of VALIB was supported by the following projects:
This support is greatly appreciated.
Copyright (c) 2010-2020, Jakub Šístek All rights reserved. Redistribution and use in source and binary forms, with or without modification, are permitted provided that the following conditions are met: 1. Redistributions of source code must retain the above copyright notice, this list of conditions and the following disclaimer. 2. Redistributions in binary form must reproduce the above copyright notice, this list of conditions and the following disclaimer in the documentation and/or other materials provided with the distribution. 3. Neither the name of the copyright holder nor the names of contributors may be used to endorse or promote products derived from this software without specific prior written permission. This software is provided by the copyright holders and contributors `as is' and any express or implied warranties, including, but not limited to, the implied warranties of merchantability and fitness for a particular purpose are disclaimed. In no event shall the copyright holder or contributors be liable for any direct, indirect, incidental, special, exemplary, or consequential damages (including, but not limited to, procurement of substitute goods or services; loss of use, data, or profits; or business interruption) however caused and on any theory of liability, whether in contract, strict liability, or tort (including negligence or otherwise) arising in any way out of the use of this software, even if advised of the possibility of such damage.
For assistance, just email the author of VALIB Jakub Šístek at
sistek@math.cas.cz
1.8.17