Tutorials

Installation & setup

Both Turbulence Realm-Tracker and Turbulence Realm SINDy ship as platform-specific installers that bundle every dependency — no Python installation is required. This tutorial covers the Windows setup installer and the Linux .deb / .run installers for both apps.

Windows — setup installer (recommended)

Both apps use an Inno Setup installer wizard with a no-liability disclaimer on the license page.

1. Download the setup installer:
   • Tracker: TurbulenceRealmTracker-3.2.0-setup.exe (118 MB) from the download page
   • SINDy: TurbulenceRealmSINDy-2.2.1-Setup.exe (231 MB) from the download page
2. Double-click the downloaded .exe to launch the installer.
3. Read and accept the no-liability disclaimer on the license page.
4. Choose the install location (defaults to Program Files).
5. Select Start Menu shortcuts and an optional desktop icon.
6. Click Install — the app is ready to use from the Start Menu.

Uninstall: Add/Remove Programs (Settings → Apps) → Turbulence Realm-Tracker / Turbulence Realm SINDy → Uninstall.

Linux — .deb package (Debian/Ubuntu)

The .deb package installs to /opt, creates an XDG Applications menu entry (Science category) with icon, adds a PATH symlink, and includes clean uninstall scripts.

Launch from Applications → Science → Turbulence Realm-Tracker (or SINDy), or run TurbulenceRealmTracker / TurbulenceRealmSINDy in a terminal.

Uninstall: sudo dpkg -r turbulencerealmtracker (or turbulencerealm-sindy).

Linux — .run self-extracting installer (any distro)

The .run installer works on any Linux distribution. It displays the no-liability disclaimer in the terminal, installs to /opt (or $HOME/.local for non-root), creates a menu entry, and offers a desktop shortcut.

Read and accept the no-liability disclaimer (type y). Launch from the Applications menu or run the app command in a terminal.

Uninstall:

• Tracker: sudo /opt/TurbulenceRealmTracker/uninstall.sh
• SINDy: sudo /opt/TurbulenceRealmSINDy/uninstall.sh

System requirements

• Windows: Windows 10/11 (x64)
• Linux: Ubuntu 20.04+ / Debian 11+ / Fedora 33+ (x64) with X11, OpenGL, fontconfig, libGL, libEGL, and libglib2.0
• Tracker: 4 GB RAM (8 GB recommended), 500 MB disk
• SINDy: 8 GB RAM (16 GB recommended for ML), 1 GB disk, optional NVIDIA GPU with CUDA for ML training
• A display (the GUI requires a desktop environment)

Verifying the installation

After installation, launch either app. You should see the Turbulence Realm gold/cream UI with the brand logo. If you get missing library errors on Linux, install them:

Once the app launches, continue to Tutorial 01 — Your first tracking run or Tutorial 06 — From video to equation.

Your first tracking run

This tutorial walks through the basic workflow end to end — from loading a video to exporting your first velocity dataset.

1. Load a video

File → Open Video… (Ctrl+O) or the Load Video button. Supported formats: MP4, AVI, MOV, MPEG, MKV.

2. Calibrate

1. Enter the real-world distance in Calibration Distance (m).
2. Click Calibrate.
3. Click and drag on the frame to draw a line spanning that distance.
4. The scale (m/px) is computed and shown in the status bar.

3. Select bubbles

Click Select Bubbles (Ctrl+B) and drag rectangles around each bubble. Use Tools → Auto-detect Bubbles to let the app propose ROIs you can accept or refine.

4. Track

Click Start Tracking (Ctrl+T). Tracking runs on a background thread; the UI stays responsive. Live velocity/displacement plots and metrics update as frames are processed.

5. Review & export

• Pick a bubble from the dropdown to view its plots.
• Analyze shows summary statistics.
• Save Data (Ctrl+S) exports CSV + JSON.
• File → Export Plots… saves high-resolution PNGs.
• Session → Save Session persists the whole run for later re-analysis.

6. Auto-save & recovery

Progress is auto-saved to ~/.tr_track/.tr_track_autosave/. If the app crashes, restart and choose File → Recover Auto-saved Progress….

Multi-point & grid calibration

Multi-point calibration

