Skip to content

Home

Jump to bottom
Brian Kyanjo edited this page Feb 19, 2026 · 73 revisions

The code GeoFlood is a new distributed parallel adaptive computational model for overland flows based on shallow water equations on mapped logically Cartesian adaptive meshes. The model is written in C, C++, CUDA, Fortran and uses the ForestClaw library. The Code has both a CPU and GPU parallelised version, which a user can switch between using a flag in the setrun.py file.

GeoFlood extensions

GeoFlood is linked to ForestClaw which is a parallel library for solving PDEs on dynamic adaptive quadtree or octree meshes. Based on the highly scalable p4est quadtree/octree meshing library, ForestClaw can take advantage of distributed parallelism on desktops, clusters, as well as supercomputers.

Building and Installing GeoFlood

Before proceeding with the instructions below, ensure you have installed all necessary dependencies and the ForestClaw library using the CMake build system. If not, please follow the steps outlined in installing-preliminaries and forestclaw-installation-for-geoflood to install the preliminaries and ForestClaw, respectively.

  • If you are using a high-performance computing (HPC) machine, verify that all required packages listed in installing-preliminaries are properly installed or loaded before you proceed.
  • For those setting up the hybrid CPU/GPU version, ensure the following:
    • In addition to the initial dependencies installations, confirm that the CUDA drivers and toolkit are installed. You can check their installation by running: $ nvidia-smi and $ nvcc --version. If they are not installed, follow the instructions at cuda-preliminaries for detailed setup guidance.
    • For HPC users, make sure the CUDA toolkit is actively loaded during your session.
    • It is recommended to use a CUDA version of at least 11.0.

Once all dependencies are in place, and assuming you've correctly followed the ForestClaw building and installation guidelines, ensure that the FCLAW environment variable points to a super-directory containing your ForestClaw source code and build directories. The following steps will guide you through building and running GeoFlood.

  1. Clone the GeoFlood source code
cd $FCLAW 
git clone https://github.com/KYANJO/GeoFlood.git

  1. Configure the build:

    i). Transfer the provided script into a new file named $FCLAW/config-geoflood.sh. Make sure to verify that FCLAW_PATH correctly points to your forestclaw_build directory:

  #!/usr/bin/env bash
  set -e

  # Resolve script directory
  SCRIPT_DIR="$( cd "$( dirname "${BASH_SOURCE[0]}" )" && pwd )"

  # Default ForestClaw path relative to this script
  FCLAW_PATH_DEFAULT="${SCRIPT_DIR}/forestclaw-build/local"

  # Allow override via environment variable
  FCLAW_PATH="${FCLAW_PATH:-$FCLAW_PATH_DEFAULT}"

  # Convert to absolute path (portable)
  FCLAW_PATH="$(cd "$FCLAW_PATH" && pwd)"

  # Sanity check
  if [[ ! -d "$FCLAW_PATH" ]]; then
    echo "Error: ForestClaw path not found: $FCLAW_PATH"
    exit 1
  fi

  echo "Using ForestClaw install at:"
  echo "  $FCLAW_PATH"
  echo ""

  cmake configure \
    -DP4EST_ROOT="$FCLAW_PATH" \
    -DSC_ROOT="$FCLAW_PATH" \
    -DFORESTCLAW_ROOT="$FCLAW_PATH" \
    -DCMAKE_C_COMPILER=mpicc \
    -DCMAKE_CXX_COMPILER=mpicxx \
    -DCMAKE_C_FLAGS="-O2 -g -Wall -std=c99 -lz" \
    -DCMAKE_CXX_FLAGS="-O2 -g -Wall -std=c++17" \
    -DCMAKE_Fortran_COMPILER=gfortran \
    -DCMAKE_Fortran_FLAGS="-O2 -g -Wall -Wno-unused-dummy-argument -cpp" \
    -DCMAKE_PREFIX_PATH="$FCLAW_PATH" \
    -DCMAKE_INSTALL_PREFIX="$FCLAW_PATH" \
    -Dcpuflood=ON \
    ../GeoFlood

