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.

Mean & Convergence

Open from ‘3. Analysis →\to Mean & Convergence‘.

The Mean & Convergence module is the recommended first stop for any new dataset. It serves two purposes: plotting mean velocity profiles along arbitrary lines (similar to the Reynolds stress line-profile mode but for first-order statistics), and quantitatively verifying that the dataset has enough snapshots for the higher-order statistics computed by other modules to be trustworthy.

The module has two tabs: ‘Mean Velocity‘ (line profiles) and ‘Convergence‘ (cumulative statistics at a picked point).

Mean Velocity tab

This tab plots ⟨U⟩\langle U \rangle, ⟨V⟩\langle V \rangle, and (for stereo data) ⟨W⟩\langle W \rangle along a user-drawn line, in the same style as Reynolds stress line profiles.

Mean & Convergence module, Mean Velocity tab. Left: |\langle U \rangle| field with a free line drawn (cyan). Right: \langle U \rangle, \langle V \rangle profiles along the line as a function of arc length. Stereo data adds \langle W \rangle.

Figure 1:Mean & Convergence module, Mean Velocity tab. Left: ∣⟨U⟩∣|\langle U \rangle| field with a free line drawn (cyan). Right: ⟨U⟩\langle U \rangle, ⟨V⟩\langle V \rangle profiles along the line as a function of arc length. Stereo data adds ⟨W⟩\langle W \rangle.

Normalization by UmU_m

A checkbox labeled ‘Normalize by UmU_m‘ and a paired spinbox let you divide the plotted velocity components by a user-supplied bulk or reference velocity. When checked, the y-axis labels switch to U/U_m [-], V/U_m [-], etc. The arc-length axis is not normalized, matching the convention used elsewhere in uPrime.

Multi-case comparison

uPrime can overlay imported cases (CSV files exported from previous uPrime sessions or other tools that follow the same column layout) on top of the current profile. This is useful for comparing experimental runs, conditions, or numerical-versus-experimental data.

The same multi-case workflow is available in Reynolds Stress, TKE Budget, Spectra, Correlation, and Anisotropy windows (see Chapter ??).

Exporting

Click ‘Export Profile…‘ to save the current profile as a CSV file. The header records the line geometry (endpoints), the UmU_m value (or N/A if normalization is off), and the column layout. Multi-case overlays can be exported together using ‘Export All Cases…‘.

Convergence tab

The Convergence tab quantifies whether the dataset has enough snapshots for the first three moments of the velocity fluctuations to be statistically converged. This serves as a numerical check on the assumptions made by every other turbulence-statistics module.

Background

Given a sequence of NN snapshots, the cumulative running statistics are

⟨u′⟩N=1N∑i=1N(ui−⟨u⟩final),⟨u′u′⟩N=1N∑i=1N(ui−⟨u⟩final)2,⟨u′u′u′⟩N=1N∑i=1N(ui−⟨u⟩final)3,\begin{align} \langle u' \rangle_N &= \frac{1}{N} \sum_{i=1}^{N} (u_i - \langle u \rangle_{\mathrm{final}}), \\ \langle u' u' \rangle_N &= \frac{1}{N} \sum_{i=1}^{N} (u_i - \langle u \rangle_{\mathrm{final}})^2, \\ \langle u' u' u' \rangle_N &= \frac{1}{N} \sum_{i=1}^{N} (u_i - \langle u \rangle_{\mathrm{final}})^3, \end{align}

where ⟨u⟩final\langle u \rangle_{\mathrm{final}} is the mean computed over all loaded snapshots. With this definition, the curves approach a non-zero asymptote as NN grows, which is what allows convergence to be visually inspected.

The cumulative moments are computed using Welford’s online algorithm extended to the third central moment. This is a single-pass O(N)O(N) computation, numerically stable, and avoids storing per-snapshot residuals.

A trailing-window stability criterion is used to find the convergence point N∗N^*:

N∗=min⁡{N  :  max⁡n∈[N−W,N]qn−min⁡n∈[N−W,N]qnσscale<ε}N^* = \min\left\{ N \;:\; \frac{\max_{n \in [N - W, N]} q_n - \min_{n \in [N - W, N]} q_n}{\sigma_{\mathrm{scale}}} < \varepsilon \right\}

