PyStormTracker 0.3.3__tar.gz → 0.4.0__tar.gz

pystormtracker-0.4.0/.dockerignore

@@ -0,0 +1,16 @@
+.coverage
+.coverage.*
+.git
+.github
+.mypy_cache/
+.pytest_cache/
+.ruff_cache/
+.venv/
+.vscode/
+__pycache__/
+benchmark/
+data/test/
+docs/
+htmlcov/
+tests/
+worktrees/

{pystormtracker-0.3.3 → pystormtracker-0.4.0}/.github/workflows/ci.yml

@@ -8,6 +8,7 @@ on:
       - 'pyproject.toml'
       - 'uv.lock'
       - 'Dockerfile'
+      - '.github/workflows/ci.yml'
   push:
     branches:
       - main
@@ -20,6 +21,9 @@ on:
       - 'pyproject.toml'
       - 'uv.lock'
       - 'Dockerfile'
+      - '.github/workflows/ci.yml'
+  release:
+    types: [published]
   workflow_dispatch:
 
 concurrency:
@@ -83,6 +87,7 @@ jobs:
       fail-fast: false
       matrix:
         python-version: ["3.11", "3.12", "3.13", "3.14"]
+        min-deps: [false]
         include:
           - python-version: "3.11"
             min-deps: true
@@ -105,8 +110,20 @@ jobs:
         if: ${{ matrix.min-deps }}
         run: uv sync --group dev --resolution lowest-direct
       - name: Run Unit Tests
-        run: |
-          uv run pytest -vv
+        if: matrix.python-version != '3.13' || matrix.min-deps
+        run: uv run pytest -vv
+
+      - name: Run Unit Tests with Coverage
+        if: matrix.python-version == '3.13' && !matrix.min-deps
+        run: uv run pytest -vv --cov=pystormtracker --cov-report=term-missing --cov-report=xml
+
+      - name: Upload coverage reports to Codecov
+        if: matrix.python-version == '3.13' && !matrix.min-deps
+        uses: codecov/codecov-action@v5
+        with:
+          files: ./coverage.xml
+          flags: unit
+          token: ${{ secrets.CODECOV_TOKEN }}
 
   integration-tests:
     name: integration-tests (Python ${{ matrix.python-version }}, ${{ matrix.arch }})
@@ -117,10 +134,10 @@ jobs:
         include:
           - arch: amd64
             os: ubuntu-24.04
-            python-version: "3.14"
+            python-version: "3.13"
           - arch: arm64
             os: ubuntu-24.04-arm
-            python-version: "3.14"
+            python-version: "3.13"
     steps:
       - uses: actions/checkout@v6
         with:
@@ -136,16 +153,32 @@ jobs:
       - name: Install dependencies
         run: uv sync --frozen --group dev
       - name: Run Integration Tests
-        run: |
-          uv run pytest -vv tests/test_integration.py --run-integration
+        if: matrix.arch != 'amd64'
+        run: uv run pytest -vv tests/test_integration.py --run-integration
+
+      - name: Run Integration Tests with Coverage
+        if: matrix.arch == 'amd64'
+        run: uv run pytest -vv --cov=pystormtracker --cov-report=term-missing --cov-report=xml tests/test_integration.py --run-integration
+
       - name: Upload coverage reports to Codecov
+        if: matrix.arch == 'amd64'
         uses: codecov/codecov-action@v5
         with:
+          files: ./coverage.xml
+          flags: integration
           token: ${{ secrets.CODECOV_TOKEN }}
 
   docker-build:
     name: docker-build
-    needs: [integration-tests]
+    needs: [ruff-lint, ruff-format, mypy-typecheck, unit-tests, integration-tests]
+    # Only run on merges to main, release branches, tags, releases, or manual dispatch
+    if: |
+      github.event_name != 'pull_request' &&
+      (github.ref == 'refs/heads/main' ||
+       startsWith(github.ref, 'refs/heads/release/') ||
+       startsWith(github.ref, 'refs/tags/v') ||
+       github.event_name == 'release' ||
+       github.event_name == 'workflow_dispatch')
     runs-on: ubuntu-latest
     steps:
       - name: Checkout repository
@@ -164,20 +197,47 @@ jobs:
           push: false
           load: true
           platforms: linux/amd64
