Introduction¶

This section provides a general overview of NaluWindUtils and describes features common to all utilities available within this package.

Installing NaluWindUtils¶

NaluWindUtils is written using C++ and Fortran and depends on several packages for compilation. Every effort is made to keep the list of third party libraries (TPLs) similar to the Nalu dependencies. Therefore, users who have successfully built Nalu on their systems should be able to build NaluWindUtils without any additional software. The main dependencies are listed below:

Operating system — NaluWindUtils has been tested on Linux and Mac OS X operating systems.
C++ compiler — Like Nalu, this software package requires a recent version of the C++ compiler that supports the C++11 standard. The build system has been tested with GNU GCC, LLVM/Clang, and Intel suite of compilers.
Trilinos Project — Particularly the Sierra ToolKit (STK) and Seacas packages for interacting with Exodus-II mesh and solution database formats used by Nalu.
YAML C++ – YAML C++ parsing library to process input files.

Users are strongly encouraged to use the Spack package manager to fetch and install Trilinos along with all its dependencies. Spack greatly simplifies the process of fetching, configuring, and installing packages without the frustrating guesswork. Users unfamiliar with Spack are referred to the installation section in the official Nalu documentation that describes the steps necessary to install Trilinos using Spack. Users unable to use Spack for whatever reason are referred to Nalu manual that details steps necessary to install all the necessary dependencies for Nalu without using Spack.

While not a direct build dependency for NaluWindUtils, the users might want to have Paraview or VisIt installed to visualize the outputs generated by this package.

Compiling from Source¶

If you are on an HPC system that provides Modules Environment, load the necessary compiler modules as well as any other package modules that are necessary for Trilinos.

Clone the latest release of NaluWindUtils from the git repository.

cd ${HOME}/nalu/
git clone https://github.com/NaluCFD/NaluWindUtils.git
cd NaluWindUtils

# Create a build directory
mkdir build
cd build

Run CMake configure. The examples directory provides two sample configuration scripts for spack and non-spack builds. Copy the appropriate script into the build directory and edit as necessary for your particular system. In particular, the users will want to update the paths to the various software libraries that CMake will search for during the configuration process. Please see CMake Configuration Options for information regarding the different options available.

The code snippet below shows the steps with the Spack configuration script, replace the file name doConfigSpack.sh with doconfig.sh for a non-spack environment.
```
# Ensure that `build` is the working directory
cp ../examples/doConfigSpack.sh .
# Edit the script with the correct paths, versions, etc.

# Run CMake configure
./doConfigSpack.sh -DCMAKE_INSTALL_PREFIX=${HOME}/nalu/install/
```

Run make to build and install the executables.

make         # Use -j N if you want to build in parallel
make install # Install the software to a common location

Test installation

bash$ ${HOME}/nalu/install/bin/nalu_preprocess -h
Nalu preprocessor utility. Valid options are:
  -h [ --help ]                         Show this help message
  -i [ --input-file ] arg (=nalu_preprocess.yaml)
                                        Input file with preprocessor options

If you see the help message as shown above, then proceed to General Usage section to learn how to use the compiled executables. If you see errors during either the CMake or the build phase, please capture verbose outputs from both steps and submit an issue on Github.

Note

The WRF to Nalu inflow conversion utility is not built by default. Users must explicitly enable compilation of this utility using the ENABLE_WRFTONALU flag. The default behavior is chose to eliminate the extra depenency on NetCDF-Fortran package required build this utility. The examples/doConfigSpack.sh provides an example of how to build the this utility if desired.
See Building Documentation for instructions on building a local copy of this user manual as well as API documentation generated using Doxygen.
Run make help to see all available targets that CMake understands to quickly build only the executable you are looking for.

Building Documentation¶

Official documentation is available online on ReadTheDocs site. However, users can generate their own copy of the documentation using the RestructuredText files available within the docs directory. NaluWindUtils uses the Sphinx documentation generation package to generate HTML or PDF files from the rst files. Therefore, the documentation building process will require Python and Sphinx packages to be installed on your system.

The easiest way to get Sphinx and all its dependencies is to install the Anaconda Python Distribution for the operating system of your choice. Expert users can use Miniconda to install basic packages and install additional packages like Sphinx manually within a conda environment.

Doc Generation Using CMake¶

Enable documentation genration via CMake by turning on the ENABLE_SPHINX_DOCS flag.
Run make docs to generate the generate the documentation in HTML form.
Run make sphinx-pdf to generate the documentation using latexpdf. Note: requires Latex packages installed in your system.

