Configuration Files

Floodwater uses a series of YAML configuration files to define how the system will operate. These files are designed to be re-used so that only minimal changes are required to reuse files for different suites.

The required configuration files are:

• Suite Configuration File - This defines the basic operation of the suite, i.e. the name of the suite, which options will be turned on and off, the locations of other files, and the model geometries to be used.

• Credentials File - This file defines the credentials used to access parts of the system which are.

• System Configuration File - This file defines the information that is specific to a particular system. This includes the location of any executables that are necessary as well as the type of queueing system.

There are some configuration files which are optional:

• APSViz Configuration File - This file optionally defines how to interact with the APSViz system

• FloodID Configuration File - This file optionally defines how to interact with the FloodID system

All YAML configuration files are validated against a schema, which will throw errors if it is not adhered to.

Additionally, there is a yaml configuration file that is specific to each model geometry that is used within the system. This file is used to define specific model settings used within each specific model, and can range from the physics implementations to the locations of boundary conditions which should be used.

Suite Configuration File

The suite configuration file defines the basic operation of the suite. It is a YAML file with the following structure. Note that some parameters are optional.

prefix: <string>
directory: <string>
system_config: <string>
credential_file: <string>
project_code: <string> (optional)
job_comment: <string> (optional)
start: <datetime>
compute:
    adcirc_compute_cores: <int>
    adcirc_writer_cores: <int> (optional)
    adcirc_memory: <string>
    processing_cores: <int>
    processing_memory: <string>
    hours_per_padcirc_day: <float>
    hours_per_padcswan_day: <float>
    hecras_compute_cores: <int> (optional)
    hecras_memory: <string> (optional)
    hours_per_hecras_day: <float> (optional)
    xbeach1d_compute_cores: <int> (optional)
    xbeach1d_memory: <string> (optional)
    hours_per_xbeach1d_day: <float> (optional)
    max_hours_per_xbeach1d_transect: <float> (optional)
simulation:
    water_level: <float>
    spinup_duration: <float> (optional, default: 18.0)
    forecast_length: <int> (optional)
    meteo: <string>
    storm: <string> (optional)
    storm_name: <string> (optional)
    basin: <string> (optional)
    year: <int> (optional)
    advisory: <int> (optional)
    ensemble_members: <dict> (optional)
    initialization_skip: <int> (optional)

    hotstart:
        enabled: <bool>
        date: <datetime>
        adcirc: <string>
        hecras: <string> (optional)
        sfincs: <string> (optional)

    models:
        adcirc:
            <adcirc model configuration>, See below
        hecras:
            <hecras model configuration> (optional), See below
        xbeach-1d:
            <xbeach-1d model configuration> (optional), See below
archive:
    s3:
        enabled: <bool>
        bucket: <string>
        profile: <string>
external_services:
    apsviz:
        enabled: <bool>
        config: <string>
    floodid:
        enabled: <bool>
        config: <string>
alerts:
    push:
        enabled: <bool>
        interval: <int>

The complete description of the options is below:

• prefix

  The prefix is used to define the name of the suite. This is used for annotation purposes for the user and for transmission to external locations

• directory

  The directory is used to define the location where the suite will be run.

• system_config

  The system configuration file is used to define the system specific information. This is used to define the location of executables and the type of queueing system. See below for more information

• credential_file

  The credential file is used to define the credentials used to access parts of the system. This is used to define the location of executables and the type of queueing system. See below for more information

• project_code (optional)

  The project code is used define the project code to use within external transmission

• job_comment (optional)

  The job comment option is used to define the slurm job comment within AWS parallel cluster cost tracking

• start

  The start time is used to define the start time of the simulation. This is used to define the start time of the simulation. The format should be YYYY-MM-DD HH:MM

• compute

  The compute key defines the compute parameters for the various models. There keys within this dictionary are:

  • adcirc_compute_cores

    The number of cores to use for the ADCIRC model

  • adcirc_writer_cores (optional)

    The number of cores to use for the ADCIRC writer. This is used to write the ADCIRC output to disk. If not specified, this defaults to 0

  • adcirc_memory

    The amount of memory to use for the ADCIRC model

  • processing_cores

    The number of cores to use for the postprocessing

  • processing_memory

    The amount of memory to use for the postprocessing

  • hours_per_padcirc_day

    The number of hours to run the ADCIRC model per day

  • hours_per_padcswan_day

    The number of hours to run the ADCIRC+SWAN model per day

  • hecras_compute_cores (optional)

    The number of cores to use for the HEC-RAS model

  • hecras_memory (optional)

    The amount of memory to use for the HEC-RAS model

  • hours_per_hecras_day (optional)

    The number of hours to run the HEC-RAS model per day

  • xbeach1d_compute_cores (optional)

    The number of cores to use for the XBeach-1D model

  • xbeach1d_memory (optional)

    The amount of memory to use for the XBeach-1D model

  • hours_per_xbeach1d_day (optional)

    The number of hours to run the XBeach-1D model per day

  • max_hours_per_xbeach1d_transect (optional)

    The maximum number of hours to run a single transect for the XBeach-1D model

