flowtracks 1.5.1__tar.gz → 1.5.2.dev1__tar.gz

flowtracks-1.5.2.dev1/.github/workflows/python-package.yml

@@ -0,0 +1,41 @@
+name: Python Package
+
+on:
+  push:
+    branches: [ master ]
+    tags:
+      - 'v*'
+  pull_request:
+    branches: [ master ]
+  workflow_dispatch:
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    strategy:
+      fail-fast: false
+      matrix:
+        python-version: ["3.11", "3.12", "3.13"]
+
+    steps:
+    - uses: actions/checkout@v3
+    - name: Set up Python ${{ matrix.python-version }}
+      uses: actions/setup-python@v4
+      with:
+        python-version: ${{ matrix.python-version }}
+    - name: Install dependencies
+      run: |
+        python -m pip install --upgrade pip
+        python -m pip install pytest numpy scipy tables vtk pyvista
+        python -m pip install -e .
+    - name: Test with pytest
+      run: |
+        pytest
+    - name: Lint (ruff)
+      run: |
+        python -m pip install ruff
+        ruff check .
+
+# NOTE: this workflow never publishes. The single deploy path is
+# python-publish.yml (release-event). Keeping publishing here as well
+# would double-publish every release (and fail on file-name reuse).

flowtracks-1.5.2.dev1/.github/workflows/python-publish.yml

@@ -0,0 +1,99 @@
+# Publishes flowtracks to PyPI (trusted publishing, environment "pypi"):
+#
+# - every push to master -> a DEVELOPMENT release, X.Y.(Z+1).devN, N = commits
+#   since the last vX.Y.Z tag (setuptools-scm). pip and uv skip development
+#   releases unless asked for one (`pip install --pre`, or a requirement such
+#   as `flowtracks>=1.5.2.dev3`), so stable users are unaffected while
+#   downstream projects can pin the newest code;
+# - a published GitHub release (tag vX.Y.Z) -> the stable X.Y.Z.
+#
+# Tests and ruff gate both. This is the only workflow that publishes.
+
+name: Upload Python Package
+
+on:
+  push:
+    branches: [master]
+    paths-ignore: ["**.md", "doc/**"]
+  release:
+    types: [published]
+  workflow_dispatch:
+
+permissions:
+  contents: read
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+      - name: Test and lint
+        run: |
+          python -m pip install --upgrade pip
+          python -m pip install pytest ruff tables vtk pyvista scikit-image
+          python -m pip install -e .
+          pytest -q
+          ruff check .
+
+  release-build:
+    runs-on: ubuntu-latest
+    needs: test
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          fetch-depth: 0          # setuptools-scm derives the version from tags
+
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.x"
+
+      - name: Build release distributions
+        run: |
+          python -m pip install build
+          python -m build
+
+      - name: Check the version
+        run: |
+          VERSION=$(ls dist/*.whl | sed -E 's/.*flowtracks-([^-]+)-.*/\1/')
+          echo "Built version: $VERSION"
+          if [ "${{ github.event_name }}" = "release" ]; then
+            # a release must build exactly its tag's version (v1.2.2 -> 1.2.2)
+            if [ "$VERSION" != "${GITHUB_REF#refs/tags/v}" ]; then
+              echo "Error: tag ${GITHUB_REF#refs/tags/} builds $VERSION"; exit 1
+            fi
+          else
+            case "$VERSION" in *.dev*) ;; *) echo "Error: $VERSION is not a dev version"; exit 1 ;; esac
+          fi
+
+      - name: Upload distributions
+        uses: actions/upload-artifact@v4
+        with:
+          name: release-dists
+          path: dist/
+
+  pypi-publish:
+    runs-on: ubuntu-latest
+    needs:
+      - release-build
+    permissions:
+      # IMPORTANT: this permission is mandatory for trusted publishing
+      id-token: write
+    environment:
+      name: pypi
+      url: https://pypi.org/p/flowtracks
+
+    steps:
+      - name: Retrieve release distributions
+        uses: actions/download-artifact@v4
+        with:
+          name: release-dists
+          path: dist/
+
+      - name: Publish release distributions to PyPI
+        uses: pypa/gh-action-pypi-publish@release/v1
+        with:
+          packages-dir: dist/
+          skip-existing: true     # a re-run of the same commit is not an error

flowtracks-1.5.2.dev1/.gitignore

