flowtracks 1.8.0__tar.gz → 1.8.1.dev7__tar.gz

{flowtracks-1.8.0 → flowtracks-1.8.1.dev7}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: flowtracks
-Version: 1.8.0
+Version: 1.8.1.dev7
 Summary: Library for handling 3D PTV trajectory databases and Lagrangian/Eulerian turbulence post-processing.
 Author-email: Yosef Meller <yosefm@gmail.com>
 License-Expression: GPL-3.0-only AND BSD-3-Clause

{flowtracks-1.8.0 → flowtracks-1.8.1.dev7}/flowtracks/_version.py

@@ -18,7 +18,7 @@ version_tuple: tuple[int | str, ...]
 commit_id: str | None
 __commit_id__: str | None
 
-__version__ = version = '1.8.0'
-__version_tuple__ = version_tuple = (1, 8, 0)
+__version__ = version = '1.8.1.dev7'
+__version_tuple__ = version_tuple = (1, 8, 1, 'dev7')
 
-__commit_id__ = commit_id = 'g478fd2bef'
+__commit_id__ = commit_id = 'g4874e6164'

flowtracks-1.8.1.dev7/flowtracks/combine.py

@@ -0,0 +1,176 @@
+# SPDX-License-Identifier: BSD-3-Clause
+# SPDX-FileCopyrightText: Alex Liberzon
+"""flowtracks.combine - CLI entrypoint for postptv-combine
+
+Vectorized 3D Eulerian binning, ensemble phase-averaging across realizations/subfolders,
+and Zarr + VTK (ParaView) export.
+
+Usage:
+    postptv-combine [DATA_DIR]
+"""
+
+from pathlib import Path
+
+import numpy as np
+import xarray as xr
+
+from flowtracks import eulerian as post_analysis_xr
+from flowtracks.io import Scene
+from flowtracks.phase_average import fluctuations, phase_average
+from flowtracks.writers import write_eulerian_series
+
+
+def run_combine(data_dir: str | Path = ".", method: str = "per_run",
+                grid_params=None, first=1, last=5005, cycletime=5005,
+                deltat=50, base_time=1, min_count=2):
+    """Combine realizations into Eulerian/phase-averaged outputs.
+
+    method:
+      - "per_run" (default, current): bin each realization to a per-run
+        phase grid, then count-weighted ensemble/phase averaging across runs.
+        Per-run ``min_count`` masking is applied before combining.
+      - "pooled": collect all filtered samples from all runs together (keeping
+        run index and per-run counts per bin/phase), then bin/average on the
+        pooled total. ``min_count`` applies to pooled counts, so a bin sparse
+        in one run but sufficient across runs can remain valid.
+    """
+    data_path = Path(data_dir)
+    res_dir = data_path / "res"
+    vtk_dir = data_path / "vtk_output"
+
+    # Locate all run.zarr directories or trajectories.h5 files
+    all_zarr = list(data_path.rglob("run.zarr")) + list(data_path.rglob("*.zarr"))
+    all_h5 = list(data_path.rglob("trajectories.h5"))
+
+    all_datasets = sorted(all_zarr + all_h5, key=lambda x: len(x.parts))
+    if not all_datasets:
+        print(f"[postptv-combine] No Zarr or trajectories.h5 datasets found in {data_path}, skipping stage.")
+        return
+
+    seen_parents = set()
+    traj_files = []
+    for h in all_datasets:
+        parent = h.parent if h.parent.name != "res" else h.parent.parent
+        if parent not in seen_parents:
+            seen_parents.add(parent)
+            traj_files.append(h)
+
+    print(f"[postptv-combine] Found {len(traj_files)} realization dataset(s): {[f.relative_to(data_path) for f in traj_files]}")
+
+    if grid_params is None:
+        grid_params = {
+            'min_x': -0.021, 'max_x': 0.070, 'stepx': 45,
+            'min_y': -0.071, 'max_y': 0.016, 'stepy': 43,
+            'min_z': -0.061, 'max_z': 0.001, 'stepz': 31,
+        }
+
+    run_scenes = []
+    for traj_file in traj_files:
+        set_name = traj_file.parent.name if traj_file.parent.name != "res" else traj_file.parent.parent.name
+        if set_name == data_path.name:
+            set_name = "run1"
+        print(f"[postptv-combine] Loading realization '{set_name}' ({traj_file})...")
+        scene = Scene(str(traj_file)) if str(traj_file).endswith(".h5") else str(traj_file)
+        run_scenes.append((set_name, scene))
+
+    pooled_result = None
+    if method == "pooled":
+        print("[postptv-combine] Pooling ALL runs together (keeping run index/counts per bin/phase)...")
+        pooled_result = post_analysis_xr.eulerian_grid_pooled(
+            run_scenes, grid_params, first=first, last=last,
+            cycletime=cycletime, deltat=deltat, base_time=base_time,
+            min_count=min_count,
+        )
+        final_ds = pooled_result.dataset
+        # attach per-run counts for bookkeeping/comparison
+        final_ds = final_ds.assign(counts_per_run=pooled_result.counts_per_run)
+
+        # pooled turbulent statistics + derived fields (functional parity with
+        # per_run path, computed from collected particle samples)
+        print("[postptv-combine] Computing pooled turbulent statistics from collected samples...")
+        pooled_stats = post_analysis_xr.pooled_turbulent_statistics(pooled_result)
+        print("[postptv-combine] Computing derived fields (MKE, TKE, VEL)...")
+        derived = post_analysis_xr.derived_fields(
+            final_ds, pooled_stats, fields=["MKE", "TKE", "VEL"],
+            counts=final_ds[post_analysis_xr.COUNT_VAR],
+            fluid_min=2,
+        )
+        final_ds = xr.merge([final_ds, pooled_stats, derived])
+    else:
+        ds_sets = {}
+        set_names = []
+        for set_name, scene in run_scenes:
+            print(f"[postptv-combine] Processing realization '{set_name}' (per-run binning)...")
+            ds = post_analysis_xr.eulerian_grid(
+                scene, grid_params, first=first, last=last,
+                cycletime=cycletime, deltat=deltat, base_time=base_time,
+                min_count=min_count,
+            )
+            ds_sets[set_name] = ds
+            set_names.append(set_name)
+
+        if len(ds_sets) == 1:
+            final_ds = list(ds_sets.values())[0]
+        else:
+            print(f"[postptv-combine] Stacking realizations along 'set' dimension: {set_names}")
+            combined = xr.concat(list(ds_sets.values()), dim=xr.DataArray(set_names, dims="set", name="set"))
+
+            print("[postptv-combine] Computing ensemble phase-averaging across realizations...")
+            avg = phase_average(combined, weights=combined["par_ave2"])
+
+            print("[postptv-combine] Computing turbulent fluctuations and statistics...")
+            fl = fluctuations(combined, avg)
+
+            u_rms = np.sqrt((fl["u_ins_mean"]**2).mean("set"))
+            v_rms = np.sqrt((fl["v_ins_mean"]**2).mean("set"))
+            w_rms = np.sqrt((fl["w_ins_mean"]**2).mean("set"))
+
+            stats = xr.Dataset({
+                'u_ins_u_ins': (fl['u_ins_mean']**2).mean('set'),
+                'v_ins_v_ins': (fl['v_ins_mean']**2).mean('set'),
+                'w_ins_w_ins': (fl['w_ins_mean']**2).mean('set'),
+                'u_ins_v_ins': (fl['u_ins_mean']*fl['v_ins_mean']).mean('set'),
+                'u_ins_w_ins': (fl['u_ins_mean']*fl['w_ins_mean']).mean('set'),
+                'v_ins_w_ins': (fl['v_ins_mean']*fl['w_ins_mean']).mean('set'),
+                'u_rms': u_rms,
+                'v_rms': v_rms,
+                'w_rms': w_rms,
+            })
+
+            print("[postptv-combine] Computing derived fields (MKE, TKE, VEL)...")
+            derived = post_analysis_xr.derived_fields(avg, stats, fields=['MKE', 'TKE', 'VEL'])
+            final_ds = xr.merge([avg, stats, derived])
+
+    out_dir = res_dir if res_dir.exists() else data_path
+    zarr_out = out_dir / ("post_analysis_pooled.zarr" if method == "pooled" else "post_analysis.zarr")
+    print(f"[postptv-combine] Saving Zarr output -> {zarr_out}")
+    post_analysis_xr.save_zarr(final_ds, zarr_out)
+
+    if pooled_result is not None:
+        samples_npz = out_dir / "post_analysis_pooled_samples.npz"
+        print(f"[postptv-combine] Saving pooled sample table -> {samples_npz}")
+        np.savez_compressed(
+            samples_npz,
+            run_names=np.array(pooled_result.run_names, dtype=object),
+            **pooled_result.samples,
+        )
+
+    print(f"[postptv-combine] Exporting ParaView series -> {vtk_dir}")
+    write_eulerian_series(final_ds, vtk_dir)
+    print(f"[postptv-combine] Complete! Saved {zarr_out.name}")
+    return {"dataset": final_ds, "pooled_result": pooled_result, "output": zarr_out}
+
+
+def main():
+    import argparse
+    parser = argparse.ArgumentParser(description="Combine 3D-PTV realizations (postptv-combine)")
+    parser.add_argument("data_dir", nargs="?", default=".", help="Data directory to search")
+    parser.add_argument("--method", choices=["per_run", "pooled"], default="per_run",
+                        help="Averaging method: per_run (default, current: bin per run then "
+                             "combine) or pooled (collect all runs together, pooled min_count)")
+    args = parser.parse_args()
+    run_combine(args.data_dir, method=args.method)
+
+
+if __name__ == "__main__":
+    main()