• simulation

  The simulation key defines the simulation parameters for the suite. The keys within this dictionary are:

  • water_level

    The water level to use for the simulation

  • spinup_duration (optional)

    The spinup duration to use for the simulation. This defaults to 18.0 hours

  • forecast_length (optional)

    The forecast length to use for the simulation. This defaults to 120 hours

  • meteo

    The meteorological source to use for the simulation. This can be one of the following:

    • gfs

    • gefs

    • hwrf

    • nam

    • nhc

    • coamps

  • storm (optional)

    This is the name of the storm to use for the simulation suite. In the case of the nhc, this is the storm number. For a model like HWRF or COAMPS-TC, this is the given name for the storm (ex. hwrf: ian09l, coamps: 09L)

  • storm_name (optional)

    This is the name of the storm to use for the simulation suite. This is used for annotation purposes for the user and for transmission to external locations

  • basin (optional)

    This is the basin to use for NHC based simulations. Valid basins are al, ep, and cp.

  • year (optional)

    This is the year to use for NHC based simulations. By default, this is the current year.

  • advisory (optional)

    This is the advisory to use for NHC based simulations. This should be an integer value and is required when NHC based simulations are run.

  • ensemble_members (optional)

    This is a dictionary which defines the ensemble members to use for the simulation. When using NHC based forcing, the ensemble members are defined as a dictionary with the track perturbations. When using GEFS based ensembles, the ensemble members are defined as a list of empty dictionaries. The definition of ensemble members is shown below.

  • initialization_skip (optional)

    This is the number of hours to skip at the beginning of input meteorological forcing data while it comes into dynamic equilibrium. Often, these models can be initialized without a fully dynamic vortex, so it is necessary to skip some time at the start of the simulation to allow the model to come into equilibrium. This defaults to 0 hours.

  • hotstart (optional)

    This is a dictionary which allows the user to hotstart a simulation from a separate instance of Floodwater. The restriction on this parameter is that the cycles must align between the two simulations, i.e. a suite running that has cycles at 0, 6, 12, 18 cannot hotstart from a suite that has cycles at 3, 9, 15, 21. The hotstart dictionary is defined as follows:

    • enabled

      A boolean value which indicates whether or not to enable the hotstart

    • date

      The date that the hotstart file(s) specified represent

    • adcirc

      Path to a directory containing the ADCIRC hotstart files (fort.67.nc, fort.68.nc, maxele.63.nc). The code will determine the appropriate file to use for hotstarting the simulation

    • hecras (optional)

      Path to a HEC-RAS hot start file

    • sfincs (optional)

      Path to a SFINCS hot start file

  • models

    The models key defines the models to use for the simulation. The keys within this dictionary are:

    • adcirc

      The ADCIRC model configuration. See below for more information

    • hecras (optional)

      The HEC-RAS model configuration. See below for more information

    • xbeach-1d (optional)

      The XBeach-1D model configuration. See below for more information

• archive

  The archive key defines the archive parameters for the suite. The keys within this dictionary are:

  • s3

    The s3 key defines the s3 parameters for the suite. The keys within this dictionary are:

    • enabled

      A boolean value which indicates whether or not to enable the s3 archive

    • bucket

      The name of the s3 bucket to use for the archive

    • profile

      The name of the AWS profile to use for the archive

• external_services

  The external_services key defines the external services parameters for the suite. The keys within this dictionary are:

  • apsviz

    The apsviz key defines the APSViz parameters for the suite. The keys within this dictionary are:

    • enabled

      A boolean value which indicates whether or not to enable the APSViz service

    • config

      The path to the APSViz configuration file (details below)

  • floodid

    The floodid key defines the FloodID parameters for the suite. The keys within this dictionary are:

    • enabled

      A boolean value which indicates whether or not to enable the FloodID service

    • config

      The path to the FloodID configuration file (details below)

• alerts

  The alerts key defines the alert parameters for the suite. The keys within this dictionary are:

  • push

    The push key defines the use of push alerts using the Pushover service. Pushover provides a simple REST interface to send alerts and an app for Apple/Android devices to receive them. Push alerts are sent when items in the running suite are in an error or late state. The keys within this dictionary are:

    • enabled

      A boolean value which indicates whether or not to enable the push alerts

    • interval

      The interval to use for push alerts. This is the number of minutes between scans for potential push alerts

Ensemble member definition:

ensemble_members: [NHC]
    member_name: {}  # The default NHC track
    member_name:
        veer: percent to veer. Positive right, negative left
        forward_speed: percent to change speed. Positive faster, negative slower
        intensity: percent to change intensity. Positive stronger, negative weaker

ensemble_members: [GEFS]
    member_name_1: {}
    member_name_2: {}
    member_name_3: {}

A minimal ADCIRC suite configuration which runs using the Global Forecast System (GFS) meteorology would look like this:

prefix: "my_suite"
directory: "/home/user/floodwater"
system_config: "/path/to/my_system_config.yml"
credential_file: "/path/to/my_credentials.yml"
start: "2018-09-01 00:00:00"
compute:
    adcirc_compute_cores: 16
    adcirc_memory: "32GB"
