Fortuna 2.5 User's Guide: Difference between revisions

Line 18:

Once the checkout from the repository is completed, you are ready to compile. <code>cd</code> to the <code>src</code> directory at the top of the source code directory tree and from a <code>csh</code> shell run <code>source g5_modules</code>. This will load the appropriate modules and create the necessary environment for compiling and running. It is tailored to the individual systems that GEOS-5 usually runs on, so it probably won't work elsewhere. After that you can run <code>make install</code>, which will create the necessary executables in the directory <code>''ARCH''/bin</code>, where ''ARCH'' is the local architecture (most often <code>Linux</code>).

== Setting up a Global Model Run ==

The following describes how to set up a global model run. The prodcedure to set up a single column model run is described in [[Fortuna 2.4 Single Column Model]].

=== Using <code>gcm_setup</code> ===

The setup script for global runs, <code>gcm_setup</code>, is in the directory <code>src/Applications/GEOSgcm_App</code>. The following is an example of a session with the setup script, with commentary. :

<pre>

Enter the Experiment ID:

</pre>

Enter a name and hit return. For this example we'll set the experiment ID to "myexp42". Experiment IDs need to have no whitespace and not start with a digit, since it will be the prefix of job names and PBS imposes certain limits on job names.

<pre>

Enter a 1-line Experiment Description:

</pre>

This should be short but descriptive, since it will be used to label plots. It can have spaces, though the string will be stored with underscores for the spaces. Provide a description and hit return.

<pre>

Enter the Lat/Lon Horizontal Resolution: IM JM

or ..... the Cubed-Sphere Resolution: cNN

</pre>

The lat/lon option allows four resolutions: 144x91, 288x181, 576x361 or 1152x721 corresponding rougly to 2, 1, 1/2 and 1/4 degree resolutions. Enter a resolution like so:

<pre>

144 91

</pre>

and hit enter.

<pre>

Enter the Model Vertical Resolution: LM (Default: 72)

</pre>

The current standard is 72 levels, and unless you know what you are doing you should stick with that.

<pre>

Do you wish to run GOCART? (Default: NO or FALSE)

</pre>

GOCART is the interactive chemistry package, as opposed to prescribed chemistry. It incurs a significant performance cost, so unless you know you want it, you should go with the default. The following assumes that you have entered "y".

<pre>

Enter the GOCART Emission Files to use: "CMIP" (Default), "PIESA", or "OPS":

</pre>

Select your favorite emission files here.

<pre>

Enter the AERO_PROVIDER: GOCART (Default) or PCHEM:

</pre>

Here you get to choose again to use interactive or prescribed aerosols.

<pre>

Enter the tag or directory (/filename) of the HISTORY.AGCM.rc.tmpl to use

(To use HISTORY.AGCM.rc.tmpl from current build, Type: Current )

-------------------------------------------------------------------------

Hit ENTER to use Default Tag/Location: (Fortuna-2_4)

</pre>

This provides a default HISTORY.rc (output specification) file. The initial default will be the tag of the build in which you are running <code>gcm_setup</code>. The idea is that you can save a custom <code>HISTORY.rc</code> to the repository and have it checked out for your experiments.

<pre>

This U.S. Government resource is for authorized users only. By accessing

this system you are consenting to complete monitoring with no expectation

of privacy. Unauthorized access or use may subject you to disciplinary

action and criminal prosecution.

===================================================================

Checking out HISTORY.AGCM.rc.tmpl

RCS: /cvsroot/esma/esma/src/Applications/GEOSgcm/Application/HISTORY.AGCM.rc.tmpl,v

VERS: 1.16.2.3

***************

Enter Desired Location for HOME Directory (to contain scripts and RC files)

Hit ENTER to use Default Location:

----------------------------------

Default: /discover/nobackup/aeichman/myexp42

</pre>

This option determines where the experiment's home directory is located -- where the basic job scripts and major RC files (<code>AGCM.rc</code>, <code>CAP.rc</code> and <code>HISTORY.rc</code>) will be located. The first time you run the script it will default to a subdirectory under your account's home directory named <code>geos5</code>, remember what you decide (in <code>~/.HOMDIRroot</code>) and use that as a default in subsequent times the script is run. This initial default is fine, though another possibility is to enter your nobackup space, as shown here. This will place all of the HOME directory files of the experiment together with the rest of them.

