nekstab / nekstab

An open source toolbox based on Krylov methods for highly parallel global linear stability analysis of incompressible flow problems for Nek5000.

nekStab is a toolbox for performing bifurcation analysis using the spectral element CFD solver Nek5000. It is released under the BSD-3-Clause license.

The project started in 2010 with the PhD thesis of Jean-Christophe Loiseau and builds on the work of former PhD students of our group such as Frédéric Alizard, Stefania Cherubini, Alessandro Bucci, Mirko Farano, Francesco Picella and Ricardo Frantz. Ricardo is the one who brought all the previous contributions together in a single toolbox.

It is actively maintained mainly by Ricardo Frantz and Jean-Christophe Loiseau. Both of them work at DynFluid, a fluid dynamics laboratory part of Arts et Métiers Institute of Technology.

News

• February 2022: The first official version of 'nekStab' is available online! It is released under the BSD-3-Clause license. Do not hesitate to contact us, have a look at the documentation or read the release notes if you want to know more.

First Steps

nekStab is a toolbox written in 'Fortran 90' for the spectral element solver Nek500. If you already have C and Fortran compilers, you can install both on Ubuntu/Debian distributions with the following commands.

Prerequisites

Linux

sudo apt-get -y install libmpich-dev libopenblas-dev cmake m4 htop

MacOS

brew install mpich gfortran wget git cmake htop

Cloning the repository and Nek5000

git clone --depth=50 https://github.com/nekStab/nekStab.git
cd nekStab
./Nek5000clone.sh

Run vim $HOME/.bashrc and add the following :

export NEKSTAB_SOURCE_ROOT=$HOME/nekStab
export NEK_SOURCE_ROOT=$NEKSTAB_SOURCE_ROOT/Nek5000
export PATH=$NEK_SOURCE_ROOT/bin:$PATH
export PATH=$NEKSTAB_SOURCE_ROOT/bin:$PATH

Computing the fixed point for the cylinder flow example using the Newton-Krylov solver on 4 processors is as simple as

Go to a given example folder and compile the code:

cd ~/nekStab/examples/cylinder/baseflow/newton  
./cmpile.sh all

alternatively you can compile with makeneks followed by the case name:

makeneks 1cyl

If 'Compilation successful!' then you can run the code:

nekbmpi 1cyl 4

to follow the code output in the logfile try:

tail -f logfile

To stop the code just:

killall nek5000

For more information on compiling the code on Mac OS or optional packages, see the Documentation.

Development

nekStab is mainly developed by Jean-Christophe Loiseau and Ricardo Frantz. However, we welcome contributors of all levels of experience. If you are planning a larger contribution, we encourage you to discuss the concept here on GitHub and to interact with us regularly to ensure your efforts are targeted.

Help and support

Although nekStab relies on Nek5000, none of us are active developers of Nek5000. If you have questions about Nek5000, please contact the dedicated GitHub repo and documentation

Communication

• Mail : Jean-Christophe Loiseau or Ricardo Frantz
• Website : https://nekstab.github.io/

Citation

When using nekStab, please consider citing one of the following papers :

• Frantz et al. (2023) presents the complete theoretical framework underlying nekStab.

