DPIVSoft Python

DPIVSoft is an open-source PIV (Particle Image Velocimetry) code, originally written in MATLAB by Thomas Leweke and Patrice Meunier (https://www.irphe.fr/~meunier/). This project ports it to Python and adds GPU acceleration through OpenCL.

Documentation (user guide and API reference): https://dpivsoft-python.readthedocs.io

Features

• 2D PIV with iterative window deformation, on CPU or GPU (OpenCL), with masking of solid bodies
• Stereo PIV: target calibration (TSI and LaVision), Soloff 3-component reconstruction and disparity (Δz) correction
• Synthetic particle images from analytic flows or custom velocity fields (e.g. CFD)
• Post-processing: vorticity, divergence and other derived fields
• Per-vector uncertainty from the correlation peak ratio — Xue et al., Meas. Sci. Technol. 25, 115301 (2014)
• Forces from 2D PIV fields:
  • Vorticity-based impulse method — Martín-Alcántara & Fernández-Feria, Phys. Rev. Fluids 4, 024702 (2019)
  • Mesh-based projection method — Chang, Proc. R. Soc. A 437:517–525 (1992)
• A GUI for PIV, masks, stereo, post-processing, synthetic images and uncertainty

Status

DPIVSoft is in beta, and the API may change between versions.

• 2D PIV (CPU and GPU) is the mature part: tested against analytic flows, with the GPU path checked against the CPU one.
• Stereo PIV is validated on synthetic images only, not yet against experimental ground truth. Treat it as experimental.
• Force methods are validated on analytic benchmark fields, not on noisy PIV data. The wall-shear term of the projection method is not reliable from PIV.

Results changed in several recent releases; check the changelog before reprocessing older data. Testing and feedback are welcome.

Installing

pip install dpivsoft

From source:

git clone https://gitlab.com/jacabello/dpivsoft_python.git
cd dpivsoft_python
python -m pip install .

For development, install in editable mode with the build, lint and documentation tools: python -m pip install -e ".[dev,docs]". requirements.txt pins one set of versions known to work.

Requirements:

• Python ≥ 3.11 (tested on 3.11, 3.12 and 3.13). Dependencies are listed in pyproject.toml and installed by pip.
• For the GPU path, an OpenCL runtime for your device (tested on an AMD RX 580). The CPU path needs none.

Quick start

GUI

Start the GUI from the Python environment where DPIVSoft is installed:

python -m dpivsoft.gui                 # empty window
python -m dpivsoft.gui session.yaml    # reopen a saved session (File → Save session)

The GUI needs tkinter, which pip cannot install. Some Python distributions package it separately (python3-tk on Debian/Ubuntu, python-tk on Homebrew). python -m tkinter opens a small test window if it is available.

Each PIV or stereo run writes its parameters.yaml next to the results, so it can be repeated from a script. Forces have no GUI tab; compute them from a script.

Scripts

Start with dpivsoft/Examples/simple_tutorial.py, then the getting started guide.

Examples

Example scripts are in dpivsoft/Examples/:

• simple_tutorial.py — basic 2D PIV run (synthetic images → CPU PIV → plotting)
• GPU_simple_tutorial.py — the same run on the GPU
• masked_airfoil_tutorial.py — airfoil flow with the solid body masked out
• stereo_tutorial.py — stereo PIV with calibration and 3-component reconstruction (downloads a ~197 MB public dataset)
• forces_tutorial.py — forces on an analytic oscillating-cylinder flow with both methods
• mesh_tutorial.py — FEM mesh and auxiliary potentials for the projection method
• uncertainty_tutorial.py — calibrate per-vector uncertainty and check its coverage
• performance.py — GPU vs CPU benchmark

Testing

Run the tests from a cloned repository (some write inside Examples/):

python -m unittest discover dpivsoft/tests -b

Or run a single suite, e.g. python -m unittest dpivsoft.tests.test_masking -b.

The GPU tests need an OpenCL device, the GUI smoke tests need a display, and the real-image part of test_cpt_sorting needs the PIV Challenge case E target downloaded by stereo_tutorial.py.

Contributors

1. Jorge Aguilar-Cabello

Acknowledgements

1. Patrice Meunier
2. Thomas Leweke
3. Raul Infante-Sainz
4. Luis Parras
5. Carlos del Pino

How to cite this work

J. Aguilar-Cabello, L. Parras, C. del Pino (2022), "DPIVSoft-OpenCL: A multicore CPU–GPU accelerated open-source code for 2D Particle Image Velocimetry," SoftwareX 20, 101256. https://doi.org/10.1016/j.softx.2022.101256