Draw several calibration lines of known length. The app combines them into a robust scale (median of per-point scales) and reports an error margin (coefficient of variation). A margin below 5% is considered reliable.

Grid / checkerboard calibration

For camera distortion correction, print a standard checkerboard pattern and hold it in the camera's field of view. Use Tools → Grid Calibration, enter the square size, and the app will:

1. Detect the inner corners with cv2.findChessboardCorners.
2. Derive the scale from the average corner spacing.
3. Report the per-corner variation as an accuracy indicator.

Calibration history

Every calibration is recorded per video. Use Tools → Calibration History to reuse or compare previous calibrations for the same footage.

Presets

Tools → Calibration Presets offers common reference distances (1 mm capillary, 10 cm tank, 50 cm flume, 1 m basin) so you don't have to type the number each time.

Advanced analysis & data science

Turn raw tracks into publishable insight with the analysis and data-science tools.

Statistics & smoothing

Analysis → Statistics Summary shows average and maximum speed, final displacement, and per-bubble sizing. Advanced Analysis runs the full pipeline: Savitzky-Golay smoothing (configurable window), acceleration computation, comparative cross-correlation between bubble pairs, bootstrap confidence intervals, and Welch's t-test for significance.

Statistical report

Analysis → Statistical Report generates a comprehensive Markdown report with descriptive statistics, per-bubble summaries, and comparative tables — ready to drop into a paper.

FFT analysis

Analysis → FFT Analysis computes the Fast Fourier Transform of each bubble's velocity signal, reporting the dominant frequency (Hz) and its magnitude. Useful for detecting oscillation patterns.

Bubble classification & prediction

• Bubble Classification classifies each bubble's motion pattern (e.g. "rising", "oscillating", "turbulent") based on statistical features, with a confidence score.
• Trajectory Prediction predicts the future trajectory using linear extrapolation. Configure the prediction horizon (number of frames) and review the predicted final position.

Visualization export

File → Visualization Export produces movement heatmaps, contact-sheet time-lapses, and time-lapse videos for every bubble.

Automatic multi-object tracking (MOT)

Version 3.1 adds a tracking-by-detection engine that finds and follows every bubble in the frame automatically — no manual ROI selection needed. It uses a constant-velocity Kalman filter per track and Hungarian assignment (SORT-style), surviving short occlusions and bubble crossings.

GUI workflow

1. Load & calibrate as in Tutorial 01 — open the video and draw a calibration line so velocities come out in m/s.
2. Tools → Auto-Track All (MOT) — the app detects bubble candidates, launches the multi-object tracker, and draws a box + trajectory for every bubble.
3. Review the live telemetry: per-bubble speed, displacement and track count update as frames are processed.
4. Analysis → Event Detection to mine coalescence / breakup / flux events from the resulting tracks.
5. File → PDF Report for a one-click multi-page session report.

Headless API (no Qt)

track_video_auto runs the full MOT pipeline without a GUI — safe in notebooks, servers and batch scripts:

result.mot_tracker.all_tracks exposes the raw Kalman tracks for event mining (coalescence, breakup, line-crossing flux — see Tutorial 04).

Physics, flow fields, events & reporting

Version 3.1 adds research-grade analytics on top of the tracked kinematics. This tutorial covers the new Analysis menu items and the headless functions behind them.

1. Dimensionless numbers & drag (Physics)

Analysis → Physics (Re/We/Eo) computes the Reynolds, Weber, Eötvös, Morton and Froude numbers for each tracked bubble, the measured drag coefficient from a force balance, the Schiller-Naumann correlation, and the Clift-Grace-Weber terminal-velocity comparison. Supply the continuous- and dispersed-phase properties (defaults: air bubble in clean water at 20 °C; presets for seawater, glycerol, silicone oil).

2. Watershed segmentation & bubble-size distribution

Analysis → Size Distribution (BSD) segments each bubble's actual outline (splitting touching bubbles with a distance-transform watershed) and reports the equivalent diameter, aspect ratio, orientation and circularity per bubble, plus the distribution statistics: d10 (number-weighted mean), d32 (Sauter mean), and projected void fraction.

3. Eulerian flow fields

