iagyonwu / spod_python

Pythonic spectral proper orthogonal decomposition

---

Spectral Proper Orthogonal Decomposition in Python

Spectral Proper Orthogonal Decomposition (SPOD) decomposes the space-time dataset into mutually orthogonal modes. Each mode oscillates at a single frequency and is ranked by the energy level. The SPOD workflow is illustrated in the following figure. For a detailed understanding of SPOD, the readers are redirected to: (1) SPOD theory [1]; (2) SPOD algorithm [2]; (3) SPOD reconstruction [3]; (4) SPOD applications [4].

This repository contains a Pythonic realization of SPOD and its applications to a range of fluid mechanics problems. If this script appears useful for your research, an explicit mention of the work [5] would be highly appreciated.

Quick Start

Step 1: Download package

Download from Git clone in the terminal

git clone https://github.com/HexFluid/spod_python.git

Download from browser

Download from this link and then unzip it.

Step 2: Install prerequisites

Launch a terminal (UNIX) or an Anaconda Prompt (Windows) window and change directory to spod_python. Run the following command line to install/upgrade the prerequisite Python packages.

pip install -r requirements.txt

Step 3: Load example data

Run the following script with Python 3 to load the data:

import h5py
import os

current_path = os.getcwd() # assuming Python launched in the 'spod_python' dir
data_path    = os.path.join(current_path,'tutorials','bstep_data','bstepDDES.h5')

h5f  = h5py.File(data_path,'r')
data = h5f['data'][:]        # flow field data
dt   = h5f['dt'][0]          # unit in seconds
h5f.close()

Step 4: Run SPOD

Run the following script to obtain SPOD results:

import spod

spod.spod(data,dt,current_path,weight='default',nOvlp='default',window='default',method='fast')

SPOD_LPf  = h5py.File(os.path.join(current_path,'SPOD_LPf.h5'),'r') # load data from h5 format
L = SPOD_LPf['L'][:,:]    # modal energy E(f, M)
P = SPOD_LPf['P'][:,:,:]  # mode shape
f = SPOD_LPf['f'][:]      # frequency
SPOD_LPf.close()

Step 5: Postprocess

Finally, run the following script to visualize the SPOD spectrum:

fig = spod.plot_spectrum(f,L,hl_idx=5)

Expected results:

For more postprocess tutorials including plotting mode shapes and reconstructed flow fields, please refer to the scripts with detailed comments in tutorials.

Memory Usage

SPOD is a memory-demanding algorithm. Before running it on your own case, please check if the memory requirement has been met. The figure below helps estimate the memory usage of new cases. All data are provided in the table and are obtained by running spod.spod using default parameters.

Nt: number of snapshots; Nq: number of data per snapshot

For fluid mechanics applications, the problem size can be reduced by selecting data every few grid points and time steps. This approach degrades the resolution in small scales but preserves that in the large scales. It is the large scales that are of interest to SPOD.

A more memory-efficient SPOD algorithm named streaming SPOD [2] will be implemented in this package in later versions.

List of Files

.
|-- docs
|   |-- figs
|   |-- tabs
|-- tutorials
|   |-- bstep_data
|   |   |-- singlevar_results
|   |   |-- multivar_results
|   |   |-- bstepDDES.h5
|   |-- comp_data
|   |   |-- singlevar_results
|   |   |-- compDDES.h5
|   |-- cooling_data
|   |   |-- multivar_results
|   |   |-- coolingDDES.h5
|   |-- jet_data
|   |   |-- singlevar_results
|   |   |-- jetLES.h5
|   |-- 00_jet_single_var.py
|   |-- 01_bstep_single_var.py
|   |-- 02_bstep_multi_var.py
|   |-- 03_comp_single_var.py
|   |-- 04_cooling_multi_var.py
|-- LICENSE
|-- requirements.txt
|-- spod.py

• spod.py: main script of spod_python
• requirements.txt: a list of prerequisite Python libraries
• LICENSE: license file
• tutorials
  • bstep_data
    • singlevar_results: postprocess results of the single variable case
    • multivar_results: postprocess results of the multiple variable case
    • bstepDDES.h5: flow field and grid data (HDF5 format)
  • comp_data
    • singlevar_results: postprocess results of the single variable case
    • compDDES.h5: pressure and grid data of a compressor rotor blade (HDF5 format)
  • cooling_data
    • multivar_results: postprocess results of the multiple variable case
    • coolingDDES.h5: flow field and grid data (HDF5 format)
  • jet_data
    • singlevar_results: postprocess results of the single variable case
    • jetLES.h5: flow field and grid data (HDF5 format)
  • 00_jet_single_var.py: tutorial script for single variable SPOD of the jet case
  • 01_bstep_single_var.py: tutorial script for single variable SPOD of the backward-facing step case
  • 02_bstep_multi_var.py: tutorial script for multiple variable SPOD of the backward-facing step case
  • 03_comp_single_var.py: tutorial script for single variable SPOD of the compressor rotor blade case
  • 04_cooling_multi_var.py: tutorial script for multiple variable SPOD of the film cooling case
• docs
  • figs: figures appeared in the markdown files
  • tabs: tables of spod_python performance data

References

[1] Towne, A., Schmidt, O. T., & Colonius, T. (2018). Spectral proper orthogonal decomposition and its relationship to dynamic mode decomposition and resolvent analysis. Journal of Fluid Mechanics, 847, 821-867. [DOI]

[2] Schmidt, O. T., & Towne, A. (2019). An efficient streaming algorithm for spectral proper orthogonal decomposition. Computer Physics Communications, 237, 98-109. [DOI]

[3] Nekkanti, A., & Schmidt, O. (2021). Frequency–time analysis, low-rank reconstruction and denoising of turbulent flows using SPOD. Journal of Fluid Mechanics, 926, A26. [DOI]

[4] Schmidt, O. T., & Colonius, T. (2020). Guide to spectral proper orthogonal decomposition. AIAA Journal, 58(3), 1023-1033. [DOI]

[5] He, X., Fang, Z., Rigas, G. & Vahdati, M., (2021). Spectral proper orthogonal decomposition of compressor tip leakage flow. Physics of Fluids, 33(10), 105105. [DOI][preprint]