simulation:
    water_level: 0.0
    meteo: gfs
    models:
        adcirc: <See ADCIRC Configuration>

Model Specific Schemas

The model specific schemas are shown below.

ADCIRC

The ADCIRC model is the only model that is required at this time, though, we expect that future iterations of the forecast system will remove this limitation

adcirc:
    geometry: <string>
    geometry_name: <string> (optional)
    waves: <bool> (optional)
    meteo_domain: <list of floats> (optional)
    meteo_resolution: <float> (optional)
    meteo_background_domain: <list of floats> (optional)
    meteo_background_resolution: <float> (optional)
    station_file: <string> (optional)
    output: (optional)
        velocity: <bool>
        meteorology: <bool>
        inundation: <bool>
        wave_height: <bool>
        wave_peak_period: <bool>
        wave_direction: <bool>
        wave_mean_period: <bool>
    postprocessing: (optional)
        analysis:
            scripts:
                - name: <string>
                  enabled: <bool>
                  script: <string>
                  args: <string> (optional)
                  duration: <int> (optional)
                  depends: <list of strings> (optional)
        forecast:
            scripts:
                - name: <string>
                  enabled: <bool>
                  script: <string>
                  args: <string> (optional)
                  duration: <int> (optional)
                  depends:
                      - <list of strings> (optional)

A minimal ADCIRC configuration would look like this:

adcirc:
    geometry: /path/to/geometry

This very simple configuration would run the ADCIRC model with default settings for the meteorological domain, though this is rarely what you would want. A more complete configuration would look like this:

adcirc:
    geometry: /path/to/geometry
    meteo_domain: [ -98.0, 25.0, -88.0, 31.0 ]
    meteo_resolution: 0.10

Full ADCIRC configuration options

The complete list of options for the ADCIRC model are described below. There are many optional parameters which can be edited and updated as the user sees fit.

• geometry

  The path to the ADCIRC geometry file. This is a required parameter

• geometry_name (optional)

  The name of the geometry. This is used in the case that a user wants to override the name specified in the model configuration file

• waves

  A boolean value which indicates whether or not to run the wave model (SWAN)

• meteo_domain (optional)

  A list of floats which defines the domain of the meteorological forcing. The order of the list is [min_lon, min_lat, max_lon, max_lat]

• meteo_resolution (optional)

  The resolution of the meteorological forcing in degrees

• meteo_background_domain (optional)

  A list of floats which defines the domain of the meteorological background forcing. The order of the list is [min_lon, min_lat, max_lon, max_lat]. This will be used in the case that your configuration has multiple types of forcing, i.e. HWRF on top of GFS

• meteo_background_resolution (optional)

  The resolution of the meteorological background forcing in degrees

• station_file (optional)

  The path to the station file. This is a file which contains a list of stations which will be used to extract time series data from the ADCIRC output

• output (optional)

  These keys control the different output options within the ADCIRC model. By default, most output is turned on.

• postprocessing / forecast (optional)

  A dictionary which defines the postprocessing options for the ADCIRC model and which phase of simulation they will run for. The scripts dictionary allows the user to execute an arbitrary script at the end of the simulation. This is useful for one-off items which are not necessary to include within the Floodwater system as a whole. The user can provide the name of the script, the path to the script, and any arguments that should be passed to the script. The duration parameter is the expected duration of the script so it can be monitored by the system.

HEC-RAS

The HEC-RAS model is an optional model which can be run in addition to the ADCIRC model. It is not required for the operation of the system. HEC-RAS can be forced at its boundary with water levels from the ADCIRC model and wind and pressure data from the specified meteorological source. Currently, the model must consists only of a single 2D domain. It is expected that future iterations of the system will support the use of multiple 2D domains. Additionally, the system is configured and tested for HEC-RAS 6.1. The system is unlikely to work with versions prior to 6.1 and it is unknown if the system works with versions later than 6.1.

hecras:
    geometry: <string>
    geometry_name: <string> (optional)
    meteo_domain: <list of floats> (optional)
    meteo_resolution: <float> (optional)
    postprocessing: (optional)
        analysis:
            scripts:
                - name: <string>
                  enabled: <bool>
                  script: <string>
                  args: <string> (optional)
                  duration: <int> (optional)
                  depends: <list of strings> (optional)
        forecast:
            scripts:
                - name: <string>
                  enabled: <bool>
                  script: <string>
                  args: <string> (optional)
                  duration: <int> (optional)
                  depends: <list of strings> (optional)
        raster_topography: <string>
        raster_resolution: <float>
        raster_bounding_box: <list of floats>

A minimal HEC-RAS configuration would look like this:

hecras:
    geometry: /path/to/geometry

This very simple configuration would run the HEC-RAS model with default settings for the meteorological domain, though this is rarely what you would want. A more complete configuration would look like this:

hecras:
    geometry: /path/to/geometry
    meteo_domain: [ -98.0, 25.0, -88.0, 31.0 ]
    meteo_resolution: 0.10

Full HEC-RAS configuration options