-          tags: "${{ vars.DOCKER_IMAGE_NAME }}:${{ github.sha }}"
+          tags: "${{ github.repository_owner }}/${{ vars.DOCKER_IMAGE_NAME }}:${{ github.sha }}"
           cache-from: type=gha,scope=docker-build
           cache-to: type=gha,mode=max,scope=docker-build
 
       - name: Smoke test Docker image
         run: |
-          docker run --rm ${{ vars.DOCKER_IMAGE_NAME }}:${{ github.sha }} --help
+          # Test CLI help
+          docker run --rm ${{ github.repository_owner }}/${{ vars.DOCKER_IMAGE_NAME }}:${{ github.sha }} --help
+          # Test library import
+          docker run --rm --entrypoint python ${{ github.repository_owner }}/${{ vars.DOCKER_IMAGE_NAME }}:${{ github.sha }} -c "import pystormtracker as pst; print('Import success')"
 
       - name: Run Trivy vulnerability scanner
         uses: aquasecurity/trivy-action@0.35.0
         with:
-          image-ref: "${{ vars.DOCKER_IMAGE_NAME }}:${{ github.sha }}"
+          image-ref: "${{ github.repository_owner }}/${{ vars.DOCKER_IMAGE_NAME }}:${{ github.sha }}"
           format: "table"
           exit-code: "0"
           ignore-unfixed: true
           vuln-type: "os,library"
           severity: "CRITICAL,HIGH"
+
+  pypi-build:
+    name: pypi-build
+    needs: [ruff-lint, ruff-format, mypy-typecheck, unit-tests, integration-tests]
+    # Only run on merges to main, release branches, tags, releases, or manual dispatch
+    if: |
+      github.event_name != 'pull_request' &&
+      (github.ref == 'refs/heads/main' ||
+       startsWith(github.ref, 'refs/heads/release/') ||
+       startsWith(github.ref, 'refs/tags/v') ||
+       github.event_name == 'release' ||
+       github.event_name == 'workflow_dispatch')
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v6
+        with:
+          ref: ${{ github.ref }}
+          fetch-depth: 0
+      - name: Set up uv
+        uses: astral-sh/setup-uv@v7
+        with:
+          enable-cache: true
+      - name: Build release distributions
+        run: uv build --wheel --sdist

{pystormtracker-0.3.3 → pystormtracker-0.4.0}/.github/workflows/docker-publish.yml

@@ -1,11 +1,9 @@
 name: Docker Publish
 
 on:
-  push:
-    branches:
-      - main
-  release:
-    types: [published]
+  workflow_run:
+    workflows: ["CI"]
+    types: [completed]
   workflow_dispatch:
 
 concurrency:
@@ -13,23 +11,33 @@ concurrency:
   cancel-in-progress: false
 
 env:
-  DOCKER_HUB_REPO: docker.io/${{ vars.DOCKER_IMAGE_NAME }}
-  GHCR_REPO: ghcr.io/${{ vars.DOCKER_IMAGE_NAME }}
+  # Publish to ORG on release, else to OWNER (personal) for merge to main/manual
+  DOCKER_HUB_REPO: docker.io/${{ (github.event_name == 'release' || (github.event_name == 'workflow_run' && github.event.workflow_run.event == 'release')) && vars.DOCKER_ORG_NAME || github.repository_owner }}/${{ vars.DOCKER_IMAGE_NAME }}
+  GHCR_REPO: ghcr.io/${{ (github.event_name == 'release' || (github.event_name == 'workflow_run' && github.event.workflow_run.event == 'release')) && vars.DOCKER_ORG_NAME || github.repository_owner }}/${{ vars.DOCKER_IMAGE_NAME }}
 
 jobs:
   build-and-push:
     runs-on: ubuntu-latest
+    # Only run if CI succeeded (for workflow_run) or if it's a manual trigger.
+    # Added head_repository check for security in trusted context.
+    if: |
+      (github.event_name == 'workflow_run' && 
+       github.event.workflow_run.conclusion == 'success' && 
+       github.event.workflow_run.head_repository.full_name == github.repository &&
+       (github.event.workflow_run.head_branch == 'main' || github.event.workflow_run.event == 'release')) ||
+      github.event_name == 'workflow_dispatch'
     permissions:
       actions: read