{flowtracks-1.8.0 → flowtracks-1.8.1.dev7}/flowtracks/eulerian.py

@@ -8,6 +8,7 @@ and per-slice derived turbulence fields, chained after phase_average_xr.
 Run:  uv run python src/post_analysis_xr.py [post_recipe.yaml]
 """
 
+from dataclasses import dataclass
 from pathlib import Path
 
 import numpy as np
@@ -103,6 +104,112 @@ def _bin_counts_sums(pos, vel, ti, edges4, shape):
     return counts, sums
 
 
+def _grid_spec(grid_params, cycletime=None, deltat=90, base_time=100000,
+               fin=None, voxel_rule="half-open", n_frames_in_period=None,
+               n_phases=None, phase_zero_frame=None):
+    """Resolve grid/phase parameters shared by per-run and pooled binning."""
+    if n_frames_in_period is not None:
+        cycletime = n_frames_in_period
+    if cycletime is None:
+        raise ValueError(
+            "a period is required: pass cycletime (legacy) or "
+            "n_frames_in_period (shared vocabulary)."
+        )
+    if n_phases is not None:
+        fin = n_phases
+    if phase_zero_frame is not None:
+        base_time = phase_zero_frame
+    zaman = deltat * 2 + 1
+    fin = int(np.ceil(cycletime / zaman)) if fin is None else int(fin)
+    edges = [np.linspace(grid_params[f"min_{d}"], grid_params[f"max_{d}"],
+                         grid_params[f"step{d}"] + 1) for d in "xyz"]
+    mids = [0.5 * (b[:-1] + b[1:]) for b in edges]
+    if voxel_rule not in ("half-open", "ceil"):
+        raise ValueError("voxel_rule must be 'half-open' or 'ceil'")
+    shape4 = (*[grid_params[f"step{d}"] for d in "xyz"], fin)
+    return {
+        "cycletime": cycletime, "deltat": deltat, "base_time": base_time,
+        "zaman": zaman, "fin": fin, "edges": edges, "mids": mids,
+        "shape4": shape4, "voxel_rule": voxel_rule,
+    }
+
+
+def _collect_scene_arrays(scene):
+    """Return (pos, vel, time) arrays for a scene-like or Zarr/legacy source."""
+    if hasattr(scene, "collect"):
+        pos, vel, time = (np.asarray(a) for a in scene.collect(["pos", "velocity", "time"]))
+    else:
+        from flowtracks.io import trajectories
+        trajs = trajectories(str(scene))
+        p_list, v_list, t_list = [], [], []
+        for tr in trajs:
+            p_list.append(tr.pos())
+            v_list.append(tr.velocity())
+            t_list.append(tr.time())
+        pos = np.vstack(p_list) if p_list else np.empty((0, 3))
+        vel = np.vstack(v_list) if v_list else np.empty((0, 3))
+        time = np.concatenate(t_list) if t_list else np.empty((0,))
+    pos = np.asarray(pos, dtype=float).reshape(-1, 3)
+    vel = np.asarray(vel, dtype=float).reshape(-1, 3)
+    time = np.asarray(time).ravel()
+    return pos, vel, time
+
+
+def _prepare_binned_samples(scene, grid_params, first, last, spec, qc=None):
+    """Collect, QC/filter, and phase-bin samples for one scene.
+
+    Returns (pos, vel, time, ti) after domain/time/QC filtering and phase
+    assignment. Uses the same filtering semantics as :func:`eulerian_grid`.
+    """
+    pos, vel, time = _collect_scene_arrays(scene)
+    if qc is not None:
+        q = dict(qc)
+        keep_qc = qc_mask(pos, vel,
+                          min_speed=q.get("min_speed"),
+                          max_speed=q.get("max_speed"),
+                          finite_only=q.get("finite_only", True))
+        pos, vel, time = pos[keep_qc], vel[keep_qc], time[keep_qc]
+
+    mask = (time >= first) & (time <= last)
+    if pos.shape[0]:
+        edges = spec["edges"]
+        use_ceil = spec["voxel_rule"] == "ceil"
+        for d, b in enumerate(edges):
+            if use_ceil:
+                mask &= (pos[:, d] > b[0]) & (pos[:, d] < b[-1])
+            else:
+                mask &= (pos[:, d] >= b[0]) & (pos[:, d] < b[-1])
+    pos, vel, time = pos[mask], vel[mask], time[mask]
+
+    if pos.shape[0]:
+        ti = np.clip(((time.astype(np.int64) - spec["base_time"] - 1)
+                      % int(spec["cycletime"])) // spec["zaman"],
+                     0, spec["fin"] - 1)
+    else:
+        ti = np.empty((0,), dtype=np.int64)
+    return pos, vel, time, ti
+
+
+def _spatial_bin_indices(pos, edges, voxel_rule="half-open"):
+    """Compute (ix, iy, iz) integer bin indices for positions inside edges.
+
+    Assumes samples are already filtered to the grid domain. Uses uniform-grid
+    arithmetic (matching the linspace edges used by grid specs).
+    """
+    idx = []
+    for d, b in enumerate(edges):
+        n = len(b) - 1
+        dx = b[1] - b[0]
+        if voxel_rule == "ceil":
+            # legacy MATLAB rule: idx = ceil((p-min)/d)-1, lower voxel on edge
+            j = np.ceil((pos[:, d] - b[0]) / dx).astype(np.int64) - 1
+        else:
+            # half-open [edge_i, edge_{i+1}): internal-edge points -> upper bin
+            j = np.floor((pos[:, d] - b[0]) / dx).astype(np.int64)
+        idx.append(np.clip(j, 0, n - 1))
+    return idx[0], idx[1], idx[2]
+
+
 def _bin_counts_sums_ceil(pos, vel, ti, mins, deltas, shape):
     """MATLAB-``ceil`` voxel rule: ``idx = ceil((p - min) / d) - 1``.
 