The complete list of options for the HEC-RAS model are described below.

• geometry

  The path to the HEC-RAS geometry file. This is a required parameter

• geometry_name (optional)

  The name of the geometry. This is used in the case that a user wants to override the name specified in the model configuration file

• meteo_domain (optional)

  A list of floats which defines the domain of the meteorological forcing. The order of the list is [min_lon, min_lat, max_lon, max_lat]

• meteo_resolution (optional)

  The resolution of the meteorological forcing in degrees

• postprocessing / forecast (optional)

  The postprocessing options center around computing a peak water surface elevation raster, which is used for display on the web interfaces that the system connects to. The raster option is a boolean value which indicates whether or not to run the raster generation scripts for the HEC-RAS model. Additionally, since HEC-RAS uses a subgrid methodology, to generate meaningful water level information, the user must supply a raster so that the wet/dry mask can be computed. The user will also need to supply information about where the raster should be created and at what resolution.

SFINCS

The SFINCS model is an optional model which can be run in addition to the ADCIRC model. It is not required for the operation of the system. SFINCS can be forced at its boundary with water levels from the ADCIRC model and wind and pressure data from the specified meteorological source.

sfincs:
    geometry: <string>
    geometry_name: <string> (optional)
    meteo_domain: <list of floats> (optional)
    meteo_resolution: <float> (optional)
    postprocessing: (optional)
        analysis:
            scripts:
                - name: <string>
                  enabled: <bool>
                  script: <string>
                  args: <string> (optional)
                  duration: <int> (optional)
                  depends: <list of strings> (optional)
        forecast:
            scripts:
                - name: <string>
                  enabled: <bool>
                  script: <string>
                  args: <string> (optional)
                  duration: <int> (optional)
                  depends: <list of strings> (optional)

A minimal SFINCS configuration would look like this:

sfincs:
    geometry: /path/to/geometry

This very simple configuration would run the SFINCS model with default settings for the meteorological domain, though this is rarely what you would want. A more complete configuration would look like this:

sfincs:
    geometry: /path/to/geometry
    meteo_domain: [ -98.0, 25.0, -88.0, 31.0 ]
    meteo_resolution: 0.10

Full SFINCS configuration options

The complete list of options for the SFINCS model are described below.

• geometry

  The path to the SFINCS geometry file. This is a required parameter

• geometry_name (optional)

  The name of the geometry. This is used in the case that a user wants to override the name specified in the model configuration file

• meteo_domain (optional)

  A list of floats which defines the domain of the meteorological forcing. The order of the list is [min_lon, min_lat, max_lon, max_lat]

• meteo_resolution (optional)

  The resolution of the meteorological forcing in degrees

XBeach-1D

The XBeach-1D model is an optional model which can be run in addition to the ADCIRC model. It is not required for the operation of the system. XBeach-1D can be forced at the transect starting locations with water levels and wave information from the ADCIRC+SWAN model. The simulations are run in parallel, with each transect being run on a separate core.

xbeach-1d:
    geometry: <string>
    geometry_name: <string> (optional)
    transect_selection_method:
        proximity:
            x: <float>
            y: <float>
            radius: <float>
            wave_height: <float> (optional)
            wave_period: <float> (optional)
            scripts:
                - name: <string>
                  enabled: <bool>
                  script: <string>
                  args: <string> (optional)
                  duration: <int> (optional)
                  depends: <list of strings> (optional)
        conditions:
            wave_height: <float> (optional)
            wave_period: <float> (optional)
            scripts:
                - name: <string>
                  enabled: <bool>
                  script: <string>
                  args: <string> (optional)
                  duration: <int> (optional)
                  depends: <list of strings> (optional)

A minimal XBeach-1D configuration would look like this:

xbeach-1d:
    geometry: /path/to/geometry

This very simple configuration would run the XBeach-1D model with default settings for the transect selection method. A more complete configuration would look like this:

xbeach-1d:
    geometry: /path/to/geometry
    transect_selection_method:
        proximity:
            x: -97.0
            y: 28.0
            radius: 0.5
            wave_height: 0.5

This would select transects within 0.5 degrees of the point (-97.0, 28.0) and would only select transects which have a wave height of at least 0.5 meters.

Full XBeach-1D configuration options

The complete list of options for the XBeach-1D model are described below.

• geometry

  The path to the XBeach-1D geometry file. This is a required parameter

• geometry_name (optional)

  The name of the geometry. This is used in the case that a user wants to override the name specified in the model configuration file

• transect_selection_method

  The transect selection method can be either proximity or conditions. The proximity method selects transects based on their proximity to a point and the conditions method selects transects based on their conditions. The proximity method requires the user to specify the x and y coordinates of the point and the radius of the circle around the point. The conditions method requires the user to specify the wave height that the transect must have in order to be selected.

Credentials File

The credentials file is used to define the credentials used to access parts of the system. This information has been specifically removed from other files so that other files can be shared without sharing credentials mistakenly. The file is a YAML file with the following structure:

