Installation and Configuration

Generic description

Configuration of the VTF software can be envoked by running vtf/configure -C. The additional options --enable-opt={yes/no} and --enable-mpi={yes/no} toggle the building of optimized/debug code and parallel/serial build. A build directory compilervendor-{debug/opt}-{mpi}-{64bit} with all Makefiles for your actual machine will be created. A list of available options is shown with vtf/configure --help.

• Mandatory vtf/configure arguments for all applications involving AMROC:
  • HDF4_DIR
• Optional vtf/configure arguments:
  • VISUAL3_DIR
  • CANTERA_DIR

The specification of HDF4_DIR is mandatory for compilation of AMROC. The specification of VISUAL3_DIR for native AMROC visualization and CANTERA_DIR for reactive simulations with AMROC and WENO-TCD patch solver remains optional. For convenience of off-site users pre-compiled libraries of HDF4r1.2 and Visual3 for a few machines are provided in the repository in vtf/third-party. For instance

./configure -C --enable-opt=no --enable-mpi=no HDF4_DIR=`pwd`/third-party/HDF4.2r1/linux VISUAL3_DIR=`pwd`/third-party/Visual3/linux

would be a valid configuration for AMROC users on an arbitrary linux machine.

A further option to initiate the configuration process is by running vtf/setup. This script is a convenient wrapper for vtf/configure and its most relevant options. vtf/setup contains useful instructions on possible switches, the appropriate specification of necessary configuration variables in order to ensure their automatic recovery, and additional packages. A detailed explanation of the configuration options in vtf/setup is available.

Since HDF4 is available for a large number of machines in more recent versions (only bugfixes nowadays) from the HDF home page, it is highly recommended to download it from there. If you do so, make sure that $HDF4_DIR/include contains the header files hcomp.h, hdf.h, herr.h, hntdefs.h, htags.h, mfgr.h, netcdf.h, hbitio.h, hdf2netcdf.h, hdfi.h, hlimits.h, hproto.h, local_nc.h, mfhdf.h, vg.h and $HDF4_DIR/lib at least libdf.a, libjpeg.a, libmfhdf.a, libz.a.

hdf2v3 based on Visual3 is one possible visualizer for AMROC-HDF4 files. Note however that the provided Visual3 libraries are in 32-bit format only. Further visualizers are supported by converting the HDF4 files into an appropriate format using hdf2file, see AMROC HDF page for supported formats. Visual3 is available only in binary format from the Visual3 home page. If you download Visual3 yourself make sure that $VISUAL3_DIR/include/wsdepend.h exists and $VISUAL3_DIR/lib contains at least libVisual3.a. Before using hdf2v3 see the Installation notes on Visual3. In order to compile hdf2v3 your system's installation need to support X11 and OpenGL development.

For the WENO-TCD patch solver under amroc/weno you can also optionally add the directory vtf/third-party/cantera, which can be installed and compiled on your machine by executing the script vtf/third-party/cantera/install. The target directory of the cantera installation has to be passed to this script as an argument. After running for instance vtf/third-party/cantera/install $HOME/cantera use the additional argument CANTERA_DIR=$HOME/cantera for configure. Make sure to build Cantera and the VTF with the same compilers! You might have to set the shell variables $CC, $CXX, $F77, $F90 eventually before running vtf/third-party/cantera/install.

Short tips and tricks for recent 64bit Ubuntu systems (e.g., 18.04)

Install the following packages:

sudo apt-get install make bison flex libfl-dev patch zlib1g-dev libjpeg62 libjpeg62-dev libxi-dev gfortran g++ gnuplot paraview autoconf mpi-default-bin mpi-default-dev libhdf4-0 libhdf4-dev

Use the pre-compiled system version of HDF4:

• mkdir $HOME/hdf4
• ln -s /usr/include/hdf $HOME/hdf4/include
• ln -s /usr/lib $HOME/hdf4/lib

Then run the configuration command using the system-provided HDF4 library, e.g.,

./configure -C --enable-opt=yes --enable-mpi=yes HDF4_DIR=$HOME/hdf4

Short tips and tricks for recent 64bit Fedora systems (e.g., 28)

Install the following packages:

sudo dnf install autoconf automake binutils gawk gcc g++ gfortran glibc-devel gnuplot make python python-devel byacc flex openmpi openmpi-devel openmpi-libs libjpeg-turbo libjpeg-turbo-devel zlib zlib-devel hdf hdf-devel

Use the pre-compiled system version of HDF4:

• mkdir $HOME/hdf4
• ln -s /usr/include/hdf $HOME/hdf4/include
• ln -s /usr/lib64/hdf $HOME/hdf4/lib

The precompiled version on Fedora is dependent on libtirpc.so. To ensure that it is linked together with HDF4, change the last line in vtf/amroc/amroc.in to

HDF4_LIBS="-L$HDF4_DIR/lib -lmfhdf -ldf \$(SZLIB) -lz -ljpeg -ltirpc"

After this modification force a re-generation of the Makefiles, by running autoreconf -fv in the vtf-directory.

Then run the configuration command using the system-provided HDF4 library, e.g.,

./configure -C --enable-opt=yes --enable-mpi=yes HDF4_DIR=$HOME/hdf4

Adjusting the shell search path

The build environment for the VTF allows a user to keep multiple toplevel build directories (i.e. gnu-debug-mpi, gnu-opt-mpi, intel-debug, ...) on one machine. Scripts are provided to adjust the environment of the current shell to run executables transparent for the user from different locations. These scripts are vtf/ac/paths.sh and vtf/ac/paths.csh. They can be run from an arbitrary directory in the following way:

• bash: source paths.sh [path to toplevel build directory] or . paths.sh [path to toplevel build-directory]
• sh, ksh: . paths.sh [path to toplevel build-directory]
• csh, tcsh: source paths.csh [path to toplevel build-directory]
  • Execution of paths.csh requires the previous inclusion of the script directory ac into the PATH with setenv PATH {path to toplevel src directory}/ac:$PATH .

Testing the installation and the build

As a test for a correct setup the AMROC test scripts vtf/amroc/testrun.sh, vtf/amroc/testrun_gfm.sh, vtf/fsi/testrun.sh can be used:

• Extend your shell enviroment for your current build as explained above.
• cd into the toplevel build directory and execute
• ../amroc/testrun.sh -m make -s -r 4 for a parallel test and ../amroc/testrun.sh -m make -s -r 0 in serial. Note that all reference data have been produced for 4 processors. Minor differences, also in output indexing, can occur for different processor count.
• The test is successful if, after some apparent compute time, Gnuplot windows with evolving graphs pop up.

Supported Machines

The VTF is written in ANSI-compliant C++, C, Fortran 77, and Fortran 90 code and should compile on all modern Unix systems. The building of parallel programs requires MPI.

-- RalfDeiterding - 20 May 2019