search

uofs-simlab / Summa-Actors

GNU General Public License v3.0
0 stars 1 forks source link

readme

SUMMA-Actors: Structure for Unifying Multiple Modeling Alternatives with Actors

SUMMA-Actors is a powerful extension of the existing SUMMA hydrological modeling framework, designed to leverage the Actor Model for enhanced scalability and fault-tolerance. SUMMA-Actors is built using the C++ Actor Framework and the key highlights include:

Resources

Bug Reports, Feature Requests, and Questions

For bug reports, feature requests, and questions, please open an issue on the GitHub at https://github.com/uofs-simlab/Summa-Actors/issues

Quick Start

SUMMA-Actors seamlessly integrates with two versions of the SUMMA hydrological modeling framework:

The build process for both verisions is largely the same, below are the steps common to both versions. For version specific instructions, please refer to the relevant sections below.

Directory Structure

The directory structure for SUMMA-Actors is as follows:

Summa-Actors/
├── bin/
├── build/
|   ├── build_scripts/
│   |   ├── build.sh
|   ├── cmake/
│   ├── includes/
│   ├── source/
│   ├── summa/ (Versions Specific - 3.x.x or 4.x.x)
│   └── v4_build_scripts/
├── containers/
│   ├── apptainer.def
│   └── Dockerfile
├── .gitignore
└── README.md

Dependencies

Install most dependencies using your preferred package manager. If you’re using Ubuntu, check our Dockerfile for specific installation examples.

Version 4.x.x Build Instructions

1) git clone https://github.com/uofs-simlab/Summa-Actors.git 2) cd Summa-Actors/build/ 3) git clone -b develop https://github.com/ashleymedin/summa.git 4) cd build_scripts/ 5) Modify the build.sh script to match your system.

Version 3.x.x Build Instructions

1) git clone https://github.com/uofs-simlab/Summa-Actors.git 2) cd Summa-Actors/build 3) git clone https://github.com/CH-Earth/summa.git 4) cd build_scripts/ 5) Modify the build.sh script to match your system. 6) ./build.sh

Running SUMMA-Actors

Running SUMMA-Actors is similar to running the original version of SUMMA. Input and configuration files remain identical alowing exising projects and fileManager.txt files to be used seamlessly with SUMMA-Actors. Please refer to the SUMMA documentation regarding input files and simulation configuration. The only difference, if desired, is the option to use a config.json file to fine tune how SUMMA-Actors will perform. Please refer to the relevant section for more information on the config.json file and the more advanced features of SUMMA-Actors.

Below is the help message for SUMMA-Actors, which provides a brief overview of both the avialable options and the currently unimplemented options.

Usage: summa_actors -m master_file [-g startGRU countGRU] [-c config_file] [-b backup_server] [-s server_mode]
  Available options:
    -m, --master:         Define path/name of master file (can be specified in config)
    -g, --gru:            Run a subset of countGRU GRUs starting from index startGRU 
    -c, --config:         Path name of the Summa-Actors config file (optional but recommended)
    -s, --suffix          Add fileSuffix to the output files
        --gen-config:     Generate a config file
    -b, --backup-server:  Start backup server, requires a server and config_file
        --server-mode:    Enable server mode
    -h, --help:           Print this help message
  Unimplemented Options:
    -n, --newFile         Define frequency [noNewFiles,newFileEveryOct1] of new output files
    -h, --hru             Run a single HRU with index of iHRU
    -r, --restart         Define frequency [y,m,d,e,never] to write restart files
    -p, --progress        Define frequency [m,d,h,never] to print progress
    -v, --version         Display version information of the current build

Example Usage

./summa_actors -g 1 10 -m /path/to/master_file.txt

Config File and Advanced Features

Config File

The config.json file is a JSON file that is used to configure SUMMA-Actors. It can be generated by running ./summa_actors --gen-config, and allows some fine tunning of the SUMMA-Actors program including operating SUMMA-Actors in additional modes. The details of the config file can be found on our wiki page here.

Example usage of the config.json file is as follows. Note that the config.json file has a field for the file_master.txt file, so the -m flag is not required when using the config.json file.

./summa_actors -g 1 10 -c /path/to/config.json

Advanced Features

SUMMA-Actors has additional feature that are not covered in this README. For more information on these features, please refer to the SUMMA-Actors Advanced Features Wiki Page. Here is a short summary of some of the optional features:

Scientific Use:

Please feel free to contribute to our project by submitting pull requests or opening issues. We only ask that if you use SUMMA-Actors that you kindly cite one of our publications:

@article{klenk2024improving,
  title={Improving resource utilization and fault tolerance in large simulations via actors},
  author={Klenk, Kyle and Spiteri, Raymond J},
  journal={Cluster Computing},
  pages={1--18},
  year={2024},
  publisher={Springer}
}

@inproceedings{klenk2024high,
  title={High-Throughput Scientific Computation with Heterogeneous Clusters: A Kitchen-Sink Approach using the Actor Model},
  author={Klenk, Kyle and Moayeri, Mohammad Mahdi and Spiteri, Raymond J},
  booktitle={Proceedings of the 2024 SIAM Conference on Parallel Processing for Scientific Computing (PP)},
  pages={78--89},
  year={2024},
  organization={SIAM}
}

Credits

The initial implementation of SUMMA is credited to the initial publications below. These publications can be found in Water Resources Research.

We also credit the original creators of the C++ Actor Framework which allowed us to implement the actor model into SUMMA-Actors. Links to their research work can be found below.