suzerain Build Procedure
                    ===============================

0. Purpose
----------

Suzerain is a framework for performing direct numerical simulation (DNS) of
the Navier-Stokes equations using spectral numerics.  It is well-suited to
memory-intensive, structured spectral turbulence simulations and the
postprocessing of their results across MPI-parallel, distributed-memory
machines.  This framework and its included applications are written in C++
(C++17), C (C99), and Fortran.


1. Introduction
---------------

This document describes how to build Suzerain from source code on Unix-like
systems.  For information on the numerics, please see the model documents
under writeups/ that are built when a LaTeX installation is available.


2. Dependencies
---------------

The code depends upon the following libraries:

    1) Apache Log4cxx from http://logging.apache.org/log4cxx/
    2) Boost from http://www.boost.org/
    3) Eigen from http://eigen.tuxfamily.org/
    4) ESIO from https://github.com/RhysU/ESIO
    5) FFTW from http://www.fftw.org/ compiled with MPI support
    6) GNU Scientific Library (GSL) 2.8 or later from
       http://www.gnu.org/software/gsl/

The following optional dependencies are recommended for full functionality:

    1) Antioch from https://github.com/libantioch/antioch
    2) GRVY from https://github.com/hpcsci/grvy
    3) SymPy from http://sympy.org
    4) underling from https://github.com/RhysU/underling

The post-processing and pre-processing utilities under postproc/ and preproc/
additionally use the following tools:

    1) GNU Octave from https://octave.org/
    2) gnuplot from http://www.gnuplot.info/
    3) h5py from https://www.h5py.org/
    4) matplotlib from https://matplotlib.org/
    5) NumPy from https://numpy.org/
    6) pandas from https://pandas.pydata.org/
    7) Python 3 from https://www.python.org/
    8) SciPy from https://scipy.org/

The following additional tools are used during development:

    1) LCOV from https://github.com/linux-test-project/lcov for code coverage
       reports (enabled with --enable-coverage)
    2) mpiP from http://mpip.sourceforge.net/ for lightweight, scalable MPI
       profiling (enabled with --with-mpiP)
    3) Perl from https://www.perl.org/ for Fortran dependency tracking in largo/
    4) SageMath from https://www.sagemath.org/ to regenerate the symbolic
       test sources (tests/*.sage)

On Ubuntu 24.10, most required and optional dependencies are available as
system packages.  Install the build toolchain:

    sudo apt install autoconf automake bsdextrautils g++ gfortran hdf5-tools \
        libtool make pkg-config

Install MPI and the required libraries:

    sudo apt install \
        hdf5-helpers hdf5-tools libboost-all-dev libeigen3-dev \
        libfftw3-dev libfftw3-mpi-dev libgsl-dev \
        libhdf5-openmpi-dev liblog4cxx-dev libmkl-dev \
        libopenmpi-dev openmpi-bin

Optionally, install documentation tools:

    sudo apt install doxygen graphviz texlive-full

Optionally, install the post-processing and analysis tools:

    sudo apt install gnuplot octave python3 python3-h5py python3-matplotlib \
        python3-numpy python3-packaging python3-pandas python3-scipy \
        python3-sympy

Optionally, install additional development tools (binutils-dev supplies the
libbfd/libiberty needed to build mpiP, which is not itself packaged):

    sudo apt install binutils-dev lcov perl sagemath

When MKL is installed from Ubuntu packages, configure suzerain like...

    CPPFLAGS="-I/usr/include/mkl" ./configure

...possibly supplying PKG_CONFIG_PATH for any prerequisites installed in
user-space, e.g. ESIO, GRVY, and Underling.


3. Configuration
----------------

If you have no `configure' script in the top level directory, run `bootstrap'
to create one using GNU autoconf and automake.  Using bootstrap will require a
recent version of autoconf, automake, and pkg-config's pkg.m4 macros.

Before compiling suzerain, you need to run the provided `configure' script.
Generally, just `./configure' will work, but you may wish to provide more
parameters.  Run `./configure --help' for details.


4. Compilation
--------------

To compile suzerain after it has been configured, simply type 'make'.

After the compilation one or more ready-to-use executables should reside in the
src directory.  Related documentation will be built in the doc subdirectory.


5. Testing
--------------

Automated tests can be compiled and run using 'make check'.


6. Attribution
--------------

If you find Suzerain useful towards publishing research, please consider citing:

Rhys Ulerich.  Reducing Turbulence- and Transition-Driven Uncertainty in
Aerothermodynamic Heating Predictions for Blunt-Bodied Reentry Vehicles.  PhD
thesis, The University of Texas at Austin, 2014.