CaNS-EIGEN is a code for massively-parallel numerical simulations of fluid flows. It aims at solving any fluid flow of an incompressible, Newtonian fluid that can benefit from a direct solver for the second-order finite-difference Poisson equation in a 3D Cartesian grid that may be non-uniform along all directions.

This solver extends the FFT-based Poisson solver in CaNS with a tensor-based eigendecomposition method. For non-uniform grids, the one-dimensional operators are diagonalized numerically and the FFTs are replaced by dense eigenprojections, which can be expressed as a single GEMM (General Matrix-Matrix Multiplication) per transformed direction; on uniform grids, this reduces to the classical method of eigenfunction expansions. Since both formulations share the same tensor-product structure, FFT- and GEMM-based transforms can be mixed along the first two domain directions. As in CaNS, in the third domain direction, the solver solves a tridiagonal system using TDMA.

CaNS also allows for choosing an implicit temporal discretization of diffusion terms. Diffusion may be treated explicitly in all directions, implicitly only along Z, implicitly along Y and Z, or implicitly along all directions. For the implicit modes, this results in solving a 1D, 2D, or 3D Helmholtz equation per velocity component. The same FFT/GEMM transform options described above for the pressure Poisson equation are used by the Helmholtz solvers in the implicit directions.

References

P. Costa, D. Palancha, J. Romero, R. Verzicco, and M. Fatica. A GEMM-based direct solver for finite-difference Poisson problems in non-uniform grids. (2026). [arXiv preprint]

P. Costa. A FFT-based finite-difference solver for massively-parallel direct numerical simulations of turbulent flows. Computers & Mathematics with Applications 76: 1853--1862 (2018). doi:10.1016/j.camwa.2018.07.034 [arXiv preprint]

[04/05/2026]: We have implemented support for YZ-implicit momentum diffusion, complementing the existing explicit, Z-implicit, and fully implicit diffusion modes.

[25/04/2026]: CaNS-EIGEN is released!

See the Release Notes for more details.

[26/03/2026]: We have extended the I/O capabilities of CaNS for checkpointing and data visualization of structured subset outputs, and added support for two new backends that enable data compression: HDF5 and ADIOS2. See the updated docs/INFO_INPUT.md and docs/INFO_VISU.md for more details.

[06/08/2025]: An OpenMP GPU backend is available in the openmp-port branch. See that branch for the corresponding implementation updates and GPU-backend compilation details.

[06/08/2025]: Support for running on AMD-based supercomputers and a new GPU communication backend are available! CaNS has been ported to other platforms using HIP, thanks to the recently developed diezDecomp library. See the updated docs/INFO_COMPILING.md for more details.

Some features are:

• Hybrid MPI/OpenMP parallelization
• FFTW guru interface / cuFFT used for computing multi-dimensional vectors of 1D transforms
• The right type of transformation (Fourier, cosine, sine, etc.) is automatically determined from the input file
• Explicit, Z-implicit, YZ-implicit, and fully implicit temporal integration options for the momentum diffusion terms
• cuDecomp pencil decomposition library for hardware-adaptive distributed memory calculations on many GPUs
• diezDecomp pencil decomposition library for distributed memory calculations on various GPU/CPU hardware platforms
• 2DECOMP&FFT library used for performing global data transpositions on CPUs and some of the data I/O
• GPU acceleration using OpenACC directives (and option to switch to OpenMP target offload in the openmp-port branch)
• A different canonical flow can be simulated just by changing the input files

Some examples of flows that this code can solve are:

• periodic or developing channel
• periodic or developing square duct
• tri-periodic domain
• lid-driven cavity

This project aimed first at being a modern alternative to the well-known FISHPACK routines (Paul Swarztrauber & Roland Sweet, NCAR) for solving a three-dimensional Helmholtz equation. After noticing some works simulating canonical flows with iterative solvers -- when faster direct solvers could have been used instead -- it seemed natural to create a versatile tool and make it available. This code can be used as a first base code for which solvers for more complex flows can be developed (e.g. extensions with fictitious domain methods).

The fluid flow is solved with a second-order finite-difference pressure-correction scheme, discretized in a MAC grid arrangement. Time is advanced with a three-step low-storage Runge-Kutta scheme. Optionally, for increased stability at low Reynolds numbers, at the price of higher computational demand, the momentum diffusion term can be treated implicitly along Z, along YZ, or along all directions. See the reference above for details.

Since CaNS loads the external pencil decomposition libraries as Git Submodules, the repository should be cloned as follows:

git clone --recursive https://github.com/CaNS-World/CaNS

so the libraries are downloaded too. Alternatively, in case the repository has already been cloned without the Submodules (i.e., folders cuDecomp and 2decomp-fft under dependencies/ are empty), the following command can be used to update them:

git submodule update --init --recursive

The prerequisites for compiling CaNS are the following:

• MPI
• FFTW3/cuFFT library for CPU/GPU runs
• The nvfortran compiler (for GPU runs)
• CMake for compiling the cuDecomp library (for GPU runs)
• NCCL and NVSHMEM (optional, may be exploited by the cuDecomp library)
• OpenMP (optional)
• HDF5 and ADIOS2 for checkpointing (optional)

For most systems, CaNS can be compiled from the root directory with the following commands make libs && make, which will compile the 2DECOMP&FFT/cuDecomp libraries, and CaNS.

The Makefile in the root directory is used to compile the code, and is expected to work out-of-the-box for most systems. The build.conf file in the root directory can be used to choose the Fortran compiler (MPI wrapper), and a few pre-defined profiles depending on the nature of the run (e.g., production vs debugging), and pre-processing options; see INFO_COMPILING.md for more details. The default build.conf file is created from configs/defaults/build-default.conf at the first compilation. Concerning the pre-processing options, the following are available:

• SINGLE_PRECISION : calculation will be carried out in single precision (the default precision is double)
• GPU : enable GPU-accelerated runs

The input file input.nml sets the physical and computational parameters. In the examples/ folder are examples of input files for several canonical flows. See INFO_INPUT.md for a detailed description of the input file.

Files out1d.h90, out2d.h90 and out3d.h90 in src/ set which data are written in 1-, 2- and 3-dimensional output files, respectively. The code should be recompiled after editing out?d.h90 files.

Run the executable with mpirun using a number of tasks that complies with what has been set in the input file input.nml. Data will be written by default to a folder named data/, which must be located where the executable is run (by default, the run/ folder).

See INFO_VISU.md.

We appreciate any contributions and feedback that can improve CaNS. If you wish to contribute to the tool, please get in touch with the maintainers or open an Issue in the repository / a thread in Discussions. Pull Requests are welcome, but please propose/discuss the changes in a linked Issue first.

Please read the ACKNOWLEDGEMENTS, LICENSE files.