Note: This configuration is designed for CPU-only operation of GeoFlood. To enable the hybrid CPU/GPU version, add the following options to your configuration file just before the line ../GeoFlood:

-DCMAKE_CUDA_FLAGS="-Xptxas -O2" \
-DCMAKE_CUDA_SEPARABLE_COMPILATION=ON \
-Dcpu_cuda=ON \

ii). Make this file executable:

chmod u+x config-geoflood.sh

iii). Create the build directory and configure GeoFlood:

mkdir geoflood-build 
cd geoflood-build
../config-geoflood.sh
  1. Build and install GeoFlood:
make 
make install

The executables will be placed in the $FCLAW/geoflood-build/examples/TO_THE_EXAMPLE directory.

Code Execution and Runs

After building GeoFlood, ensure you can access the executables within the example directories. To facilitate this, set a global environment variable for all versions of the software:

export GFLOOD_BIN=$FCLAW/geoflood-build/example

Alternatively, you can create a symbolic link from the $FCLAW/geoflood-build/example/TO_CPUFLOOD/TO_SPECIFIC_EXAMPLE/SPECIFIC_EXAMPLE_EXECUTABLE directory to $FCLAW/GeoFlood/example/TO_CPUFLOOD/TO_SPECIFIC_EXAMPLE directory. Execute this while located in the $FCLAW/GeoFlood/example/TO_CPUFLOOD/TO_SPECIFIC_EXAMPLE directory:

ln -sf $FCLAW/geoflood-build/example/TO_CPUFLOOD/TO_SPECIFIC_EXAMPLE/SPECIFIC_EXAMPLE_EXECUTABLE

For our demonstration, we'll be using the malpasset example located in the examples/cpuflood directory. Start by navigating to the correct folder:

cd $FCLAW/GeoFlood/examples/cpuflood/malpasset

Follow these steps to prepare the dataset for the malpasset example within the $FCLAW/GeoFlood/examples/cpuflood/malpasset directory:

  • Download the submission_datasets.zip file by clicking here.
  • Unzip the submission_datasets.zip file. Note: The submission_datasets.zip includes various datasets, such as those for the benchmark_test_cases.
  • Find the dataset for the malpasset problem inside submission_datasets/Malpasset/scatch.
  • Copy the entire scatch directory into the malpasset directory.

After setting up the dataset, run the Python script setrun.py to create the necessary input files and the geoflood.ini configuration file for the GeoFlood processes:

python setrun.py

To run the GeoFlood malpasset example in a serial manner, use the command below:

 $GFLOOD_BIN/cpuflood/malpasset/malpasset -F geoflood.ini --user:cuda=0

Alternatively: if you have created a symbolic link for the malpasset executable, use this command instead:

./malpasset -F geoflood.ini

For parallel execution of the malpasset example with 4 cores, use the following command:

mpirun -n 4 $GFLOOD_BIN/cpuflood/malpasset/malpasset -F geoflood.ini

Alternatively: if the executable is symbolically linked, this command can be used:

mpirun -n 4 ./malpasset -F geoflood.ini

These commands initiate the malpasset example utilizing the settings specified in the geoflood.ini file.

Note: GPU-accelerated cases can be found in the $FCLAW/GeoFlood/examples/cpu_cuda directory and can be operated in a similar manner.

Visualization

You can visualize the results using Python scripts located in the scripts directory. To generate visualization files that can be viewed on a web browser or on Google Earth (if the computational domain uses latitude-longitude coordinates), execute the following command:

python make_plots_kml.py

This script will generate numerous figures and save them in the _plots directory, where you can view the results of the simulation directly.

Google Earth Display for Non-Lat-Long Coordinate Systems

For simulations in non-lat-long coordinate systems, a specialized post-processing script called plot_gcp.py has been developed. This script uses ground control points geo-referenced from QGIS for visualization. To run this script, use the command:

python plot_gcp_gdal.py

Additionally, Matlab can be used for visualization, offering more flexibility to adjust and select colormaps tailored to your specific simulation requirements.

Clone this wiki locally