Koopman Analysis GUI

Overview

This application provides an intuitive GUI for executing and visualizing data-driven analysis based on the Koopman operator theory using .npz formatted datasets. It supports analysis methods such as EDMD (Extended Dynamic Mode Decomposition), gEDMD and Logarithmic EDMD, allowing for a seamless workflow from adjusting various parameters to visualizing the matrix, spectrum, modes and eigenfunctions.

Index

• Requirements
• Installation
• Usage
  • How to launch the application
  • How to use the application
    • Analysis Result details
    • Matrix Visualization
    • Spectrum Visualization
    • Modes Visualization
    • Eigenfunctions Visualization
    • Other Options
• References
• Open Source Software
• License

Requirements

This software requires the following dependencies:

• Git
• Python 3.11 or higher

Note

Internal analysis and rendering utilize packages such as numpy, scipy, scikit-learn, matplotlib, seaborn, tkinter, and tkmacosx.

Installation

Run the following command in your terminal to install the application:

/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/fumito100111/koopman-analysis-gui/HEAD/install.sh)"

If you have already installed the application, you can update it by running the following command:

kagui update

Usage

How to launch the application

After installation, you can launch the application by running the following command in your terminal:

kagui run

How to use the application

After launching the application, you will see a GUI with various options for selecting the analysis method, adjusting parameters, loading datasets, and visualizing results.

1. Select Analysis Method: Choose the desired analysis method (EDMD, gEDMD, or Logarithmic EDMD) from the radio buttons.

2. Adjust Parameters: Use the sliders and input fields to adjust the parameters for the selected analysis method. If you use the gEDMD or Logarithmic EDMD method, you need to specify the time-step size ($\Delta t$) for the analysis. If you apply penalized regression, you need to select the regularization method and adjust the regularization parameter ($\alpha$).

3. Select Dataset: Click the Select dataset button to choose a .npz file containing the dataset you want to analyze. .npz files should contain the following arrays:

   • X: A 2D array of shape (n_features, n_samples) representing the state snapshots at time $t$.
   • Y: A 2D array of shape (n_features, n_samples) representing the state snapshots at time $t + 1$ or $t + \Delta t$.

4. Select Analysis Modes: Choose the analysis modes you want to visualize by selecting the radio buttons for Matrix, Spectrum, Modes, and Eigenfunctions.

   • Matrix: Visualize the Koopman operator (or generator) matrix.

   • Spectrum: Visualize the eigenvalues of the Koopman operator (or generator). If you use the EDMD method, the eigenvalues are in the discrete-time spectrum. If you use the gEDMD or Logarithmic EDMD method, the eigenvalues are transformed to the continuous-time spectrum.

   • Modes: Visualize the $i$-th Koopman mode.

   • Eigenfunctions: Visualize the $i$-th Koopman eigenfunction.

5. Run Analysis: Click the Run Analysis button to execute the analysis based on the selected method and parameters. The results will be displayed in the left panel of the GUI according to the selected analysis modes. The terminal at the bottom will show the log of the analysis, including the selected method, parameters, test evaluation metrics ($RMSE$, $MAE$, $Relative Error$, $R^2$), and any errors or warnings encountered during the analysis.

Analysis Result details

After running the analysis, the result details will be displayed in the terminal at the bottom of the GUI. The details include the selected method, parameters, test evaluation metrics ($RMSE$, $MAE$, $Relative Error$, $R^2$), and any errors or warnings encountered during the analysis.

Important

If you set the train ratio to 1.0, the test evaluation metrics will not be calculated, and the terminal will show a warning message indicating that the test evaluation metrics are not available.

Matrix Visualization

The matrix visualization displays the Koopman operator (or generator) matrix as a heatmap.

Spectrum Visualization

The spectrum visualization displays the eigenvalues of the Koopman operator (or generator) in the complex plane.

If you use the EDMD method, the eigenvalues are in the discrete-time spectrum, and the unit circle is highlighted to indicate stability.

If you use the gEDMD or Logarithmic EDMD method, the eigenvalues are transformed to the continuous-time spectrum, and the imaginary axis is highlighted to indicate stability.

Modes Visualization

The modes visualization displays the $i$-th Koopman mode as a bar plot.

You can change the selected mode index by using the < or > buttons.

Eigenfunctions Visualization

The eigenfunctions visualization displays the $i$-th Koopman eigenfunction as a contour plot.

You can change the selected eigenfunction index by using the < or > buttons.

Other Options

You do not need to run the analysis again to change the operator options or the visualization modes.

If you want to switch between the left-hand and right-hand operators, you can change the Operator Options in the right panel of the GUI.

If you want to change the analysis modes, you can switch the Analysis Modes in the right panel of the GUI.

References

1. A Data-Driven Approximation of the Koopman Operator: Extending Dynamic Mode Decomposition
2. Data-driven approximation of the Koopman generator: Model reduction, system identification, and control
3. Koopman-Based Lifting Techniques for Nonlinear Systems Identification

Open Source Software

This project utilizes the following open-source software:

• Python
• NumPy
• SciPy
• scikit-learn
• Matplotlib
• Seaborn
• tkmacosx

License

This project is licensed under the MIT License. See the LICENSE file for details.