Heracles 4.0 User's Guide: Difference between revisions

(4 intermediate revisions by the same user not shown)

Line 23:

=== 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. :

Line 28:

Line 29:

Enter the Experiment ID:

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 the queue system imposes certain limits on job names.

Line 36:

Line 38:

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.

Enter an Experiment Source Tag for History (Default: Heracles-4_0):

The setup script extracts the repository tag of the model you checked out into your sandbox, checks out that tag from the repository, and creates a tarball of the source tree to keep with the experiment. It also <code>diff</code>s your sandbox against the tag it checks out and records those differences with the tarball in <i>EXPDIR</i>/src. This is where you can change the default tag extracted from your sandbox.

The setup script extracts the repository tag of the model you checked out into your sandbox, checks out that tag from the repository, and creates a tarball of the source tree to keep with the experiment. It also <code>diff</code>s your sandbox against the tag it checks out and records those differences with the tarball in <code><i>EXPDIR</i>/src</code>. This is where you can change the default tag extracted from your sandbox.

Do you wish to CLONE an old experiment? (Default: NO or FALSE)

This gives you an opportunity to copy the setup of an existing experiment while changing what needs to be changed to make it work.

Line 188:

Line 194:

=== 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.

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 now netcdf files with metadata instead of the previous flat binary files but typically have the same naming convention, 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. If you have restarts from a previous model version it may be worthwhile to try running with them as the model will check to see if they are in netcdf format, and if not, convert them.

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).

Line 269:

Line 275:

Setting <code>PRINTSPEC</code> to 3 will make the model send to standard output a list of exports available to <code>HISTORY.rc</code> in the model's current configuration, and then exit without integrating. The list includes each export's gridded component and short name (both necessary to include in <code>HISTORY.rc</code>), long (descriptive) name, units, and number of dimensions. Note that run-time options can affect the exports available, so see to it that you have those set as you intend. The other <code>PRINTSPEC</code> values are useful for debugging.

While you can set <code>PRINTSPEC</code>, submit <code>~~qsub~~ gcm_run.j</code>, and get the export list as part of PBS standard output, there are quicker ways of obtaining the list. One way is to run it as a single column model on a single processor, as explained in [[Heracles 4.0 Single Column Model]]. Another way is to run it in an existing experiment. In the <code>scratch</code> directory of an experiment that has already run, change <code>PRINTSPEC</code> in <code>CAP.rc</code> as above. Then, in the file <code>AGCM.rc</code>, change the values of <code>NX</code> and <code>NY</code> (near the beginning of the file) to 1. Then, from an interactive job (one processor will suffice), run the executable <code>GEOSgcm.x</code> in <code>scratch</code>. You will need to run <code>source src/g5_modules</code> in the model's build tree to set up the environment. The model executable will simply output the export list to <code>stdout</code>.

While you can set <code>PRINTSPEC</code>, submit <code>sbatch gcm_run.j</code>, and get the export list as part of PBS standard output, there are quicker ways of obtaining the list. One way is to run it as a single column model on a single processor, as explained in [[Heracles 4.0 Single Column Model]]. Another way is to run it in an existing experiment. In the <code>scratch</code> directory of an experiment that has already run, change <code>PRINTSPEC</code> in <code>CAP.rc</code> as above. Then, in the file <code>AGCM.rc</code>, change the values of <code>NX</code> and <code>NY</code> (near the beginning of the file) to 1. Then, from an interactive job (one processor will suffice), run the executable <code>GEOSgcm.x</code> in <code>scratch</code>. You will need to run <code>source src/g5_modules</code> in the model's build tree to set up the environment. The model executable will simply output the export list to <code>stdout</code>.

===Outputting Derived Fields===

@@ Line 23: / Line 23: @@
 === 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.  :
@@ Line 28: / Line 29: @@
   Enter the Experiment ID:
 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 the queue system imposes certain limits on job names.
@@ Line 36: / Line 38: @@
 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.
   Enter an Experiment Source Tag for History (Default: Heracles-4_0):
-The setup script extracts the repository tag of the model you checked out into your sandbox, checks out that tag from the repository, and creates a tarball of the source tree to keep with the experiment. It also <code>diff</code>s your sandbox against the tag it checks out and records those differences with the tarball in <i>EXPDIR</i>/src. This is where you can change the default tag extracted from your sandbox.
+The setup script extracts the repository tag of the model you checked out into your sandbox, checks out that tag from the repository, and creates a tarball of the source tree to keep with the experiment. It also <code>diff</code>s your sandbox against the tag it checks out and records those differences with the tarball in <code><i>EXPDIR</i>/src</code>. This is where you can change the default tag extracted from your sandbox.
   Do you wish to CLONE an old experiment? (Default: NO or FALSE)
+This gives you an opportunity to copy the setup of an existing experiment while changing what needs to be changed to make it work.
@@ Line 188: / Line 194: @@
 === 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.
+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 now netcdf files with metadata instead of the previous flat binary files but typically have the same naming convention, 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.  If you have restarts from a previous model version it may be worthwhile to try running with them as the model will check to see if they are in netcdf format, and if not, convert them.
 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).
@@ Line 269: / Line 275: @@
 Setting <code>PRINTSPEC</code> to  3 will make the model send to standard output a list of exports available to <code>HISTORY.rc</code> in the model's current configuration, and then exit without integrating. The list includes each export's gridded component and short name (both necessary to include in <code>HISTORY.rc</code>), long (descriptive) name, units, and number of dimensions.  Note that run-time options can affect the exports available, so see to it that you have those set as you intend.  The other <code>PRINTSPEC</code> values are useful for debugging.
-While you can set  <code>PRINTSPEC</code>, submit <code>qsub gcm_run.j</code>, and get the export list as part of PBS standard output, there are quicker ways of obtaining the list.  One way is to run it as a single column model on a single processor, as explained in [[Heracles 4.0 Single Column Model]].  Another way is to run it in an existing experiment.  In the <code>scratch</code> directory of an experiment that has already run, change <code>PRINTSPEC</code> in  <code>CAP.rc</code> as above.  Then, in the file <code>AGCM.rc</code>, change the values of <code>NX</code> and <code>NY</code> (near the beginning of the file) to 1.  Then, from an interactive job (one processor will suffice), run the executable <code>GEOSgcm.x</code> in <code>scratch</code>.  You will need to run <code>source src/g5_modules</code> in the model's build tree to set up the environment.  The model executable will simply output the export list to <code>stdout</code>.
+While you can set  <code>PRINTSPEC</code>, submit <code>sbatch gcm_run.j</code>, and get the export list as part of PBS standard output, there are quicker ways of obtaining the list.  One way is to run it as a single column model on a single processor, as explained in [[Heracles 4.0 Single Column Model]].  Another way is to run it in an existing experiment.  In the <code>scratch</code> directory of an experiment that has already run, change <code>PRINTSPEC</code> in  <code>CAP.rc</code> as above.  Then, in the file <code>AGCM.rc</code>, change the values of <code>NX</code> and <code>NY</code> (near the beginning of the file) to 1.  Then, from an interactive job (one processor will suffice), run the executable <code>GEOSgcm.x</code> in <code>scratch</code>.  You will need to run <code>source src/g5_modules</code> in the model's build tree to set up the environment.  The model executable will simply output the export list to <code>stdout</code>.
 ===Outputting Derived Fields===