pykitPIV is a Python package that provides rich and reproducible virtual environments for training machine learning (ML) algorithms in velocimetry.

pykitPIV gives the user, or the ML agent, a lot of flexibility in selecting various parameters that would normally be available in an experimental setting, such as seeding density, properties of the laser plane, camera exposure, particle loss, or experimental noise. We also provide an atlas of challenging synthetic velocity fields from analytic formulations, including compressible and incompressible (potential) flows. The effects of particle drift and diffusion in stationary isotropic turbulence can also be added atop the velocity fields using the simplified Langevin model (SLM). In addition, a variational approach can connect with the real wind tunnel experimentation and use a generative model to sample new training data that belong to the distribution of the specific experimental setting. This can help in re-training ML agents whenever there is a need to extend their range of operation to new experimental scenarios.

pykitPIV can operate in particle image velocimetry (PIV) or background-oriented Schlieren (BOS) mode. It exploits the idea that if the time separation between two experimental images is small, the kinematic relationship between two consecutive images is sufficient to determine particle displacement fields.

The graph below shows the overview of functionalities and possible workflows constructed from the five main classes that mimic an experimental setup and act as a virtual wind tunnel. The ML module (pykitPIV.ml) connects with each of the five main classes and provides integrations with algorithms such as convolutional neural networks, reinforcement learning, variational and generative approaches, and active learning. ML agents have freedom in interacting with the virtual experiment, can assimilate data from a real experiment, and can be trained to perform a variety of tasks using diverse custom-built rewards and sensory cues.

Kamila Zdybał is pykitPIV’s primary developer and point of contact and can be contacted by email at kamila.zdybal@empa.ch. Other authors who contributed to pykitPIV are Claudio Mucignat, Stephan Kunz, and Ivan Lunati.

If you use pykitPIV in your work, we will appreciate the citation to the following paper:

@article{pykitPIV2025,
title = "pykitPIV: A framework for flexible and reproducible virtual training of machine learning models in optical velocimetry",
journal = "SoftwareX",
volume = "31",
pages = "102356",
year = "2025",
issn = "2352-7110",
doi = "https://doi.org/10.1016/j.softx.2025.102356",
url = "https://github.com/kamilazdybal/pykitPIV",
author = "Zdybał, K. and Mucignat, C. and Lunati, I."
}

---

Installation

• Installation instruction
  • Installation
  • Local documentation build
  • Unit tests

Preliminaries

• Virtual wind tunnel with pykitPIV
• Indexing convention
• Randomization of experimental settings
  • Using randomized values
  • Forcing a fixed value
• Image generation parameters cheatsheet
  • Class: Particle
  • Class: FlowField
  • Class: Image

Quickstart

• Quickstart your image generation
• A gallery of examples
  • Virtual PIV of a Taylor-Green vortex
  • Virtual PIV with a compressible/incompressible flow
  • Virtual PIV environment for reinforcement learning
  • Variational-generative approach for creating new training samples

User Guide

• Class: Particle
  • ParticleSpecs
  • Particle
  • upload_particle_coordinates()
  • plot_properties()
• Class: FlowField
  • FlowFieldSpecs
  • FlowField
  • print_available_fields()
  • generate_constant_velocity_field()
  • generate_shearing_velocity_field()
  • generate_random_velocity_field()
  • generate_sinusoidal_velocity_field()
  • generate_checkered_velocity_field()
  • generate_chebyshev_velocity_field()
  • generate_spherical_harmonics_velocity_field()
  • generate_directionally_divergent_velocity_field()
  • generate_radial_velocity_field()
  • generate_potential_velocity_field()
  • generate_taylor_green_vortex_velocity_field()
  • generate_langevin_velocity_field()
  • compute_displacement_field()
  • upload_velocity_field()
  • Flow field utilities
    • compute_divergence()
    • compute_vorticity()
    • compute_rate_of_strain_tensor()
    • compute_rate_of_rotation_tensor()
    • compute_q_criterion()
• Class: Motion
  • MotionSpecs
  • Motion
  • forward_euler()
  • runge_kutta_4th()
  • compute_order_parameter()
  • plot_particle_motion()
• Class: Image
  • ImageSpecs
  • Image
  • add_particles()
  • add_flowfield()
  • add_motion()
  • get_velocity_field()
  • get_velocity_field_magnitude()
  • get_displacement_field()
  • get_displacement_field_magnitude()
  • compute_light_intensity_at_pixel()
  • add_reflected_light()
  • warp_images()
  • remove_buffers()
  • measure_counts()
  • concatenate_tensors()
  • save_to_tiff()
  • save_to_h5()
  • upload_from_h5()
  • plot()
  • plot_image_pair()
  • animate_image_pair()
  • plot_field()
  • plot_field_magnitude()
  • plot_image_histogram()
• Class: Postprocess
  • Postprocess
  • add_defocus()
  • add_gaussian_noise()
  • add_shot_noise()
  • log_transform_images()
  • plot()
• Module: ml
  • Data primitives and data loaders
    • PyTorch-based
      • PIVDatasetPyTorch
    • TensorFlow-based or Keras-based
      • PIVDatasetTF
  • Variational and generative approaches
    • PIVCVAE
    • sample()
    • encode()
    • reparameterize()
    • decode()
  • Reinforcement learning environments
    • Gymnasium-based
      • PIVEnv
      • reset()
      • step()
      • render()
      • record_particles()
      • make_inference()
    • TF-Agents-based
  • Reinforcement learning agents
    • Single deep Q-network training
      • CameraAgentSingleDQN
      • choose_action()
      • train()
      • view_weights()
    • Double deep Q-network training with memory replay
      • CameraAgentDoubleDQN
      • choose_action()
      • remember()
      • train()
      • update_target_network()
      • view_weights()
  • Reinforcement learning rewards
    • Rewards
    • divergence()
    • vorticity()
    • q_criterion()
  • Reinforcement learning sensory cues
    • Cues
    • sampled_vectors()
    • sampled_magnitude()
    • sampled_divergence()
    • sampled_vorticity()
    • sampled_q_criterion()
  • Reinforcement learning utilities
    • plot_trajectory()

Tutorials

• Generate synthetic PIV images
• Image statistics
• Radial flows
• Potential flows
• Simplified Langevin model (SLM)
• Upload an external velocity field
• Generate temporal sequence of PIV images
• Postprocess PIV images
• Feature size estimation tool for PIV images
• Create a PyTorch data loader
• Integrate synthetic image generation with training a convolutional neural network (CNN)
• Create a Gymnasium reinforcement learning environment
• Single deep Q-learning
• Upload a trained reinforcement learning model
• Modeling out-of-plane particles
• Modeling astigmatic PIV
• Generate synthetic BOS images
• Computing sensory cues and rewards for reinforcement learning
• Double deep Q-learning with memory replay
• Create a TensorFlow or Keras data loader
• Train a convolutional variational autoencoder (CVAE)
• Synthetic PIV of a Taylor-Green vortex
• Single convolutional deep Q-learning