Difference between revisions of "Running GCHP: Basics"

From Geos-chem
Jump to: navigation, search
(Overview)
(Run Methods)
Line 18: Line 18:
 
== Run Methods ==
 
== Run Methods ==
  
You can run GCHP by executing the appropriate run command directly on the command line from within your run directory or by submitting your run as a batch job.  
+
You can run GCHP locally from within your run directory (interactively) or by submitting your run to your cluster's job scheduler. To make running GCHP simpler there is a folder in the GCHP run directory called <tt>runScriptSamples</tt> that contains example scripts to run GCHP. Each file includes additional steps to make the run process easier, including sourcing your environment file so all libraries are loaded, deleting file <tt>cap_restart</tt> from any previous runs, and sending standard output to a log file.
  
=== Running as a Batch Job (Recommended) ===
+
=== Running interactively ===
  
Sample run scripts are included in the <tt>runScriptSamples/</tt> subdirectory for submitting your run as a scheduled job. All example run scripts send standard output to file <tt>GCHP.log</tt> by default and require manually configuring your job-specific resources such as number of cores and nodes. If using versions prior to 12.1.0 then you must also manually add your environment filename to the script. Unless otherwise noted in the run script filename, all sample run scripts assume use of SLURM (simple linux utility for resource management). If your system is not SLURM, you can adapt the sample run scripts to work on your system.
+
Use example run script <tt>gchp.local.run</tt> to run GCHP locally on your machine. Before running, check that you have at least 6 cores available at your disposal. Then copy <tt>gchp.local.run</tt> to the main level of your run directory and type the following at the command prompt:
  
To submit your SLURM batch file, simply type:
+
./gchp.local.run
  
  sbatch gchp.run
+
If your run crashes during transport then you need additional memory. Either request an interactive session on your cluster with additional memory or consider running GCHP as a batch job by submitting your run to a job scheduler.
  
Job submission is different for other system. For example, to submit a Grid Engine batch file, type:
+
=== Running as a batch job ===
  
  qsub gchp.run
+
Sample run scripts are included in the <tt>runScriptSamples/</tt> subdirectory for submitting your run as a scheduled job. The recommended job script example is <tt>gchp.run</tt> which is custom for use with SLURM on the Harvard University Odyssey cluster. However, it may be adapted for other systems. You may also adapt the interactive run script <tt>gchp.local.run</tt> for you system as well. The "multirun" scripts are for submitting multiple consecutive jobs in a row and are more advanced. Read more about that option in the chapter on configuring a run later in this manual.
  
If your computational cluster uses a different job scheduler (e.g. LSF or PBS), then check with your IT staff about how to submit batch jobs.  
+
Example run scripts send standard output to file <tt>gchp.log</tt> by default and require manually configuring your job-specific resources such as number of cores and nodes. If using versions prior to 12.1.0 then you must also manually add your environment filename to the script; later version simply source local symbolic link gchp.env which you set to point to your environment file during run directory setup.  
  
=== Running Interactively ===
+
If using SLURM, submit your batch job with this command:
  
Before running GCHP interactively, check that your environment is set up properly and you have at least 6 cores available with 6G memory per core. Then execute the following command from within your run directory if using SLURM (you will need to adapt this for other systems):
+
  sbatch gchp.run
  
srun -n 6 --mpi=pmi2 ./geos 2>&1 | tee GCHP.log
+
Job submission is different for other system. For example, to submit a Grid Engine batch file, type:
  
This command can be broken down as follows:
+
  qsub gchp.run
 
