Skip to content

WIP: ASGS ADCIRC ONLY

ooder577 edited this page Oct 11, 2023 · 1 revision

THIS DOCUMENT IS A DRAFT

Introduction

ASGS is becoming increasingly used by folks who just want to run ADCIRC in a consistent environment that naturally supports ADCIRC in very powerful ways.

Most of the software that is built when installing ASGS is for supporting its primary use as a way to run ADCIRC in a forecasting mode during a hurricane or some other tropical event. But fundamental to it being useful for this operational use, it has evolved to support the full lifecycle of the ADCIRC program. ASGS can be build with a minimal amount of its software stack if it will only be used to build and run ADCIRC, which is going to be done within the ASGS Shell Environment.

The rest of this document covers setting up and using ASGS as a powerful environment supporting ADCIRC in a variety of ways.

Installing ASGS in ADCIRC Only Mode

ASGS is a powerful tool because it provides with it an isolated shell environment called the ASGS Shell Environment. This approach evolved over time because it was used on a variety of Linux cluster environments, which often meant that the required compilers and libraries were available but in different locations. The libraries that ADCIRC depends on are netCDF4, which depends on HDF5. So originally, the ASGS Shell Environment began simply as a way to manage the building and use of installation of netCDF4 and HDF5 in a standard relative location. Ultimately, this means that in order to build and run ADCIRC within the ASGS Shell Environment, one simply needs to build just netCDF4 and HDF5.

Currently the best way to install just netCDF4 and HDF5, is to specify the following when running the ASGS installation wizard, ./init-asgs.sh with some additional flags:

$ ./init-asgs.sh -x "--run-steps openmpi,hdf5,netcdf4"

This will run the wizard as is normal, but when the final step is reached and ASGS is being "installed", it will build only the minimal set of libraries that are required to build ADCIRC.

It is assumed that OpenMPI is available (i.e., mpif90) in the cluster environment; if it is then the openmpi step will be skipped because mpif90 will be found in the user's environment (via which mpif90). If it is not found (e.g., on a local Ubuntu installation), that an old version of OpenMPI that is known to work with gfortran will be downloaded, built, and installed first.

Building ADCIRC

ASGS supports any versions of ADCIRC and the building of ADCIRC in various forms. These forms include, downloaded from the Github site, downloaded as .zip file or already existing in a local directory.

Detailed coverage of building ADCIRC may seen by clicking here.

In this guide, the minimal installation of ADCIRC that is being discussed is referred to as ASGS lite. This is an informal reference, and may change in the future. The point is that a full build of ASGS is not needed if all one wants to do is leverage the ASGS Environment Shell for working with ADCIRC manually.

The essential steps for building ADCIRC are,

$ ./asgsh                                                   # start the ASGS Environment Shell
[ASGS (master)] machinename@default-asgs-prod> build adcirc # invoke the ADCIRCnow Wizard
...

From there, the instructions in the aforementioned guide will be a useful digression from this document.

Setting Up and Running ADCIRC

Once ASGS is installed with the minimal software to support the building of ADCIRC, one may operate inside of the ASGS Shell Environment to do their work. Appendix A is a breakdown of who may want to use ASGS for this purpose and why. The rest of this section covers the basic operation of ADCIRC when everything is done manually. It also assumes that one has already prepared all of the input files, including the mesh (fort.14) and the settings file (fort.15).

Step 1: Create a Profile

The concept of a profile in ASGS is not only useful for operators who may be tracking more than one storm or daily forecast. Because ASGS has evolved to support many versions of ADCIRC, it is useful to consider creating a seperate profile for each version of ADCIRC that might be getting used in the same ASGS Shell Environment. Assuming one has already built a version of ADCIRC and they are in the ASGS Shell Environment with the default profile loaded (it's loaded on start, asgsh, unless one specified something different at the commandline). Create a profile and saving a version of ADCIRC to it takes the following steps:

[ASGS (master)] machinename@default-asgs-prod> save profile my-first-adcirc-profile
[ASGS (master)] machinename@my-first-adcirc-profile> load adcirc

Note: load adcirc will warn if no ADCIRCs are currently available. If only one is available, that one will be saved to the profile. If there is more than one ADCIRC build available, then the user will need to select (by number) the ADCIRC to load and save. Also, once an ADCIRC is saved to a profile, it is available via PATH.

ADCIRC is now available via PATH, such that the following commands will display the full paths to the usualy ADCIRC utilities:

[ASGS (master)] machinename@my-first-adcirc-profile> which adcirc
/path/to/adcirc
[ASGS (master)] machinename@my-first-adcirc-profile> which padcirc
/path/to/padcirc
[ASGS (master)] machinename@my-first-adcirc-profile> which adcprep
/path/to/adcprep
...

Step 2: Located and Place Input Files

Step 3: Prepare the Quescript, if necessary

Step 4: Prepare the Parallel Run

Step 5: Submit the Parallel Run to Local Batch System, if necessary

Step 6: Monitoring Running ADCIRC

Step 7: Postprocessing Output Files

Appendix A - ASGS Features Supporting ADCIRC

For ADCIRC Users

For ADCIRC Researchers

For ADCIRC Development

For ADCIRC Real Time Guidance

Appendix B - Troubleshooting ADCIRC

Clone this wiki locally