Difference between revisions of "Getting Started"

From WikiROMS
Jump to navigationJump to search
m (Text replacement - "ocean.in" to "roms.in")   (change visibility)
(17 intermediate revisions by 3 users not shown)
Line 1: Line 1:
<div class="title">Getting Started</div>
<div class="title">Getting Started</div>
ROMS is a very complex model with many options and capabilities. ROMS
ROMS is a very complex model with many options and capabilities. ROMS is composed of many Fortran files ('''.F'''), a few header files ('''.h'''), various input script files ('''.in'''), a metadata variable definition file ([[varinfo.dat]]), and a single [[makefile]]. The ROMS algorithms are distributed with the following directory structure:
is composed of many Fortran files (*.F), a few header files (*.h),
various input script files (*.in), a metadata variable definition file
([[varinfo.dat]]), and a single [[makefile]]. The ROMS algorithms are
distributed with the following directory structure:


   <span class="blue">
   <span class="twilightBlue">trunk/                              Main trunk directory
  trunk/                              Main trunk directory
       /Atmosphere/                    Atmosphere models root directory
       /Atmosphere/                    Atmosphere models root directory
                   /COAMPS              COAMPS root directory (empty)
                   /COAMPS              COAMPS root directory (empty)
Line 14: Line 9:
       /Data/                          Input data root directory
       /Data/                          Input data root directory
             /ROMS/                    ROMS data root directory
             /ROMS/                    ROMS data root directory
                 /CDL                  ROMS Metadata design
                 /CDL                  ROMS NetCDF metadata design
                 /Forcing              Input test cases forcing NetCDF files
                 /Forcing              Input test cases forcing NetCDF files
                 /Grid                Input test cases grid NetCDF files
                 /Grid                Input test cases grid NetCDF files
Line 21: Line 16:
           /ARPACK                    Arpack eigenvalue problems library
           /ARPACK                    Arpack eigenvalue problems library
           /MCT                        Modeling Coupling Tool library
           /MCT                        Modeling Coupling Tool library
          /MCT_WRF                    WRF Modeling Coupling Tool library
       /Master                        Main standalone and coupling programs
       /Master                        Main standalone and coupling programs
       /ROMS/                          ROMS root directory
       /ROMS/                          ROMS root directory
             /Adjoint                  Adjoint model
             /Adjoint                  Adjoint model
                    /Biology          Adjoint biology/ecosystem models
             /Bin                      Executable scripts
             /Bin                      Executable scripts
             /Drivers                  Computational drivers
             /Drivers                  Computational drivers
Line 32: Line 27:
             /Modules                  Declaration modules
             /Modules                  Declaration modules
             /Nonlinear                Nonlinear model
             /Nonlinear                Nonlinear model
                      /Biology        Nonlinear biology/ecosystem models
                      /Sediment        Nonlinear sediment transport model
             /Obsolete                  Discontinued files
             /Obsolete                  Discontinued files
             /Programs                  Support programs
             /Programs                  Support programs
             /SeaIce                    Sea-ice model (empty)
             /SeaIce                    Sea-ice model (empty)
             /Representer              Representer model
             /Representer              Representer model
                        /Biology      Representer biology/ecosystem models
             /Tangent                  Tangent linear model
             /Tangent                  Tangent linear model
                    /Biology          Tangent linear biology/ecosystem models
             /Utility                  Generic utility files
             /Utility                  Generic utility files
             License_ROMS.text          Open source license
             License_ROMS.text          Open source license
Line 42: Line 41:
       /User/                          ROMS User interface root directory
       /User/                          ROMS User interface root directory
             /External                  User standard input scripts
             /External                  User standard input scripts
             /Functionals              User analytical expresions templates
             /Functionals              User analytical expressions templates
             /Include                  User application header files
             /Include                  User application header files
       /WAVES/                        Waves models root directory
       /WAVES/                        Waves models root directory
Line 49: Line 48:
                   /Src                SWAN model</span>
                   /Src                SWAN model</span>