metget_api_key: <metget_api_key>
metget_endpoint: <metget_server_address>
metget_api_version: 2
pushover_app_token: <pushover_app_token> (optional)
pushover_user_token: <pushover_user_token> (optional)
apsviz_rmq_username: <apsviz_rmq_username> (optional)
apsviz_rmq_password: <apsviz_rmq_password> (optional)
floodid_api_url: (optional)
floodid_api_key: (optional)

System Configuration File

The system configuration file is meant to be shareable to others who are running on the same system, but not necessarily the same workflows. This file is a YAML file with the following structure:

site_name: <string>
physical_location: <string>
scheduler_control_file: <string>.h
mpi_launch_command: <mpirun or srun>
system_modules_config: /path/to/system_modules.h
adcirc: /path/to/adcirc/build
xbeach: (optional) /path/to/executable/xbeach
sfincs: (optional) /path/to/executable/sfincs
hecras_container: (optional) /path/to/hecras/singularity/image/hec_ras.sif
singularity: (optional) /path/to/executable/singularity
figuregen: (optional) /path/to/executable/figuregen
scheduler: slurm
account: (optional) <string>
cores-per-node: <int>
compute_partition: <string>
processing_partition: <string>
postproc_time_limit: <time_string>

Full System Configuration Options

The complete list of options for the system configuration file are described below.

• site_name

  The name of the site. This is used for annotation purposes for the user and APSViz

• physical_location

  The physical location of the system. This is used for annotation purposes for the user and APSViz

• scheduler_control_file

  The scheduler control file is used to define the header information that is used in the batch job submission. This is usually somewhat system specific. Provide the file with a .h extension

• mpi_launch_command

  The command to use to launch MPI jobs. This is usually mpirun or srun

• system_modules_config

  The system modules configuration file is used to define the modules that are loaded on the system. This is usually somewhat system specific. Provide the file with a .h extension

• adcirc

  The path to the directory with the ADCIRC executables. This must contain padcirc, padcswan, and aswip

• xbeach

  The path to the XBeach-1D executable. This must be a compiled executable which will run in serial mode

• hecras_container

  The path to the HEC-RAS singularity container. This must be a singularity container which contains the HEC-RAS executable that has been added to the path

• singularity

  The path to the singularity executable

• figuregen

  The path to the FigureGen executable

• scheduler

  The scheduler to use. Currently, only slurm is supported

• account

  The account to use for batch job submission

• cores-per-node

  The number of cores per node on the system

• compute_partition

  The name of the partition to use for compute jobs

• processing_partition

  The name of the partition to use for postprocessing jobs

• postproc_time_limit

  The time limit to use for postprocessing jobs. Should be in the format accepted by the job scheduler

FloodID Configuration File

FloodID is a system operated and maintained by The Water Institute. It may serve as a useful example for other systems which an operator may want to integrate with Floodwater as an external service.

The configuration options are as follows:

enabled: <bool>
models:
  - name: <string>
    type: <string> (adcirc, sfincs)
    mesh_file: (optional)
    raster:
      domain: [min_lon, min_lat, max_lon, max_lat]
      resolution: <float>
      dem: (optional)
    stations: (optional) <string>
project_codes:
    model_results:
        - project_code_1
        - project_code_2

Full FloodID Configuration Options

The complete list of options for the FloodID configuration file are described below.

• enabled

  A boolean value which indicates whether or not to enable the FloodID service

• models

  A list of models to use. The keys within this dictionary are:

  • name

    The name of the model

  • type

    The type of the model. This can be one of the following:

    • adcirc

    • sfincs

  • mesh_file (optional)

    The path to the mesh file. This is used to define the mesh for the model. Used only for ADCIRC.

  • raster

    A dictionary which defines the raster options for the model. The keys within this dictionary are:

    • domain

      A list of floats which defines the domain of the raster. The order of the list is [min_lon, min_lat, max_lon, max_lat]

    • resolution

      The resolution of the raster in degrees

    • dem (optional)

      The path to the digital elevation model file. This is used to define the elevation of the raster used in downscaling. Used only for SFINCS.

  • stations (optional)

    The path to the stations file. This is used to define the stations for the model.

  • project_codes

    A dictionary which defines the project codes to use for the model. The keys within this dictionary are:

    • model_results

      A list of project codes to use for the model results

    • dashboards

      A list of project codes to use for the dashboards

The stations file for FloodID uses the following format:

- service: <string>
  id: <string>
  index: <int> or [int, int]
- service: <string>
  id: <string>
  index: <int> or [int, int]
- service: <string>
  id: <string>
  index: <int> or [int, int]

The index value is used to provide information to the FloodID user interface as to which location in the model corresponds to the station. The index value may not always be the nearest location within the model, so it is best to allow the user to specify this manually as they’d always be able to find a nearest station and supply it if they’d prefer. The index can be either a single value (i.e. for ADCIRC or HEC-RAS) or a pair of values representing the i, j indices for a gridded model (i.e. for SFINCS). The full description of the stations file is below:

• service

  The service to use for the station. This can be one of the following:

  • usgs

  • noaa

  • ndbc

• id

  The id of the station. This is the station id used by the service

