CoastalApp

CoastalApp will be deprecated. Please switch to https://github.com/oceanmodeling/ufs-coastal

Contacts:

• Panagiotis.Velissariou@noaa.gov
• Saeed.Moghimi@noaa.gov

Introduction

CoastalApp is a modeling framework for coastal applications and regional forecasts. It consists of coupled modeling components that link the atmospheric, ocean and terrestrial realms under one common framework. CoastalApp is a flexible and portable modeling system. Flexibility means that additional modeling components can be added with ease and portability means that CoastalApp can be built and run under different computing environments and operating systems.

CoastalApp is based on the ESMF (https://earthsystemmodeling.org/) framework for building a NUOPC/NEMS coupling application that includes two types of components (a) 1-way and 2-way coupled modeling components (model source + NUOPC Cap) and (b) data components (NUOPC Cap only) that pass forcing data, as needed, via NetCDF files to the various models in CoastalApp. The application is based on its predecessor ESMF application ADC-WW3-NWM-NEMS (see Moghimi et. al) developed as part of the Coastal Act coupling project to determine wind versus water percentage losses caused by a Named Storm Event.

The models and modeling components (data components) currently supported in CoastalApp are outlined in Table 1. <a name="table_1"></a>

Accessing the individual modeling components

• ATMESH : https://github.com/noaa-ocs-modeling/ATMESH
• PAHM : https://github.com/noaa-ocs-modeling/PaHM
• ADCIRC : https://adcirc.org/, https://github.com/adcirc/adcirc (requires registration; please send an email request to Crystal Fulcher)
• SCHISM : http://ccrm.vims.edu/schismweb/, https://github.com/schism-dev/schism
• FVCOM : http://fvcom.smast.umassd.edu/, https://github.com/FVCOM-GitHub
• BARDATA: https://github.com/noaa-ocs-modeling/BARDATA
• WW3 : https://github.com/NOAA-EMC/WW3/wiki, https://github.com/NOAA-EMC/WW3
• WW3DATA: https://github.com/noaa-ocs-modeling/WW3DATA

Downloading CoastalApp

CoastalApp is hosted in NOAA's Office of Coast Survey github modeling repository: https://github.com/noaa-ocs-modeling along with other applications and models. The source code of CoastalApp is publicly available from the GitHub repository: <a href="https://github.com/noaa-ocs-modeling/CoastalApp" TARGET="_BLANK" REL="NOREFERRER">https://github.com/noaa-ocs-modeling/CoastalApp</a> (binary distributions of CoastalApp are not currently available).

The application can be downloaded using the following method:

Clone the source code from GitHub:

    git clone --recurse-submodules  https://github.com/noaa-ocs-modeling/CoastalApp.git

The source will be downloaded into the target directory CoastalApp. It is assumed that all subsequent operations are taking place into the CoastalApp directory.

Most of the modeling components in the CoastalApp GitHub repository (e.g., ADCIRC, SCHISM, ...) are simply git submodules (pointers) that point to the respective repository of each model. Some models, for example ADCIRC and FVCOM, require that the user is registered with the respective model repository in order to be granted access. In case, users don't have access to a model and in order to avoid errors and permission issues during the cloning process of CoastalApp, they can exclude the particular modeling component using, for example, commands like:

• Exclude ADCIRC from cloning using one of the following commands:

  • git -c submodule."ADCIRC".update=none clone --recurse-submodules https://github.com/noaa-ocs-modeling/CoastalApp.git

    OR

  • git clone --recurse-submodules=":(exclude)ADCIRC" https://github.com/noaa-ocs-modeling/CoastalApp.git

• Exclude multiple components (ADCIRC, PAHM and SCHISM) from cloning using one of the following commands:

  • git -c submodule."ADCIRC".update=none -c submodule."PAHM".update=none -c submodule."SCHISM/schism".update=none -c submodule."SCHISM/schism-esmf".update=none clone --recurse-submodules https://github.com/noaa-ocs-modeling/CoastalApp.git

    OR

  • git clone --recurse-submodules=':(exclude)ADCIRC' --recurse-submodules=':(exclude)PAHM' --recurse-submodules=":(exclude)SCHISM/*" https://github.com/noaa-ocs-modeling/CoastalApp.git

Note: The alternative method of downloading the application by fetching the zip archive via the command:

    wget https://github.com/noaa-ocs-modeling/CoastalApp/archive/refs/heads/main.zip

will download CoastalApp but all the model component directories will be empty as these components are basically pointers to their respective repositories. Only CoastalApp's configuration and build files will be available in this case. If users are only interested on how CoastalApp is configured, they can download the archive and extract the sources in the CoastalApp directory by issuing the following commands:

    unzip -o main.zip  (the data will be extracted into the CoastalApp-main directory)

    mv CoastalApp-main CoastalApp  (move the extracted files to the CoastalApp directory)

By using the distributed version control system Git, users will be able to follow the CoastalApp development and its updates and furthermore they will be able to easily merge to new versions of the application. New Git users are invited to read some of the online guides to get familiar with vanilla Git concepts and commands:

• Basic and advanced guide with the <a href="https://git-scm.com/book/en/v2/" TARGET="_BLANK" REL="NOREFERRER">Git Book</a>.
• Reference guides with the <a href="https://git-scm.com/docs/" TARGET="_BLANK" REL="NOREFERRER">Git Reference</a>.
• GitHub reference sheets with the <a href="https://training.github.com/" TARGET="_BLANK" REL="NOREFERRER">GitHub Reference</a>.
• Manage your GitHub repositories with Git <a href="https://docs.github.com/en/get-started/using-git/" TARGET="_BLANK" REL="NOREFERRER">Using Git</a>.

Building CoastalApp

The build infrastracture in CoastalApp uses a hybrid "Make" system based on GNU Make and CMake toolkits that manage building of the source code and the generation of executables and other non-source files of a program. Furthermore, CostalApp utilizes environment module systems like Lmod (installed in most HPC clusters) or Environment Modules.

Requirements

1. Recent version of CMake (version ≥ 3.2).
2. Recent Fortran/C/C++ compilers: The compilers tested are Intel ≥ 18, GCC ≥ 4.8 and PGI/NVidia ≥ 20.11.
3. Recent MPI implementation: The Message Passing Interface libraries tested are Intel's MPI, OpenMPI and MVAPICH.
4. Recent version of the <a href="https://www.unidata.ucar.edu/software/netcdf/" TARGET="_BLANK" REL="NOREFERRER">NetCDF-4</a> libraries: the Network Common Data Form (NetCDF) C and Fortran libraries (usually installed in the host OS).
5. Recent version of the <a href="https://www.hdfgroup.org/" TARGET="_BLANK" REL="NOREFERRER">HDF5</a> libraries: the High-performance software and Data Format (HDF) libraries (usually installed in the host OS).
6. Recent version of the <a href="https://earthsystemmodeling.org/" TARGET="_BLANK" REL="NOREFERRER">ESMF</a> libraries: the Earth System Modeling Framework (version ≥ 8.1).
7. <a href="https://github.com/KarypisLab/ParMETIS" TARGET="_BLANK" REL="NOREFERRER">ParMETIS</a> libraries (Optional). This library is required if building WaveWatch III (WW3 component, mandatory) or SCHISM (optional). The library is not shipped with CoastalApp and it is the user's responsibility to download the library before compiling CoastalApp. The script download_parmetis.sh in CostalApp/scripts directory is supplied for this reason.

NOTE: It is important to note that the user needs to make sure that all the libraries and CoastalApp are compiled using exactly the same compilers (and possibly versions; you cannot mix compilers and compiler versions).

Build System

To build CoastalApp the user should run the build.sh bash script (a link to the scripts/build.sh) located in the root directory of the downloaded source code. The build script a