Analysis → Flow Field computes a dense Farneback optical-flow field between consecutive frames, scales it to m/s with the session calibration, and overlays a quiver plot on the video canvas. Derived maps include speed, vorticity and divergence. A time-averaged field option is also available.

4. Event detection (coalescence, breakup, flux)

Analysis → Event Detection mines the MOT track lifecycles for flow events:

• Coalescence — two tracks end together while one continues/starts nearby (the bubbles merged).
• Breakup — one track ends and two or more start nearby (the bubble split).
• Line-crossing flux — signed counting of tracks crossing a user line (bubble flux through a cross-section, in Hz).
• Detachment frequency — rate of track births inside a region (e.g. bubble detachment at a nozzle).

5. Velocity uncertainty propagation

Analysis → Velocity Uncertainty propagates calibration spread and tracker localization jitter to per-frame and mean-speed ±1σ error bars.

6. One-click PDF report

File → PDF Report bundles the session statistics, speed/trajectory plots, physics table, uncertainty table and BSD histogram into a single multi-page PDF.

7. pandas DataFrame API

TrackingSession.to_dataframe() returns a tidy table with one row per bubble per frame — ideal for group-by analysis in pandas:

From video to equation

The core SINDy workflow: extract a velocity field with optical flow, fit a sparse dynamics model, and read off the discovered governing equation.

1. Open a video & select ROI

Click Browse… in the Video Source card or use File → Open Video (Ctrl+O). Then click Select ROI & Calibrate: draw a rectangle over the region of interest, draw a calibration line of known physical length, enter the real-world length in meters, and click OK. The calibration readout updates to show meters-per-pixel.

2. Configure optical flow

Choose a backend and options in the Optical Flow card:

• Backend: farneback (default, robust), lucas_kanade (sparse, fast), tvl1 (needs opencv-contrib), raft / pwcnet (deep learning, needs torch).
• Smoothing: none, ema, or moving to reduce flicker between frames.
• Multi-scale pyramid for large motions; Gaussian / NLM denoise for cleaner flow.

3. Configure SINDy

Choose a SINDy method and its parameters in the SINDy Model card:

• Method: select the SINDy variant — see Tutorial 07 for a full guide to each method.
• Library: polynomial, fourier, combined (poly × Fourier), custom, trig. (Auto-selected for some methods.)
• Degree: polynomial degree (1–5).
• Optimizer: stlsq (default), sr3, frols, constrained_sr3. (Auto-selected for some methods.)
• Threshold: sparsity threshold (0.001–1.0). Higher = sparser model.
• Divergence-free: enforce incompressibility (∇·u = 0) via FFT-based Helmholtz projection of the reconstructed field.

4. Run the pipeline

Click the buttons in order:

1. ① Process Optical Flow — extracts the velocity field. A live HSV + quiver preview appears with progress and ETA.
2. ② Run SINDy Modeling — fits the sparse dynamics model. Use Equation to view the discovered equation, Cross-validate for k-fold CV (crash-resistant: failed folds are reported but don't abort the run), or Compare to try multiple libraries with the selected method.
3. ③ Run SINDy Prediction — reconstructs the predicted velocity field.

5. Read the equation

After modeling, the Equation view shows the discovered sparse coefficients as a human-readable system of ODEs — the governing equation of your flow, learned directly from video.

SINDy method variants

Version 2.2.1 introduces a Method dropdown in the SINDy Model card, letting you choose between six sparse-regression frameworks. Each method is tailored to a different class of dynamical system — from standard ODEs to noisy data, implicit equations, and partial differential equations. Method-specific parameter widgets appear automatically when you select a method.

1. Classical SINDy

The standard framework: sparse regression over a dictionary of candidate functions (polynomials, Fourier, or combined) to isolate the active physical terms. Use this as your default — it is fast, well-understood, and works for most clean ODE systems.

• Parameters: Library, Degree, Optimizer (stlsq / sr3 / frols / constrained_sr3), Threshold, Divergence-free.
• Best for: Clean data, explicit ODEs, polynomial or trigonometric dynamics.

2. SINDy-PI (Parallel Implicit)

A robust upgrade to Implicit SINDy that runs parallel sparse regressions to discover rational nonlinearities and implicit differential equations where the derivative appears on both sides. SINDy-PI can identify equations like x' = x² / (1 − x²) that classical SINDy cannot represent.

• Parameters: Degree (controls the implicit library size), Threshold.
• Best for: Rational nonlinearities, implicit ODEs, equations with denominators.

3. PDE-FIND (SINDy for PDEs)

Tailored for discovering spatial-temporal partial differential equations — the kind of equations that govern fluid dynamics, transport, and wave phenomena. PDE-FIND constructs a library of spatial derivatives (up to the configured order) and temporal derivatives, then applies sparse regression to find the active PDE terms.

• Parameters: Degree, Spatial order (1–6), Temporal order (1–4), Threshold.
• Best for: PDE discovery from spatial-temporal data (Navier-Stokes, advection-diffusion, wave equations).

4. WSINDy (Weak-Formulation SINDy)

Uses the integral weak form of differential equations, shifting derivative computation to analytical test functions. This completely bypasses numerical noise amplification — making WSINDy the method of choice for noisy or low-quality data where numerical derivatives would be unreliable.

• Parameters: Degree, Spatial freq K (test function subdomain count), Temporal freq H, Threshold.
• Best for: High-noise data, low-quality measurements, situations where numerical derivatives are too noisy.

5. E-SINDy (Ensemble SINDy)

Leverages statistical bootstrapping and library ensembling to reliably identify true equations under low-data or high-noise conditions. E-SINDy generates many SINDy models by randomly subsampling the data (bagging) and randomly dropping library terms (library ensembling), then aggregates the results. Terms that appear consistently across the ensemble are likely true; terms that appear sporadically are likely noise.

• Parameters: Library, Degree, Threshold, N models (1–200), Aggregation.
• Best for: Noisy data, low-data regimes, uncertainty quantification, identifying robust terms.

6. SINDy with Control (SINDYc)

Incorporates external inputs, forcing mechanisms, and feedback control directly into the discovered mathematical framework. SINDYc extends the feature library with control input columns, allowing the discovered equation to include terms that depend on the external forcing.

• Parameters: Library, Degree, Optimizer, Threshold, Divergence-free.
• Best for: Controlled systems, forced flows, actuated dynamics, feedback loops.

Cross-validation & comparison

All six methods support the Cross-validate and Compare buttons. As of v2.2.1, both are crash-resistant:

• Cross-validate wraps each fold in a try/except. If a single fold fails (e.g. singular matrix, convergence issue), the remaining folds still complete and the failed fold is reported in the results dialog.
• Compare wraps each library/config in a try/except. If one config fails, the others still run and the failed config shows "ERROR" in the comparison table.

ML models & visualization

Train a physics-informed model

On the ML Models page select a model, adjust hyperparameters in the parameter panel, and click Train. Training runs on a background thread (v2.2) so the GUI stays responsive; logs appear in the in-app log widget. Trained models can be exported to TorchScript / ONNX. (ML models require a CUDA-capable GPU for best performance; CPU mode is available for all other features.)

• PINN — Physics-Informed Neural Network with Navier-Stokes residuals.
• Autoencoder-SINDy — compressed latent-space SINDy.
• FNO — Fourier Neural Operator for flow prediction.
• DeepONet — Deep Operator Network.
• ConvLSTM — recurrent convolutional model for temporal sequences.
• VAE / beta-VAE — variational autoencoder for flow generation.
• GAN — Generative Adversarial Network for flow synthesis.
• Ensemble — SINDy ensemble with uncertainty quantification.
• Granger causality — causal analysis between flow variables.

Visualize the results

On the Visualization page, after running the pipeline:

• Quiver plot — side-by-side actual vs SINDy-predicted velocity arrows.
• Contour / streamlines — velocity magnitude contours or streamline plots.
• Vorticity / strain — color-mapped vorticity and strain-rate fields.
• Animated heatmap — play through frames as an animated velocity heatmap in a dedicated dialog with Play/Pause control.
• Custom colormap — choose from matplotlib colormaps.
• Data table — tabular view of the velocity data.

Export with provenance

Export to CSV, HDF5, NetCDF, Parquet, or JSON metadata — each export embeds full provenance (git commit, package versions, config, seed, input SHA-256) so every result is reproducible. File → Export can also produce a PDF report and an MP4 quiver animation (FFmpeg required).