Tips, Workflow, and Troubleshooting¶
Recommended workflow¶
For any new dataset, follow this order:
Load your files (
.dator.mat). Use stride subsampling if the dataset is large.Set acquisition type and in the popup dialog or the info ribbon.
Transform: rotate to correct tilt, shift the origin to a physical reference.
Inspect the mean field. Does the flow look correct? Right direction, sensible magnitudes?
Mean & Convergence: plot the mean velocity profile through your region of interest, then check at a representative point that first and second moments are converged. Skip if your dataset is small.
Reynolds stresses: identify turbulent regions and shear layers.
TKE budget: understand energy production and transport.
Correlations: measure integral length and time scales.
POD: identify dominant coherent structures.
DMD (TR only): extract frequency-specific coherent modes.
Vortex identification: locate and quantify vortex cores.
Export results. Use the multi-case workflow to overlay against benchmark data when relevant.
Performance tips¶
POD and DMD computation time scales as . For 5000+ snapshots use stride subsampling to 1000–2000 samples first.
Velocity data is loaded as 32-bit floats (float32), halving RAM usage compared to the 64-bit default.
Close unused analysis windows to free RAM.
Use ‘Reload Last Dataset‘ to undo a bad transform without restarting.
For spatial spectra over a region, the FFT tab is faster than running multiple Welch lines.
The computation involves a Python loop over all grid points and can be slow for large grids. Start with a subsampled dataset or a small neighborhood size while exploring.
For very large
.matfiles, save with-v7.3in MATLAB to enable HDF5 chunked reading and real per-snapshot progress.
Exporting figures for publication¶
PDF / SVG: all text is embedded as editable text objects. Open in Adobe Illustrator or Inkscape to change fonts, sizes, and labels to match journal requirements.
PNG: 300 DPI by default. Suitable for Word, PowerPoint, and reports.
Enable ‘Clean export‘ and/or ‘Hide colorbar‘ for plain field images without annotations.
Known limitations¶
3D (tomographic) PIV data is not supported.
Pressure and viscous dissipation are not computed; the TKE budget residual absorbs these terms.
Taylor hypothesis (for converting temporal to spatial scales) is only valid at low turbulence intensity ().
Anisotropy analysis requires stereo data (2D3C) and will be unavailable for 2D2C datasets.
DMD requires time-resolved data and a minimum of 50 snapshots.
The computation is slower than gradient-based methods for large grids due to the neighborhood summation loop.
The Binary Space-Time tab of the Probability module requires time-resolved data; on non-TR datasets the snapshot axis has no physical time meaning and the tab is disabled.
Probability density functions, and in particular the flatness, converge far more slowly than the mean and variance. Fourth-order statistics from a few hundred snapshots should be treated as indicative only.
Quadrant analysis assumes the coordinate system is aligned with the mean shear. Align the dataset in the Coordinate Transform module first, or the quadrant labels lose their physical meaning.
Free (arbitrary-angle) lines are not offered in the PDF and Binary Space-Time tabs, and line sampling is not offered at all in the Flow Direction and Quadrant tabs.
In the Quadrant tab an ROI restricts the joint histogram and the hole-size sweep only. The Q2 and Q4 stress-fraction maps are always computed over the full domain.
All exported results are time-averaged unless otherwise noted. Per-snapshot export will be added in a future version.
.matfiles must contain multiple snapshots. Single-snapshot files are rejected before any data is loaded.For classic
.matfiles (not v7.3), the snapshot subset is applied after the full read becausescipy.io.loadmatis a single blocking call. Convert to v7.3 in MATLAB for efficient strided loading on very large files.
Common issues¶
Common issues and solutions.
| Issue | Solution |
Files do not load (.dat) | Confirm files are Tecplot ASCII format from DaVis. Binary .dat files are not supported. |
.mat load shows “Insufficient Snapshots” immediately | The file contains only one snapshot. uPrime requires multiple snapshots. Re-export from MATLAB with the time axis included as the third dimension of u, v, etc. |
.mat variable dialog cannot find u | The velocity variable name is not in the recognized list. Use the manual dropdowns in the dialog to map your variables to , , , , etc. |
.mat dx/dy shown as 0.000 mm | Coordinate arrays are degenerate (all values equal along one axis), or the meshgrid orientation could not be inferred. Check that x and y contain real coordinate values. |
| Anisotropy module is greyed out | Data is 2D2C. This module requires stereo (2D3C) data with a component. |
| DMD button is greyed out | Set Acquisition Type to TR in the info ribbon and ensure at least 50 snapshots are loaded. |
| Temporal tabs are greyed out | Set Acquisition Type to Time-Resolved and enter before opening the analysis window. |
| Top-bar amber non-convergence label is shown | Dataset has fewer than 500 snapshots. Open Mean & Convergence and verify convergence at a point in your region of interest. |
| PDF save fails: permission denied | The file is open in Adobe Acrobat. Close it in Acrobat first, then save again. |
| Rotation gives a blank result | Mirror the dataset before rotating, not after. |
| Lumley triangle points outside boundary | Insufficient snapshots or masked/invalid vectors near the sampling line. Avoid masked regions when drawing the analysis line. |
| DMD spectrum dominated by high- modes | Apply the growth rate filter ( threshold) to focus on near-neutral physically meaningful modes. |
| computation is very slow | Reduce the neighborhood half-width , or subsample the dataset before computing. |
| Binary Space-Time tab is greyed out | Data is marked Non-TR. Set Acquisition Type to Time-Resolved and enter in the info ribbon before opening the window. |
| PDF looks spiky or has empty bins | Too few samples for the chosen bin count. Reduce the number of bins, or switch from Point to Line, ROI, or Whole field sampling to pool more samples. |
| Reverse-flow probability is 0 everywhere | The flow does not reverse in this dataset, or the coordinate system is rotated so that reversal appears in the other component. Check the alignment in Coordinate Transform. |
| Quadrant fractions do not sum as expected | Both the time fractions and the stress fractions sum to 1 only at hole size . At the excluded weak events are missing by design, and the shortfall measures how much of the signal is weak. |
| Grey patches in an FFP or RFP map | Those points lie outside the ROI, so they were never computed. Grey means untouched, not zero probability. |
| Imported case appears at wrong scale | The imported CSV uses a different or different units than the current session. Check the case’s header and re-export consistently. |