• index

  The index of the station. This is the index of the station within the model. This can be either a single value (i.e. ADCIRC, HEC-RAS) or a pair of values for a gridded model (i.e. SFINCS)

APSViz Configuration File

The APSViz configuration file is used to define the connection information for the APSViz system. This file is a YAML file with the following structure:

s3:
  bucket: <string>
  profile: <string>
thredds:
  config:
   - name: <string>
     protocol: ftpgo
     server: <string>
     server_download: <string>
     port: <int>
     username: <string>
     base_directory: /path/to/thredds/directory
     rsa_keyfile: /path/to/rsa/keyfile.rsa
messaging:
  rmq:
    host: <string>
    runtime_queue: <string>
    adcirc_properties_queue: <string>
    generic_properties_queue: <string>

Full APSViz Configuration Options

The complete list of options for the APSViz configuration file are described below.

• s3: The s3 key is used to define the connection information for the S3 bucket which is used to store the APSViz data. In the case of HEC-RAS, a geotiff is published to an S3 bucket

  • bucket: The name of the S3 bucket

  • profile: The AWS profile to use for the S3 bucket

• thredds

  • config

    • name: Name of the thredds server instance. Used only for annotation purposes

    • protocol: The protocol to use to connect to the server. Currently, only ftpgo is supported

    • server: The server to connect to

    • server_download: The server to connect to for downloading files

    • port: The port to connect to

    • username: The username to use to connect to the server

    • base_directory: The base directory to use for the server

    • rsa_keyfile: The path to the RSA keyfile to use for the server

• messaging

  • rmq

    • host: The host to use for the RabbitMQ server

    • runtime_queue: The name of the runtime queue to use

    • adcirc_properties_queue: The name of the ADCIRC properties queue to use

    • generic_properties_queue: The name of the generic properties queue to use

Model Geometry Configuration Files

ADCIRC

The ADCIRC configuration file is used to set the parameters used within the model, including model time step, nodal attributes included in the model, physics settings, boundary conditions, and model geometry name. The file is ALWAYS named config.yaml and resides in a folder which contains the raw model files and any prepared decompositions.

Mesh decomposition is typically a process that is a nontrivial time consideration. The script floodwater_adcirc_generate_prepdir, which is installed with the system, can generate a pre-packaged decomposition archive automatically. The output from this script should be stored alongside the other files in this mesh data directory. It will be named something like decomp001023.tar.gz. Note that the number of cores provided should be the number of compute cores, not the total number of cores (i.e. including writier processors).

name: mesh_name
dt: 2
attributes:
- surface_submergence_state
- surface_canopy_coefficient
- mannings_n_at_sea_flood
- sea_surface_height_above_geoid
physics:
  preset: standard
datum_transform_file: /path/to/datum_transform_file
flow_boundary: [see_flow_boundary]
tide_boundary:
  Q1:
  - - amplitude
    - phase
  - - amplitude
    - phase
  O1:
  - - amplitude
    - phase
  - - amplitude
    - phase

The list of valid tide constituent names can be computed using the following:

import numpy
import utide
valid_tides = []
invalid_tides = []
[valid_tides.append(name) if ~numpy.isnan(amp) else invalid_tides.append(name) for name,amp,freq in zip(utide.ut_constants["const"]["name"], utide.ut_constants["const"]["doodsonamp"], utide.ut_constants["const"]["freq"])]

valid_tides = ['SA', 'SSA', 'MM', 'MSF', 'MF', 'ALP1', '2Q1', 'SIG1', 'Q1', 'RHO1', 'O1', 'TAU1', 'BET1', 'NO1', 'CHI1', 'PI1', 'P1', 'S1', 'K1', 'PSI1', 'THE1', 'J1', 'OO1', 'UPS1', 'OQ2', 'EPS2', '2N2', 'MU2', 'N2', 'NU2', 'GAM2', 'H1', 'M2', 'H2', 'LDA2', 'L2', 'T2', 'S2', 'R2', 'K2', 'ETA2', 'M3']

The most common tides used are: M2, S2, N2, K2, K1, O1, P1, and Q1

A description of the keys used in the model configuration file are below:

• name

  The name of the mesh geometry. This is used for annotation purposes for the user

• dt

  The ADCIRC time step to use in seconds

• attributes

  Attributes in the fort.13 nodal attributes file to be included in simulations

