ASGS Compiling ADCIRC - StormSurgeLive/asgs GitHub Wiki

Introduction

ASGS contains advanced support for managing ADCIRC version building official upstream versions of ADCIRC. There is also support for existing ADCIRC code that might have been modified starting with an official version.

This document will describe ADCIRC building support and provide a few tips about using the ASGS Shell Environment (asgsh) as a platform for managing ADCIRC compiling, debugging, and development activities.

Assumptions:

This guide assumes ASGS has been installed [^1] and one is able to launch the ASGS Shell from the commandline.
This guide also assumes one has access to the ADCIRC code repositories on GitHub. See [^2].

Quick Start

Start the ASGS Shell Environment, usually called asgsh with the single command:

login> ./asgsh
issue the command, build adcirc; it will present you with a menu of choices similar to the following:

 ||ASGS Supported ADCIRC versions||
 |~~~VERSION~~~~~~~~~~~~~~~~~~~~~~~~~~~~~DESCRIPTION
 |1 ) latest-stable                     | Most stable SHA of the upstream development branch (90b399f)       |
 |2 ) latest-stable-bkp                 | Most stable SHA of the upstream development branch (90b399f)       |
 |3 ) latest-upstream                   | Latest upstream development HEAD (bleeding edge)                   |
 |4 ) noaa.stofs.2d.glo.v1.1.0r2        | upstream version tagged, noaa.stofs.2d.glo.v1.1.0r2                |
 |5 ) v53release                        | latest upstream v53                                                |
 |6 ) v53release-adcircpolate           | v53release with experimental adaptive mesh refinement (TACC/ND)    |
 |7 ) v53release-gfortran-10            | v53 with build support for gfortran 10                             |
 |8 ) v53release-testsuite              | v53 with backported utilities for upstream testsuite               |
 |9 ) v55-GLOBAL                        | publicly available ADCIRC v55 (10.5281/zenodo.3911282)             |
 |10) v55.01                            | upstream version v55.01                                            |
 |11) v55.01-5bc04d6                    | upstream version v55.01 SHA 5bc04d6                                |
 |12) v55release                        | short lived "v55release"                                           |
 |13) v55release-swan-gfortran-10       | v55release with build support for gfortran >= 10                   |
 |14) custom                            | select this option for custom directory                            |
 --
  
 What supported 'version' of the ADCIRC source do you wish to build (by name or select 1-14)? [latest-stable]

It is important to note, that the menu items (except the custom option) is listed by virtue of existing as a directory inside of $SCRIPTDIR/patches/ADCIRC. See the following section on adding or modifying ADCIRC patches.

Select a VERSION by the name present in the column or by menu number (note: The menu above is subject to change, but is essentially what will be seen. Once invoked, a user may specify a menu number or the string under the VERSION heading.)
Follow the prompts, and it will build ADCIRC (note: for custom, the wizard will ask for a path to a local directory containing ADCIRC source code; all others use the upstream ADCIRC git repo to get the source.)

Once ADCIRC is built, then the version of ADCIRC will be available for the following asgsh commands:

list adcirc - enumerates ADCIRC versions that have been registed in asgsh * load adcirc - loads specified ADCIRC into PATH and saves it to the current asgsh profile

The ADCIRC binaries are located in the directory, $ADCIRCBASE/work.

(TODO: need a document on, Working with ASGS Profiles ...)

The file, $ADCIRCBASE/adcirc.bin.buildinfo.json, contains all details regarding the build parameters; which can be useful for debugging and tracking experiments. $ADCIRCBASE/asgs-build.sh contains the actual build commands used to compile ADCIRC.

Adding or Modifying ADCIRC Patch Sets

See Adding and Modifying ADCIRC Patch Sets.

Addition Information

All versions above custom are offically supported by virtue of their being a directory for it in $SCRIPTDIR/patches/ADCIRC. Each supported version has its own directory and a set of patches that will get applied. They are also all tied to a particular upstream ADCIRC by git branch, tag, or commit SHA.

Working with supported `VERSION`s of ADCIRC

A version of ADCIRC is supported if a directory for it exists in $SCRIPTDIR/patches/ADCIRC. Each version directory contains a set of source code diff (i.e., diff or git diff) files that are then applied during the progression of the ADCIRC build wizard to some official code from the upstream repository using the patch command. Creating and maintaining patchsets is beyond the scope of this document, but is something that should be captured in a document.

(TODO: need a document on, Working with ADCIRC patchsets in ASGS ...)

Working with zipped archives of ADCIRC

ADCIRC source code is publicly available on a particular open source software site as a .zip file; and ASGS supports the downloading and building of this remote .zip as a demonstration of the capability to support remote methods of distribution in addition to source code in git repositories or already prepared on a local file system.

Working with `custom` ADCIRC Source Directories

The last entry in the menu above indicates that the user has their own ADCIRC source code, and would like to build it and register it within ASGS. This allows for further customization; and it even makes ASGS an attractive platform for ADCIRC studies, research, development, and testing.

Two differences between a custom built ADCIRC and a supported version of ADCIRC are:

custom built ADCIRC has no patches applied to it (this may change in the future if and when needed)
supported ADCIRCs get the initial source code directly from the upstream git repository; from there, the patches are applied using patch. It is this patched code that is compiled.

How Does ADCIRC Get Registered with ADCIRC?

Once ADCIRC is successfully built, a profile is created inside of the directory, $SCRIPTDIR/.adirc-meta. This file is basically a set of exportd shell environment variables that are used by the load adcirc command to update important variables like: PATH, LD_LIBRARY_PATH, and LD_INCLUDE_PATH.

ASGS lite

One may use ASGS just for ADCIRC by installing a minimal configuratin of ASGS. Since only netCDF and HDF5 are required to be present, the following init-asgs.sh command will provide a minimal asgsh environment that may then be used to manage ADCIRC:

login> ./init-asgs.sh -x "--run-steps openmpi,hdf5,netcdf"

The installation time for ASGS will be minimized here since it only has to build locally used netCDF and HDF5. And everything else is skipped (e.g., perl, etc). Once this ASGS lite version is installed, ./asgsh is available for use and the information in this document applies completely.

If mpif90 is detected as being available via PATH, then the openmpi step will be skipped.

Conclusion

This document is a living document. If information is found lacking, please file a GitHub issue to add the missing information if it would be helpful. And please reach out to us if there are any questions or if there are needs or ideas that could help make this document and ADCIRC build support in ASGS even better!