ROMS uses extensively [[C-preprocessing]] to activate and/or deactivate
ROMS uses [[C-preprocessing]] extensively to activate and/or deactivate
the various numerical and physical algorithm [[Options | options]]. It also uses
the various numerical and physical algorithm [[Options | options]]. It also uses
[[NetCDF]] to manage input and output data streams. It is highly
[[NetCDF]] to manage input and output data streams. It is highly
recommended that first time users learn the basics about NetCDF
recommended that first time users learn the basics of NetCDF
before starting working with ROMS.
before working with ROMS.


==Basic Steps==
==Basic Steps==


* Register at the ROMS website ([http://www.myroms.org www.myroms.org]) to get access to the algorithms and other user privileges. Select an username and password which will be used in the future to login and post messages in the ROMS forum, algorithm downloads, and contributing to wikiROMS.
* Register at the ROMS website ([http://www.myroms.org www.myroms.org]) to get access to the algorithms and other user privileges. Select a '''username''' and '''password''' which will be used in the future to login and post messages on the ROMS forum, algorithm downloads, and contributing to wikiROMS.


* Use a [http://subversion.tigris.org/ Subversion] client to "checkout" the latest version of the ROMS trunk (Detailed information can be found [[Subversion | here]]).
* Make sure that you have the following required software in your computer before attempting to compile and run an application:
** [http://subversion.tigris.org/ Subversion] client to download source
** Fortran 90 or Fortran 95 compiler
** [http://gcc.gnu.org/onlinedocs/cpp/ cpp] program for [[C-preprocessing]] ROMS source code.
** [http://www.gnu.org/software/make/ GNU make] version '''3.81''' or higher to compile ROMS
** [http://www.perl.org/ Perl] interpreter program
** [http://www.unidata.ucar.edu/software/netcdf/ NetCDF] library, with Fortran 90 interface
** Message Passing Interface (MPI) library to run in parallel on a distributed-memory system


* Make roms by typing 'make' This will run the makefile at the top of the directory structure. This file will include a special makefile particular to your operating system and compiler, found in the Compilers subdirectory.  You may need to edit this so that ROMS can find your netcdf libraries.  You can also modify the compiler flags here if you want to, say, compile ROMS to run with the MPI libraries.
* Use a [[Subversion | Subversion]] client to '''checkout''' the latest version of the ROMS '''trunk'''. It is highly recommended that you checkout the code on the same system that you will be compiling and running the code on to avoid file format issues.


* TIP:  You can type make -j <number of processors> to make ROMS faster. This will spread the make process over more than one processor. Often, you can also compile in debug mode (FFLAG=-g) -- that will typically compile much faster, so you can make sure the code compiles.  However, it will cause the code to run *much* more slowly.  Usually, you will want to optimize the code with a compiler flag -O.  We have found that level 2 optimization (FFLAG=-O2) is usually good enough, and compiles faster than higher level optimization.
* We recommend that you use the included '''[[build Script|build script]]''' to compile and link ROMS. This will set up your build environment and execute the [[gmake|make]] command to build the default ROMS [[UPWELLING_CASE | upwelling]] application. This process allows you to avoid editing the [[makefile]]. Please visit the '''[[build Script|build script]]''' page for more detailed instructions.
** You can also type <span class="red">make</span> at the top of the directory structure where the [[makefile]] is located but we do not recommend this process because it requires changing the ROMS files which can cause conflicts when you update you ROMS code.


* TIP: You can also build ROMS ''without'' modifying the makefile or anything else in the source distribution by using the "build.sh" script.  See a [[BuildSH | detailed example of using "build.sh" to build the LAKE_SIGNELL test case]].


==Questions from New Users==
{{note}}'''Note:''' To speed compilation, you may want to add the '''-j <n>''' flag to the build command (i.e. '''build.sh -j 4''') where '''<n>''' is the number of processors you wish to compile with. Even single processor machines can benefit from the -j flag with '''<n>&nbsp;=&nbsp;2'''.


* My build finished with no errors. Where is the ROMS executable?
It is either in oceanS (serial), oceanO (OpenMP), oceanM (MPI), or oceanG (debug). Check the makefile to see which options are on.


* What do I have to do to run an application?
{{note}}'''Note:''' To make sure your application can compile successfully, you might want to set '''USE_DEBUG''' to '''on''' in the [[build Script|build script]] since it will compile faster. Once your application can compile you can unset '''USE_DEBUG''' in order to create an optimized executable. Please visit the '''[[build Script|build script]]''' page for more information
There are basically four levels of complexity in running an application.
# Canned applications that come with the ROMS distribution and don't need input. These can be run by editing ./Include/cppdefs.h to #define one (all others should be #undef) of the pre-defined model applications. Then make (good practice to make clean first) and, if you are lucky, the program will build. It should run with the command ./oceanS
# Canned applications that come with ROMS and require input files. Same as above, but now they have to be run with a command like ./oceanS < External/ocean_some_predefined_app.in. These may also require netCDF input files with names like ocean_some_predefined_app.nc.
# User-specified applications with no input data. These are the best test beds for new users or new algorithms. They consist of a set of selected cpp options in /Include/cppdefs.h, a user-generated .in file, and usually modifications to /Nonlinear/analytical.F to specify intial, boundary, and forcing conditions internally.
# User applications with input data...the real deal. These require changes to cppdefs.h, some_app.in, and appropriate input files for initialization and forcing.


*Why the _r8 at the end of real constants?
 
Some computers use 32 bits for single precision real numbers and 64 bits for double precision, and some use 64 and 128, respectively. For consistent results on various machines, ROMS takes advantage of the intrinsic F90/95 function SELECTED_REAL_KIND( ). (See ./Modules/mod_kinds.F). This allows you to associate an integer parameter with a specific data type...in this case r8 is associated with 64-bit precision. RTFM (Read the Fortran90 Manual), or better yet, chapter 11 in [[Bibliography#ChapmanSJ_2004a | Chapman, 2004]].
{{note}}'''Note:''' In SVN revision 933 (January 26, 2019) all <span class="red">ocean_*.in</span> files were renamed to <span class="red">roms_*.in</span> and all <span class="red">ocean*</span> ROMS executables were renamed to <span class="red">roms*</span> in order to facilitate and clarify model coupling efforts. More information can be found in the ROMS repository [https://www.myroms.org/projects/src/ticket/794 Trac ticket #794]. If you are working with a ROMS release prior to revision 933 you will need to replace <span class="red">roms_upwelling.in</span> with <span class="red">ocean_upwelling.in</span> and <span class="red">romsS</span>, <span class="red">romsM</span>, or <span class="red">romsO</span> with <span class="red">oceanS</span>, <span class="red">oceanM</span>, or <span class="red">oceanO</span> in all commands below.
 
* To run ROMS in serial, just type: <div class="box"><span class="red">romsS &lt; ROMS/External/roms_upwelling.in &gt; & log &</span></div>or to run in parallel (distributed-memory) on two processors: <div class="box"><span class="red">mpirun -np 2 romsM ROMS/External/roms_upwelling.in &gt; & log &</span></div>or to run in parrallel (shared-memory) on two processors:<div class="box"><span class="red">setenv OMP_NUM_THREAD 2<br>romsO < ROMS/External/roms_upwelling.in > & log &</span></div>Here, the the file <span class="red">ROMS/External/roms_upwelling.in</span> contains all the input parameters to required by this application. Visit [[roms.in]] for more information.
 
{{note}}Notice that in distributed-memory, the leading <span class="red">&lt;</span> is omitted so all parallel threads can read and process this input script without any communications in between.

Revision as of 15:13, 17 July 2019

Getting Started

ROMS is a very complex model with many options and capabilities. ROMS is composed of many Fortran files (.F), a few header files (.h), various input script files (.in), a metadata variable definition file (varinfo.dat), and a single makefile. The ROMS algorithms are distributed with the following directory structure:

 trunk/                               Main trunk directory
      /Atmosphere/                    Atmosphere models root directory
                 /COAMPS              COAMPS root directory (empty)
                 /WRF                 WRF root directory (empty)
      /Compilers/                     make configuration files
      /Data/                          Input data root directory
           /ROMS/                     ROMS data root directory
                /CDL                  ROMS NetCDF metadata design
                /Forcing              Input test cases forcing NetCDF files
                /Grid                 Input test cases grid NetCDF files
                /Initial              Input test cases initial conditions NetCDF files
      /Lib/                           External libraries
          /ARPACK                     Arpack eigenvalue problems library
          /MCT                        Modeling Coupling Tool library
      /Master                         Main standalone and coupling programs
      /ROMS/                          ROMS root directory
           /Adjoint                   Adjoint model
                   /Biology           Adjoint biology/ecosystem models
           /Bin                       Executable scripts
           /Drivers                   Computational drivers
           /External                  Standard input scripts
           /Functionals               Analytical expression header files
           /Include                   Test cases configuration header files
           /Modules                   Declaration modules
           /Nonlinear                 Nonlinear model
                     /Biology         Nonlinear biology/ecosystem models
                     /Sediment        Nonlinear sediment transport model
           /Obsolete                  Discontinued files
           /Programs                  Support programs
           /SeaIce                    Sea-ice model (empty)
           /Representer               Representer model
                       /Biology       Representer biology/ecosystem models
           /Tangent                   Tangent linear model
                   /Biology           Tangent linear biology/ecosystem models
           /Utility                   Generic utility files
           License_ROMS.text          Open source license
           Version                    SVN Version information
      /User/                          ROMS User interface root directory
           /External                  User standard input scripts
           /Functionals               User analytical expressions templates
           /Include                   User application header files
      /WAVES/                         Waves models root directory
            /SWAN                     SWAN root directory
                 /External            SWAN input data and standard input files
                 /Src                 SWAN model

ROMS uses C-preprocessing extensively to activate and/or deactivate the various numerical and physical algorithm options. It also uses NetCDF to manage input and output data streams. It is highly recommended that first time users learn the basics of NetCDF before working with ROMS.

Basic Steps

  • Register at the ROMS website (www.myroms.org) to get access to the algorithms and other user privileges. Select a username and password which will be used in the future to login and post messages on the ROMS forum, algorithm downloads, and contributing to wikiROMS.
  • Make sure that you have the following required software in your computer before attempting to compile and run an application:
    • Subversion client to download source
    • Fortran 90 or Fortran 95 compiler
    • cpp program for C-preprocessing ROMS source code.
    • GNU make version 3.81 or higher to compile ROMS
    • Perl interpreter program
    • NetCDF library, with Fortran 90 interface
    • Message Passing Interface (MPI) library to run in parallel on a distributed-memory system
  • Use a Subversion client to checkout the latest version of the ROMS trunk. It is highly recommended that you checkout the code on the same system that you will be compiling and running the code on to avoid file format issues.
  • We recommend that you use the included build script to compile and link ROMS. This will set up your build environment and execute the make command to build the default ROMS upwelling application. This process allows you to avoid editing the makefile. Please visit the build script page for more detailed instructions.
    • You can also type make at the top of the directory structure where the makefile is located but we do not recommend this process because it requires changing the ROMS files which can cause conflicts when you update you ROMS code.


NoteNote: To speed compilation, you may want to add the -j <n> flag to the build command (i.e. build.sh -j 4) where <n> is the number of processors you wish to compile with. Even single processor machines can benefit from the -j flag with <n> = 2.


NoteNote: To make sure your application can compile successfully, you might want to set USE_DEBUG to on in the build script since it will compile faster. Once your application can compile you can unset USE_DEBUG in order to create an optimized executable. Please visit the build script page for more information


NoteNote: In SVN revision 933 (January 26, 2019) all ocean_*.in files were renamed to roms_*.in and all ocean* ROMS executables were renamed to roms* in order to facilitate and clarify model coupling efforts. More information can be found in the ROMS repository Trac ticket #794. If you are working with a ROMS release prior to revision 933 you will need to replace roms_upwelling.in with ocean_upwelling.in and romsS, romsM, or romsO with oceanS, oceanM, or oceanO in all commands below.

  • To run ROMS in serial, just type:
    romsS < ROMS/External/roms_upwelling.in > & log &
    or to run in parallel (distributed-memory) on two processors:
    mpirun -np 2 romsM ROMS/External/roms_upwelling.in > & log &
    or to run in parrallel (shared-memory) on two processors:
    setenv OMP_NUM_THREAD 2
    romsO < ROMS/External/roms_upwelling.in > & log &
    Here, the the file ROMS/External/roms_upwelling.in contains all the input parameters to required by this application. Visit roms.in for more information.

NoteNotice that in distributed-memory, the leading < is omitted so all parallel threads can read and process this input script without any communications in between.