Overview

The underling library provides simple, scalable means to manipulate MPI-parallel, three dimensional pencil decompositions using FFTW. Pencil decompositions are a natural way to distribute O(n^3) data across O(n^2) processors and are well-suited for memory-intensive, structured spectral turbulence simulations and postprocessing codes. The library is written in C99 and may be used by C89 or C++ applications.

The underling library provides:

In- and out-of-place pencil transposes built using FFTW MPI
In- and out-of-place FFTs built atop the pencil transposes using FFTW
FFTs allowing for up to two non-Fourier directions and one real-to-complex Fourier direction
Documented, usable intermediate data storage allowing computation on partially transposed data
Options for both reducing on-node data movement and contiguously packing results in memory
Interleaving of multiple complex- or real-valued fields if so desired
The ability to concurrently work with multiple pencil decompositions across one or more MPI communicators
On-node multithreading for FFTs and data shuffling inherited from FFTW
An out-of-the-box benchmarking tool for experimenting with the library
Lots of warm fuzzy feelings because of a comprehensive test suite

Installation

See the README for build instructions, dependencies, and configuration details.

API Reference

underling.h: C API for parallel, 3D pencil decompositions
underling.hpp: C++ API for parallel, 3D pencil decompositions
underling_fftw.h: C API for Fast Fourier Transforms atop pencil decompositions
underling_fftw.hpp: C++ API for Fast Fourier Transforms atop pencil decompositions
error.h: C/C++ error handling API

License

Copyright (C) 2010–2013, 2026 Rhys Ulerich underling is free software: you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation, either version 3 of the License, or (at your option) any later version.

underling is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details.