@@ -128,6 +235,25 @@ def _bin_counts_sums_ceil(pos, vel, ti, mins, deltas, shape):
     return counts, sums
 
 
+@dataclass
+class PooledEulerianResult:
+    """Result of pooled (all-runs-together) Lagrangian -> Eulerian binning.
+
+    dataset: pooled phase-binned mean/count grid with dims (x,y,z,phase);
+        ``min_count`` is applied on the pooled total count (not per run).
+    samples: flat table of every binned sample from all runs with arrays
+        ``run_index, ix, iy, iz, phase, u, v, w`` (and ``time``), enabling
+        per-(bin,phase) statistics over the full pooled particle collection.
+    counts_per_run: per-run sample counts with dims (x,y,z,phase,run).
+    run_names: realization names in run order.
+    """
+
+    dataset: xr.Dataset
+    samples: dict
+    counts_per_run: xr.DataArray
+    run_names: list
+
+
 def eulerian_grid(scene, grid_params, first, last, cycletime=None,
                   deltat=90, base_time=100000, min_count=50,
                   smoothing_sigma=None, *, fill_value=float("nan"),
@@ -403,6 +529,136 @@ def eulerian_windowed(scene, grid_params, first, last, window_frames: int,
     )
 
 
+def eulerian_grid_pooled(scenes, grid_params, first, last, cycletime=None,
+                         deltat=90, base_time=100000, min_count=50,
+                         *, fill_value=float("nan"), qc=None, add_valid=True,
+                         fin=None, voxel_rule="half-open",
+                         n_frames_in_period=None, n_phases=None,
+                         phase_zero_frame=None, collect_samples=True):
+    """Pool Lagrangian samples from ALL runs, then bin to a phase grid.
+
+    Unlike the per-run ``eulerian_grid`` -> stack -> combine path, samples are
+    not reduced per run first: every filtered sample is assigned to
+    (ix,iy,iz,phase) with a ``run_index`` and collected together. The returned
+    mean/count grid applies ``min_count`` to the *pooled* total count, so a bin
+    that is too sparse in one run but sufficient across runs can still be
+    valid (contrast with per-run masking).
+
+    scenes: mapping ``{run_name: scene}`` or a sequence of
+    ``(run_name, scene)`` pairs, in run order.
+
+    Limitations vs :func:`eulerian_grid` (not yet supported here):
+    - ``smoothing_sigma`` (Gaussian smoothing of sums/counts) is not applied.
+    - ``chunk_frames`` (bounded-memory accumulation) is not supported; all
+      samples are binned per run in one vectorized pass.
+    - ``qc`` is supported.
+
+    collect_samples: when True (default), return the flat per-sample table in
+    ``result.samples`` for computing arbitrary per-(bin,phase) statistics.
+
+    Returns :class:`PooledEulerianResult`.
+    """
+    if isinstance(scenes, dict):
+        items = list(scenes.items())
+    else:
+        items = list(scenes)
+    run_names = [str(name) for name, _ in items]
+    if not items:
+        raise ValueError("eulerian_grid_pooled() requires at least one scene.")
+
+    spec = _grid_spec(grid_params, cycletime=cycletime, deltat=deltat,
+                      base_time=base_time, fin=fin, voxel_rule=voxel_rule,
+                      n_frames_in_period=n_frames_in_period, n_phases=n_phases,
+                      phase_zero_frame=phase_zero_frame)
+    edges, mids, shape4, fin_n = spec["edges"], spec["mids"], spec["shape4"], spec["fin"]
+
+    total_counts = np.zeros(shape4, dtype=np.int64)
+    total_sums = [np.zeros(shape4, dtype=np.float64) for _ in range(3)]
+    counts_per_run_list = []
+
+    sample_parts = {k: [] for k in ("run_index", "ix", "iy", "iz", "phase", "u", "v", "w", "time")}
+
+    use_ceil = spec["voxel_rule"] == "ceil"
+    if use_ceil:
+        mins = [grid_params[f"min_{d}"] for d in "xyz"]
+        deltas = [(grid_params[f"max_{d}"] - grid_params[f"min_{d}"])
+                  / grid_params[f"step{d}"] for d in "xyz"]
+
+    for r_idx, (_, scene) in enumerate(items):
+        pos, vel, time, ti = _prepare_binned_samples(
+            scene, grid_params, first, last, spec, qc=qc)
+        if pos.shape[0] == 0:
+            counts_per_run_list.append(np.zeros(shape4, dtype=np.int64))
+            continue
+
+        # vectorized binning per run (counts + sums), same math as eulerian_grid
+        if use_ceil:
+            c, sl = _bin_counts_sums_ceil(pos, vel, ti, mins, deltas, shape4)
+        else:
+            edges4 = [*edges, np.arange(spec["fin"] + 1) - 0.5]
+            c, sl = _bin_counts_sums(pos, vel, ti, edges4, shape4)
+        c = c.astype(np.int64)
+        counts_per_run_list.append(c)
+
+        total_counts = total_counts + c
+        for d in range(3):
+            total_sums[d] = total_sums[d] + sl[d]
+
+        if collect_samples:
+            ix, iy, iz = _spatial_bin_indices(pos, edges, voxel_rule=spec["voxel_rule"])
+            ip = ti.astype(np.int64)
+            sample_parts["run_index"].append(np.full(pos.shape[0], r_idx, dtype=np.int32))
+            sample_parts["ix"].append(ix.astype(np.int32))
+            sample_parts["iy"].append(iy.astype(np.int32))
+            sample_parts["iz"].append(iz.astype(np.int32))
+            sample_parts["phase"].append(ip.astype(np.int32))
+            sample_parts["u"].append(vel[:, 0].astype(np.float64))
+            sample_parts["v"].append(vel[:, 1].astype(np.float64))
+            sample_parts["w"].append(vel[:, 2].astype(np.float64))
+            sample_parts["time"].append(time.astype(np.float64))
+
+    if counts_per_run_list:
+        counts_per_run = np.stack(counts_per_run_list, axis=-1)
+    else:
+        counts_per_run = np.zeros((*shape4, 0), dtype=np.int64)
+
+    if collect_samples and sample_parts["run_index"]:
+        samples = {k: np.concatenate(v) for k, v in sample_parts.items()}
+    else:
+        samples = {k: np.empty((0,), dtype=np.float64 if k in ("u", "v", "w", "time") else np.int32)
+                   for k in sample_parts}
+
+    low = total_counts < min_count
+    counts_out = np.where(low, 0, total_counts)
+    fill = np.full(shape4, float(fill_value), dtype=np.float64)
+    data = {}
+    for d, vname in enumerate(VEL_VARS):
+        s = np.where(low, 0.0, total_sums[d])
+        mean = np.divide(s, counts_out, out=fill.copy(), where=counts_out != 0)
+        data[vname] = (DIMS, mean)
+    data[COUNT_VAR] = (DIMS, counts_out.astype(np.int64))
+    if add_valid:
+        data[VALID_VAR] = (DIMS, total_counts >= min_count)
+
+    ds = xr.Dataset(
+        data,
+        coords={"x": mids[0], "y": mids[1], "z": mids[2], "phase": np.arange(fin_n)},
+        attrs={"first": first, "last": last, "cycletime": spec["cycletime"],
+               "zaman": spec["zaman"], "fin": fin_n, "min_count": min_count,
+               "voxel_rule": spec["voxel_rule"], "fill_value": float(fill_value),
+               "pooling": "all_runs_together"},
+    )
+    cpr = xr.DataArray(
+        counts_per_run,
+        dims=("x", "y", "z", "phase", "run"),
+        coords={"x": mids[0], "y": mids[1], "z": mids[2],
+                "phase": np.arange(fin_n), "run": run_names},
+        name="counts_per_run",
+    )
+    return PooledEulerianResult(dataset=ds, samples=samples,
+                                counts_per_run=cpr, run_names=run_names)
+
+
 def shift_phase(ds: xr.Dataset, shift: int) -> xr.Dataset:
     """Cyclically roll all fields along phase to align with the cycle. Pure."""
     if shift == 0:
@@ -412,6 +668,107 @@ def shift_phase(ds: xr.Dataset, shift: int) -> xr.Dataset:
     return out
 
 
+def pooled_bin_statistics(result, ix, iy, iz, phase):
+    """Compute basic statistics for one (bin, phase) from pooled samples.
+
+    Returns a dict with count, per-run counts, mean and std velocity
+    components, speed stats, and contributing run indices. Works on the flat
+    sample table stored in :class:`PooledEulerianResult`.
+    """
+    s = result.samples
+    if s["run_index"].size == 0:
+        return {"count": 0}
+    m = ((s["ix"] == ix) & (s["iy"] == iy) & (s["iz"] == iz)
+         & (s["phase"] == phase))
+    if not np.any(m):
+        return {"count": 0}
+    u, v, w = s["u"][m], s["v"][m], s["w"][m]
+    rid = s["run_index"][m]
+    per_run = np.bincount(rid, minlength=len(result.run_names))
+    speed = np.sqrt(u * u + v * v + w * w)
+    return {
+        "count": int(m.sum()),
+        "per_run_counts": {name: int(per_run[i]) for i, name in enumerate(result.run_names)},
+        "mean": np.array([u.mean(), v.mean(), w.mean()]),
+        "std": np.array([u.std(ddof=0), v.std(ddof=0), w.std(ddof=0)]),
+        "speed_mean": float(speed.mean()),
+        "speed_std": float(speed.std(ddof=0)),
+        "runs_present": [result.run_names[i] for i in np.where(per_run > 0)[0]],
+    }
+
+
+def pooled_turbulent_statistics(result, fluid_min=None):
+    """Count-weighted second moments of velocity fluctuations from pooled samples.
+
+    Computes, for each (x,y,z,phase) bin, the second moments of deviations
+    from the pooled mean using all collected particle samples. Returns an
+    xr.Dataset with the same variable names as :func:`turbulent_statistics`
+    (``u_ins_u_ins``, ..., ``u_rms``, ``v_rms``, ``w_rms``) so it can be
+    passed to :func:`derived_fields`.
+    """
+    ds = result.dataset
+    u_mean = ds["u_ins_mean"].values
+    v_mean = ds["v_ins_mean"].values
+    w_mean = ds["w_ins_mean"].values
+
+    shape = u_mean.shape  # (nx, ny, nz, nphase)
+    n_total = np.zeros(shape, dtype=np.float64)
+    uu = np.zeros(shape, dtype=np.float64)
+    vv = np.zeros(shape, dtype=np.float64)
+    ww = np.zeros(shape, dtype=np.float64)
+    uv = np.zeros(shape, dtype=np.float64)
+    uw = np.zeros(shape, dtype=np.float64)
+    vw = np.zeros(shape, dtype=np.float64)
+
+    s = result.samples
+    if s["run_index"].size > 0:
+        # velocity arrays
+        u_arr = s["u"]
+        v_arr = s["v"]
+        w_arr = s["w"]
+        ix_arr = s["ix"].astype(np.int64)
+        iy_arr = s["iy"].astype(np.int64)
+        iz_arr = s["iz"].astype(np.int64)
+        ip_arr = s["phase"].astype(np.int64)
+
+        # flatten linear index
+        lin = ((ix_arr * shape[1] + iy_arr) * shape[2] + iz_arr) * shape[3] + ip_arr
+
+        # per-sample mean at that bin
+        mu_u = u_mean.ravel()[lin]
+        mu_v = v_mean.ravel()[lin]
+        mu_w = w_mean.ravel()[lin]
+
+        du = u_arr - mu_u
+        dv = v_arr - mu_v
+        dw = w_arr - mu_w
+
+        for arr, acc in [(du*du, uu), (dv*dv, vv), (dw*dw, ww),
+                         (du*dv, uv), (du*dw, uw), (dv*dw, vw)]:
+            acc_flat = acc.ravel()
+            np.add.at(acc_flat, lin, arr)
+            acc[:] = acc_flat.reshape(shape)
+
+        # counts
+        n_flat = n_total.ravel()
+        np.add.at(n_flat, lin, 1.0)
+        n_total[:] = n_flat.reshape(shape)
+
+    # divide by count (NaN where 0)
+    n_safe = np.where(n_total > 0, n_total, np.nan)
+    out = xr.Dataset(attrs=ds.attrs)
+    out["u_ins_u_ins"] = (DIMS, np.where(n_total > 0, uu / n_safe, np.nan))
+    out["v_ins_v_ins"] = (DIMS, np.where(n_total > 0, vv / n_safe, np.nan))
+    out["w_ins_w_ins"] = (DIMS, np.where(n_total > 0, ww / n_safe, np.nan))
+    out["u_ins_v_ins"] = (DIMS, np.where(n_total > 0, uv / n_safe, np.nan))
+    out["u_ins_w_ins"] = (DIMS, np.where(n_total > 0, uw / n_safe, np.nan))
+    out["v_ins_w_ins"] = (DIMS, np.where(n_total > 0, vw / n_safe, np.nan))
+    out["u_rms"] = (DIMS, np.sqrt(np.where(n_total > 0, uu / n_safe, np.nan)))
+    out["v_rms"] = (DIMS, np.sqrt(np.where(n_total > 0, vv / n_safe, np.nan)))
+    out["w_rms"] = (DIMS, np.sqrt(np.where(n_total > 0, ww / n_safe, np.nan)))
+    return out
+
+
 def phase_metric_curve(ds: xr.Dataset, var_names=VEL_VARS, rho: float = 1200.0) -> xr.DataArray:
     """Spatially-averaged MKE per phase, ignoring zero/NaN voxels.
 

{flowtracks-1.8.0 → flowtracks-1.8.1.dev7}/flowtracks.egg-info/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: flowtracks
-Version: 1.8.0
+Version: 1.8.1.dev7
 Summary: Library for handling 3D PTV trajectory databases and Lagrangian/Eulerian turbulence post-processing.
 Author-email: Yosef Meller <yosefm@gmail.com>
 License-Expression: GPL-3.0-only AND BSD-3-Clause

{flowtracks-1.8.0 → flowtracks-1.8.1.dev7}/flowtracks.egg-info/SOURCES.txt

@@ -764,6 +764,7 @@ scripts/view_trajectories_3d.py
 tests/conftest.py
 tests/helpers.py
 tests/test_analysis.py
+tests/test_averaging_method_differences.py
 tests/test_binning_equivalence.py
 tests/test_clean.py
 tests/test_derived_fields.py
@@ -780,6 +781,7 @@ tests/test_phase_align_synthetic_sets.py
 tests/test_phase_average_xr.py
 tests/test_phase_shift_extraction_and_vtr_export.py
 tests/test_phasing.py
+tests/test_pooled_ensemble.py
 tests/test_post_analysis_edge_cases.py
 tests/test_post_analysis_xr.py
 tests/test_provenance.py

{flowtracks-1.8.0 → flowtracks-1.8.1.dev7}/flowtracks.egg-info/scm_file_list.json

@@ -757,6 +757,7 @@
     "tests/conftest.py",
     "tests/helpers.py",
     "tests/test_analysis.py",
+    "tests/test_averaging_method_differences.py",
     "tests/test_binning_equivalence.py",
     "tests/test_clean.py",
     "tests/test_derived_fields.py",
@@ -773,6 +774,7 @@
     "tests/test_phase_average_xr.py",
     "tests/test_phase_shift_extraction_and_vtr_export.py",
     "tests/test_phasing.py",
+    "tests/test_pooled_ensemble.py",
     "tests/test_post_analysis_edge_cases.py",
     "tests/test_post_analysis_xr.py",
     "tests/test_provenance.py",

flowtracks-1.8.1.dev7/flowtracks.egg-info/scm_version.json

@@ -0,0 +1,8 @@
+{
+  "tag": "1.8.0",
+  "distance": 7,
+  "node": "g4874e61642b4982a450a452736ff84a6a84dabd8",
+  "dirty": false,
+  "branch": "master",
+  "node_date": "2026-11-14"
+}

flowtracks-1.8.1.dev7/requriments.txt

@@ -0,0 +1 @@
+certifi>=2026.10.19