WIP: ASGS ADCIRC ONLY - StormSurgeLive/asgs GitHub Wiki
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
...