-      contents: read
+      contents: write
       packages: write
       id-token: write
       attestations: write
+      artifact-metadata: write
     steps:
       - name: Checkout repository
         uses: actions/checkout@v6
         with:
-          ref: ${{ github.ref }}
+          ref: ${{ github.event.workflow_run.head_sha || github.ref }}
           fetch-depth: 0
 
       - name: Set up QEMU
@@ -58,18 +66,20 @@ jobs:
           images: |
             ${{ env.DOCKER_HUB_REPO }}
             ${{ env.GHCR_REPO }}
+          # Fix: Tell the metadata action the real ref, otherwise it defaults to 'main'
+          ref: ${{ github.event.workflow_run.head_branch || github.ref }}
           tags: |
-            # Always tag with short SHA
-            type=sha,format=short,prefix=
-            # Tag with 'edge' only for main branch
-            type=edge,branch=main
-            # Branch tag for all branches except main
-            type=ref,event=branch,enable=${{ github.ref_name != 'main' }}
+            # Tag with 'edge' only for main branch builds
+            type=edge,branch=main,priority=700
             # Semver tags for releases (includes 'latest')
-            type=semver,pattern=latest
-            type=semver,pattern={{version}}
-            type=semver,pattern={{major}}.{{minor}}
-            type=semver,pattern={{major}},enable=${{ !startsWith(github.ref_name, 'v0') }}
+            type=semver,pattern=latest,priority=1000
+            type=semver,pattern={{version}},priority=900
+            type=semver,pattern={{major}}.{{minor}},priority=900
+            type=semver,pattern={{major}},enable=${{ !startsWith(github.ref_name, 'v0') }},priority=900
+            # Branch tag for all branches except main
+            type=ref,event=branch,enable=${{ github.ref_name != 'main' }},priority=600
+            # Always tag with short SHA
+            type=sha,format=short,prefix=,priority=100
 
       - name: Build and push Docker image
         id: push
@@ -85,8 +95,8 @@ jobs:
           cache-from: type=gha,scope=docker-build
           cache-to: type=gha,mode=max,scope=docker-build
 
-      - name: Generate artifact attestation (Docker Hub)
-        uses: actions/attest-build-provenance@v4
+      - name: Attest Provenance (Docker Hub)
+        uses: actions/attest@v4
         with:
           subject-name: ${{ env.DOCKER_HUB_REPO }}
           subject-digest: ${{ steps.push.outputs.digest }}
@@ -101,7 +111,7 @@ jobs:
           format: cyclonedx-json
 
       - name: Attest SBOM (Docker Hub)
-        uses: actions/attest-sbom@v4
+        uses: actions/attest@v4
         with:
           subject-name: ${{ env.DOCKER_HUB_REPO }}
           subject-digest: ${{ steps.push.outputs.digest }}

{pystormtracker-0.3.3 → pystormtracker-0.4.0}/.github/workflows/python-publish.yml

@@ -4,8 +4,9 @@
 name: Upload Python Package
 
 on:
-  release:
-    types: [published]
+  workflow_run:
+    workflows: ["CI"]
+    types: [completed]
 
 concurrency:
   group: ${{ github.workflow }}-${{ github.ref }}
@@ -17,6 +18,13 @@ permissions:
 jobs:
   release-build:
     runs-on: ubuntu-latest
+    # Only run if CI succeeded AND it was a release event.
+    # Added head_repository check for security.
+    if: |
+      github.event_name == 'workflow_run' && 
+      github.event.workflow_run.conclusion == 'success' && 
+      github.event.workflow_run.event == 'release' &&
+      github.event.workflow_run.head_repository.full_name == github.repository
     permissions:
       contents: read
       id-token: write
@@ -25,6 +33,7 @@ jobs:
     steps:
       - uses: actions/checkout@v6
         with:
+          ref: ${{ github.event.workflow_run.head_sha }}
           fetch-depth: 0
 
       - name: Set up uv
@@ -64,7 +73,8 @@ jobs:
         id: get_version
         run: |
           # Strips 'v' prefix from tag_name (e.g. v0.2.1 -> 0.2.1)
