.. |br| raw:: html
.. _rundir-ex-fullchem: ######################################################### Example: Create a full-chemistry simulation run directory ######################################################### Let us walk through the process of creating a run directory for a global GEOS-Chem full-chemistry simulation. #. Navigate to the GCClassic superproject folder and get a directory listing: .. code-block:: console $ cd /path/to/your/GCClassic $ ls -CF AUTHORS.txt CMakeScripts/ LICENSE.txt SUPPORT.md run@ test@ CMakeLists.txt CONTRIBUTING.md README.md docs/ src/ As mentioned previously, :file:`run@` is a symbolic link. It actually points to the to the :file:`src/GEOS-Chem/run/GCClassic` folder. This folder contains several scripts and template files for run directory creation. |br| |br| #. Navigate to the run folder and get a directory listing: .. code-block:: console $ cd run $ ls -CF archiveRun.sh* gitignore init_rd.sh* createRunDir.sh* HEMCO_Config.rc.templates/ README.md geoschem_config.yml.templates/ HEMCO_Diagn.rc.templates/ runScriptSamples/ getRunInfo* HISTORY.rc.templates/ setupForRestarts.sh* You can see several folders (highlighted in the directory display with :file:`/`) and a few executable scripts (highlighted with :file:`*`). The script we are interested in is :file:`createRunDir.sh`. |br| |br| #. Run the :file:`createRunDir.sh` script. Type: .. code-block:: console $ ./createRunDir.sh |br| #. You will then be prompted to supply information about the run directory that you wish to create: .. code-block:: console =========================================================== GEOS-CHEM RUN DIRECTORY CREATION =========================================================== ----------------------------------------------------------- Choose simulation type: ----------------------------------------------------------- 1. Full chemistry 2. Aerosols only 3. Carbon 4. Hg 5. POPs 6. Tagged O3 7. Trace metals 8. TransportTracers 9. CH4 10. CO2 11. Tagged CO >>> To create a run directory for the full-chemistry simulation, type :command:`1` followed by the :command:`ENTER` key. .. tip:: To exit, the run directory creation process, type :literal:`Ctrl-C` at any prompt. |br| #. You will then be asked to specify any additional options for the full-chemistry simulation (such as adding the RRTMG radiative transfer model, APM or TOMAS microphysics, etc.) .. code-block:: console ----------------------------------------------------------- Choose additional simulation option: ----------------------------------------------------------- 1. Standard 2. Benchmark 3. Complex SOA 4. Marine POA 5. Acid uptake on dust 6. TOMAS 7. APM 8. RRTMG >>> For the standard full-chemistry simulation, type :command:`1` followed by :command:`ENTER`. To add an option to the full-chemistry simulation, type a number between :command:`2` and :command:`8` and press :command:`ENTER`. |br| |br| #. You will then be asked to specify the meteorology type for the simulation (`GEOS-FP `_, `MERRA-2 `_), or GCAP 2.0). .. code-block:: console ----------------------------------------------------------- Choose meteorology source: ----------------------------------------------------------- 1. MERRA-2 (Recommended) 2. GEOS-FP 3. GEOS-IT 4. GISS ModelE2.1 (GCAP 2.0) >>> You should use the recommended option (MERRA-2) if possible. Type :command:`1` followed by :command:`ENTER`. .. attention:: The convection scheme used to generate archived GEOS-FP meteorology files changed from RAS to Grell-Freitas starting 01 June 2020 with impact on vertical transport. Discussion and analysis of the impact is available at https://github.com/geoschem/geos-chem/issues/1409. To fix this issue, different GEOS-Chem convection schemes are called based on simulation start time. This ensures comparability in GEOS-Chem runs using GEOS-FP fields generated using the RAS convection scheme and fields generated using Grell-Freitas, but only if the simulation does not cross the 01 June 2020 boundary. We therefore recommend splitting up GEOS-FP runs in time such that a single simulation does not span this date. For example, configure one run to end on 01 June 2020 and then use its output restart to start another run on 01 June 2020.. Alternatively consider using MERRA2 which was entirely generated with RAS, or GEOS-IT which was entirely generated with Grell-Freitas. If you wish to use a GEOS-FP meteorology year different from your simulation year please create a GEOS-Chem GitHub issue for assistance to avoid accidentally using zero convective precipitation flux. #. The next menu will prompt you for the horizontal resolution that you wish to use: .. code-block:: console ----------------------------------------------------------- Choose horizontal resolution: ----------------------------------------------------------- 1. 4.0 x 5.0 2. 2.0 x 2.5 3. 0.5 x 0.625 >>> If you wish to set up a global simulation, type either :command:`1` or :command:`2` followed by :command:`ENTER`. If you wish to set up a nested-grid simulation, type :command:`3` and hit :command:`ENTER`. Then you will be followed by a nested-grid menu: .. code-block:: console ----------------------------------------------------------- Choose horizontal grid domain: ----------------------------------------------------------- 1. Global 2. Asia 3. Europe 4. North America 5. Custom >>> Select your preferred horizontal domain, followed by :command:`ENTER`. |br| |br| #. You will then be prompted for the vertical dimension of the grid. .. code-block:: console ----------------------------------------------------------- Choose number of levels: ----------------------------------------------------------- 1. 72 (native) 2. 47 (reduced) >>> For most simulations, you will want to use :command:`72` levels. Type :command:`1` followed by :command:`ENTER`. For some memory-intensive simulations (such as nested-grid simulations), you can use 47 levels. Type :command:`2` followed by :command:`ENTER`. |br| |br| #. You will then be prompted for the folder in which you wish to create the run directory. .. code-block:: console ----------------------------------------------------------- Enter path where the run directory will be created: ----------------------------------------------------------- >>> You may enter an absolute path (e.g. :file:`$HOME/myusername/my-run-dirs` followed by :command:`ENTER)`. You may also enter a relative path (e.g :file:`~/my-run-dirs` followed by :command:`ENTER`). In this case you will see that the :file:`./createRunDir.sh` script will expand the path to an absolute path. |br| |br| #. The next menu will prompt you for the run directory name. .. code-block:: console ----------------------------------------------------------- Enter run directory name, or press return to use default: NOTE: This will be a subfolder of the path you entered above. ----------------------------------------------------------- >>> You should use the default run directory name whenever possible. Type :command:`ENTER` to select the default. You will then see output similar to this: .. code-block:: console -- Using default directory name gc_4x5_merra2_fullchem or if you are creating a nested grid simulation: .. code-block:: console -- Using default directory name gc_05x0625_merra2_fullchem and then: .. code-block:: console -- See rundir_vars.txt for summary of default run directory settings -- This run directory has been set up to start on 20190701 -- A restart file for this date has been copied to the Restarts subdirectory -- You may add more restart files using format GEOSChem.Restart.YYYYMMDD_HHmmz.nc4 -- Change simulation start and end dates in configuration file geoschem_config.yml -- Default frequency and duration of diagnostics are set to monthly -- Modify diagnostic settings in HISTORY.rc and HEMCO_Config.rc |br| #. The next menu will prompt you with: .. code-block:: console ----------------------------------------------------------- Do you want to track run directory changes with git? (y/n) ----------------------------------------------------------- Type :command:`y` and then :command:`ENTER`. Then you will be able to track changes that you make to GEOS-Chem configuration files with Git. This can be a lifesaver when debugging---you can revert to an earlier state and then start fresh. You will then see this output: .. code-block:: console Initialized empty Git repository in /path/to/gc_4x5_merra2_fullchem/.git/ |br| #. The next (and final) menu will ask you: .. code-block:: console ----------------------------------------------------------- Do you want to build the KPP-Standalone Box Model? (y/n) ----------------------------------------------------------- >>> Type :program:`y` and then :command:`ENTER` you wish to build the :program:`KPP-Standalone Box Model`, or :program:`n` then :program:`ENTER` to skip this step. If you choose to build KPP-Standalone, you will be given this reminder: .. code-block:: console >>>> REMINDER: You must compile with options: -DKPPSA=y <<<< Please see the Supplemental Guide entitled :ref:`kppsa-guide` for further usage instructions. Lastly, you will see a message to indicate that run directory creation has completed successfully. .. code-block:: console Created /path/to/gc_4x5_merra2_fullchem You may now navigate to this directory and start editing the :ref:`GEOS-Chem configuration files `.