where W=max⁡(50,N/10)W = \max(50, N/10) and σscale\sigma_{\mathrm{scale}} is component-aware: ⟨u′u′⟩final\sqrt{\langle u'u'\rangle_{\mathrm{final}}} for first moments, ⟨u′u′⟩final\langle u'u'\rangle_{\mathrm{final}} for second, and ⟨u′u′⟩final3/2\langle u'u'\rangle_{\mathrm{final}}^{3/2} for third (and similarly per-component for vv and ww). The criterion further requires the inequality to hold continuously across the next WW samples (sustained crossing), which prevents spurious early matches when the trailing-window range happens to be small by chance.

Reference: Welford, B.P. (1962). Note on a method for calculating corrected sums of squares and products. Technometrics, 4(3), 419–420.

Using the tab

Convergence tab, point picker. The |\langle U \rangle| field is shown in viridis. The boundary margin (grey overlay) is determined by the kernel size and clicks inside it are rejected. The picked point and kernel footprint are shown as a red marker.

Figure 2:Convergence tab, point picker. The ∣⟨U⟩∣|\langle U \rangle| field is shown in viridis. The boundary margin (grey overlay) is determined by the kernel size and clicks inside it are rejected. The picked point and kernel footprint are shown as a red marker.

Grid layout (raw values)

In grid mode, ⟨u′⟩N\langle u' \rangle_N, ⟨u′u′⟩N\langle u'u' \rangle_N, and ⟨u′u′u′⟩N\langle u'u'u' \rangle_N are plotted in physical units, one subplot per component (rows: uu, vv, optionally ww) and per moment order (columns: 1, 2, 3). A pair of dashed horizontal lines marks the threshold band qfinal±ε⋅σscaleq_{\mathrm{final}} \pm \varepsilon \cdot \sigma_{\mathrm{scale}} around the asymptote, and a vertical line at N∗N^* shows the sustained-crossing convergence point. Curves that never satisfy the criterion are labeled ‘Not converged‘.

Convergence tab, grid layout (planar 2D2C: 2 \times 3 subplots). Each panel shows a cumulative moment in physical units, the dashed threshold band around its final-value asymptote, and the vertical N^* line where the sustained-crossing criterion is first met. Third moments typically require many more snapshots than first or second moments to converge.

Figure 3:Convergence tab, grid layout (planar 2D2C: 2×32 \times 3 subplots). Each panel shows a cumulative moment in physical units, the dashed threshold band around its final-value asymptote, and the vertical N∗N^* line where the sustained-crossing criterion is first met. Third moments typically require many more snapshots than first or second moments to converge.

Single plot (normalized)

In single-plot mode, every selected curve is normalized by its own scale σscale\sigma_{\mathrm{scale}} so they share a common dimensionless y-axis. Curves are color-coded by component (uu, vv, ww) and styled by moment order (solid for first, dashed for second, dotted for third). Per-component dashed threshold bands are drawn around each curve’s asymptote qfinal/σscaleq_{\mathrm{final}}/\sigma_{\mathrm{scale}}.

Convergence tab, single normalized layout. All selected curves are overlaid on one axes and approach their respective non-zero asymptotes (one per curve). Per-component dashed threshold bands flank each asymptote.

Figure 4:Convergence tab, single normalized layout. All selected curves are overlaid on one axes and approach their respective non-zero asymptotes (one per curve). Per-component dashed threshold bands flank each asymptote.

Exporting

Click ‘Export CSV…‘ to save the cumulative moments. The header block records the picked point indices and physical coordinates, the kernel size, the three thresholds, the dataset NtotalN_{\mathrm{total}}, and the N∗N^* value computed for each quantity. The columns are NN, ⟨u′⟩N\langle u' \rangle_N, ⟨u′u′⟩N\langle u'u' \rangle_N, ⟨u′u′u′⟩N\langle u'u'u' \rangle_N, ⟨v′⟩N\langle v' \rangle_N, ..., adding ww components for stereo data.

Inline non-convergence notice

The Reynolds Stress, TKE Budget, and Spectral Analysis windows display a persistent amber top-bar label when the loaded dataset has fewer than 500 snapshots:

⚠ Only N=234 snapshots loaded. Statistics may not be converged. Use the Mean & Convergence module to verify.

The label is hidden automatically when the dataset has 500 or more snapshots. Other modules (Correlation, Anisotropy, POD, DMD, Vortex Identification) are silent. The 500 threshold is hardcoded in core/constants.py as CONVERGENCE_WARNING_N and can be changed in source builds.

Top-bar non-convergence label as it appears in the Reynolds Stress window with N = 234 snapshots. The label is hidden automatically once N \geq 500.

Figure 5:Top-bar non-convergence label as it appears in the Reynolds Stress window with N=234N = 234 snapshots. The label is hidden automatically once N≥500N \geq 500.