<pre>

Enter Desired Location for EXP Directory (to contain model output and restart files)

Hit ENTER to use Default Location:

----------------------------------

Default: /discover/nobackup/aeichman/myexp42

</pre>

This determines the experiment directory, where restart files and various job output is stored. These are the storage-intensive parts and so default to the <code>nobackup</code> space.

<pre>

Enter Location for Build directory containing: src/ Linux/ etc...

Hit ENTER to use Default Location:

----------------------------------

Default: /discover/nobackup/aeichman/Fortuna-2_4

</pre>

This determines which of your local builds is used to create the experiment. It defaults to the build of the script you are running, which is generally a good idea.

<pre>

Current GROUPS: g0620

Enter your GROUP ID for Current EXP: (Default: g0620)

</pre>

This is used for by the job accounting system. If you are not in the default group, you will probably have been informed.

<pre>

-----------------------------------

building file list ... done

GEOSgcm.x

sent 50117242 bytes received 42 bytes 33411522.67 bytes/sec

total size is 50110997 speedup is 1.00

Creating gcm_run.j for Experiment myexp42 ...

Creating gcm_post.j for Experiment myexp42 ...

Creating gcm_plot.j for Experiment myexp42 ...

Creating gcm_archive.j for Experiment myexp42 ...

Creating gcm_regress.j for Experiment myexp42 ...

Creating AGCM.rc for Experiment myexp42 ...

Creating CAP.rc for Experiment myexp42 ...

Creating HISTORY.rc for Experiment myexp42 ...

Done!

-----

Build Directory: /discover/nobackup/aeichman/Fortuna-2_4

----------------

The following executable has been placed in your Experiment Directory:

----------------------------------------------------------------------

/discover/nobackup/aeichman/Fortuna-2_4/Linux/bin/GEOSgcm.x

You must now copy your AGCM Initial Conditions into:

----------------------------------------------------

/discover/nobackup/aeichman/myexp42

</pre>

And the experiment is set up. After you copy initial condition files (aka restarts) to the experiment directory, you can submit your job.

===Do not copy old experiments===

When creating related experiments, you will be tempted to copy the experiment directory tree of an older experiment. '''Do ''not'' copy old experiments, run <code>gcm_setup</code> instead.''' There are numerous instances where an experiment-specific directory is used in the run scripts created from templates by <code>gcm_setup</code> and they will wreak subtle and pervasive havoc if executed in an unexpected environment. This warning is especially true between model versions. A useful and relatively safe exception to this rule is to copy previously used examples of <code>HISTORY.rc</code>. However, you need to change the lines labeled <code>EXPID</code> and <code>EXPDSC</code> to the values in your automatically-generated <code>HISTORY.rc</code> or the plotting will fail.

=== Using restart files ===

Restart files provide the initial conditions for a run, and a set needs to be copied into a fresh experiment directory before running. This includes the file <code>cap_restart</code>, which provides the model starting date and time in text. Restart files themselves are resolution-specific and sometimes change between model versions. As of the current model version, they are flat binary files with no metadata, so they tend to be stored together with restarts of the same provinance with the date either embedded in the filename or in an accompanying <code>cap_restart</code>, typically under a directory indicating the model version.

A cleanly completed model run will leave a set of restarts and the corresponding <code>cap_restart</code> in its experiment directory. Another source is <code>/archive/u/aeichman/restarts</code>. Restarts are also left during runs in date-labeled tarballs in the <code>restarts</code> directory under the experiment directory before being transferred to the user's <code>/archive</code> space. You may have to create the <code>cap_restart</code>, which is simply one line of text with the date of the restart files in the format ''YYYYMMDD HHMMSS'' (with a space).

Failing the above sources, you can convert restarts from different resolutions and model versions, including MERRA, as described in [[Regridding Restarts for Fortuna 2.4]].

