From 45d543e0efd05e7bfae46bb10e5ee080c8279d01 Mon Sep 17 00:00:00 2001 From: Kyle <kyle.c.klenk@gmail.com> Date: Thu, 11 Apr 2024 18:42:39 +0000 Subject: [PATCH] Update instructions for local build --- .gitignore | 1 + README.md | 53 ++++++++++++++++++++++++- build/build_scripts/README.md | 3 ++ build/build_scripts/build_v4_cluster.sh | 15 +++++++ build/build_scripts/build_v4_local.sh | 15 +++++++ utils/containers/Dockerfile | 13 +++--- 6 files changed, 93 insertions(+), 7 deletions(-) create mode 100644 build/build_scripts/README.md create mode 100755 build/build_scripts/build_v4_cluster.sh create mode 100755 build/build_scripts/build_v4_local.sh diff --git a/.gitignore b/.gitignore index 9c3347b..bab41eb 100644 --- a/.gitignore +++ b/.gitignore @@ -28,3 +28,4 @@ build/summa_old bin/config.json bin/summa_sundials build/cmake_build/ +build/build_scripts/cmake_build diff --git a/README.md b/README.md index 3bbb606..2ad6f16 100644 --- a/README.md +++ b/README.md @@ -21,7 +21,7 @@ SUMMA-Actors is set up with the following sub-directories, we will consider the First clone Summa-Actors to your workstation. Then cd into `build/` and clone `summa` into Summa-Actor's build directory as folder summa. -## Compiling SUMMA-Actors +## Compiling SUMMA-Actors -- With SUMMA verswion 3.x.x ### Dependencies SUMMA-Actors has only one additional dependency, the [C++ Actor Framework](https://github.com/actor-framework/actor-framework), specifically the [0.18.6 @@ -43,7 +43,6 @@ Additional dependencies required by both SUMMA and SUMMA actors are: * gfortran * [NetCDF-Fortran](https://github.com/Unidata/netcdf-fortran) * [OpenBLAS](https://github.com/xianyi/OpenBLAS) - * [SUNDIALS V6.6](https://github.com/LLNL/sundials/releases/tag/v6.6.0) (optional) ### Steps To Compile ``` @@ -67,6 +66,35 @@ module load netcdf-fortran/4.5.2 module load caf ``` +## Compiling SUMMA-Actors -- With SUMMA version 4.x.x +The latest version of SUMMA introduced sundials as a dependency for its numerical solver. As a result the steps to compile SUMMA-Actors have changed +slightly. The dependecies above still apply, wiht the addition of sundials. The following steps can be used to install sundials on a Linux system: +```bash +wget https://github.com/LLNL/sundials/releases/download/v7.0.0/sundials-7.0.0.tar.gz +tar -xzf sundials-7.0.0.tar.gz +mkdir sundials && cd sundials +mkdir /usr/local/sundials +mkdir builddir && cd builddir +cmake ../../sundials-7.0.0 -DBUILD_FORTRAN_MODULE_INTERFACE=ON \ + -DCMAKE_Fortran_COMPILER=gfortran \ + -DCMAKE_INSTALL_PREFIX=/usr/local/sundials \ + -DEXAMPLES_INSTALL_PATH=/code/sundials/instdir/examples +make +make install +``` + +### Steps to Compile +```bash +git clone https://git.cs.usask.ca/numerical_simulations_lab/actors/Summa-Actors.git +cd Summa-Actors/build +git clone -b develop https://github.com/KyleKlenk/summa.git +cd Summa-Actors/build/build_scripts +# There are two files here, one for building on a local machine and one for building on the alliance cluster +# If local build ensure that the paths in the script are correct and +# match the paths to the dependencies on your system +./build_v4_local.sh +``` + ## Running SUMMA-Actors SUMMA-Actors can be run in two modes, distributed and non-distributed. The distributed mode used to create ad-hoc clusters. The command line arguments are kept as close to the original SUMMA as possible. However, there are options not yet available in SUMMA-Actors that are in the original SUMMA. Here is a full list of the available and unavailable options: @@ -110,6 +138,27 @@ Clients can simply be added with `./summa_actors -c` NOTE: Each system will need a copy of the forcing data or input data, or the data should be in a singular location like on a cluster system. +### Data-Assimilation Mode +Data-assimilation mode forces all HRUs to run a single timestep before moving on. This is akin to how real world experiments are run where data is collected and then used to +update the model. To run this mode on a single node there are a few options that are needed to be set in the config file: + - `data_assimilation_mode` (true/false) Enables data-assimilation mode + - `batch_size` (int) number of HRU actors a HRU_batch actor will run. (9999 = default) and (1) will not use an intermediate batch actor + +This mode also works in a distributed environment, the user just needs to ensure that the config file contains +the following distributed mode settings: + - `distributed_mode` (true/false) Enables the distributed mode + - `num_nodes` (int) Number of nodes for the simulation + +Using the distributed mode requires the user to declare how many nodes or more specifically, how many client actors will connect to the server. Once all +actors are connected the server will start the simulation. +```bash +# To start the Server +$summa_exe -g 1 $total_hru -c $config_summa -s + +# To start the client +$summa_exe -g 1 $total_hru -c $config_summa --host=$host +``` + ### Config File The config file is a JSON file that is used to configure SUMMA-Actors. It is highly recommended to use a config file as it allows the user to fine tune how SUMMA-Actors will perform. Using `./summa_actors --gen-config` will generate a configuration file that can then be filled in. Below is a list of the available options and their descriptions. diff --git a/build/build_scripts/README.md b/build/build_scripts/README.md new file mode 100644 index 0000000..dd1ee13 --- /dev/null +++ b/build/build_scripts/README.md @@ -0,0 +1,3 @@ +This directory contains some example scripts that can be used for building +Summa-Actors depending on if building in a cluster or on a local machine. + diff --git a/build/build_scripts/build_v4_cluster.sh b/build/build_scripts/build_v4_cluster.sh new file mode 100755 index 0000000..e271db5 --- /dev/null +++ b/build/build_scripts/build_v4_cluster.sh @@ -0,0 +1,15 @@ +#!/bin/bash + +# If most libraries were installed with apt-get, then the following should work +# Otherwise, you may need to adjust the paths +export FC=gfortran # Fortran compiler family +export LINK_DIRS='/usr/local/lib;/usr/lib' # Link directories for cmake +export INCLUDES_DIRS='/usr/local/include;/usr/include' # directories for INCLUDES cmake variable (cmake uses semicolons as separators) +export LIBRARY_LINKS='-llapack;-lgfortran;-lnetcdff;-lnetcdf' # list of library links (cmake uses semicolons as separators) + +# Set the following paths +export SUNDIALS_PATH="/usr/local/sundials" +export ACTOR_FRAMEWORK_PATH="/usr/local" + +cmake -B ./cmake_build -S ../summa/build/. -DCMAKE_BUILD_TYPE=Sundials_Actors_Debug +cmake --build ../cmake_build --target all diff --git a/build/build_scripts/build_v4_local.sh b/build/build_scripts/build_v4_local.sh new file mode 100755 index 0000000..5831b36 --- /dev/null +++ b/build/build_scripts/build_v4_local.sh @@ -0,0 +1,15 @@ +#!/bin/bash + +# If most libraries were installed with apt-get, then the following should work +# Otherwise, you may need to adjust the paths +export FC=gfortran # Fortran compiler family +export LINK_DIRS='/usr/local/lib;/usr/lib' # Link directories for cmake +export INCLUDES_DIRS='/usr/local/include;/usr/include' # directories for INCLUDES cmake variable (cmake uses semicolons as separators) +export LIBRARY_LINKS='-llapack;-lgfortran;-lnetcdff;-lnetcdf' # list of library links (cmake uses semicolons as separators) + +# Set the following paths +export SUNDIALS_PATH="/usr/local/sundials" +export ACTOR_FRAMEWORK_PATH="/usr/local" + +cmake -B ./cmake_build -S ../summa/build/cmake/. -DCMAKE_BUILD_TYPE=Sundials_Actors +cmake --build ./cmake_build --target all diff --git a/utils/containers/Dockerfile b/utils/containers/Dockerfile index b376058..a1d97f6 100644 --- a/utils/containers/Dockerfile +++ b/utils/containers/Dockerfile @@ -1,4 +1,4 @@ -FROM ubuntu:20.04 +FROM ubuntu:22.04 WORKDIR /code @@ -31,21 +31,24 @@ RUN tar -xvf 0.18.6.tar.gz WORKDIR /code/actor-framework-0.18.6 RUN ./configure WORKDIR /code/actor-framework-0.18.6/build -RUN make +RUN make -j 4 RUN make test RUN make install WORKDIR /code # Install Sundials -RUN wget https://github.com/LLNL/sundials/releases/download/v6.3.0/sundials-6.3.0.tar.gz -RUN tar -xzf sundials-6.3.0.tar.gz +RUN wget https://github.com/LLNL/sundials/releases/download/v7.0.0/sundials-7.0.0.tar.gz +RUN tar -xzf sundials-7.0.0.tar.gz RUN mkdir sundials WORKDIR /code/sundials RUN mkdir /usr/local/sundials RUN mkdir builddir WORKDIR /code/sundials/builddir -RUN cmake ../../sundials-6.3.0 -DBUILD_FORTRAN_MODULE_INTERFACE=ON -DCMAKE_Fortran_COMPILER=gfortran -DCMAKE_INSTALL_PREFIX=/usr/local/sundials -DEXAMPLES_INSTALL_PATH=/code/sundials/instdir/examples +RUN cmake ../../sundials-7.0.0 -DBUILD_FORTRAN_MODULE_INTERFACE=ON \ + -DCMAKE_Fortran_COMPILER=gfortran \ + -DCMAKE_INSTALL_PREFIX=/usr/local/sundials \ + -DEXAMPLES_INSTALL_PATH=/code/sundials/instdir/examples RUN make RUN make install -- GitLab