+
{| border=1 cellspacing=0 cellpadding=5
+
|-bgcolor="#CCCCCC"
+
!width="200ox"|Command
+
!width="800px"|What it does
+
 
+
|-valign="top"
+
|<tt>srun ... ./geos</tt>
+
|Runs executable <tt>geos</tt> as a parallel job
+
 
+
|-valign="top"
+
|<tt>-n 6</tt>
+
|Specifies how many individual CPU cores are requested for the run. The number given here should always be the total number of cores, regardless of how many nodes they are spread over. The number of CPUs that you request must be a multiple of 6 (at least one core for each of the [http://geos-chem.org/cubed_sphere/CubeSphere_step-by-step.html cubed-sphere faces], and the same number of cores for each face).
+
 
+
|-valign="top"
+
|<tt>--mpi-pmi2</tt>
+
|Specifies usage of the MVAPICH2 implementation of MPI. Do not include this if not using MVAPICH2.
+
 
+
|-valign="top"
+
|<tt><nowiki>2>&1 | tee GCHP.log</nowiki></tt>
+
|Specifies that all MAPL output, both standard and error, be written to both the screen and to file <tt>GCHP.log</tt>.
+
 
+
|}
+
  
You can also adapt a GCHP run script for interactive use. Simply comment out the scheduler-specific code such as #SBATCH headers for SLURM.
+
If your computational cluster uses a different job scheduler (e.g. LSF or PBS), then check with your IT staff about how to submit batch jobs. Please also consider submitting your working run script for inclusion in the run script examples folder in future versions.
  
 
== Verifying a Successful Run ==
 
== Verifying a Successful Run ==

Revision as of 22:21, 6 March 2019

Previous | Next | User Manual Home | GCHP Home

  1. Hardware and Software Requirements
  2. Downloading Source Code and Data Directories
  3. Obtaining a Run Directory
  4. Setting Up the GCHP Environment
  5. Compiling
  6. Basic Example Run
  7. Configuring a Run
  8. Output Data
  9. Developing GCHP
  10. Run Configuration Files


Overview

This page presents the basic information needed to run a simple GCHP test case. The default GCHP run directories are configured for a 1-hr simulation at c24 resolution using native resolution meteorology, six cores, and one node. This simple configuration is a good test case to check that GCHP runs on your system. Typically the TransportTracer simulation requires about 50G and the standard and benchmark simulations require about 110G.

Run Methods

You can run GCHP locally from within your run directory (interactively) or by submitting your run to your cluster's job scheduler. To make running GCHP simpler there is a folder in the GCHP run directory called runScriptSamples that contains example scripts to run GCHP. Each file includes additional steps to make the run process easier, including sourcing your environment file so all libraries are loaded, deleting file cap_restart from any previous runs, and sending standard output to a log file.

Running interactively

Use example run script gchp.local.run to run GCHP locally on your machine. Before running, check that you have at least 6 cores available at your disposal. Then copy gchp.local.run to the main level of your run directory and type the following at the command prompt:

./gchp.local.run

If your run crashes during transport then you need additional memory. Either request an interactive session on your cluster with additional memory or consider running GCHP as a batch job by submitting your run to a job scheduler.

Running as a batch job

Sample run scripts are included in the runScriptSamples/ subdirectory for submitting your run as a scheduled job. The recommended job script example is gchp.run which is custom for use with SLURM on the Harvard University Odyssey cluster. However, it may be adapted for other systems. You may also adapt the interactive run script gchp.local.run for you system as well. The "multirun" scripts are for submitting multiple consecutive jobs in a row and are more advanced. Read more about that option in the chapter on configuring a run later in this manual.

Example run scripts send standard output to file gchp.log by default and require manually configuring your job-specific resources such as number of cores and nodes. If using versions prior to 12.1.0 then you must also manually add your environment filename to the script; later version simply source local symbolic link gchp.env which you set to point to your environment file during run directory setup.

If using SLURM, submit your batch job with this command:

 sbatch gchp.run

Job submission is different for other system. For example, to submit a Grid Engine batch file, type:

 qsub gchp.run

If your computational cluster uses a different job scheduler (e.g. LSF or PBS), then check with your IT staff about how to submit batch jobs. Please also consider submitting your working run script for inclusion in the run script examples folder in future versions.

Verifying a Successful Run

There are several ways to verify that your run was successful.

  1. NetCDF files are present in the OutputDir subdirectory.
  2. GCHP.log ends with timing information for the run.
  3. Your scheduler log (e.g. output from SLURM) does not contain any obvious errors.
  4. GCHP.log contains text with format "AGCM Date: YYYY/MM/DD Time: HH:mm:ss" for each timestep (e.g. 00:10, 00:20, 00:30, 00:40, 00:50, and 01:00 for a 1-hr run).

If it looks like something went wrong, check all log files (type "ls *.log" in run directory to list them) as well as your scheduler output file (if one exists) to determine where there may have been an error. Beware that if you have a problem in one of your configuration files then you will likely see a MAPL error with traceback to the GCHP/Shared directory. Review all of your configuration files to ensure you have proper setup.

GCHP errors can be cryptic. If you find yourself debugging within MAPL then you may be on the wrong track as most issues can be resolved by updating the run settings. If you cannot figure out where you are going wrong please create an issue on the GCHP GitHub issue tracker located at https://github.com/geoschem/gchp/issues.


Previous | Next | User Manual Home | GCHP Home