Application Set-up: Difference between revisions
No edit summary (change visibility) |
m Text replacement - "\.in" to ".in" (change visibility) |
||
| (24 intermediate revisions by 4 users not shown) | |||
| Line 1: | Line 1: | ||
<div class="title"> | <div class="title">Application Set-up</div> | ||
New users to ROMS should read the | '''New users to ROMS should read the [[Getting Started]] guide. For information on the ROMS algorithms and internal workings of the code see the [[Technical Reference]]. You should familiarize yourself with the [[C_Preprocessor]].''' | ||
Most users configuring a typical application of the forward simulation model will need to edit only the few files described below. For so-called ''realistic'' applications of particular coastal regions or open ocean basins, most of the work in configuring the model is actually in the creation of the various input netcdf files. | '''Most users configuring a typical application of the forward simulation model will need to edit only the few files described below. For so-called ''realistic'' applications of particular coastal regions or open ocean basins, most of the work in configuring the model is actually in the creation of the various input netcdf files.''' | ||
__TOC__ | __TOC__ | ||
== | == Case Name == | ||
The [[makefile]] | The first thing you need to come up with when designing a new application is a name for your case. This name is provided via [[makefile#ROMS_APPLICATION | ROMS_APPLICATION]], either via the [[makefile]] or the [[build Script]]. This name should be reasonably short, all uppercase, with spaces converted to underscores. For example, let's say we pick the name '''WIKI_TEST'''. This name gets defined during the build, so you can add code protected by '''#ifdef WIKI_TEST''' as needed. | ||
{{note}}This would be a good time to either copy the [[makefile]] or the [[build Script]] to create one specific to this case prior to editing it. | |||
== Case-specific Include File == | |||
Each application has its own include file, included by [[cppdefs.h]]. The name of this file is the name of your application ('''WIKI_TEST''' here) turned into lower case, with '.h' appended ('''wiki_test.h'''). The location of this file is set by [[makefile#MY_HEADER_DIR | MY_HEADER_DIR]], pointing to '''User/Include''' or some other location of your choosing. | |||
The complete list of options to be set prior to compilation are listed in [[Options]]. Place those you need in the '''wiki_test.h''' file. These include algorithm choices (e.g. advection and turbulence closure schemes), boundary conditions, output options (averages, diagnostics, stations, floats), and application modules (biology, sediments). Each line should be of the form: | |||
#define SOME_VAR | |||
Note that any undefined variable need not be mentioned. | |||
<br />{{warning}} '''Warning:''' If you copy a predefined application from '''ROMS/Include''' as a template for your application you '''must''' rename it. If you don't change the name, ROMS will use the one in '''ROMS/Include''' and your file will be ignored during the build procedure. | |||
== Functionals == | |||
Some of the '''cpp''' [[Options]] have names beginning with '''ANA_'''. For each one of these, you will be expected to provide an analytic expression for the field in question in the corresponding include file. These files are listed in [[Functionals]] and their location is determined by [[makefile#MY_ANALYTICAL_DIR | MY_ANALYTICAL_DIR]]. You may chose to copy those from '''User/Functionals''' to some new directory and place your version of the assignments within: | |||
#ifdef WIKI_TEST | |||
! Set weird and wonderful winds | |||
... | |||
#endif | |||
This makes it easy to search for later, if nothing else. | |||
== Input Parameter Files == | == Input Parameter Files == | ||
ROMS reads several input parameter files at run time. File [[ | ROMS reads several input parameter files at run time. File [[roms.in]] controls the fundamental behavior of the forward model run, and directs ROMS to other input files such as [[stations.in]], [[floats.in]] etc that may or may not be required depending on the options that are active. It might be wise to copy '''roms.in''' to '''roms_wiki_test.in''' prior to making any changes. | ||
=== [[ | === [[roms.in]] === | ||
The [[ | The [[roms.in]] file is used to set many parameter values that can be altered without recompiling. In serial execution, roms.in is read from the UNIX standard input. In parallel execution using [[MPI]], the roms.in file is processed in parallel by all threads so the usage syntax is different. See [[Getting_Started]] for guidance. | ||
Other input files read when certain application options are activated are: | Other input files read when certain application options are activated are: | ||
| Line 41: | Line 47: | ||
=== [[biology.in]] === | === [[biology.in]] === | ||
== varinfo.dat == | === [[sediment.in]] === | ||
== [[varinfo.dat]] == | |||
The [[varinfo.dat]] file manages features of input/output through netcdf files. | |||
The most important function of varinfo.dat is to specify the netcdf variable name associated with the internal (to ROMS) index variable name. The index variable name is set in the code, but the name in the netcdf file can be changed by the user by editing varinfo.dat. | |||
The units entry in varinfo.dat shows the default units assumed by ROMS but for input variables this can be changed this through an input scale factor. | |||
These features are described in more detail at [[varinfo.dat]]. | |||
== Input Netcdf Files == | == Input Netcdf Files == | ||
Latest revision as of 17:37, 8 January 2021
New users to ROMS should read the Getting Started guide. For information on the ROMS algorithms and internal workings of the code see the Technical Reference. You should familiarize yourself with the C_Preprocessor.
Most users configuring a typical application of the forward simulation model will need to edit only the few files described below. For so-called realistic applications of particular coastal regions or open ocean basins, most of the work in configuring the model is actually in the creation of the various input netcdf files.
Case Name
The first thing you need to come up with when designing a new application is a name for your case. This name is provided via ROMS_APPLICATION, either via the makefile or the build Script. This name should be reasonably short, all uppercase, with spaces converted to underscores. For example, let's say we pick the name WIKI_TEST. This name gets defined during the build, so you can add code protected by #ifdef WIKI_TEST as needed.
This would be a good time to either copy the makefile or the build Script to create one specific to this case prior to editing it.
Case-specific Include File
Each application has its own include file, included by cppdefs.h. The name of this file is the name of your application (WIKI_TEST here) turned into lower case, with '.h' appended (wiki_test.h). The location of this file is set by MY_HEADER_DIR, pointing to User/Include or some other location of your choosing.
The complete list of options to be set prior to compilation are listed in Options. Place those you need in the wiki_test.h file. These include algorithm choices (e.g. advection and turbulence closure schemes), boundary conditions, output options (averages, diagnostics, stations, floats), and application modules (biology, sediments). Each line should be of the form:
#define SOME_VAR
Note that any undefined variable need not be mentioned.
Warning: If you copy a predefined application from ROMS/Include as a template for your application you must rename it. If you don't change the name, ROMS will use the one in ROMS/Include and your file will be ignored during the build procedure.
Functionals
Some of the cpp Options have names beginning with ANA_. For each one of these, you will be expected to provide an analytic expression for the field in question in the corresponding include file. These files are listed in Functionals and their location is determined by MY_ANALYTICAL_DIR. You may chose to copy those from User/Functionals to some new directory and place your version of the assignments within:
#ifdef WIKI_TEST ! Set weird and wonderful winds ... #endif
This makes it easy to search for later, if nothing else.
Input Parameter Files
ROMS reads several input parameter files at run time. File roms.in controls the fundamental behavior of the forward model run, and directs ROMS to other input files such as stations.in, floats.in etc that may or may not be required depending on the options that are active. It might be wise to copy roms.in to roms_wiki_test.in prior to making any changes.
roms.in
The roms.in file is used to set many parameter values that can be altered without recompiling. In serial execution, roms.in is read from the UNIX standard input. In parallel execution using MPI, the roms.in file is processed in parallel by all threads so the usage syntax is different. See Getting_Started for guidance.
Other input files read when certain application options are activated are:
stations.in
floats.in
biology.in
sediment.in
varinfo.dat
The varinfo.dat file manages features of input/output through netcdf files.
The most important function of varinfo.dat is to specify the netcdf variable name associated with the internal (to ROMS) index variable name. The index variable name is set in the code, but the name in the netcdf file can be changed by the user by editing varinfo.dat.
The units entry in varinfo.dat shows the default units assumed by ROMS but for input variables this can be changed this through an input scale factor.
These features are described in more detail at varinfo.dat.
Input Netcdf Files
Coordinates
Grid and bathymetry, and vertical s-coordinate stretching
Initial conditions
Initial conditions, restart, and using output files (history and averages) for input
Forcing files
Surface fluxes, atmospheric boundary layers, tides
Open boundary condition data
boundary file formats and conventions, tides