-          VERSION=${{ github.event.release.tag_name }}
+          # In workflow_run for a release, head_branch contains the tag name.
+          VERSION=${{ github.event.workflow_run.head_branch }}
           echo "version=${VERSION#v}" >> $GITHUB_OUTPUT
 
       - name: Retrieve release distributions

pystormtracker-0.4.0/.gitignore

@@ -0,0 +1,40 @@
+# Byte-compiled / optimized / DLL files
+__pycache__/
+*.py[cod]
+*.so
+
+# Python Environments & Caches
+.venv/
+env/
+.mypy_cache/
+.pytest_cache/
+.ruff_cache/
+.cache/
+
+# Distribution / packaging
+build/
+dist/
+sdist/
+
+# Unit test / coverage reports
+htmlcov/
+.tox/
+.coverage
+.coverage.*
+coverage.xml
+
+# Sphinx documentation
+docs/_build/
+
+# IPython intermediate checkpoints
+.ipynb_checkpoints
+
+# Data and Track files
+*.nc
+*.txt
+!data/test/tracks/*.txt
+*.pickle
+
+# IDE and Project Tooling
+.vscode/
+worktrees/

pystormtracker-0.4.0/.python-version

@@ -0,0 +1 @@
+3.13

pystormtracker-0.4.0/ARCHITECTURE.md

@@ -0,0 +1,97 @@
+# PyStormTracker Architecture
+
+This document describes the modern, high-performance architecture of PyStormTracker, detailing how it leverages vectorization and decoupled components to process massive climate datasets efficiently.
+
+## 1. High-Level Design Philosophy
+
+PyStormTracker is built for scale and extensibility. The architecture is centered around three core principles:
+1.  **Unified API (Tracker Protocol):** A structural interface that allows the CLI and Python API to support multiple tracking algorithms (e.g., `SimpleTracker`, `HodgesTracker`) interchangeably.
+2.  **Centralized Threshold Management:** The `SimpleDetector` is responsible for managing variable-specific detection thresholds (e.g., `1e-4` for vorticity), ensuring consistent behavior across different parallel backends.
+3.  **Vectorization & JIT:** Heavy mathematical operations are offloaded to **Numba** JIT-compiled kernels and **NumPy** broadcasting, bypassing Python's loop overhead and Global Interpreter Lock (GIL).
+4.  **Hybrid Parallelism:** The architecture parallelizes the computationally intensive **Detection** phase while centralizing the **Linking** phase to ensure perfect serial-parallel consistency.
+
+---
+
+## 2. Modern Core Components
+
+### 2.1 Array-Backed Data Models (`Tracks`, `Track`, `Center`)
+The data models utilize a contiguous memory paradigm:
+*   **`Tracks`**: The central container holding contiguous 1D NumPy arrays for `track_ids`, `times`, `lats`, `lons`, and a dictionary of scientific variables.
+*   **`Track`**: A lightweight "view" into the `Tracks` arrays for a specific ID.
+*   **`Center`**: A simple dataclass used strictly for iteration or final data export.
+
+**Benefits:** By avoiding the creation of millions of Python objects, memory usage is minimized, and data serialization between parallel processes is nearly instantaneous. Raw NumPy arrays also enable extremely fast distance calculations via C-level broadcasting.
+
+### 2.2 Shared DataLoader
+Data loading is encapsulated in a dedicated `DataLoader` class (`io/loader.py`). This component handles:
+*   **Format Abstraction**: Seamlessly detects and opens NetCDF (via `h5netcdf` or `netcdf4`) and GRIB (via `cfgrib`) files.
+*   **Variable Mapping**: Automatically maps common variable aliases (e.g., `msl`/`slp`, `vo`/`rv`) and coordinate names (`latitude`/`lat`), allowing the same tracking logic to work across different data providers.
+*   **Contiguous I/O**: Performs single-block contiguous reads from disk, bypassing HDF5 lock contention.
+
+### 2.3 Vectorized Linker (`SimpleLinker`)
+Trajectory construction uses NumPy broadcasting to calculate Haversine distance matrices between existing track tails and new storm centers. By sorting points spatially before matching, the Linker ensures deterministic, greedy nearest-neighbor linking.
+
+### 2.4 Parallel Pipeline (Gather-then-Link)
+To ensure that parallel results are bit-wise identical to serial runs, PyStormTracker uses a hybrid parallel strategy:
+1.  **Parallel Detection**: Assigned time chunks are distributed across Dask or MPI workers. Each worker runs Numba kernels to find centers and returns raw coordinate arrays.
+2.  **Centralized Linking**: The main process gathers the raw detections from all workers and performs a single sequential link. 
+
+**Why this works:** In storm tracking, the **Detection** phase (finding local extrema in 3D grids) consumes >95% of the runtime. The **Linking** phase (connecting coordinate lists) is extremely fast once vectorized. Centralizing the link eliminates the complex "merging" bugs found in tree-reduction strategies while maintaining near-perfect parallel scaling.
+
+---
+
+## 3. The `Tracker` Protocol
+
+The `Tracker` Protocol (defined in `src/pystormtracker/models/tracker.py`) provides a standardized interface for all tracking algorithms:
+
+```python
+import pystormtracker as pst
+
+# Instantiate any compliant tracker
+tracker = pst.SimpleTracker()
+
+# Standardized .track() method
+tracks = tracker.track(
+    infile="era5_msl.nc", 
+    varname="msl", 
+    start_time="2025-01-01",
+    backend="dask"
+)
+
+# Standardized export
+tracks.write("output.txt", format="imilast")
+```
+
+---
+
+## 4. Future Architectural Direction
+
+To further optimize scalability and memory efficiency for native-resolution climate datasets (e.g., 0.25° ERA5), the architecture is evolving towards deeper integration with the scientific Python ecosystem:
+
+*   **Idiomatic Xarray (`apply_ufunc`):** Transitioning away from custom MPI/Dask chunking in favor of Xarray's native `apply_ufunc(..., dask="parallelized")`. This delegates chunk management and distributed execution entirely to Xarray/Dask, reducing custom orchestration code.
+*   **Lazy Evaluation & Thread Topology:** Shifting from eager chunk-loading to lazy, frame-by-frame memory access to eliminate out-of-memory risks on large domains. Concurrently, strictly pinning Numba thread topologies to prevent CPU oversubscription in multi-process backends.
+*   **Tree-based Linking:** Upgrading the current NumPy-broadcasting linker to utilize C-level tree structures (e.g., `scipy.spatial.cKDTree`), breaking the $O(N^2)$ scaling barrier for extremely long or dense trajectory sequences.
+
+For more details on specific planned implementations, see the [Roadmap](ROADMAP.md).
+
+---
+
+## 5. Performance Benchmarks
+
+To quantify the efficiency gains of the modern array-backed JIT architecture, a comprehensive performance comparison was conducted between the legacy object-oriented system (`v0.3.3`) and the current implementation.
+
+Detailed execution timings (breaking down Detection, Linking, Export, and I/O Overhead) across Serial, Dask, and MPI backends for both standard and high-resolution ERA5 datasets are available in the [Benchmark Report](benchmark/BENCHMARK.md).
+
+---
+
+## Appendix: Evolution from Legacy Architecture
+
+The current architecture represents a fundamental shift from the legacy nested-object design used in earlier versions.
+
+| Feature | Legacy Architecture (v0.3.x and earlier) | Modern Architecture (v0.4.0+) |
+| :--- | :--- | :--- |
+| **Data Storage** | Nested lists of `Center` and `Track` objects. | Flat, C-contiguous NumPy arrays. |
+| **Parallelism** | Threads (bottlenecked by GIL). | Processes/MPI (true concurrent I/O). |
+| **Linking Strategy** | Tree-reduction (prone to boundary splits). | Parallel Detect + Centralized Link (perfect matching). |
+| **Linker** | $O(N^2)$ nested Python loops. | Vectorized NumPy matrix broadcasting. |
+| **I/O** | Many small lazy-loaded chunks. | Contiguous shared `DataLoader`. |

{pystormtracker-0.3.3 → pystormtracker-0.4.0}/CITATION.cff

@@ -12,14 +12,14 @@ identifiers:
     value: 10.5281/zenodo.18764813
 repository-code: 'https://github.com/mwyau/PyStormTracker'
 url: 'https://pystormtracker.readthedocs.io/'
-abstract: A Parallel Object-Oriented Cyclone Tracker in Python
+abstract: A High-Performance Cyclone Tracker in Python
 keywords:
   - cyclone tracking
   - climate variability
   - dask
   - mpi
 license: BSD-3-Clause
-version: 0.3.3
+version: 0.4.0
 date-released: '2026-03-10'
 preferred-citation:
   type: article

{pystormtracker-0.3.3 → pystormtracker-0.4.0}/PKG-INFO

@@ -1,7 +1,7 @@
 Metadata-Version: 2.4
 Name: PyStormTracker
-Version: 0.3.3
-Summary: A Parallel Object-Oriented Cyclone Tracker in Python
+Version: 0.4.0
+Summary: A High-Performance Cyclone Tracker in Python
 Project-URL: Homepage, https://pypi.org/project/PyStormTracker/
 Project-URL: Repository, https://github.com/mwyau/PyStormTracker.git
 Project-URL: Issues, https://github.com/mwyau/PyStormTracker/issues
@@ -22,13 +22,15 @@ Requires-Dist: dask>=2024.1.0
 Requires-Dist: distributed>=2024.1.0
 Requires-Dist: h5netcdf>=1.0.0
 Requires-Dist: h5py>=3.8.0
+Requires-Dist: matplotlib>=3.10.8
+Requires-Dist: numba>=0.60.0
 Requires-Dist: numpy>=1.24.0
-Requires-Dist: scipy>=1.9.2
+Requires-Dist: pandas>=3.0.1
 Requires-Dist: xarray>=2024.9.0
 Provides-Extra: all
 Requires-Dist: cfgrib>=0.9.15.1; extra == 'all'
 Requires-Dist: eccodes>=2.43.0; extra == 'all'
-Requires-Dist: eccodeslib>=2.43.0; extra == 'all'
+Requires-Dist: eccodeslib>=2.43.0; (sys_platform != 'win32') and extra == 'all'
 Requires-Dist: mpi4py>=4.1.0; extra == 'all'
 Requires-Dist: netcdf4>=1.6.1; extra == 'all'
 Provides-Extra: docs
@@ -38,7 +40,7 @@ Requires-Dist: sphinx>=9.0.4; extra == 'docs'
 Provides-Extra: grib
 Requires-Dist: cfgrib>=0.9.15.1; extra == 'grib'
 Requires-Dist: eccodes>=2.43.0; extra == 'grib'
-Requires-Dist: eccodeslib>=2.43.0; extra == 'grib'
+Requires-Dist: eccodeslib>=2.43.0; (sys_platform != 'win32') and extra == 'grib'
 Provides-Extra: mpi
 Requires-Dist: mpi4py>=4.1.0; extra == 'mpi'
 Provides-Extra: netcdf4
@@ -57,29 +59,37 @@ Description-Content-Type: text/markdown
 [![GHCR](https://img.shields.io/badge/ghcr.io-xddd%2Fpystormtracker-blue?logo=github)](https://github.com/orgs/xddd/packages/container/package/pystormtracker)
 [![DOI](https://zenodo.org/badge/36328800.svg)](https://doi.org/10.5281/zenodo.18764813)
 
-**PyStormTracker** is a Python package for cyclone trajectory analysis, implementing the "Simple Tracker" algorithm described in **Yau and Chang (2020)**. It is currently being expanded to include a Python port of the adaptive constraints tracking algorithm from **Hodges (1999)** (originally in C) and the Accumulated Track Activity metrics from **Yau and Chang (2020)** (originally in Matlab).
+**PyStormTracker** is a high-performance Python package for cyclone trajectory analysis. It implements the "Simple Tracker" algorithm and provides a scalable framework for processing large-scale climate datasets like ERA5.
 
-Initially developed at the **National Center for Atmospheric Research (NCAR)** as part of the **2015 SIParCS** program, PyStormTracker leverages task-parallel strategies and tree reduction algorithms to efficiently and accurately process large-scale climate datasets.
+The project is currently being expanded to include a Python port of the adaptive constraints tracking algorithm from **Hodges (1999)** and Accumulated Track Activity metrics.
+
+Initially developed at the **National Center for Atmospheric Research (NCAR)** as part of the **2015 SIParCS** program, PyStormTracker leverages task-parallel strategies and tree reduction algorithms to efficiently process large-scale climate datasets.
 
 ## Features
 
-- **Modern & Typed**: Strictly targets **Python 3.11+** with complete type hints and strict `mypy` compliance.
-- **Xarray Native**: Leverages `xarray` for robust, high-performance coordinate-aware processing, lazy data loading, and optimized I/O.
-- **Scalable Execution**: Supports multiple backends:
-  - **Dask (Default)**: Automatically scales to utilize all available CPU cores.
-  - **MPI**: Enables distributed execution across cluster nodes via `mpi4py`.
-  - **Serial**: Standard sequential execution for debugging or small datasets.
-- **Robust Feature Detection**: Employs optimized $O(N)$ extrema filtering with robust handling of masked or missing data.
-- **Interoperable Output**: Exports tracking results to the standard IMILAST intercomparison format (`.txt`) with human-readable datetime strings.
+- **High-Performance Architecture**: Uses an **Array-Backed** data model to eliminate Python object overhead and ensure zero-copy serialization during parallel execution. **Achieves up to 11.8x speedup in serial workloads.**
+- **JIT-Optimized Kernels**: Core mathematical filters are implemented in **Numba**, running at raw C speeds while releasing the GIL for true multi-process execution.
+- **Xarray Native**: Seamlessly handles NetCDF and GRIB formats with coordinate-aware processing and robust variable alias handling (e.g., `msl`/`slp`, `lon`/`longitude`).
+- **Scalable Backends**: 
+  - **Serial (Default)**: Standard sequential execution.
+  - **Dask**: Multi-process tree-reduction for local or distributed scaling.
+  - **MPI**: High-performance distributed execution via `mpi4py`.
+- **Typed & Modern**: Built for **Python 3.11+** with strict type safety and `mypy` compliance.
+- **Interoperable**: Full support for the standard **IMILAST** intercomparison format (`.txt`) with human-readable datetime strings.
+
+<p align="center">
+  <img src="benchmark/benchmark_0_25x0_25_breakdown.png" width="600" alt="v0.4.0 Performance Improvements">
+  <br>
+  <i>Significant performance gains in v0.4.0+ compared to the legacy v0.3.3 architecture on high-resolution ERA5 data.</i>
+</p>
 
 ## Technical Methodology
 
-PyStormTracker treats meteorological fields as 2D images, utilizing `scipy.ndimage` for robust feature detection and tracking:
+PyStormTracker treats meteorological fields as 2D images and leverages JIT-compiled Numba loops for high-performance feature detection:
 
 - **Local Extrema Detection**: Employs an optimized sliding window filter to efficiently identify local minima (e.g., cyclones) or maxima (e.g., anticyclones, vorticity).
 - **Intensity & Refinement**: Applies the discrete **Laplacian operator** to measure the "sharpness" of the field at each candidate center. This metric resolves duplicate detections, ensuring only the most physically intense point is retained when adjacent pixels are flagged.
-- **Spherical Continuity**: Uses `mode='wrap'` for all spatial filters to correctly handle periodic boundary conditions across the Prime Meridian, allowing for seamless global tracking.
-- **Trajectory Linking**: Connects detected centers across consecutive time steps into continuous trajectories using a nearest-neighbor heuristic linking strategy.
+- **Trajectory Linking**: Connects detected centers across consecutive time steps into continuous trajectories using a vectorized nearest-neighbor heuristic linking strategy.
 
 ## Documentation
 
@@ -90,7 +100,7 @@ Full documentation, including API references and advanced usage examples, is ava
 ### Prerequisites
 - Python 3.11+
 - (Optional) OpenMPI for MPI support.
-- **Windows Users**: Note that the `grib` optional dependency (via `eccodeslib`) currently only supports Linux and macOS.
+- **Windows Users**: the `eccodeslib` GRIB helper library is only required on Linux/macOS. (Note: GRIB/ecCodes support on Windows is currently experimental and untested).
 
 ### From PyPI (Recommended)
 You can install the latest stable version of PyStormTracker directly from PyPI:
@@ -119,23 +129,61 @@ uv sync
 
 ## Usage
 
+### Command Line Interface
+
 Once installed, you can use the `stormtracker` command directly:
 
 ```bash
-stormtracker -i era5_msl_2025-2026_djf_2.5x2.5.nc -v msl -o my_tracks
+stormtracker -i data.nc -v msl -o my_tracks
 ```
 
-### Command Line Arguments
+#### Command Line Arguments
 
 | Argument | Short | Description |
 | :--- | :--- | :--- |
-| `--input` | `-i` | **Required.** Path to the input NetCDF file. |
+| `--input` | `-i` | **Required.** Path to the input NetCDF/GRIB file. |
 | `--var` | `-v` | **Required.** Variable name to track (e.g., `msl`, `vo`). |
 | `--output` | `-o` | **Required.** Path to the output track file (appends `.txt` if missing). |
 | `--num` | `-n` | Number of time steps to process. |
+| `--threshold` | `-t` | Detection threshold (defaults: `1e-4` for `vo`, `0.0` otherwise). |
 | `--mode` | `-m` | `min` (default) for low pressure, `max` for vorticity/high pressure. |
-| `--backend` | `-b` | `dask` (default), `serial`, or `mpi`. |
+| `--backend` | `-b` | `serial` (default), `dask`, or `mpi`. |
 | `--workers` | `-w` | Number of Dask workers (defaults to CPU core count). |
+| `--engine` | `-e` | Xarray engine (e.g., `h5netcdf`, `netcdf4`, `cfgrib`). |
+
+### Python API
+
+You can easily integrate PyStormTracker into your own scripts or Jupyter Notebooks:
+
+```python
+import pystormtracker as pst
+
+# 1. Instantiate the tracker (defaults to Serial backend)
+tracker = pst.SimpleTracker()
+
+# 2. Run the tracking algorithm. Returns an array-backed Tracks object.
+tracks = tracker.track(
+    infile="data.nc", 
+    varname="msl", 
+    mode="min",
+    start_time="2025-01-01",   # Optional: limit by start date
+    end_time="2025-01-31",     # Optional: limit by end date
+    backend="dask",            # Optional: use 'serial', 'dask', or 'mpi'
+    n_workers=4
+)
+
+# 3. Analyze the results programmatically
+for track in tracks:
+    if len(track) >= 8:
+        print(f"Track {track.track_id} lived for {len(track)} steps.")
+
+# 4. Export results
+tracks.write("output.txt", format="imilast")
+```
+
+## Sample Data
+
+Sample datasets for testing and benchmarking are hosted in the [PyStormTracker-Data](https://github.com/mwyau/PyStormTracker-Data) repository.
 
 ## Development
 
@@ -163,7 +211,9 @@ uv run mypy src/
 ### Tiered Testing
 To keep development cycles fast, testing is tiered:
 - **Fast Tests**: Default local runs (skips integration tests).
-- **Integration Tests**: ONLY long-running integration/regression tests.
+- **Integration Tests**: Integration and regression tests.
+  - **Local**: Runs "short" variants (60 time steps) to ensure backend consistency quickly.
+  - **CI**: Runs "full" (all time steps) variants, including legacy regressions.
 - **Full Suite**: Everything.
 
 **Run fast unit tests only (Default):**
@@ -171,7 +221,7 @@ To keep development cycles fast, testing is tiered:
 uv run pytest
 ```
 
-**Run ONLY integration tests:**
+**Run integration tests (Short variants locally):**
 ```bash
 uv run pytest --run-integration
 ```
@@ -187,7 +237,7 @@ If you use this software in your research, please cite the following:
 
 - **Yau, A. M. W.**, 2026: mwyau/PyStormTracker. *Zenodo*, [https://doi.org/10.5281/zenodo.18764813](https://doi.org/10.5281/zenodo.18764813).
 
-- **Yau, A. M. W., and E. K. M. Chang**, 2020: Finding Storm Track Activity Metrics That Are Highly Correlated with Weather Impacts. Part I: Frameworks for Evaluation and Accumulated Track Activity. *J. Climate*, **33**, 10169–10186, [https://doi.org/10.1175/JCLI-D-20-0393.1](https://doi.org/10.1175/JCLI-D-20-0393.1).
+- **Yau, A. M. W. and Chang, E. K. M.**, 2020: Finding Storm Track Activity Metrics That Are Highly Correlated with Weather Impacts. *J. Climate*, **33**, 10169–10186, [https://doi.org/10.1175/JCLI-D-20-0393.1](https://doi.org/10.1175/JCLI-D-20-0393.1).
 
 ## References