• physics

  The physics key is used to set up the model physics and solver parameters. The preset key is used to select from a number of canned configurations. Subsequent keys can be used to modify the presets.

  • preset

    The following presets can be selected: standard, explicit, pringle, jjw

    • standard preset

      implicit solver, eddy viscosity turbulence model with 2.0 coefficient, time weighting = 0.35, 0.30, 0.35, Garratt wind drag with 0.0025 limit, 0.0010 bottom friction limit, tau0 = 0.005, advection disabled, implicit gravity wave disabled

    • explicit preset

      explicit solver, Smagorinsky turbulence with 0.2 coefficient, time weighting = 0.00, 1.00, 0.00, Garratt wind drag with 0.0025 limit, 0.0010 bottom friction limit, tau0 = 0.005, advection enabled, implicit gravity wave disabled

    • pringle preset

      implicit solver, Smagorinsky turbulence with 0.2 coefficient, time weighting = 0.50, 0.50, 0.00, Garratt wind drag with 0.0025 limit, 0.0010 bottom friction limit, tau0 = 8/5*dt, advection enabled, implicit gravity wave enabled

    • jjw preset

      implicit solver, Smagorinsky turbulence with 0.2 coefficient, time weighting = 0.80, 0.20, 0.00, Garratt wind drag with 0.0025 limit, 0.0010 bottom friction limit, tau0 = 0.05, advection enabled, implicit gravity wave enabled, direct velmin calculation enabled

  • additional keys

    The following are additional keys which can be specified to update the model configuration

    • time_weighting_coefficients

      Set using an array of a, b, c

    • solver

      Set to either “implicit” or “explicit”

    • turbulence

      Set to either eddy_viscosity or smagorinsky. Requires setting an associated value in subsequent key

    • eddy_viscosity_coefficient

      Sets the global eddy viscosity coefficient if not using a spatially varying coefficient in the fort.13

    • smagorinsky_coefficient

      Sets the Smagorinsky coefficient. Note, does not need to be set to negative as is done in the fort.15

    • h0

      Sets the minimum depth for wetting/drying

    • velmin

      Sets the minimum velocity for wetting/drying

    • hbreak

      Sets the break depth for the hybrid friction relationship (unused)

    • ftheata, fgamma

      Parameters used for the hybrid friction relationship (unused)

    • wind_drag_formula

      Sets the wind drag formula to use (garratt or powell)

    • wind_drag_limit

      Sets the wind drag limit to use

    • bottom_friction_limit

      Sets the bottom friction limit to use in Manning’s n based simulations

    • tau0

      Sets the tau0 parameter as specified in the fort.15. All typical fort.15 rules apply

    • advection

      Set to True to turn advection on or False to turn advection off

    • use_direct_velmin

      Set to True to activate direct calculation of velmin in wetting/drying

    • self_attraction_and_loading

      Set to True to activate self attraction and loading terms (fort.24 or fort.24.nc)

    • swan_physics_version

      Sets the SWAN model physics version (gen1, gen2, gen3, gen3-st6)

    • swan_max_iterations

      Sets the maximum number of iterations for the SWAN model

    • swan_convergence_npts

      Sets the percentage of points which must converge for the SWAN model

    • swan_spectral_directions

      Sets the number of spectral directions in the SWAN model (default 36)

    • swan_spectral_frequency_bins

      Sets the number of spectral frequency bins in the SWAN model (default 40)

    • swan_spectral_frequency_minimum

      Sets the minimum spectral frequency in the SWAN model (default 0.031384)

    • swan_spectral_frequency_maximum

      Sets the maximum spectral frequency in the SWAN model (default 1.420416)

    • wave_coupling_interval

      Sets the interval at which the ADCIRC and SWAN models are coupled

    • coordinate_system

      Sets the coordinate system to use. This is passed as the ICS variable to ADCIRC

    • quadratic_friction_coefficient

      If using a quadratic friction coefficient, this sets the value of the coefficient

    • coordinate_rotation

      If using a rotated coordinate system, this sets the rotation. This should be a list of two values

  • datum_transform_file

    Path to the datum transform file. This is an ADCIRC mesh where the nodal elevation is the datum shift to apply to the model water level output. All other efforts after this except APSViz uploads use the transformed water levels.

  • flow_boundary

    The flow boundary key specifies the inflow boundary conditions to apply to the model. See the flow boundary schema for more information.

  • tide_boundary

    The tide boundary key specifies a set of key/value pairs where the key is the harmonic constituent and the value is an array of amplitude/phase along the open boundary as it appears in the fort.15. Valid harmonic constituent names are: Q1, O1, P1, K1, M2, N2, S2,

HEC-RAS

The HEC-RAS configuration file is used to set the parameters used within the model, including which plan/geometry combination should be used and how boundary conditions should be treated. The file is ALWAYS named config.yaml and resides in a folder which contains the model geometry files.

name: model_name
geometry: 1
plan: 1
timestep: 60
flow_boundary: [see_flow_format]

A description of the keys used in the model configuration file are below:

• name

  The name of the HEC-RAS model. This is used for annotation purposes for the user

• model

  The base name of the model that appears at the start of all model files

• geometry

  HEC-RAS geometry number to use

• timestep

  The model timestep to use in seconds

• plan

  HEC-RAS plan number to use

• flow_boundary

  These are boundary conditions which will be configured to come from USGS and RFC sources. The model key is the name of the boundary as it appears in the model geometry. The usgs and rfc keys are the names of the USGS and RFC stations to use for the boundary condition.

SFINCS

The SFINCS geometry file defines very basic parameters for the SFINCS model. The file is ALWAYS named config.yaml and resides in a folder which contains the model geometry files named like sfincs.*.

model: model_name
name: geometry_name
epsg: epsg-code
flow_boundary: [see_flow_format]
boundary_location_override:
    epsg: epsg-code
    positions:
        - [lon, lat]
        - [lon, lat]
        - [lon, lat]

