build roms

Build Script - build.sh, build.bash

As mentioned in makefile, you need to provide settings for some user-defined choices before you can compile ROMS. If you have more than one application (or more than one compiler), you may get tired of editing the makefile. One option is to have a makefile for each configuration, then type:

 make -f makefile.circle_pgi

for instance. If that's too cumbersome, there's also an option of keeping track of the user-defined choices in a build script. There are now two of these scripts in the ROMS/Bin directory: build.sh (which is surprisingly a csh script) and build.bash. The build scripts use environment variables to provide values for the user-defined make variables, overwriting those found in the ROMS makefile. Just as in the multiple makefile option, you will need as many copies of the build script as you have applications. The scope of these variables is local to the build script, allowing you to compile different applications at the same time from the same sources as long as each $(SCRATCH_DIR) is unique.

Usage:

./build.sh [options]

Options:

-j [N] Compile in parallel using N CPUs. Omit argument to compile
on all available CPUs.
-noclean Do not clean already compiled objects.

Example:

./build.sh -j 2

There is a section (the one from build.sh is shown below) in the the build scripts to make it easier to switch between different compilers and MPI implementations. This will only apply to MPI implementations that use the mpif90 wrapper script (MPICH, MPICH2, OpenMPI, etc.).

if ($?USE_MPIF90) then
switch ($FORT)

case "ifort"
# setenv PATH /opt/intelsoft/mpich/bin:$PATH
# setenv PATH /opt/intelsoft/mpich2/bin:$PATH
setenv PATH /opt/intelsoft/openmpi/bin:$PATH
breaksw

case "pgi"
setenv PATH /opt/pgisoft/mpich/bin:$PATH
# setenv PATH /opt/pgisoft/openmpi/bin:$PATH
breaksw

case "g95"
# setenv PATH /opt/g95soft/mpich2/bin:$PATH
setenv PATH /opt/g95soft/openmpi/bin:$PATH
breaksw

endsw
endif

Keep in mind that you need to adjust the paths to you MPI implementations for your particular system. You must also set USE_MPIF90 to on.

The path of the libraries required by ROMS can be set using environment variables which take precedence over the values specified in the makefile macro definitions file (Compilers/*.mk). If so desired, uncomment the local USE_MY_LIBS definition in the build script and edit the paths to your values. For most applications, only the location of the NetCDF library (NETCDF_LIBDIR) and include directory (NETCDF_INCDIR) are needed. Below is an except from this section

setenv USE_MY_LIBS on

if ($?USE_MY_LIBS) then
switch ($FORT)

case "ifort"
setenv ARPACK_LIBDIR /opt/intelsoft/PARPACK
setenv ESMF_DIR /opt/intelsoft/esmf
setenv ESMF_OS Linux
setenv ESMF_COMPILER ifort
setenv ESMF_BOPT O
setenv ESMF_ABI 64
setenv ESMF_COMM mpich
setenv ESMF_SITE default
setenv HDF5_LIBDIR /opt/intelsoft/hdf5/lib
setenv MCT_INCDIR /opt/intelsoft/mct/include
setenv MCT_LIBDIR /opt/intelsoft/mct/lib
setenv NETCDF_INCDIR /opt/intelsoft/netcdf/include
setenv NETCDF_LIBDIR /opt/intelsoft/netcdf/lib
setenv PARPACK_LIBDIR /opt/intelsoft/PARPACK
breaksw

. . .

case "gfortran"
setenv ARPACK_LIBDIR /opt/gfortransoft/PARPACK
setenv HDF5_LIBDIR /opt/gfortransoft/hdf5/lib
setenv MCT_INCDIR /opt/gfortransoft/mct/include
setenv MCT_LIBDIR /opt/gfortransoft/mct/lib
setenv NETCDF_INCDIR /opt/gfortransoft/netcdf/include
setenv NETCDF_LIBDIR /opt/gfortransoft/netcdf/lib
setenv PARPACK_LIBDIR /opt/gfortransoft/PARPACK
breaksw

endsw
endif

The new structure of ROMS (version 3.0 or higher) allows user specific CPP definitions and analytical options to be set in a small number of separate standalone header files. Therefore, users no longer have to modify small blocks of code within huge files as was necessary in previous versions (cppdefs.h and analytical.F). This makes it easy to distribute the configuration for a specific application via a small number of source code related files plus the inputs (grid, initial conditions, and forcing NetCDF files), while allowing users of the application to keep current with central code improvements via svn. This also takes care of all licensing issues. You are free to include your own statement of your contributions in the files you distribute. The license and copyright statements by the ROMS developer group remain in the source code distributed at www.myroms.org.

We recommend that users work with a local source code that is regularly updated with the official version at the ROMS svn repository using svn update. This will allow bug fixes and new code developments to be pushed out to users and minimize the risk of a user unwittingly working with code with known flaws. There are a few standalone applications in ROMS website Datasets menu. The user can download any of these set-ups. Note that these applications do not include the source code since the user can checkout the latest version of ROMS from the svn repository. We usually create a Projects root directory containing all applications. For example, the double gyre test case (double_gyre.tar.gz) has the following directory structure:

 Projects                               root directory 
         /double_gyre                   idealized double gyre test case 
                     /Data              input NetCDF files 
                     /Forward           nonlinear model, ensembles 
                     /IS4DVAR           incremental, strong contraint 4DVar 
                     /OBS               data assimilation observations

If you check the IS4DVAR sub-directory, you will find the following files:

 Projects 
         /double_gyre 
                     /IS4DVAR 
                             /build.sh
                             /double_gyre.h
                             /job_is4dvar.sh
                             /is4dvar.in
                             /ocean_double_gyre.in
                             /s4dvar.in

Notice that there is a local copy of the header file double_gyre.h containing the CPP options to use in this application. We highly recommend that the user have a local copy of the header file instead of editing the distributed files in the ROMS/Include directory. During the compilation build.sh will direct make to use the appropriate one.

Environment Variables

Currently, the build.sh and build.bash set the following environment variables described in makefile as well as a few local to the scripts:

MY_PROJECT_DIR

This is used in setting SCRATCH_DIR and BINDIR.

MY_ROMS_SRC

Set the path to the user's local current ROMS source code. This is used so that the script can be run from any directory, not necessarily only from the top ROMS directory.

Summary

The purpose of the build script is to protect you from ever having to look at the makefile directly. If you find that you need to modify something in the ROMS compilation system, you should be familiar with the material in gmake.