OPT-TT-WDMD

Reference code for Optimized Tensor-Train Windowed Dynamic Mode Decomposition (OPT-TT-WDMD).

This repository accompanies the manuscript:

An Algebraically Optimized Tensor-Train Windowed Dynamic Mode Decomposition Method for Large-Scale Non-Stationary Flows

Open-access preprint: SSRN paper page

This repository provides a compact implementation of OPT-TT-WDMD and the minimal scripts needed to reproduce the main numerical checks when the required external DNS data are available.

Overview

Windowed Dynamic Mode Decomposition (WDMD) is useful for analyzing non-stationary flow data, but repeatedly applying DMD over many windows becomes expensive for large tensorized snapshot sequences.

This package implements three closely related code paths:

• dense WDMD on flattened snapshots,
• direct TT-WDMD on a window-local tensor-train representation,
• OPT-TT-WDMD using one global tensor-train representation and temporal-core slicing.

The optimized path follows the algebraic organization described in the manuscript: build a single global tensor-train representation of the full space-time snapshot tensor, reuse the shared spatial TT cores, slice the final temporal core for each window, and form each reduced DMD operator from compact temporal-core factors.

Repository Structure

.
+-- src/optttwdmd/
|   +-- tensor_train.py      # TT-SVD and TT contraction helpers
|   +-- dmd.py               # Dense DMD reduced-operator utilities
|   +-- windowed.py          # WDMD, direct TT-WDMD, and OPT-TT-WDMD routines
+-- examples/
|   +-- synthetic_demo.py    # Data-free consistency demonstration
+-- experiments/
|   +-- fig09_dns_spectrum.py
|   +-- generate_runtime_csv.py
|   +-- fig10_runtime.py
|   +-- fig11_speedup.py
+-- docs/
|   +-- data_access.md
+-- pyproject.toml
+-- requirements.txt
+-- LICENSE
+-- README.md

Environment

The package requires Python 3.9 or newer and uses PyTorch tensors for the main linear algebra operations.

python -m venv .venv
source .venv/bin/activate
pip install -e .

For a manual dependency installation:

pip install -r requirements.txt

GPU acceleration is optional. For small demos and most code inspection tasks, CPU execution is sufficient.

Quick Start

Run the synthetic consistency demo:

python examples/synthetic_demo.py

The demo constructs a small four-dimensional tensor, compares dense WDMD, direct TT-WDMD, and OPT-TT-WDMD on the same window, prints the eigenvalue agreement, and writes a diagnostic plot under outputs/.

Data Shape Convention

The code expects tensorized flow snapshots in the shape:

(n1, n2, ..., nd, nt)

The final axis is time. Dense DMD views each snapshot as a flattened vector of size n1 * n2 * ... * nd.

Manuscript Scripts

Included scripts:

• experiments/fig09_dns_spectrum.py: eigenvalue consistency check.
• experiments/generate_runtime_csv.py: runtime benchmark CSV generation.
• experiments/fig10_runtime.py: runtime comparison from benchmark CSV.
• experiments/fig11_speedup.py: speedup plot from the same benchmark CSV.

Generated arrays, result tensors, and figures are outputs, not source files, and are not tracked by Git.

Runtime figures can be regenerated after preparing the benchmark tensor:

python experiments/generate_runtime_csv.py
python experiments/fig10_runtime.py
python experiments/fig11_speedup.py

Data Availability

The full DNS datasets used in the manuscript are not included because of their storage size and redistribution constraints. Users who want to run the method on their own data should provide tensors in the shape described above.

The repository excludes by default:

*.npy
*.npz
*.pt
*.pth
data/
outputs/
figures/
results/

See docs/data_access.md for DNS data-source notes and local tensor conventions.

License

This repository is released under the MIT License. See LICENSE.

Citation

If you use this code, please cite the open-access SSRN preprint linked above. A complete journal citation will be added after formal publication.