Skip to article frontmatterSkip to article content
Site not loading correctly?

This may be due to an incorrect BASE_URL configuration. See the MyST Documentation for reference.

Getting Started

What is uPrime?

uPrime reads Tecplot .dat files exported from LaVision DaVis, and MATLAB .mat files containing PIV or CFD velocity fields. It provides a graphical interface for turbulence post-processing. You do not need to know Python, MATLAB, or any programming language to use it. Everything is point-and-click.

The workflow is always the same:

  1. Load your snapshots (.dat or .mat).

  2. Set the acquisition type and sampling frequency.

  3. Align the coordinate system if needed.

  4. Verify statistical convergence in the ‘Mean & Convergence‘ module.

  5. Open any analysis module and explore your data.

What uPrime can do

System requirements

Minimum system requirements.

ItemRequirement
Operating systemWindows 10/11 (primary); macOS 12+; Linux (Ubuntu 20+)
Python3.10 or later (source installation only)
RAM8 GB minimum; 16 GB or more recommended for large datasets
Display1920×\times1080 or larger strongly recommended
Python dependencies (source installation)
numpyArray operations and numerical core
scipySignal processing and spectral analysis
matplotlibPlotting and figure export
PyQt6Graphical user interface
pyfftwFast Fourier transforms (accelerates spectral analysis)
h5pyRead v7.3 (HDF5-based) .mat files

Installation

Download uPrime_v0.7.1.exe from the GitHub Releases page and double-click to launch. No Python or any other software is required.

Option B: Run from source

  1. Clone the repository:

    git clone https://github.com/CmdrRyder/uPrime.git
    cd uPrime
  2. Install dependencies:

    pip install -r requirements.txt
  3. Launch:

    python main.py

Input file formats

uPrime accepts two file formats: Tecplot ASCII .dat (one snapshot per file) and MATLAB .mat (full time series in a single file). The file type is auto-detected from the extension.

Tecplot ASCII (.dat)

uPrime reads Tecplot ASCII .dat files in the standard DaVis export format. Each file contains one PIV snapshot. Select multiple files at once to load a full time series.

uPrime automatically reads the physical units from the variable name strings in the file header (e.g. "x [mm]", "Velocity u [m/s]"). If units are not specified in the header, it defaults to millimetres for coordinates and m/s for velocity. All internal computations are performed in SI units regardless of the input.

MATLAB (.mat)

uPrime also loads MATLAB .mat files. Both classic v5/v7 (read via scipy.io) and v7.3 (HDF5-based, read via h5py) are supported. Format detection is automatic.

When you select a .mat file, uPrime reads only the variable names and shapes (no data) and shows the variable confirmation dialog (Figure 1). The dialog appears within seconds even for very large files.

.mat variable confirmation dialog. The top panel lists every variable in the file with its shape. Six dropdowns map the file variables to uPrime’s expected roles (x, y, U, V, W, isValid); auto-detected matches are pre-filled. The bottom panel sets the snapshot subset to load (start, end, step), with a live readout of the resulting count and estimated memory size. Click ‘Load‘ to confirm and start the actual data read.

Figure 1:.mat variable confirmation dialog. The top panel lists every variable in the file with its shape. Six dropdowns map the file variables to uPrime’s expected roles (xx, yy, UU, VV, WW, isValid); auto-detected matches are pre-filled. The bottom panel sets the snapshot subset to load (start, end, step), with a live readout of the resulting count and estimated memory size. Click ‘Load‘ to confirm and start the actual data read.

Snapshot subset.

The dialog includes Start, End, and Step spinboxes. They allow loading only a slice (e.g. snapshots 0–999) or a strided subsample (e.g. every 10th snapshot from 0 to 9999). The estimated in-memory size updates live. This is useful for preliminary inspection of very large files before committing to the full load.

Mask convention.

A ‘Mask convention‘ dropdown sits next to the isValid selector. The default, ‘1 = valid (uPrime default)‘, matches the .dat convention. If your file uses the opposite convention (for example a Mask variable where 1 marks points to exclude), select ‘1 = invalid (mask out)‘. uPrime applies the chosen convention directly, with no auto-detection. After loading, the status bar warns if the resulting masked fraction is extreme (below 5% or above 95%); if that warning is unexpected, reload with the other convention.

Progress feedback.

For v7.3 files (HDF5), the read is chunked snapshot-by-snapshot and the progress bar advances determinately. For classic .mat files, the read is a single blocking call from scipy.io, so a busy indicator is shown along with the file size in the status bar. After the read, the status bar prints a confirmation listing the chosen variables and snapshot count, for example:

Loaded .mat: x=X, y=Y, u=U, v=V, w=(none), isValid=(none), N=1000 of 9999 (range 0:9990 step 10)

Error dialog shown when a .mat file contains only one snapshot. The check is performed on the metadata before any data is loaded, so the error appears immediately regardless of the file size.

Figure 2:Error dialog shown when a .mat file contains only one snapshot. The check is performed on the metadata before any data is loaded, so the error appears immediately regardless of the file size.