@article{frantz2023krylov,
    author = {Frantz, R. A. S. and Loiseau, J.-Ch. and Robinet, J.-Ch.},
    title = "{Krylov Methods for Large-Scale Dynamical Systems: Application in Fluid Dynamics}",
    journal = {Applied Mechanics Reviews},
    volume = {75},
    number = {3},
    year = {2023},
    month = {03},
    issn = {0003-6900},
    doi = {10.1115/1.4056808},
    url = {https://doi.org/10.1115/1.4056808},
    note = {030802},
    eprint = {https://asmedigitalcollection.asme.org/appliedmechanicsreviews/article-pdf/75/3/030802/6996354/amr\_075\_03\_030802.pdf},
}

• Loiseau et al. (2019) presents most of the theoretical framework underlying nekStab.

@incollection{chapter:loiseau:2019,
  title={Time-stepping and Krylov methods for large-scale instability problems},
  author={Loiseau, J.-Ch. and Bucci, M. A. and Cherubini, S. and Robinet, J.-Ch.},
  booktitle={Computational Modelling of Bifurcations and Instabilities in Fluid Dynamics},
  pages={33--73},
  year={2019},
  publisher={Springer}
}

• Loiseau et al. (J. Fluid Mech., 2014) describes the first implementation of the Arnoldi solver in Nek5000.

@article{jfm:loiseau:2014,
    title={Investigation of the roughness-induced transition: global stability analyses and direct numerical simulations},
    author={Loiseau, J.-Ch. and Robinet, J.-Ch. and Cherubini, S. and Leriche, E.},
    journal={J. Fluid Mech.},
    volume={760},
    pages={175--211},
    year={2014},
}

nekstab's Issues

Journal of Open Source Software

We need to talk about this with JC Senior, but I think writing a paper for the Journal of Open Source Software might be a good idea to publicize the repo. We do need to take a few actions before that though.
This includes:

• Clean up the code
• Maybe a bit of restructuring?
• Properly documenting the whole code.
• Update/improve the documentation website.
• Make sure the code is properly licensed.

Once all of this is done, I'll start writing the paper. A simple markdown file is sufficient apparently. I'll look into it shortly.
What do you think?

Newton-Krylov solver for UPO

Linear optimal control module

Need to implement tools from optimal control theory. Long time project.

Resolvent analysis

Need to import what Alessandro did during his PhD. Performance-wise, not sure whether it should be done using the optimization procedure or the direct-adjoint eigensolver (with forcing).

Validation folder

Add a folder wherein we provide a number of validations of the standard tools with appropriate references.
This needs to include at least :

• Base flow computations (e.g. cylinder flow, open cavity, backward facing step)
• Direct and adjoint eigenmodes and eigenspectra
• Transient growth curves and corresponding optimal modes

Optimisation module

Implementation of the work by Mirko Farano and Alessandro Bucci.

Schur step restart

Document and standardize examples

Need to standardize the examples folder as well as adding a README.md for each documenting precisely :

• which case it is (e.g. domain size, Re, etc)
• adding some references for comparison (kind of goes along the same line as the validation folder but less deep)
• select the most representative examples rather than having dozens of them.

Optimal Time-Dependent modes (OTD)

• Babaee & Sapsis, 2016
• Blanchard & Spasis, 2019

Pseudo-arclength continuation for bifurcation diagram computation

Lancsoz solver for optimal transient growth

Implement Lancsoz solver as a replacement for Arnoldi for transient growth computation.
Need to simultaneously outpost the optimal initial perturbation and corresponding response.

Lyapunov exponents computation

Documentation is down

Despite what the badge says, the documentation is currently down.
We need to put it back online and probably rewrite part of it for improvement.

VANS implementation for square cylinder

Document critical functions

Need to add some documentation to a number of critical functions including :

• Inputs and outputs
• Pre-requirements
• References to the corresponding algorithms/analyses

Could the open code sove flow stability of the flow past a 3-D bluff body?

Could the open code sove the flow stability of a flow past a 3-D bluff body?

add topics

I suggest adding the topics cfd, nek5000 in the About section

Add the option to use catalyst with KTH framework

https://github.com/KTH-Nek5000/InSituPackage

Tutorial section

Broken links on tools /nekamgsetup

Finite-differences approximation of the Jacobian-vector product

Second and fourth-order finite-difference approximations of the Jacobian-vector product have been implemented in the dedicated branch. So far, it has been validated for the two-dimensional cylinder flow, both for the Newton-Krylov solver and the stability analysis. It doesn't work on the thermosyphon though. The Krylov vectors generated do not seem to make any sense. I am not sure where it comes from.

Block eigensolver / subspace iteration for transient growth

One major result in transient is to compute the optimal gain as a function of T. For a new value of T close to the previous one (kind of like continuation), the set of optimal perturbations should be quite similar to the one computed previously. If we can leverage all of the previously computed optimal perturbations using a block eigensolver/subspace iteration technique, that could massively reduce the overall number of iterations needed to compute the whole G(t) curve.

Fix GitHub Actions scripts

Script to recompile all cases and run 100 steps in DNS after each commit

POD/DMD Post-processing

Need to implement the POD/DMD post-processing tools.
Although I do have a python script to do it, it doesn't scale well for very large problems as it basically on plain numpy/scipy.

Create a case.parstab to get rid of uparam

Matrix-vector product for the transient growth

Need to re-implement the appropriate matvec interface for direct-adjoint transient growth.

Sensitivity to steady forcing

WIP with Gabriele

Improved GMRES solver with recycling to speed-up the Newton solver.

Here is a nice paper showing how one can recycle Krylov subspaces from one Newton step to the other to reduce the overall number of matrix-vector products. Although the standard Newton-GMRES solver in the time-stepper approach is already reasonably fast, this could further reduce the time-to-solution, most notably for very large-scale problems.