@@ Line 18: / Line 18: @@
 Once the checkout from the repository is completed, you are ready to compile.  <code>cd</code> to the <code>src</code> directory at the top of the source code directory tree and from a <code>csh</code> shell run <code>source g5_modules</code>.  This will load the appropriate modules and create the necessary environment for compiling and running.  It is tailored to the individual systems that GEOS-5 usually runs on, so it probably won't work elsewhere.  After that you can run <code>make install</code>, which will create the necessary executables in the directory <code>''ARCH''/bin</code>, where ''ARCH'' is the local architecture (most often <code>Linux</code>).
+== Setting up a Global Model Run ==
+The following describes how to set up a global model run.  The prodcedure to set up a single column model run is described in [[Fortuna 2.4 Single Column Model]].
+=== Using <code>gcm_setup</code> ===
+The setup script for global runs, <code>gcm_setup</code>, is in the directory <code>src/Applications/GEOSgcm_App</code>.  The following is an example of a session with the setup script, with commentary.  :
+<pre>
+ Enter the Experiment ID:
+</pre>
+Enter a name and hit return.  For this example we'll set the experiment ID to "myexp42".  Experiment IDs need to have no whitespace and not start with a digit, since it will be the prefix of job names and PBS imposes certain limits on job names.
+<pre>
+Enter a 1-line Experiment Description:
+</pre>
+This should be short but descriptive, since it will be used to label plots.  It can have spaces, though the string will be stored with underscores for the spaces.  Provide a description and hit return.
+<pre>
+Enter the Lat/Lon Horizontal Resolution: IM JM
+   or ..... the Cubed-Sphere Resolution: cNN
+</pre>
+The lat/lon option allows four resolutions: 144x91, 288x181, 576x361 or 1152x721 corresponding rougly to 2, 1, 1/2 and 1/4 degree resolutions.  Enter a resolution like so:
+<pre>
+91
+</pre>
+and hit enter.
+<pre>
+Enter the Model Vertical Resolution: LM (Default: 72)
+</pre>
+The current standard is 72 levels, and unless you know what you are doing you should stick with that.
+<pre>
+Do you wish to run GOCART? (Default: NO or FALSE)
+</pre>
+GOCART is the interactive chemistry package, as opposed to prescribed chemistry.  It incurs a significant performance cost, so unless you know you want it, you should go with the default.  The following assumes that you have entered "y".
+<pre>
+Enter the GOCART Emission Files to use: "CMIP" (Default), "PIESA", or "OPS":
+</pre>
+Select your favorite emission files here.
+<pre>
+Enter the AERO_PROVIDER: GOCART (Default) or PCHEM:
+</pre>
+Here you get to choose again to use interactive or prescribed aerosols.
+<pre>
+Enter the tag or directory (/filename) of the HISTORY.AGCM.rc.tmpl to use
+(To use HISTORY.AGCM.rc.tmpl from current build, Type:  Current         )
+-------------------------------------------------------------------------
+Hit ENTER to use Default Tag/Location: (Fortuna-2_4)
+</pre>
+This provides a default HISTORY.rc (output specification) file.  The initial default will be the tag of the build in which you are running <code>gcm_setup</code>.  The idea is that you can save a custom <code>HISTORY.rc</code> to the repository and have it checked out for your experiments.
+<pre>
+This U.S. Government resource is for authorized users only.  By accessing
+this system you are consenting to complete monitoring with no expectation
+of privacy.  Unauthorized access or use may subject you to disciplinary
+action and criminal prosecution.
+===================================================================
+Checking out HISTORY.AGCM.rc.tmpl
+RCS:  /cvsroot/esma/esma/src/Applications/GEOSgcm/Application/HISTORY.AGCM.rc.tmpl,v
+VERS: 1.16.2.3
+***************
+Enter Desired Location for HOME Directory (to contain scripts and RC files)
+Hit ENTER to use Default Location:
+----------------------------------
+Default:  /discover/nobackup/aeichman/myexp42
+</pre>
+This option determines where the experiment's home directory is located -- where the basic job scripts and major RC files (<code>AGCM.rc</code>, <code>CAP.rc</code> and <code>HISTORY.rc</code>) will be located.  The first time you run the script it will default to a subdirectory under your account's home directory named <code>geos5</code>, remember what you decide (in <code>~/.HOMDIRroot</code>) and use that as a default in subsequent times the script is run.  This initial default is fine, though another possibility is to enter your nobackup space, as shown here.  This will place all of the HOME directory files of the experiment together with the rest of them.
+<pre>
+Enter Desired Location for EXP Directory (to contain model output and restart files)
+Hit ENTER to use Default Location:
+----------------------------------
+Default:  /discover/nobackup/aeichman/myexp42
+</pre>
+This determines the experiment directory, where restart files and various job output is stored.  These are the storage-intensive parts and so default to the <code>nobackup</code> space.
+<pre>
+Enter Location for Build directory containing:  src/ Linux/ etc...
+Hit ENTER to use Default Location:
+----------------------------------
+Default:  /discover/nobackup/aeichman/Fortuna-2_4
+</pre>
+This determines which of your local builds is used to create the experiment.  It defaults to the build of the script you are running, which is generally a good idea.
+<pre>
+Current GROUPS: g0620
+Enter your GROUP ID for Current EXP: (Default: g0620)
+</pre>
+This is used for by the job accounting system.  If you are not in the default group, you will probably have been informed.
+<pre>
+-----------------------------------
+building file list ... done
+GEOSgcm.x
+sent 50117242 bytes  received 42 bytes  33411522.67 bytes/sec
+total size is 50110997  speedup is 1.00
+Creating gcm_run.j for Experiment myexp42 ...
+Creating gcm_post.j for Experiment myexp42 ...
+Creating gcm_plot.j for Experiment myexp42 ...
+Creating gcm_archive.j for Experiment myexp42 ...
+Creating gcm_regress.j for Experiment myexp42 ...
+Creating AGCM.rc for Experiment myexp42 ...
+Creating CAP.rc for Experiment myexp42 ...
+Creating HISTORY.rc for Experiment myexp42 ...
+Done!
+-----
+Build Directory: /discover/nobackup/aeichman/Fortuna-2_4
+----------------
+The following executable has been placed in your Experiment Directory:
+----------------------------------------------------------------------
+/discover/nobackup/aeichman/Fortuna-2_4/Linux/bin/GEOSgcm.x
+You must now copy your AGCM Initial Conditions into:
+----------------------------------------------------
+/discover/nobackup/aeichman/myexp42
+</pre>
+And the experiment is set up.  After you copy initial condition files (aka restarts) to the experiment directory, you can submit your job.
+===Do not copy old experiments===
+When creating related experiments, you will be tempted to copy the experiment directory tree of an older experiment.  '''Do ''not'' copy old experiments, run <code>gcm_setup</code> instead.'''  There are numerous instances where an experiment-specific directory is used in the run scripts created from templates by <code>gcm_setup</code>  and they will wreak subtle and pervasive havoc if executed in an unexpected environment.  This warning is especially true between model versions.  A useful and relatively safe exception to this rule is to copy previously used examples of <code>HISTORY.rc</code>.  However, you need to change the lines labeled <code>EXPID</code> and <code>EXPDSC</code> to the values in your automatically-generated  <code>HISTORY.rc</code> or the plotting will fail.
+=== Using restart files ===
+Restart files provide the initial conditions for a run, and a set needs to be copied into a fresh experiment directory before running.  This includes the file <code>cap_restart</code>, which provides the model starting date and time in text.  Restart files themselves are resolution-specific and sometimes change between model versions.  As of the current model version, they are flat binary files with no metadata, so they tend to be stored together with restarts of the same provinance with the date either embedded in the filename or in an accompanying <code>cap_restart</code>, typically under a directory indicating the model version.
+A cleanly completed model run will leave a set of restarts and the corresponding <code>cap_restart</code> in its experiment directory.  Another source is <code>/archive/u/aeichman/restarts</code>.  Restarts are also left during runs in date-labeled tarballs in the <code>restarts</code> directory under the experiment directory before being transferred to the user's <code>/archive</code> space.  You may have to create the <code>cap_restart</code>, which is simply one line of text with the date of the restart files in the format ''YYYYMMDD HHMMSS'' (with a space).
+Failing the above sources, you can convert restarts from different resolutions and model versions, including MERRA, as described in  [[Regridding Restarts for Fortuna 2.4]].