@@ -0,0 +1,14 @@
+*.pyc
+.spyder*
+# Ad-hoc local scripts and the figures they dump (never library output).
+scratch*
+build/*
+MANIFEST
+dist/*
+flowtracks.egg-info/*
+examples/.ipynb_checkpoints/*
+doc/build/*
+*.json
+.pypi_token
+uv.lock
+flowtracks/_version.py

flowtracks-1.5.2.dev1/CLAUDE.md

@@ -0,0 +1,123 @@
+# CLAUDE.md
+
+This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
+
+## What this is
+
+`postptv` publishes as the **`flowtracks`** package: post-processing of 3D
+Particle Tracking Velocimetry (3D-PTV) trajectory databases — reading
+per-frame particle data, building trajectories, interpolating Lagrangian data
+onto Eulerian grids, phase/ensemble averaging for periodic flows, smoothing,
+stitching, and VTK export. It is one stage of a larger multi-repo pipeline;
+see `~/projects/CLAUDE.md` for how this repo relates to `openptv2`,
+`openptv-cloud`, `flowtracks_examples`, and `matlab_to_python_3dptv`.
+
+## Commands
+
+Uses **uv**.
+
+```bash
+uv sync --group dev          # installs pytest, pytest-benchmark
+uv run pytest                # full suite (testpaths = tests/)
+uv run pytest tests/test_scene.py::test_name -v   # single test
+uv run pytest tests/test_speedup_equivalence.py -v  # perf-vectorization equivalence tests
+uv run pytest --benchmark-only    # pytest-benchmark suite (see .benchmarks/)
+```
+
+No linter is configured in `pyproject.toml`; there is no build step (pure
+Python, no Cython here — unlike `openptv2`).
+
+## Architecture
+
+### Two parallel data backends, one duck-typed interface
+
+The library has two generations of "give me particle data" reader, and newer
+code (`eulerian.py`, `phase_average.py`) is written to work against either:
+
+- **`scene.py` (`Scene`)** — the original backend. Wraps a PyTables HDF5 file
+  with a `/particles` table plus a `/bounds` (or similar) trajectory-index
+  table. Frame/trajectory queries are built as PyTables `read_where()`
+  query strings via `gen_query_string()`.
+- **`zarr_scene.py` (`ZarrScene`)** — a Zarr-backed counterpart with the same
+  public methods (duck-typed, not a subclass — the backing stores are too
+  different to share a base class). Reads a `trajectories/` group with
+  `pos`/`vel`/`time`/`trajid`(/`accel`) arrays. This layout is shared with
+  `openptv2`'s `storage.seal()` run-store output, so `ZarrScene` transparently
+  reads either a flowtracks-written Zarr export (`io.save_zarr_trajectories`)
+  or an openptv2 RunStore — no conversion step. `collect()`'s `where`
+  filtering is reimplemented in plain numpy instead of a query-string DSL,
+  since there's no query engine to target.
+
+When touching either backend, check whether the change needs to be mirrored
+in the other — callers like `eulerian.py`'s `scene.collect(...)` fast path
+are written to accept both.
+
+### Trajectory data model
+
+`trajectory.py` defines `ParticleSet` (the base class: an array of `pos`,
+`velocity`, plus arbitrary per-timepoint keyword properties, each auto-getting
+a getter/setter pair via `create_property`), and `Trajectory` /
+`ParticleSnapshot` on top of it. `Frame` is a plain data-holder with
+`.particles` / `.tracers` attributes.
+
+### I/O module (`io.py`)
+
+Central entry points: `trajectories()` / `iter_trajectories()` for reading,
+`save_trajectories()` (legacy NPZ-directory format) and
+`save_particles_table()` (HDF5, the recommended format) for writing. Format is
+inferred from the file name via `infer_format()`. Zarr save/read paths
+(`save_zarr_trajectories`, `read_zarr_trajectories`) live alongside these.
+
+### xarray/YAML-recipe modules (newer, parallel implementation track)
+
+`phase_average.py` and `eulerian.py` are **xarray re-expressions** of older
+imperative scripts (`phase_average_fluctuations.py`,
+`batch_Lagrangian_to_Eulerian.py`, `turbulent_statistics.py`,
+`sample_vtkcode.py` — some of these live in `examples/`, not in the package).
+They operate as pure `Dataset -> Dataset` stages driven by a YAML recipe, and
+are meant to consolidate the domain math (often a one-liner) while making the
+data contract (dims, coords, attrs) explicit and self-describing. When adding
+post-processing logic, prefer extending these over the older imperative
+scripts they replace.
+
+### `pipeline.py`
+
+Thin per-stage wrapper functions (`ptv_is_to_lagrangian`,
+`lagrangian_to_eulerian`, `phase_average_all_sets`, ...) — each one is
+independently runnable and is the unit the cloud orchestrator (in
+`openptv-cloud`) distributes across runs. Stages import their real logic from
+the xr modules or `examples/` scripts; nothing is implemented twice here.
+
+### Other modules
+
+- `stitching.py` — reconnects broken trajectory segments across short frame
+  gaps (linear-sum-assignment candidate matching).
+- `smoothing.py`, `interpolation.py` — trajectory smoothing and RBF/IDW
+  interpolation onto grids.
+- `analysis.py`, `combine.py`, `pairs.py` — trajectory-level statistics and
+  multi-run combination.
+- `writers.py`, `graphics.py`, `nhist.py` — visualization/export helpers
+  (ParaView export goes through `writers.write_eulerian_series` /
+  `write_trajectories_vtp`; the legacy `vtk_export.py` module is removed).
+- `an_scene.py` — an alternate/legacy scene analysis path; check before
+  extending whether logic belongs there or in `scene.py`/`zarr_scene.py`.
+
+### Performance work in flight
+
+Several modules carry "vectorize X, verify equivalence" pairs: a vectorized
+implementation plus a `tests/test_*_equivalence.py` test asserting it matches
+the original loop-based output bit-for-bit (or within tolerance) on the same
+inputs. `SPEEDUP_PLAN.md` and `future_plan.md` track the broader roadmap
+(Zarr/xarray/Dask migration, turbulence statistics, RTS Kalman smoothing,
+CLI, GPU hooks) — check these before assuming a described feature already
+exists; several are aspirational, not built.
+
+## Notes
+
+- Python ≥3.11. Some docstrings/comments still carry Python-2-era artifacts
+  (`from builtins import object`, `# from past.builtins import range`) —
+  harmless leftovers, not evidence the code needs to support Python 2.
+- `examples/` contains runnable scripts and marimo/Jupyter notebooks that
+  exercise the pipeline end-to-end (`marimo_*`, `batch_Lagrangian_to_Eulerian.py`,
+  `run_pipeline.py`) — useful as real usage references when a docstring is
+  unclear.

{flowtracks-1.5.1 → flowtracks-1.5.2.dev1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: flowtracks
-Version: 1.5.1
+Version: 1.5.2.dev1
 Summary: Library for handling 3D PTV trajectory databases and Lagrangian/Eulerian turbulence post-processing.
 Author-email: Yosef Meller <yosefm@gmail.com>
 License:                     GNU GENERAL PUBLIC LICENSE

flowtracks-1.5.2.dev1/RELEASE.md

@@ -0,0 +1,39 @@
+# Release Process
+
+Versions come from git tags ([setuptools-scm](https://setuptools-scm.readthedocs.io));
+nothing in the source tree holds a version number.
+
+## Development releases (automatic)
+
+Every push to `master` that passes the tests is published to PyPI as a
+development release: `X.Y.(Z+1).devN`, where `vX.Y.Z` is the last tag and `N`
+the number of commits since it (e.g. `1.5.2.dev3`).
+
+`pip install flowtracks` and `uv add flowtracks` ignore development releases,
+so users of the stable version never get them by accident. To use one:
+
+```bash
+pip install --pre flowtracks                  # newest, including dev releases
+pip install "flowtracks>=1.5.2.dev3"          # at least this commit
+```
+
+(uv accepts a dev release whenever the requirement itself names one, as in
+the second line.)
+
+## Stable releases
+
+We follow [Semantic Versioning](https://semver.org/): MAJOR for incompatible
+API changes, MINOR for new backward-compatible functionality, PATCH for
+backward-compatible bug fixes.
+
+1. Make sure `master` is pushed and its CI is green.
+2. Create the release on GitHub (this creates the tag):
+   ```bash
+   gh release create vX.Y.Z --title vX.Y.Z --notes "..."
+   ```
+3. `.github/workflows/python-publish.yml` runs the tests, builds `X.Y.Z` from
+   the tag (and fails if the tag and the built version differ) and publishes
+   it to PyPI via trusted publishing (GitHub environment `pypi`).
+
+The installed version is `flowtracks.__version__` (written to
+`flowtracks/_version.py` at build/install time; not in git).