The boundary condition override allows the user to specify the locations of the boundary nodes which may not be correct with respect to the outer model geometry.

XBeach-1D

The XBeach-1D configuration file is used to set the parameters used within the model, including the locations of the transects that should be used. Since XBeach requires multiple input files per transect, they are organized in a directory structure as follows:

[transect_directory]
├── T0001
│   ├── T0001_bedfric.txt
│   ├── T0001_info.txt
│   ├── T0001_XYdata.txt
│   ├── x_file_tnsct_0001.txt
│   └── y_file_tnsct_0001.txt
├── T0002
│   ├── T0002_bedfric.txt
│   ├── T0002_info.txt
│   ├── T0002_XYdata.txt
│   ├── x_file_tnsct_0002.txt
│   └── y_file_tnsct_0002.txt

Transects are numbered with an integer identifier. They do not need to be sequential, but they must be unique.

The config.yaml file that is used for the model will look like:

name: model_name
offshore_locations: "/path/to/offshore_locations.txt"
transect_directory: "/path/to/transect_directory"

The offshore_locations file is a text file which contains a list of the offshore locations where boundary condition information is extracted. These should be in WGS84 coordinates. The file should look like:

3    #...Point Count
1 -97.0 28.0
2 -97.1 28.1
3 -97.2 28.2

Next, the info file contains some of the metrics of importance for the transect. The file should look like:

T_ID    1
alfa    -160.18654293903464
Nx  885
zdatum  0.26
zone    18
XD  1
lon -75.53899999999999
lat 35.7939
date    2
Dhigh   4.337309027117621
Dlow    3.455597140294281
DuneW   4.583310410496779
DuneRH  0.8817118868233402
DuneV   17.875586275913363
BeachW  107.7077946466743
BeachV  171.8288934989446
BeachSlope  0.029669135374808753
DepOfClosure    -11.077
NearshoreSlp    0.008443387584221173

Flow Boundary Schema

Flow boundary conditions are used through multiple models. Therefore, the schema used to specify them has been unified across each model and allows for significant flexibility in specifying the boundary conditions.

The flow boundary for a single boundary inflow location is as follows:

- name: Boundary Name
  default_flow: flow_cms
  source: [list of stations]
  model_reference:
    location: [lon, lat]
    name: stn_name

Where the stations are specified as a list of locations to be used within the model. The keys represent:

• name

  The name of the boundary condition. This is used for annotation purposes for the user

• default_flow

  The default flow to use for the station when no data is available. This is used to specify the flow in cubic meters per second

• source

  A list of stations to use for the boundary condition. This is used to specify the stations to use for the boundary condition

• model_reference

  A dictionary which specifies the location of the station or the name of the station. For some models, it is necessary to locate the station. HEC-RAS locates by name, SFINCS and ADCIRC locate by location. For SFINCS and ADCIRC, if a position is not provided, the boundaries will be specified in the order that they are found in the model ata.

The source key allows the user to specify a list of services that should be aggregated to form a boundary condition.

- type: usgs/rfc/nwm
  priority: 0
  stations: [list of stations]
  stage_discharge_relationship: [file]

The keys represent:

• type

  The type of service to use for the boundary condition. This can be one of the following:

  • usgs - USGS WaterData API

  • rfc - River Forecast Center

  • nwm - National Water Model

• priority

  The priority of the service. This is used to determine which service to use when multiple services are available. The service with the lowest priority will be used first. If the service does not have data, the next service will be used.

• stations

  A list of stations to use for the boundary condition. This is used to specify the stations to use for the boundary condition

• stage_discharge_relationship

  The path to the stage discharge relationship file. This is used to specify the stage discharge relationship for the boundary condition when using ADCIRC’s type 32 boundary condition. The stage discharge relationship should be generated from the model and not from observation.

The station list is a list of dictionaries which specify the station information.

- id: station_id
  delay_time: delay_seconds
  scaling_factor: scaling_factor
  attributes: [list of attributes]

The keys represent:

• id

  The id of the station. This is the station id used by the service

• delay_time (optional)

  The delay time for the station. This is used to specify the delay in seconds for the station

• scaling_factor (optional)

  The scaling factor for the station. This is used to specify the scaling factor for the station

• attributes (optional)

  A list of attributes to use for the station. This is used to specify special processing options that can be used for the station. Currently, the attributes are:

  • POSITIVE_ONLY - Only use positive values for the station’s discharge

Putting it all together, a full flow boundary configuration file might look like:

- name: Boundary Name
  default_flow: 10000
  source:
    - type: usgs
      priority: 0
      stations:
        - id: station_id_usgs_1
          delay_time: 0
          scaling_factor: 0.8
        - id: station_id_usgs_2
          delay_time: 3600
          scaling_factor: 1.2
    - type: rfc
      priority: 1
      stations:
        - id: station_id_rfc
    - type: nwm
      priority: 2
      stations:
        - id: station_id_nwm
          delay_time: 7200

Your station flow input file can be tested using the floodwater command line interface via the data subcommand.