The resulting documentation will be available in doc/manual/html and doc/manual/latex directories respectively for HTML and PDF builds within the CMake build directory. See also Building API Documentation.

Doc Generation Without CMake¶

Since CMake will require users to have Trilinos installed, an alternate path is provided to bypass CMake and generate documentation using Makefile on Linux/OS X systems and make.bat file on Windows systems provided in the docs/manual directory.

cd docs/manual
# To generate HTML documentation
make html
open build/html/index.html

# To generate PDF documentation
make latexpdf
open build/latex/NaluWindUtils.pdf

# To generate help message
make help

Note

Users can also use pipenv or virtualenv as documented here to manage their python packages without Anaconda.

CMake Configuration Options¶

Users can use the following variables to control the CMake behavior during configuration phase. These variables can be added directly to the configuration script or passed as arguments to the script via command line as shown in the previous section.

CMAKE_INSTALL_PREFIX¶: The directory where the compiled executables and libraries as well as headers are installed. For example, passing -DCMAKE_INSTALL_PREFIX=${HOME}/software will install the executables in ${HOME}/software/bin when the user executes the make install command.

CMAKE_BUILD_TYPE¶

Controls the optimization levels for compilation. This variable can take the following values:

Value

Typical flags

RELEASE

-O2 -DNDEBUG

DEBUG

-g

RelWithDebInfo

-O2 -g

Example: -DCMAKE_BUILD_TYPE:STRING=RELEASE

Trilinos_DIR¶: Absolute path to the directory where Trilinos is installed.

YAML_ROOT¶: Absolute path to the directory where the YAML C++ library is installed.

ENABLE_WRFTONALU¶: A boolean flag indicating whether the WRF to Nalu conversion utility is to be built along with the C++ utilities. By default, this utility is not built as it requires the NetCDF-Fortran library support that is not part of the standard Nalu build dependency. Users wishing to enable this library must make sure that the NetCDF-Fortran library has been installed and configure the NETCDF_F77_ROOT and NETCDF_DIR appropriately.

NETCDF_F77_ROOT¶: Absolute path to the location of the NETCDF Fortran 77 library.

NETCDF_DIR¶: Absolute path to the location of the NETCDF C library.

ENABLE_SPHINX_DOCS¶: Boolean flag to enable building Sphinx-based documentation via CMake. Default: OFF.

ENABLE_DOXYGEN_DOCS¶: Boolean flag to enable extract source code documentation using Doxygen. Default: OFF.

ENABLE_SPHINX_API_DOCS¶: Enable embedding API documentation generated from Doxygen within user and developer manuals. Default: OFF.

Further fine-grained control of the build environment can be achieved by using standard CMake flags, please see CMake documentation for details regarding these variables.

CMAKE_VERBOSE_MAKEFILE¶

A boolean flag indicating whether the build process should output verbose commands when compiling the files. By default, this flag is OFF and make only shows the file being processed. Turn this flag ON if you want to see the exact command issued when compiling the source code. Alternately, users can also invoke this flag during the make invocation as shown below:

bash$ make VERBOSE=1

CMAKE_CXX_COMPILER¶: Set the C++ compiler used for compiling the code

CMAKE_C_COMPILER¶: Set the C compiler used for compiling the code

CMAKE_Fortran_COMPILER¶: Set the Fortran compiler used for compiling the code

CMAKE_CXX_FLAGS¶: Additional flags to be passed to the C++ compiler during compilation. For example, to enable OpenMP support during compilation pass -DCMAKE_CXX_FLAGS=" -fopenmp" when using the GNU GCC compiler.

CMAKE_C_FLAGS¶: Additional flags to be passed to the C compiler during compilation.

CMAKE_Fortran_FLAGS¶: Additional flags to be passed to the Fortran compiler during compilation.

General Usage¶

Most utilities require a YAML input file containing all the information necessary to run the utility. The executables have been configured to look for a default input file name within the run directory, this default filename can be overridden by providing a custom filename using the -i option flag. Users can use the -h or the --help flag with any executable to look at various command line options available as well as the name of the default input file as shown in the following example:

bash$ src/preprocessing/nalu_preprocess -h
Nalu preprocessor utility. Valid options are:
  -h [ --help ]                         Show this help message
  -i [ --input-file ] arg (=nalu_preprocess.yaml)
                                        Input file with preprocessor options

The output above shows the default input file name as nalu_preprocess.yaml for the nalu_preprocess utility.

Note

It is assumed that the bin directory where the utilities were installed are accessible via the user’s PATH variable. Please refer to Installing NaluWindUtils for more details.