 |
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. Subroutines 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 one or more 3x3 matrices, 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 then be used for postprocessing, e.g. by plotting isosurfaces of the scalar quantities. The functions can be called from ParaView through a plug-in, details of using this functionality are described below.
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/valib.c which just includes all the headers and can be compiled into a library, libvalib.a or libvalib.so.
The testing program test/test_valib 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 HIP kernels. Fortran and Python interfaces are also provided.
Some computationally intensive functions (triple decomposition method and average corotation) exploit acceleration by GPUs. These functions have a batch interface.
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 (static or shared) library libvalib.a or libvalib.so, i.e.
-LPATH_TO_VALIB/lib -lvalib
This mode can be seen as the standard usage of a precompiled library in C.
A Python interface is available for user-level C functions of VALIB. It builds the bindings using Cython, which has to be available. You will first need to build VALIB with
VA_WITH_PYTHON = 1
set in make.inc. A compiled extension pyvalib.cpython*** will be created in the directory python_module. To use it in your python code, simply import the extension with
import pyvalib
A Python plugin for the open-source postprocessing software ParaView is available in
python_module/ValibParaviewPlugin.py
The plugin uses the Python interface to call the C functions of VALIB, therefore the Python extension needs to be compiled first. Note that the version of Python used by ParaView must match the version used in the compilation of the Python extension.
Once the plugin is imported to ParaView (for example, using Tools->Manage Plugins->Load New in the GUI), the filter VALIB is exposed. To apply it to your dataset, you will need to precompute the velocity gradient field and select it in the field Velocity Gradient Array as the plugin input. Be aware that in contrast to the C and Python interfaces, here a row-major ordering of the velocity gradient components is considered, in order to be consistent with the output of the Gradient filter in ParaView. Upon applying the VALIB filter, arrays with the results of the selected vortex identification criteria will be added to the dataset.
VALIB comes with a simple Fortran 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 or libvalib.so), i.e.
-LPATH_TO_VALIB/lib -lvalib
Since version 2.0, the library comes with batch versions, which significantly accelerates evaluation of the more time consuming methods, such as the triple decomposition method with a high resolution.
Users may want to use also the base-level functions from their own CUDA kernels. 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
HIP functions share the batch interface with CUDA. For using the individual functions from user's own HIP kernels, this also corresponds to the 1st mode of use described for C/C++:
define preprocessor variable "HIP" in your code
#define HIP
or on the command line by adding on the compile line
-DHIP
Think twice if this is really needed. For C/C++/CUDA/HIP users, it may be simpler to use just the header files, i.e. the 1st way of use described at C/C++ section.
If you want to benefit from the GPU acceleration and the batch functions, you need to build the library. You will also need to build the library if you want to use it from Fortran, Python, and/or ParaView.
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 by executing
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. Marek Pátý has developed the Python module and ParaView filter. Václav Kolář provided a lot of help, consulting, and support.
Development of VALIB was supported by the following projects:
The support is greatly acknowledged.
Copyright (c) 2010-2026, 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.15.0