################### 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. .. code-block:: yaml prefix: directory: system_config: credential_file: project_code: (optional) job_comment: (optional) start: compute: adcirc_compute_cores: adcirc_writer_cores: (optional) adcirc_memory: processing_cores: processing_memory: hours_per_padcirc_day: hours_per_padcswan_day: hecras_compute_cores: (optional) hecras_memory: (optional) hours_per_hecras_day: (optional) xbeach1d_compute_cores: (optional) xbeach1d_memory: (optional) hours_per_xbeach1d_day: (optional) max_hours_per_xbeach1d_transect: (optional) simulation: water_level: spinup_duration: (optional, default: 18.0) forecast_length: (optional) meteo: storm: (optional) storm_name: (optional) basin: (optional) year: (optional) advisory: (optional) ensemble_members: (optional) initialization_skip: (optional) hotstart: enabled: date: adcirc: hecras: (optional) sfincs: (optional) models: adcirc: , See below hecras: (optional), See below xbeach-1d: (optional), See below archive: s3: enabled: bucket: profile: external_services: apsviz: enabled: config: floodid: enabled: config: alerts: pushover: enabled: interval: slack: enabled: interval: 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 :code:`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 * hrrr * rainfall_source The rainfall source to use for the simulation. This can be one of the following: * off - disables precipitation forcing * wpc * hrrr * default - Uses the default rainfall source for the specified meteorological source * 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: :code:`ian09l`, coamps: :code:`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 :code:`al`, :code:`ep`, and :code:`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: * pushover The pushover 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 * slack The slack key defines the use of push alerts to a Slack webhook URL as defined in the credentials file. The alerts are the same as used in the push over alerts and alerts are sent for aborted and late tasks * enabled A boolean value which indicates whether or not to enable the slack alerts * interval The interval to use for slack alerts. This is the number of minutes between scans for potential slack alerts Ensemble member definition: .. code-block:: yaml 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: .. code-block:: yaml 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: 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 .. code-block:: yaml adcirc: geometry: geometry_name: (optional) waves: (optional) meteo_domain: (optional) meteo_resolution: (optional) meteo_background_domain: (optional) meteo_background_resolution: (optional) station_file: (optional) output: (optional) velocity: meteorology: inundation: wave_height: wave_peak_period: wave_direction: wave_mean_period: postprocessing: (optional) analysis: scripts: - name: enabled: script: args: (optional) duration: (optional) depends: (optional) forecast: scripts: - name: enabled: script: args: (optional) duration: (optional) depends: - (optional) A minimal ADCIRC configuration would look like this: .. code-block:: yaml 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: .. code-block:: yaml 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. .. code-block:: yaml hecras: geometry: geometry_name: (optional) meteo_domain: (optional) meteo_resolution: (optional) postprocessing: (optional) analysis: scripts: - name: enabled: script: args: (optional) duration: (optional) depends: (optional) forecast: scripts: - name: enabled: script: args: (optional) duration: (optional) depends: (optional) raster_topography: raster_resolution: raster_bounding_box: A minimal HEC-RAS configuration would look like this: .. code-block:: yaml 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: .. code-block:: yaml 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. .. code-block:: yaml sfincs: geometry: geometry_name: (optional) meteo_domain: (optional) meteo_resolution: (optional) postprocessing: (optional) analysis: scripts: - name: enabled: script: args: (optional) duration: (optional) depends: (optional) forecast: scripts: - name: enabled: script: args: (optional) duration: (optional) depends: (optional) A minimal SFINCS configuration would look like this: .. code-block:: yaml 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: .. code-block:: yaml 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. .. code-block:: yaml xbeach-1d: geometry: geometry_name: (optional) transect_selection_method: proximity: x: y: radius: wave_height: (optional) wave_period: (optional) scripts: - name: enabled: script: args: (optional) duration: (optional) depends: (optional) conditions: wave_height: (optional) wave_period: (optional) scripts: - name: enabled: script: args: (optional) duration: (optional) depends: (optional) A minimal XBeach-1D configuration would look like this: .. code-block:: yaml 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: .. code-block:: yaml 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: .. code-block:: yaml metget_api_key: metget_endpoint: metget_api_version: 2 pushover_app_token: (optional) pushover_user_token: (optional) apsviz_rmq_username: (optional) apsviz_rmq_password: (optional) floodid_api_url: (optional) floodid_api_key: (optional) slack_webhook_url: (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: .. code-block:: yaml site_name: physical_location: scheduler_control_file: .h mpi_launch_command: 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) cores-per-node: compute_partition: processing_partition: postproc_time_limit: 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 :code:`.h` extension * mpi_launch_command The command to use to launch MPI jobs. This is usually :code:`mpirun` or :code:`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 :code:`.h` extension * adcirc The path to the directory with the ADCIRC executables. This must contain :code:`padcirc`, :code:`padcswan`, and :code:`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 :code:`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: .. code-block:: yaml enabled: models: - name: type: (adcirc, sfincs) mesh_file: (optional) raster: domain: [min_lon, min_lat, max_lon, max_lat] resolution: dem: (optional) stations: (optional) 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: .. code-block:: yaml - service: id: index: or [int, int] - service: id: index: or [int, int] - service: id: index: 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: .. code-block:: yaml s3: bucket: profile: thredds: config: - name: protocol: ftpgo server: server_download: port: username: base_directory: /path/to/thredds/directory rsa_keyfile: /path/to/rsa/keyfile.rsa messaging: rmq: host: runtime_queue: adcirc_properties_queue: generic_properties_queue: 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 :code:`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 :code:`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 :code:`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 :code:`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). .. code-block:: yaml 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: .. code-block:: python 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_calculation 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 (:code:`fort.24` or :code:`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 :code:`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 * full_tide_potential Set to True to allow ADCIRC to compute the gravitational tide potential rather than using the tidal constituents in UTide * 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 :code:`config.yaml` and resides in a folder which contains the model geometry files. .. code-block:: yaml 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 :code:`model` key is the name of the boundary as it appears in the model geometry. The :code:`usgs` and :code:`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 :code:`config.yaml` and resides in a folder which contains the model geometry files named like :code:`sfincs.*`. .. code-block:: yaml 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: .. code-block:: bash [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 :code:`config.yaml` file that is used for the model will look like: .. code-block:: yaml name: model_name offshore_locations: "/path/to/offshore_locations.txt" transect_directory: "/path/to/transect_directory" The :code:`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: .. code-block:: bash 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: .. code-block:: bash 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: .. code-block:: yaml - 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. .. code-block:: yaml - 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 * constant - A constant value * 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. .. code-block:: yaml - 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 * constant (optional) For constant stations, the constant value to use should be supplied using the format below. Note that it is only necessary to specify either flow or stage depending on the model. .. code-block:: yaml constant: flow: 123 stage: 123 * fitting (optional) For virtual stations, these values define a set of parameters that can be used as factors to adjust the returned data. The values use a polynomial degree and a list of parameters. Up to cubic polynomials are supported. The length of the list should be the degree of the polynomial plus one. .. code-block:: yaml fitting: degree: 2 parameters: [1, 2, 3] * 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: - :code:`POSITIVE_ONLY` - Only use positive values for the station's discharge - :code:`VIRTUAL` - The station uses another as a reference and a set of parameters to adjust the values Putting it all together, a full flow boundary configuration file might look like: .. code-block:: yaml - 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 :code:`floodwater` command line interface via the :code:`data` subcommand.