Metadata-Version: 2.4
Name: dpivsoft
Version: 0.16.0
Summary: CPU and OpenCL GPU particle image velocimetry algorithms
Author: Jorge Aguilar-Cabello
License-Expression: GPL-3.0-only
Project-URL: Homepage, https://dpivsoft-python.readthedocs.io
Project-URL: Source, https://gitlab.com/jacabello/dpivsoft_python
Project-URL: Changelog, https://dpivsoft-python.readthedocs.io/en/latest/changelog.html
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Intended Audience :: Science/Research
Classifier: Natural Language :: English
Requires-Python: >=3.11
Description-Content-Type: text/markdown
License-File: LICENSE.txt
Requires-Dist: numpy>=1.26.4
Requires-Dist: reikna>=0.8.0
Requires-Dist: scipy>=1.11.4
Requires-Dist: scikit-image>=0.22.0
Requires-Dist: opencv-python>=4.8.1.78
Requires-Dist: Pillow>=10.1.0
Requires-Dist: matplotlib>=3.8.0
Requires-Dist: PyYAML>=6.0.2
Requires-Dist: pyopencl>=2024.1
Requires-Dist: Shapely>=2.0.6
Requires-Dist: importlib_resources>=5.0.0
Requires-Dist: networkx>=3.0
Requires-Dist: scikit-learn>=1.3.2
Requires-Dist: meshio>=5.3.5
Requires-Dist: gmsh>=4.13.1
Requires-Dist: scikit-fem>=10.0.2
Provides-Extra: docs
Requires-Dist: sphinx; extra == "docs"
Requires-Dist: myst-parser; extra == "docs"
Requires-Dist: furo; extra == "docs"
Provides-Extra: dev
Requires-Dist: build; extra == "dev"
Requires-Dist: twine; extra == "dev"
Requires-Dist: ruff; extra == "dev"
Dynamic: license-file

# 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](CHANGELOG.md) before reprocessing older data. Testing and feedback are welcome.

## Installing

```bash
pip install dpivsoft
```

From source:

```bash
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:

```bash
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](https://dpivsoft-python.readthedocs.io/en/latest/getting_started.html).

## 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/`):

```bash
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](https://gitlab.com/jacabello)

## Acknowledgements

1. Patrice Meunier
2. Thomas Leweke
3. [Raul Infante-Sainz](https://gitlab.com/infantesainz)
4. [Luis Parras](https://gitlab.com/lparras)
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>
