Skip to content

SURF Workflow

In this page, you will learn more about the SURF workflow.

Workflow Layout

The diagram below provides a schematic overview of the SURF workflow. It outlines the main steps involved in running a downscaling experiment — from initial setup to final postprocessing phase.

flowchart TB
    A[🚀&nbsp Start Experiment] --> Setup[🛠️ &nbsp️Experiment Setup️] -..- j1@{ shape: f-circ, label: "Junction" }
    Setup --> Pre[🏗️&nbsp️ Preprocessing] -..- j2@{ shape: f-circ, label: "Junction" }
    Pre --> Sim[🌊&nbsp Simulation] -..- j3@{ shape: f-circ, label: "Junction" }
    Sim --> Post[🎨️&nbsp Postprocessing] -..- j4@{ shape: f-circ, label: "Junction" }
    Post --> E[✅&nbsp End Experiment]

    j1 -..-> j1a([Create Experiment Directory]) -..-> j1b([Validate Configuration File]) -..-> j1
    j2 -..-> j2a([Generate High-Resolution Grid]) -..-> j2b([Prepare Atmospheric Data]) -..-> j2c([Prepare Ocean Data]) -..-> j2d([Correct with Tidal Data]) -..-> j2e([Prepare River Data]) -..-> j2f([Create SHYFEM-MPI Input Files]) -..-> j2
    j3 -..-> j3a([Generate Model Namelist]) -..-> j3b([Run Model]) -..-> j3
    j4 -..-> j4a([Validate Results]) -..-> j4b([Visualize Results]) -..-> j4

    %% Add links
    click A "#start-experiment"
    click Setup "#experiment-setup"
    click Pre "#preprocessing"
    click Sim "#simulation"
    click Post "#postprocessing"

Details

Start Experiment

Click here to expand...

The SURF workflow can be started by running the surf_shyfem command with the --output-dir and --config flags. This is what we call the SURF Command Line Interface (CLI). Please refer to the Getting Started section for more details.

Experiment Setup

Click here to expand...

The initial phase of the workflow involves preliminary steps such as:

  • Create Experiment Directory: the experiment directory, named after the 🔗Experiment name value in the configuration file, is created in the directory chosen with the --output-dir flag. For example:

    1
    surf_shyfem --output-dir $SURF_SHYFEM_DIR --config $SURF_SHYFEM_DIR/configurations/config_base_bay_madagascar.json
    This will create the experiment directory $SURF_SHYFEM_DIR/bay_madagascar, since the Experiment name value in the configuration file is bay_madagascar.

  • Validate Configuration File: The configuration file is parsed and validated to ensure that all required parameters are present and have valid values.

Preprocessing

Click here to expand...

This automated phase can be considered the core of the SURF workflow. It handles the downloading and preparation of the input datasets required for the simulation, such as bathymetry, coastline, atmospheric, river and ocean data.

The preprocessing phase includes the following steps:

  • Generate High-Resolution Grid: Generates the high-resolution grid for the nested model ensuring an accurate representation of the region of interest.
  • Prepare Atmospheric Data: Remaps atmospheric data to the region of interest.
  • Prepare Ocean Data: Remaps ocean data onto the high-resolution grid, and extracts values at the open boundaries.
  • Correct with Tidal Data: Remaps tidal data onto the high-resolution grid, and corrects sea level height values at the open boundaries.
  • Prepare River Data: Remaps the river data provided by the user onto the domain coast boundaries. For more information, please refer to the Including Rivers in the Simulation section.
  • Create SHYFEM-MPI Input Files: SHYFEM-MPI requires ocean and atmospheric input data to be written as dat files following a specific formatting, see the Data Format section.

The preparation of atmospheric and ocean data consists of several substeps, each one corresponding to a different subfolder of the preprocessing/ folder. These substeps include:

  • Download input data (into the input/ subfolder). More details about the input data sources supported by SURF can be found in the How To section.
  • Reformat data to SURF internal format (into the reformat/ subfolder). This is a necessary step to ensure that the data is in the correct format for the SHYFEM-MPI model. Examples of data formatting include renaming variables, reordering and reshaping coordinates, converting data units, clipping data to the domain of interest, etc.

  • Remap data to the high-resolution grid:

  • Extract data at the open boundaries (into the ocean_obc/ subfolder)

Simulation

Click here to expand...

In this phase, the SHYFEM-MPI ocean model is executed using the configured parameters. This automated step generates high-resolution fields that provide detailed descriptions of ocean dynamics in the selected region.

For more details on the model settings, please refer to the SHYFEM-MPI Configuration section.

Postprocessing

Click here to expand...

After the simulation is complete, post-processing is performed to visualize and analyze the model outputs.