Home » CESM Models » Paleo Climage Working Group » PaleoResources

PaleoResources


Resources for CESM1.2 Paleosimulations

Nan Rosenbloom
Esther Brady
Bette Otto-Bliesner

National Center for Atmospheric Research

  1. Getting Started
  2. Ocean
  3. Coupler mapping
  4. River runoff
  5. Atmospheric model (CAM4/CAM5)
  6. Landuse/landcover (CLM4.0)
  7. Sea ice
  8. Run time issues


Introduction

This document describes procedures developed at NCAR for creating paleoclimate simulations using the NCAR CESM1.2 series model in the fully coupled (all active components) configuration. We do not describe the creation of the forcing files used in Data Model components or in stand-alone component model runs. Note that this documentation does not discuss CLM4.5 or later land model versions. We provide tools and examples of the processes we have used to create paleoclimate simulations using the computing resources at the National Center for Atmospheric Research (NCAR). However, since the CESM model evolves continuously, this document is to be used as a guide; researchers are ultimately responsible for modifying the processes to accommodate their time period of interest as well as adapting the tools we provide to the model version they are using and the computer resources they have available. All tools discussed in this FAQ were developed to run on the computing platforms at the National Center for Atmospheric Research (NCAR) and are unsupported on all other platforms. We provide limited user support for the current version of tools on NWSC computers. Outside researchers may need to modify these procedures to accommodate earlier versions of the CESM1 model, or for the computer resources available on their home machines. Finally, the information we provide is intended to supplement the detailed usage information for each CESM1.2 series component model that can be found in the CESM1 User's Guide and a general familiarity by the user of CESM1 terminology and concepts is assumed.

Before you begin

One of the goals of the Paleoclimate Working Group is to allow the community to address scientific questions about past climates in Earth history using the CESM model. To that end we include useful tools that are designed to modify the forcing and input files for paleoclimate applications. If you are considering a Paleoclimate project using the CESM model you may find it useful to explore the questions listed below before you begin. We also strongly recommend that you complete the exercises in the CESM tutorial, and run a short pre-industrial simulation of the CESM model before you start configuring your paleoclimate simulation. We ask that users submit questions to the CESM Discussion Forum so that other users may contribute to, or benefit from, the discussion. Browse the Paleoclimate Section of the CESM Bulletin Board for related community discussion.

Question 1: What scientific question do you plan to investigate with the CESM?

Question 2: What time period do you want to simulate?

Question 3: What configuration of CESM do you plan to use?

Question 4: Do you have experience running or analyzing output from the CESM?

Question 5: What computer will you use to run your simulations?

Question 6: Is it difficult to configure the CESM model for paleoclimate simulations?

What are the differences between Deep Time and Quaternary paleoclimate simulations.

Throughout this document we differentiate between the procedures required to create (1) near-modern (e.g., Quaternary, Pliocene) or (2) Deep-Time (pre-Quaternary/Pliocene) model simulations. In near-modern simulations, the continents are in their present-day positions, and the land/sea masks do not require significant modification. Quaternary modelers are often able to use existing forcing files to simulate past climate. By contrast, deep-time simulations require drastic modifications to the land/sea mask, and the modeler is responsible for providing the orographic/bathymetric maps for their geologic period of interest.

Flow Chart

CCSM3 vs CESM1.2

The Community Climate System Model, version 3 (CCSM3) is a legacy version of the Community Earth System Model (CESM). Support for CCSM3 and all previous versions of CCSM have expired. The tools described in the CCSM3 documentation were developed to work on NCAR platforms that have since been retired and therefore these tools are no longer actively maintained. Furthermore, using the CCSM3 model is no longer supported on NCAR machines.

What input files do I need


Deep time model users need to provide gridded input files that define the surface topography, ocean bathymetry, land/sea mask, and vegetation/landuse categories for their period of scientific interest.

Topography + Bathymetry format » topobathy.nc
 The topobathy.nc netCDF file should contain topography and bathymetry on a regular latitude/longitude grid (e.g., 2°x2°). Positive values represent height above sea level and negative values represent ocean bathymetry. The topobathy.nc will define your land/ocean mask, your bathymetry (KMT), and your orography (expressed as PHIS; where PHIS = orography * 9.82m/s2).

Vegetation/Landuse » vegetation.nc
 The vegetation.nc netCDF file should contain land use (i.e., vegetation) on a regular latitude/longitude grid (e.g., 2°x2°).


CLM PLANT FUNCTION TYPE (PFT)
For most deep time paleo simulations, we assign LSM (Land Surface Model) land-use types for each grid point and then convert these LSM types to CLM (Community Land Model) surface information using the tool paleo_mkraw_cesm1.csh. Because CLM requires a complicated array of surface information for each grid cell, whereas LSM uses a simple integer value to represent land-use at each grid point, assigning an LSM integer value and using the paleo_mkraw_cesm1.csh tool to convert to LSM types to CLM format provides a simple method to create surface data information for deep time.

Modelers may first need to construct LSM land cover maps from biome maps using the LSM definitions and CLM PFT definitions used in paleo_mkraw_cesm1.csh

LSM land-use types are used in paleo_mkraw_cesm1.csh because LSM was the predecessor to CLM3 and used in CSM1.4. If this does not suite your needs, you will need to modify paleo_mkraw.csh to convert from your preferred land-use type structure to CLM surface data information.

CLM Plant Function Types

PFT Description
0 bare
1 needleleaf evergreen temperate tree
2 needleleaf evergreen boreal tree
3 needleleaf deciduous boreal tree
4 broadleaf evergreen tropical tree
5 broadleaf evergreen temperate tree
6 broadleaf deciduous tropical tree
7 broadleaf deciduous temperate tree
8 broadleaf deciduous boreal tree
9 broadleaf evergreen temperate shrub
10 broadleaf deciduous temperate shrub
11 broadleaf deciduous boreal shrub
12 arctic c3 grass
13 cool c3 grass
14 warm c4 grass
15 crop 1
16 crop 2

LSM Land cover types

No Vegetation
0 ocean
1 land ice
2 desert
Forest
3 cool needleleaf evergreen tree
4 cool needleleaf deciduous tree
5 cool broadleaf deciduous tree
6 cool mixed forest
7 warm needleleaf evergreen tree
8 warm broadleaf deciduous tree
9 warm mixed forest
10 tropical broadleaf evergreen forest
11 tropical broadleaf deciduous tree
Interrupted Woods
12 savanna
13 evergreen forest tundra
14 deciduous forest tundra
15 cool forest crop
16 warm forest crop
Non-woods
17 cool grassland
18 warm grassland
19 tundra
20 evergreen shrub land
21 deciduous shrub land
22 semi-desert
23 cool irrigated crop
24 cool crop
25 warm irrigated crop
26 warm crop
Wetland
27 forest wetland
28 non-forest wetland



Ocean

  1. Getting started

    The deep time paleo modeler is responsible for creating the binary ocean bottom topography file, the horizontal and vertical ocean grid files, a region mask file, and the ocean initial conditions. In addition, several input template files may need to be changed. For example, if the land/ocean mask is changed, the input template file containing new indices for diagnostic transport calculations will need to be changed. The namelist input file (pop2_in and user_nl_pop2) will need to be changed as well. This section will describe methods that can be used to generate these new files.

  2. Ocean Bottom topography (KMT) and Region mask

    The ocean bathymetry in POP is represented by a 2D integer field called the KMT representing the number of active depth levels at each tracer grid box.  The corresponding region mask is an integer representing a named region, defined in the *_region_ids input template file.

    For more information, please refer to the POP User's Guide.

  3. Changing Sea level and ocean bathymetry

    The process of altering the modern land/ocean mask to simulate raising/lowering sea level can be complicated and we offer these general guidelines. First, Model results will be very sensitive to ocean depth, particularly along shallow shelf regions. For this reason, we do not recommend making global changes to ocean depth (KMT) for near modern simulations, other than to make localized changes that are essential to your science (e.g., closing the Bering Strait, raising/lowering sill heights, opening the Isthmus of Panama, etc.). If, however, you do decide to change ocean depth or make comprehensive changes to sea floor relief, we advise that you run a control experiment with your modifications to test your model sensitivity to these changes. Note: Every change to the land/sea mask requires new KMT, lnd_domain, rmap and fmap files, as well as new coupler mapping files. However, in contrast to the case of a simulated sea level rise, lowered sea level simulations can generally restart the ocean and sea ice models using restart files from present-day simulations, as long as no new ocean points have been added.

    • Raising Sea level » Raising sea level requires that land cells be reclassified as ocean, which then must be initialized, since the ocean requires that all points be initialized at start up. If you configure your experiment as a startup run, the new ocean cells will automatically be filled with Levitus (Levitus et al., 1998, Steel et al., 2001) values. However, because the deep ocean takes a long time to come to equilibrium, it is generally desirable to initialize the ocean from a previously run experiment. In order to use a previous ocean restart file, you will need to modify the ocean source code to initialize the temperature and salinity fields for the new ocean cells. This process can be complex and is beyond the scope of this document.

    • Lowering Sea level » Lowering sea level requires that ocean cells be reclassified as land cells. In general, changing grid cells from ocean to land is more straightforward than turning land into ocean. For example, we use an NCL script to reassign ocean points to land when we reassign the ocean cells representing Hudson Bay to land for Pre-Pleistocene simulations. You recommend that you use the default binary CESM1 topography (KMT) and region mask files as input. Your output should be new binary files with the user-defined changes to the ocean map, which whill be used directly by the ocean model (user_nl_pop2) and are required to create new coupler mapping files that map the new land/sea map to the atmosphere.

      Hint: Check the region mask to be sure you have not eliminated any ocean regions. Eliminating ocean regions requires renumbering the ocean region in the region mask file and changing the region_ids file (e.g., gx1v6_region_ids) to correspond with your new ocean basins. By retaining at least one active ocean cell in the default regions, you can avoid having to change the region_ids.

      Hint: Carefully check your new KMT land/sea mask for narrow channels, one grid-cell bays that inhibit circulation, and changes to marginal seas. The region_mask and KMT land/sea masks must match EXACTLY. Even a single grid-cell discrepancy will cause your model to crash without warning and without an adequate error traceback.

    • Bathymetry » Model results will be very sensitive to sea floor relief. In general, we do not recommend changing sea floor relief when simulating changes in sea level, other than to make localized changes to individual grid cells in areas that are essential to your science.

  4. How do I change the region mask and region IDs

    region_mask_gx1v6
    The region_mask_gx1v6 file defines the ocean regions in CESM1 POP2. If you change the land/sea mask from the present day configuration you must also modify the region_mask.ieeei4 file to match your KMT land/sea definitions. These two files must match exactly for the model to work properly.

    gx1v6_region_ids
    If you make significant changes to your land/ocean mask you may also need to adjust the gx1v6_region_ids file, which divides the oceans into numbered regions; negatively numbered regions denote inland or marginal seas.

      »Deep Time: Since deep time simulations have ocean configurations that differ profoundly from current day, deep time modelers will need to define their own ocean regions. Typically we recommend that they define two simple regions, Northern and Southern Hemisphere.

      » Quaternary : Quaternary modelers can usually use the default ocean region mask as long as they retain at least one active ocean grid cell within each default region. However, if you remove an entire ocean basin or marginal sea, you will need to reorder all subsequent regions in the input template file.

  5. How do I design a new ocean grid for my Deep Time simulation

    If the standard Greenland 'displaced pole' grid can not be used for the new land/ocean mask, this procedure can be used to obtain a new grid. First consult the POP User's guide for information about other grids that can be used. Designing and creating a new ocean grid for Deep Time paleoclimate requires expert knowledge of climate modeling, including the 'art' of CESM climate modeling.

    a.      Choose your grid size: 

    We describe using a low resolution version of the finite volume CESM1 model (1.9x2.5 degree atm/land) with a high resolution ocean (gx1v6).  We recommend that you choose a CESM1-supported grid size for your simulation. The most common supported ocean grid sizes are styled after gx3v5 (100 longitudes and 116 latitudes) and gx1v6 (320 longitudes and 384 latitudes).  Although building a new ocean grid with a non-supported grid size is possible, (see CESM User Guide for discussion) additional changes need to be made in the ocean and ice source code.  Examples and tools described in this document are designed for supported ocean grid sizes.

    b.      Grid pole placement:

    The ocean model requires that grid poles be placed over land. Numerically no computation can be done at the convergence point of all longitudes at the grid pole. The ocean model solves this problem by shifting the grid pole away from the geographic pole and placing it over a land mass. (Atmospheric models solve this problem by using numerical filters). Therefore if there is no land at the geographic pole, the numerical pole must be shifted over land elsewhere. As long as land exists poleward of ~65o, our tools should be able to create an ocean grid for POP without code modification. 

    Pole placement is a subjective process, however, we offer a few helpful tips.

    1. Place the grid pole as close to the geographic pole as possible.
    2. It can be helpful to place the NH and SH pole on the same longitude.
    3. Place the grid pole close to the continental edge (1-2 grid cells) but be sure that you are not creating spurious land cells around the pole disc.  If you see a smooth edge to your continental boundary when you plot your grid, you will need to shift the shift the pole inland. You might also experiment with increasing jcon (reasonable range for jcon=10-20).
    4. WARNING:  Grid cell size decreases as the grid converges toward the pole point, with the consequence that if your grid cells are too small as you approach the poles, you may have to decrease the modeling timestep to avoid ocean instabilities. Therefore, try to avoid creating grid cells that are smaller than the CESM default ocean grid at your resolution.  Increasing jcon may help avoid this problem.

  6. Building a new ocean grid for Deep Time paleoclimate simulations

    The default configuration of CESM1.X/POP2 expects binary input files in BIG_ENDIAN format.

    Our tools are designed to combine the grid and KMT creation steps. Feel free to modify the provided scripts to suite your programming style. The script mk_grid_cesm.csh will create your grid using a Fortran program called ns_dipole.f, it will create your KMT file using a Fortran program called paleotop.f90, and it will convert the binary output files into a netCDF format for easier viewing and modifying. This script may need to be run iteratively depending on how many modifications to your grid are necessary. See the Overview section for guidance on how to create your grid.  Steps 1-3 will describe mk_grid_cesm.csh. 

    Once you are happy with your grid, you will then proceed to Step 4, modifying your KMT file. Modelers may modify their KMT file with whatever tools proves most useful. Some paleo modelers have used tools, such as Matlab, to modify their KMT file. See the Overview section for guidance on your KMT file.

    Once you are happy with your KMT file, then proceed to Step 5 to convert your netCDF KMT file back to the binary file required by POP. We provide a Fortran program called gridkmt_nc2bin.f90 as well as NCL scripts to accomplish this task.

    Finally, proceed to Steps 6-8 to create your region mask and edit the necessary input templates for your paleo case. All of these steps can be accomplished with mk_ocninput.csh.

    For all Fortran code, the modeler is responsible for compiling and creating executables, and changing the scripts to point to her/his code, data, and executables.

    STEP 1: Creating the ocean grid
    Tools:  mk_grid_cesm.csh/ns_dipole.f/paleotopo.f90

    Source Code on github

    Edit the top portion of the script mk_grid_cesm.csh to set the variables that define your grid in ns_dipole.f90, paleotop.f90, and grid_nc2bin.f90.

    VariableDescriptionNotes1o grid example3o grid example
    nxnumber of i grid linesgrid resolution in E/W direction320100
    nynumber of j grid linesgrid resolution in N/S direction384116
    nlatnnumber of j gridlines in NHGrid distribution should reflect science priorities (PD grid has higher resolution in NH).    nlatn+nlats=ny.  Tip: Avoid even distribution20963
    nlatsnumber of j grid lines in SH  17553
    lonnplongitude of grid North Pole  -- --
    latnpLatitude of grid North PoleTip: place pole points as close as possible to edge of continent without causing the pole to bulge outside the continental boundary on the new grid. (see pole plotting routine) -- --
    lonspLongitude of grid South pole Time period dependent -- --
    latspLatitude of grid South Pole Time period dependent -- --
    dyeqdy in degrees at Equator Tip:  CESM default ULAT at Equator.0.26o 0.6o
    dsigGaussian e-folding scale at Equator

    increasing this number widens the high resoln equatorial band

    30

    15

    jconnumber of rows of constant dy at polesincreasing this number can move the pole landward if it is extending beyond the edge of the polar continent.  Recommended range:  10-20.1111
    popgridbinary pop grid fileDefault POP2 expects BIG_ENDIAN binary format  
    gridkmt.ITER.ncnetCDF output file with KMT and ocean grid.Use this file to check your pole placement using ncl tools (e.g., plot_global_all.ncl)  

     

    STEP 2: Creating the KMT file
    Tool:  mk_grid_cesm.csh/paleotopo.f90

     NOTE:  paleotopo.f90 requires the bathymetry data be at 0.5x0.5 degree resolution.

    STEP 3.  Edit mk_grid_cesm.csh  Convert model grid and KMT to viewable file
    Tools:  mk_grid.csh/grid_bin2nc.f90 or bin2nc_i4_toporegion.090204.ncl

    • Choice a: mk_grid_cesm.csh/grid_bin2nc.f90

    The mk_grid_cesm.csh script calls the Fortran program grid_bin2nc.f90 to create a netCDF file. This information includes all grid information (i.e. variables in the pop grid file), plus elevation (bathymetry value in meters) as well as the KMT information. Other than the KMT values, all other information in the netCDF file are for viewing purposes only. Only the KMT values will be used in the POP model, the elevation variable is for your diagnostics only. Elevation values are ultimately computed in the model at runtime based on the KMT binary data file. Note: if you notice an error in your grid information, you will need to go back to the ns_dipole step for correction.  The binary file generated by ns_dipole is the file used in the model, not the variables in this diagnostic netCDF file.

    Edit mk_grid_cesm.csh for the following variables which control grid_bin2nc.F90:

    • Choice b: bin2nc_i4_toporegion.090204.ncl

    If you do not wish to create a grid/KMT netCDF file with grid_bin2nc.f90, and only want to convert the binary KMT file to a netCDF file, use the NCL script, bin2nc_i4_toporegion.090204.ncl. This NCL scripts converts both the KMT file as well as the region mask file to netCDF format.  (Simply comment out the region mask read/write sections of the code if you do not have a region mask file yet).

    At the end of the STEP 3, run mk_grid.csh.  If you choose STEP3/Choice b, comment out the grid_bin2nc section of mk_grid.csh and run bin2nc_i4_toporegion.090204.ncl.


    STEP 4: Evaluate/edit KMT
    Tool:  multi-step process

    The bottom topography (KMT) field will need to be checked and edited to eliminate potential problems at runtime. Modifying the KMT is a subjective process, and ultimately, it is up to the modeler to decide how best to make the necessary modifications. Some paleo modelers have used Matlab with a GUI-interface to change the KMT values. We offer some guidance for grid modifications, and outline a method for visualizing the grid on a regular sphere.

    • 1. poles extending beyond edge of continent?
    • 2. compare gridkmt.4.nc against gx1v6_ocn.nc (paleo_setup/ocn/gx1v6). Be sure that HTN and HTE in your gridkmt.nc file are at least as big as HTN and HTE in the gx1v6_ocn.nc grid. UNITS: --HTN and HTE in gridkmt.{ITER}.nc = m --HTN and HTE in gx1v6_ocn.nc = cm

      a.       Eliminate or widen one grid cell wide channels and bays at all levels. Horizontal velocities are defined to be zero at the corners of the KMT grid boxes, thus a channel of one grid box wide will have zero horizontal flow. One typically removes these channels by filling them with land, or widening them to have a minimum width of two grid cell.  Note, our tool contains an option to try and remove these channels automatically, but isolated points may still occur. 

      b.      Check zig-zag channels at the curves for widths of one grid cell.   These transition areas will be missed with the automatic checks and must be edited. If not, there will be no flow through the transition area due to zero velocities at all corners of (land) cell borders. The recommended change would be to widen the transition area to two ocean grid cells.

      c.      Avoid small and shallow bays.  Although a two cell wide bay may contain ocean velocities in the middle of the bay, realistically, there may not be enough circulation to fully resolve the ocean flow. Widening these bays may avoid negative salinities (in the case of too much fresh water runoff into the bay) or super-saline bays (in the case of excess evaporation).

      d.      The minimun allowable nonzero KMT value is 3 (shallowest active ocean depth).  

      e.      Visualize KMT on a sphere, with rough grid overlay.

      • 1. Create SCRIP mapping file.
        (NOTE: myConvertPOPT must be compiled with big_endian flag)
        Src: source code on github
        src: mk_SCRIPgrid.csh
        in1: nx, ny
        in2: grid.3.pop.da (binary grid file; big_endian)
        in3: kmt.3.da (binary KMT file; big_endian)
        in4: fv1.9x2.5_090205.nc (default atm grid)
        out1: gx1PT_{DATE}.nc (ocn SCRIP mapping file: center_lat, center_lon)
      • 2. Create four quadrant and two polar images of KMT on a sphere. The grid is represented as every nth longitude, overlaying the sphere.
        runscript: plot_all.ncl
        ncl: plot_global_all.ncl
        in1: gx1PT_{DATE}.nc
        ou1: Grid_PT_reg_np.ps
        ou2: Grid_PT_reg_sp.ps
        ou3: Grid_PT_reg_q1.ps
        ou4: Grid_PT_reg_q2.ps
        ou5: Grid_PT_reg_q3.ps
        ou6: Grid_PT_reg_q4.ps
      • f. Other plotting choices:

        • We provide a sample NCL script to hand edit your KMT file. This technique requires hard coding specific KMT changes within the NCL script. It is up to the modeler to determine how best to code the necessary changes.  Script change_kmt_example.ncl is provided as an example and a template. Use this code to modify your grid to open/close channels, remove islands, etc. Note: You must create coupler mapping files (described below) before you can modify your code using this NCL script. Also note that the coupler mapping filename will be incompatible with NCL's PopLatLon requirements called for in this script so you will need to copy or link the orginal filename to a new filename that matches the syntax that PopLatLon expects. e.g., ln -s map_gx1PT_TO_fv19_25_blin.{DATE}.nc map_gx1PT_to_fv19_25_bilin_da.{DATE}.nc

      • ncl: change_kmt.b2nc.ncl
        in1: kmt.3.da !! your kmt
        in2: grid.3.pop.da !! your grid
        in2: topo_bathymetry.1deg.nc !! your topo
        in3: gx1PT_{DATE}.nc
        in4: cpl_mapping/map_gx1PT_TO_fv19_25_blin.{DATE}.nc !! coupler mapping file for your run
        out1: kmt.{DATE}.nc
        out2: kmt.remap.{DATE}.nc

     

    STEP 5: Convert from final grid back to binary
    Tool:  gridkmt_nc2bin.F90/NCL

    Once you have perfected your new KMT file via the netCDF file, you will need to convert this back to binary for the POP model.

    • Choice a: gridkmt_nc2bin.F90

    Simply compile and run. The program will prompt you for input and output file names.

    • Choice b: NCL

    The example NCL script change_kmt_example.ncl writes the new KMT to both netCDF and binary.

     

    STEP 6: Create region mask
    Tool:  mk_ocninput.csh/modregmsk_edit.f

    The region mask file is a binary file with unique integer identifiers for each ocean basin.  The integer value specifies the various water bodies where the ocean model is active (lakes are handled in the land model and are considered land cells). The basins with positive integer identifiers should all connect in one large active ocean domain (as in the modern ocean). Negative values designate separate enclosed marginal seas, such as the Black Sea, for which the marginal sea balancing routine is applied.

    For deep time paleo cases, we typically create a simplified domain with two defined regions: the Northern and Southern Hemispheres.

    Once regions have been chosen, the modeler will need to modify the corresponding ASCII input_template called the region_ids file to reflect the new regions.

    The script mk_ocninput.csh actually accomplishes STEPS 6-9. It creates the region mask based on the modregmsk_edit.f code, it creates the region identifiers (region_id input_templates), it creates the diagnostic input_template for locations to compute ocean transport, and it grabs all input_templates for your grid size and copies them all to a single location with your unique grid name.

    Edit mk_ocninput to specify your code and data locations, your grid and KMT binary files names, and to specify your new unique grid name. If you have used gx3v5 for your grid size, (i.e. 100 longitudes and 116 latitudes), it would still be wise to rename your grid to something more appropriate for your case to distinguish it from the default gx3v5. For example, g3vJ where g3 would imply the gx3v5 size, but vJ would imply version Jurassic, if your period was the Jurassic. 

    You will also need to modify the mk_ocninput.csh script for each section of the script that deals with STEP 7-9.

    In STEP 6, we are modifying the ocean code modregmsk_edit.f.  Although no changes are necessary to the mk_ocninput.csh script itself, edits to the Fortran code are necessary if the modeler requires a region mask other then Northern Hemisphere and Southern Hemisphere. It is up to the modeler’s program style to determine how best to accomplish this goal for deep time periods.  Each period is unique therefore we cannot provide an all-inclusive algorithm. 

     

    STEP 7: Create region mask identifiers (input_template)
    Tool:  mk_ocninput.csh

    Be sure to read the comments in mk_ocninput.csh.

    Input_templates are ASCII files required at POP’s runtime and operate similar to namelist files. Each input_template deals with aspects of POP that can be changed by the modeler.

    The region_ids input_template compliments the region mask binary file such that it gives POP information for each ocean region.  For each region, the integer value and the ocean basin name are set. If the ocean basin is a marginal sea, the model requires a location (latitude and longitude and area) to be specified for the redistribution of net freshwater from the marginal seas. Marginal seas are flagged with a negative number.

    If the ocean basin is not a marginal sea, then these values should be set to 0. Integer values in the region_ids file must be ascending order of the absolute value of the integer. (i.e. 1, 2, -3, 4, etc. where -3 would be a marginal sea). For examples of the present day region ids, go to the POP source code under input_templates.

     

    STEP 8: Create diagnostic transport locations
    Tool:  mk_ocninput.csh

    Be sure to read the comments in mk_ocninput.csh

    The transport_contents input_template is used for diagnostic purposes only. In this file, the modeler can specify ocean locations (straits for example) for ocean transport computations that will be output in the ocean log files.

    Grid point i and j and k (depth) locations are required. The modeler should also specify whether the section is meridional or zonal and assign a section name. For examples of the present day transport_contents file, go to the POP source code under input_templates.  Note that the POP2 source code expects formatted input, so the ASCII format must match the format of the PD transport template file.

    STEP 9: Rename input templates to your gridname
    Tool:  mk_ocninput.csh

    Finally, the mk_ocninput.csh script copies all other input templates from the default location in the POP source code directory and renames them (in addition to your region_ids and transport_contents) according to your unique grid name.  These remaining input templates are as follows:

  7. Ocean initial conditions for Deep Time paleo simulations

    There are four options for initial ocean/ice conditions for startup runs. The choices include, mean, zonal-mean, startup (default), and internal. Details on how to invoke each choice are discussed in the model build scripts section.

    startup (default configuration)

    Initialize with a full spatially distributed temperature/salinity dataset

    If the modeler has latitude, longitude, and depth information on temperature and salinity, the ocean model can be initialized in the default configuration with a binary file at startup. This is recommended only if the modeler has this information on an appropriate grid or a grid that is close enough for interpolation. We provide a sample NCL script that will interpolate initial T/S information between two similar grids. This option will be more appropriate for near-modern cases

    Zonal-mean

    Initialize with a global, zonally averaged temperature/salinity distribution.

    POP allows a zonally averaged temperature/salinity file to be used for initialization. This file is binary and the format can be found in the CCSM3/POP source code, subroutine initial.F

    Mean

    Initialize with a global, horizontally averaged temperature/salinity depth profile.  Initializing with a global volume averaged temperature profile is the recommended method for deep time paleo simulations. Often, very little information on deep ocean temperatures is known, so initializing with a simple depth profile is the easiest method.

    POP requires this initial file to be a simple ASCII file with a temperature and salinity value for each vertical level.

    Internal

    Initialize with the default Levitus temperature/salinity profile.

    Present day temperature and salinity profiles can be computed internally at runtime based on 1992 Levitus data. 

    NOTE:  IAGE bug in CESM1.2

      (confirmed by Keith Lindsay and Nancy Norton)

    The non-standard initialization of TEMP & SALT is not compatible with CESM's restart script mechanisms. Despite CONTINUE_RUN being TRUE in env_run.xml, the model tries to initialize TEMP & SALT with the same IC as was used in the first submission. On restart, the IAGE initialization is trying to read from the same file that TEMP & SALT are being read from, but IAGE is not in that file. This leads to the problem that you are seeing.

    The iage error appears to be a symptom of using 'internal' or 'mean' for init_ts_option on restarts.

    The default for init_ts_option is 'ccsm_$runtype'. This gets evaluated to 'ccsm_continue' on a restart. But if init_ts_option = 'internal' or init_ts_option = 'mean', pop2 tries to continue using 'internal' or 'mean' for every submission (i.e., restart) instead of the POP2 restart files. On restart, the iage module  complains that it can't find a restart file because the model hasn't read the rpointer file, because the physics is still using internal. 

    Solution A:  The workaround is to manually set init_ts_option to 'ccsm_continue' in user_nl_pop2 for continuation runs, and comment out init_ts_option = 'mean'.

        Initial submission : user_nl_pop2 setting

    ! Use vertical column for first submission
    init_ts_option = 'mean'
    init_ts_file = 'ts_init_b20.681_1100-01_s_35.60level.dat'       (available on github)

    ! manually turn this on for all restarts after first submission
    ! init_ts_option = 'ccsm_continue'

        Restart submission : user_nl_pop2 setting

    ! Use vertical column for first submission
    ! init_ts_option = 'mean'
    ! init_ts_file = 'ts_init_b20.681_1100-01_s_35.60level.dat'       (available on github)

    ! manually turn this on for all restarts after first submission
    init_ts_option = 'ccsm_continue'

    Solution B:  An  UNTESTED solution could be to add some variant of this code to the top of Buildconf/pop2.buildnml.csh: 

    set init_ts_option = internal 
    if ($CONTINUE_RUN == 'TRUE') set init_ts_option = continue 

    Then change the init_ts_option line in the namelist to 

       init_ts_option      = '$init_ts_option'

  8. Watch for physical conditions that may be hardcoded to the modern ocean:

      Recommended pop2 namelist settings for Deep Time
      overflows_on = .false.
      overflows_interactive = .false.
      lhoriz_varying_bckgrnd = .false.
      ldiag_velocity = .false.
      ltidal_mixing = .false.
      bckgrnd_vdc1 = 0.524
      bckgrnd_vdc2 = 0.313
      sw_absorption_type = 'jerlov'
      jerlov_water_type = 3
      chl_option = 'file'
      chl_filename = 'unknown-chl'
      chl_file_fmt = 'bin'

    • Overflow regions:
      The overflow locations are grid dependent. Contact Gokhan Danabasoglu (gokhan@ucar.edu) in the NCAR ocean model group for details on the physical implications of the overflow process. (File: /models/ocn/pop2/input_templates/gx1v6_overflow)
    • Background diffusivity:
      The background diffusivity for the vertical mixing scheme has latitudinal dependence. For example, background diffusitivites are hardwired for the specific lat/lon areas bounding the modern world Banda Sea, and on the western boundaries of oceans.
    • chlorophyll
      The default choice for the “sw_absorption” in pop_in is “chlorophyll”. The chlorophyll dataset is designed for present day geography, therefore, for deep time paleo cases, the choice “jerlov” is more appropriate. See the POP user guide for more details on the pop_in file.
    • Branching from a run with overflows turned ON
      The overflow code has to modify the original startup ocean kmt bottom topography to run. These kmt changes are saved in the restart file as changes to the computational domain. On restart, the kmt field is modified as originally during startup, so it is consistent with the restart file. Our experience is that if one does a restart using a file that originally had overflows, but now you change the namelist input file to turn them off, pop may not be stable.
    • tidal mixing:
      Tidal mixing is geography dependent and is closely tied to the present day. We have
      tidal_mixing = .false.
      /

  • !-- Specify the grid type to avoid the model assumption of a uniform grid in the southern hemisphere (i.e., gx1v6).
    lat_aux_grid_type = 'user-specified'
    lat_aux_begin = -90.0
    lat_aux_end = 90.0
    n_lat_aux_grid = 180
    !-- Set the grid type to 'user-specified' to avoid the model assumption of a uniform grid in the southern hemisphere (i.e., gx1v6).
    moc_requested = .true.
    n_heat_trans_requested = .true.
    n_salt_trans_requested = .true.
    n_transport_reg = 1
    !-- dt_count sets the number of times the ocean is coupled per NCPL_BASE_PERIOD. Decreasing the ocean timestep can improve model stability, particularly in the early years of a simulation as the model is adjusting to new boundary conditions. The default ocean timestep is 23.
    dt_count = 23 (Default)
    dt_count = 30 (Lowered)
    !-- Overflow regions are hardcoded in the ocean model to present day bathymetry and must be turned off for deep time geographies.
    overflows_on = .false.
    overflows_interactive = .false.
    !--To initialize from an ocean depth/salinity profile: init_ts_option = 'mean'
    init_ts_file = '/glade/p/cesm/palwg/paleo_setup/ocn/ic/ts_init_b20.681_1100-01_s_35.60level.dat'
    init_ts_option = 'mean'
    !-- lhoriz_varying_bckgrnd (flag to allow horizontally-varying background (need bckgrnd_vdc2=0.0)), ldiag_velocity (flag to compute velocity diagnostics), overflows and tidal mixing all are geographically dependent and so present-day setups are not appropriate for deep time paleogeography.
    lhoriz_varying_bckgrnd = .false.
    ldiag_velocity = .false.
    ltidal_mixing = .false.
    !--The new background vertical velocity parameters were determined by Gokhan and Christine to increase Kappa-v in the deeper ocean in absence of tidal mixing. The tidal mixing normally would do this.
    bckgrnd_vdc1 = 0.524 (default=0.16)
    bckgrnd_vdc2 = 0.313 (default=0.0)


    (Return to top)



    coupler mapping

    1. Create SCRIP mapping file (Optional: already done in Ocean section)

      (NOTE: myConvertPOPT must be compiled with big_endian flag)
      Src: source code on github
      src: mk_SCRIPgrid.csh
      in1: nx, ny
      in2: grid.3.pop.da (binary grid file; big_endian)
      in3: kmt.3.da (binary KMT file; big_endian)
      in4: fv1.9x2.5_090205.nc (default atm grid)
      out1: gx1PT_{DATE}.nc (ocn SCRIP mapping file: center_lat, center_lon)

    2. Generate mapping files

      SrcDir: /glade/p/cesm/palwg/cesm1_2_0/tools/mapping/gen_mapping_files
      runDir: /glade/p/cesm/palwg/paleo_setup/cpl_mapping/maps/
      src: ./gen_cesm_maps.sh (NOTE: do not modify)
      N1. cp /glade/p/cesm/palwg/cesm1_2_0/tools/mapping/gen_mapping_files/gen_cesm_maps.sh .
      N2. cp /glade/p/cesm/palwg/cesm1_2_0/tools/mapping/gen_mapping_files/gen_ESMF_mapping_file/ .
      out2: map_fv19_25_TO_gx1PT_aave.{DATE}.nc
      map_fv19_25_TO_gx1PT_blin.{DATE}.nc
      map_fv19_25_TO_gx1PT_patc.{DATE}.nc
      map_gx1PT_TO_fv19_25_aave.{DATE}.nc
      map_gx1PT_TO_fv19_25_blin.{DATE}.nc
      3. % Usage: ./gen_cesm_maps.sh -fatm /glade/p/cesm/cseg/mapping/grids/fv1.9x2.5_090205.nc -natm fv19_25 -focn /glade/p/cesm/palwg/paleo_setup/ocn/mk_ocn_grid/gx1PT_{DATE}.nc -nocn gx1PT --nogridcheck

    3. Generate land and ocean domain files

      rundir:/glade/p/cesm/palwg/paleo_setup/cpl_mapping/gen_domain
      srcDir:/glade/p/cesm/palwg/paleo_setup/cpl_mapping/gen_domain/gen_domain_mlevy
      N1. make -f Makefile (if required)
      src: gen_domain.F90
      in: /glade/p/cesm/palwg/paleo_setup/cpl_mapping/maps/map_gx1PT_TO_fv19_25_aave.{DATE}.nc
      out1: domain.ocn.gx1PT.{DATE}.nc'
      out2: domain.lnd.fv19_25_gx1PT.{DATE}.nc' ! has mask in it
      4. % Usage: ./gen_domain -m /glade/p/cesm/palwg/paleo_setup/cpl_mapping/maps/map_gx1PT_TO_fv19_25_aave.{DATE}.nc -o gx1PT -l fv19_25 -c Permian

    (Return to top)



    River Runoff

    1. What files will I need for the RTM runoff model

      Deep time experiments include significant changes to the land/sea mask. Therefore, Deep Time modelers typically need to create a new runoff directional (rdirc) file. The rdirc file is used by the River Transport Model (RTM) to route river runoff to the ocean. You will also create two coupler mapping files: fmap (ROF2OCN_FMAPNAME) and rmap (ROF2OCN_RMAPNAME), which are described below.

      Near modern simulations that modify the land/sea mask (by removing Hudson Bay for the Last Glacial Maximum, for example), will need to create new coupler mapping files to reflect the changes in the land/sea mask, and in that process, they will create new fmap and rmap files as well.

      » NOTE: The 'aave' (fmap) was not required by tags older than cesm1_2_X. Therefore, if you are using cesm1_2_x, to continue an older simulation, you will need to create an fmap file and point to it in env_run.xml.

    2. How do I create an rdirc file

      RDIRC » directional river runoff vector map

        8    1 
      		  2 
        7 
      		ref  3 
        6 
      		  5 
      		  4  

      In this section we address how river runoff is mapped onto the land model (rdirc). The River Transport Model (RTM) is a component model within CESM1.2, and it uses a fixed regular grid. The runoff directional forcing file required by RTM describes vector (direction) for runoff flow at each RTM grid point (e.g., rdirc_0.5x0.5_simyr2000_slpmxvl_c120717.nc). The integer values are numbered from 1 to 8: 1=N, 2=NE, 3=E, etc.

      Near Modern

      Near modern simulations are not required to change the rdirc file, even if they modify the land/sea mask to add/change ice sheets because the coupler will autmatically re-route river runoff to the nearest ocean grid cell. However, if river runoff is integral to your science question you can make local modifications to the default rdirc file to suit your purpose. However, we do not recommend that Near Modern simulations re-create the rdirc file will make comparison to a CESM control simulation problematic.

      Deep Time
      Deep time experiments typically require significant modification of the land/sea mask, and therefore must remap river networks across the paleo topography by creating a new runoff directional dataset. This dataset is used by the River Transport Model (RTM) to route river runoff to the ocean. The CESM1 default RTM grid is at 0.5 degree resolution. However, deep time modelers can typically use a 2x2 degree grid.

      Creating RTM forcing files The deep time modeler will need to compute the runoff direction at each land grid point based on a user-provided file containing gridded topography and ocean bathymetry.

      We developed a set of offline paleo tools that map runoff for CESM1/CLM4. An ASCII file of runoff vectors is created which is used as input to the RTM at runtime. This tool uses topography to compute the direction of runoff flow. The output filename from rdirc.csh for your RTM forcing file is simply fort.10_$CASE (Fortran output file), so you may wish to rename your RTM forcing file to something more descriptive. For example, a filename for a paleo run could be: "rdirc_myrun.resolution.date.nc".

      » Create new rdirc file. (Note that the code may report errors and pause, waiting for input, before it completes. Press the return key to continue to the end of the program).

      control script  rdirc.csh (modify for your case)
      source code topo2rdirc_sed.F90 (modify for your case)
      topo2rdirc.F90
      inputstopobathy.nc (gridded input)
      output

      fort.10_$CASE (RTM forcing file used in model)
      fort.11_$CASE (infinite loop vectors)
      fort,12_$CASE
      fort.13_$CASE (redirected runoff vectors)
      fort.14_$CASE (error file)
      myPlot.runoffVectors.ps

      Usage: ./rdirc.csh

       

      » CAVEAT:  Redirecting runoff in RTM forcing file

      If your surface topography has internal basins or large flat regions, infinite loops will result, and rdirc.csh will produce another ASCII file with these loops (fort.11_$CASE).  An infinite loop is a region from which runoff will never flow out to the coastline, but circulate back to the starting point.  If infinite loops are not removed, global freshwater will not be conserved, and undesirable trends in global volume averaged ocean salinity may result. topo2dirc.F90 automatically checks for internal basins and reroutes the resulting drainage to the nearest coastline, irrespective of topography.  While the result will conserve freshwater, it may also produce unnatural drainage features that affect the science outcome of the simulation so check the output maps carefully by plotting the uncorrected and redirected runoff maps using the tool provided (plotrdirc.csh).

      » Plotting the vectors on a map [plotrdirc.csh/plot_rdirc.ncl]

      We use an NCL script to plot the directional RTM forcing vectors onto a latitude/longitude map .  (Note that the code may report errors and pause, waiting for input, before it completes.  Press the return key to continue to the end of the program).

      shell scriptplotrdirc.csh (modify for your case; IFILE, NLAT, NLON, RESOLN)
      source codeplot_rdirc.ncl
      inputs

      fort.10_$CASE
      fort.11_$CASE
      fort.13_$CASE
      fort14_$CASE

      outputpostcript file with maps of uncorrected and redirected runoff vectors

       

      » Convert to a netCDF file for CESM1/CLM4 [rtm_ncdf.pro]

      RTM now requires a netcdf rdirc file. We provide an IDL tool to convert the ASCII output into netCDF for RTM.

      source code rtm_ncdf.pro (edit to point to your final runoff file (fort.13_$CASE))
      details

        cp fort.13_$CASE rdirc.0.5x0.5.$CASE
        rtmfile1='rdirc.0.5_myCase'
        outfile='rdirc.0.5_myCase.nc'
        resnum=1 (NOTE: 0.5o)

      outputpostcript file with maps of uncorrected and redirected runoff vectors

       

      Source Code:  rtm_ncdf.pro

      % Usage:  Edit rtm_ncdf.pro to point to your fort.13_$CASE file (your renamed file)

      Start IDL on the command line.

      IDL> .rn rtm_ncdf                  ; compile rtm module

      IDL> rtm                                   ; execute code

      » Modify user_nl_rtm in your CASEROOT to point to your new file

      Your final product will be a netCDF file with your rivers mapped to your topography, using the directional vectors outlined above. user_nl_rtm: frivinp_rtm = '/myPath/rdirc.myCase.nc

      float RTM_FLOW_DIRECTION(nj, ni) ;
      RTM_FLOW_DIRECTION:long_name = "RTM flow direction" ;
      RTM_FLOW_DIRECTION:units = "unitless" ;
      RTM_FLOW_DIRECTION:mode = "time-invariant" ;
      RTM_FLOW_DIRECTION:comment = "N,NE,E,SE,S,SW,W,NW = 1,2,3,4,5,6,7,8" ;
      float xc(nj, ni) ;
      xc:long_name = "longitude of grid cell center" ;
      xc:units = "degrees_east" ;
      xc:mode = "time-invariant" ;
      float yc(nj, ni) ;
      yc:long_name = "latitude of grid cell center" ;
      yc:units = "degrees_north" ;
      yc:mode = "time-invariant" ;
      » CAVEAT:  Redirecting runoff in RTM forcing file

      If your surface topography has internal basins or large flat regions, you may end up with infinite loops in your runoff. An infinite loop is a region from which runoff will never flow out to the coastline, but circulate back to the starting point.  If infinite loops are not removed, global freshwater will not be conserved, and undesirable trends in global volume averaged ocean salinity may result.

      » Modify user_nl_rtm in your CASEROOT to point to your new file
      user_nl_rtm: frivinp_rtm = '/myPath/rdirc.myCase.nc

    3. How do I create ROF2OCN_RMAPNAME

      ROF2OCN_RMAPNAME » creating the runoff-to-ocean flux mapping file using cesm1_2_x.

      NOTE: run on yellowstone
      SOURCE: /CESMROOT/tools/mapping/gen_mapping_files/runoff_to_ocn

      runoff_map.nml Namelist input to runoff_to_ocn
      &input_nml gridtype = 'rtm'
      file_roff = '/myPath/rdirc.myCase'
      file_ocn = '/SCRIPgx1_myCase_.nc'
      file_nn = 'map_r05_myCase_to_gx1v6_myCase_nn_.nc '
      file_smooth = 'map_r05_myCase_to_gx1v6_myCase_sm_e1000r300_.nc '
      file_new = 'map_r05_myCase_to_gx1v6_myCase_nnsm_e1000r300_.nc'
      title = 'runoff map: r05_myCase -> gx1v6_myCase, nearest neighbor and smoothed '
      eFold = 1000000.0
      rMax = 300000.0
      step1 = .true.
      step2 = .true.
      step3 = .true.
      output file map_r05_myCase_to_gx1v6_myCase_nnsm_e1000r300_.nc

       

      Details:
      1. copy runoff_map.nml to a new file (e.g., runoff_map.myCase.nml)
      2. modify for your case
      3. soft link your new file to the original filename

      % Usage: % ./build.yellowstone.csh % ln -s % ./runoff_map output: map_r05x05PT_to_gx1v6PT_nnsm_e1000r300_130909.nc cp map_r05x05PT_to_gx1v6PT_nnsm_e1000r300_130909.nc /glade/p/cesm/palwg/paleo_setup/cpl_mapping/map

      % Usage:

      %    ./build.yellowstone.csh

      %    ln -s    runoff_map.myCase.nml ./runoff_map.nml

      %   ./runoff_map

      Modify env_run.xml in your CASEROOT to point to your new files
      xmlchange -file env_run.xml -id ROF2OCN_RMAPNAME -val '/myPath/map_r05_to_gx1_myCase_e1000r300_150902.nc'

    4. How do I create ROF2OCN_FMAPNAME

      ROF2OCN_FMAPNAME » Creating the runoff-to-ocean flux distribution (aave) mapping file

      ESMF generated file (type=aave) that maps an unmasked 0.5o runoff grid to a user-specified ocean grid. (README for 'create_ESMF_map.sh' script)

      inputdescription
      Source create_ESMP_map.shREADME
      -fsrc r05_nomask_070925.nc1default unmasked (0.5deg) mapping file
      -nsrc r05_nomask name of default mapping file
      -fdst gx1v6_myCase.nc paleo SCRIP mapping file
      -ndst gx1v6_myCase name of paleo SCRIP mapping file
      -map aave area average mapping
      output map_r05_nomask_TO_gx1v6_myCase_aave..nc ROF2OCN_FMAPNAME
      1Default path: /glade/p/cesm/cseg/mapping/grids/r05_nomask_070925.nc

      NOTE: run on yellowstone

      • CESMROOT: /cesm1_2_0/tools/mapping/gen_mapping_files/gen_ESMF_mapping_file

      % Usage:

      %    ln -s   /CESMROOT2/tools/mapping/gen_mapping_files/gen_ESMF_mapping_file/create_ESMF_map.sh   myWorkDir/.

      %   ./create_ESMF_map.sh -fsrc /glade/p/cesm/cseg/mapping/grids/r05_nomask_070925.nc -nsrc r05_nomask -fdst
      /glade/p/cesm/palwg/pliocene/plio/mapping/gx1v6pliocene_150902.nc -ndst gx1v6pliocene -map aave

      Modify env_run.xml in your CASEROOT to point to your new files
      xmlchange -file env_run.xml -id ROF2OCN_FMAPNAME -val '/myPath/map_r05_nomask_TO_gx1v6_myCase_aave.150902.nc'

      Once you have created your new files, point to them in user_nl_rtm and env_run.xml in $CASEROOT.
      % edit user_nl_rtm: » frivinp_rtm = '/myPath/rdirc.myCase.nc
      % xmlchange -file env_run.xml -id ROF2OCN_FMAPNAME -val '/myPath/map_r05_nomask_TO_gx1v6_myCase_aave.150902.nc'
      % xmlchange -file env_run.xml -id ROF2OCN_RMAPNAME -val '/myPath/map_r05_to_gx1_myCase_e1000r300_150902.nc'


    (Return to top)



    Atmosphere model (CAM4/CAM5)

    1. How do I change topography in a Near Modern simulation

      Paleoclimate modelers can use a CESM fortran tool called definesurf to create smoothed surface topography for paleo simulations. Near-modern paleo modelers can use definesurf to map minor topography modifications onto the present day default CAM bnd_topo file. Typical scientific applications might include incorporating ice sheets across N. America, or modifying the Greenland or Antarctic Ice Sheets. Note: If you are using CAM4, and have extended land over ocean points (e.g., over Hudson Bay), you can modify landm_coslat.ncl using mod_landm_coslat.ncl.

      NOTE: Near-modern modelers are advised to make changes to topography by first creating an anomaly map of their time period relative to present day (ΔZ = my_TOPO_paleo– my_TOPO_present-day) and then adding this anomaly (ΔZ) to the CESM present-day base topography.

        Definesurf

        Definesurf is a CESM tool used to create smoothed topography files for cam (bnd_topo). This process was modified for Deep Time by adding several steps (see below).

        • PHIS: surface geo-potential [m2/s2])
          • PHIS [m2/s2] = elevation[m] × gravity [m/s2].
        • SGH [m]: standard deviation of surface elevation.
        • SGH30 [m]: surface roughness
        • LANDFRACT: (deprecated) ignored by CAM4 and CAM5; fractional land is defined by the coupler mapping files.
        • LANDM_COSLAT: (deprecated) CAM3/CAM4 scale factor for offshore aerosols; no longer used in CAM5.
        • from_hires: (deprecated) Definesurf adds the attribute: from_hires = "true" to all output variables, prior versions of the model used this attribute to force CESM to do additional spectral filtering at runtime. This feature is no longer active in CESM1.0.

        Warning

        By default, the Ross Ice Shelf is hardcoded to 'land' in definesurf to represent modern day. To turn off the hardcoding for the Ross Ice Shelf, use the commandline flag "-r" (see Example 2 below).

        Command line examples

        General Form:
        • % definesurf -remap -t topofile -g gridfile -l landm_coslat.nc outfile.nc

        Example 1: FV 0.9x1.25 grid, Ross Ice Shelf turned ON
        • % definesurf -remap -t topo_10min.nc -g fv_0.9x1.25.nc -l landm_coslat.nc topo_remap.nc

        Example 2: FV 1.9x2.5 grid, Ross Ice Shelf turned OFF
        • % definesurf -remap -r -t topo_10min.nc -g fv_1.9x2.5.nc -l landm_coslat.nc topo_remap.nc

    2. How do I change topography in a Deep Time simulation

      Deep time modelers can also use definesurf to create smoothed topography. However, paleo maps lack high resolution information like surface roughness and topographic variance so we approximate these attributes based on present day topographic relationships.

      Definesurf requires a 10min input data, so the first step is to use NCL to remap the base input topography onto a 10min grid. We then run definesurf, using the '-r' flag to turn off the hardcoded Ross Ice Shelf. We also input the modern 'landm_coslat' file, because it is required by definesurf, but it will not be used by CAM5. We use 'ftopo' for landfrac and 'htopo' for topography; this allows definesurf to be run as an 'old style' input where definesurf is not expecting a topography 'variance', which which we don't have for deep time. We also provide the grid map required by definesurf: fv_1.9x2.5.nc (or fv_0.9x1.25.nc). With these inputfiles, definesurf creates SGH, but not SGH30, which is needed in CAM5. Therefore, we approximate SGH30 from the modern global average ratio of SGH30/SGH: SGH30 = SGH*0.16.

      Using definesurf for Deep Time

      Step 1) create a 10min topographic datafile
      • src: mk_10min_definesurf_input_paleo.ncl
      • inf1: USGS-gtopo30_10min_c050419.nc
      • inf2: permian_topo.05deg.nc
      • out1: permian_topo.10min.{DATE}.nc

      Step 2) run definesurf with Ross Ice Shelf turned OFF (-r option)
      • % ./definesurf -remap -r -t permian_topo.10min.{DATE}.nc -g fv_1.9x2.5.nc -l landm_coslat.nc bnd_topo_permian_1.9x2.5_remap.{DATE}.nc

      Step 3) Add SGH30 with 0.16 ratio (estimated from global PD SGH30/SGH ratio).
      • src: add_SGH30_paleo.ncl
      • in1: bnd_topo_permian_1.9x2.5_remap.150331.nc
      • of1: bnd_topo_permian_1.9x2.5_remap_sgh30.150331.nc

      Warning

      The 'add_SGH30_paleo.ncl' excludes LANDM_COSLAT in the bnd_topo file to avoid confusion, because the LANDM_COSLAT landmask is modern and CAM5 doesn't use landm_coslat. If you are using CAM4, set the 'write_landm_coslat' flag to TRUE in 'add_SGH30_paleo.ncl'.

    3. CAM4/CAM5 namelist options [user_nl_cam]

      This section describes the namelist parameters that control aspects of your physical boundary forcing.

    4. Orbital parameters

      Orbital parameters are set in the coupler namelist for a fully coupled CESM1 experiment.

    5. Solar constant and trace gases

      Variable Description
      solar_const Solar constant
      co2vmr CO2 volume mixing ratio
      ch4vmr CH4 volume mixing ratio
      n2ovmr N2O volume mixing ratio
      f11vmr1 CFC11 volume mixing ratio
      f12vmr1 CFC12 volume mixing ratio
      1 For Pre-Industrial paleo experiments, F11VMR and F12VMR should be set to 0.

    6. How do I change the atmosphere timestep to improve stability


      Part 1. Changing the atmosphere timestep (dtime) can improve model stability, particularly in the early years of a simulation as the model is adjusting to new boundary conditions. The atmosphere timestep (dtime) is set by the coupling frequency (ATM_NCPL) which is the interval at which the model physics and the dynamical core exchange information. Increasing the frequency of communication between the physics and the dynamics can increase model stability. ATM_NCPL can be changed in env_run.xml. The default coupling frequency is 48, which corresponds to an atmosphere timestep of 1800 seconds, or 30 minutes (ATM_NCPL = 48; dtime=1800s). To increase dtime, change ATM_NCPL to 96, which lowers the dtime to 900 seconds, or 15 minutes (ATM_NCPL = 96; dtime=900s). Note that lowering the timestep will increase model cost, so you may want to return to the default value once past the instability.

      ATM_NCPL » env_run.xml

      • ATM_NCPL sets the number of times the atm is coupled per NCPL_BASE_PERIOD

      • The atmosphere coupling interval (atm_cpl_dt) is set by ATM_NCPL. Setting the coupling frequency will automatically adjust the atmosphere timestep (dtime). In CESM, the coupling frequency for the atmosphere, land and ice must be the same, so changing ATM_NCPL will also adjust the timestep of the land and ice models.

          DEFAULT : dtime = 1800 seconds : ATM_NCPL = 48
          LOWERED : dtime = 900 seconds : ATM_NCPL = 96

      • ATM_NCPL must be changed in env_run.xml:

          ./xmlchange -file env_run.xml -id ATM_NCPL -val 96

      WARNING: Do not attempt to change dtime in user_nl_cam. In contrast to earlier model versions, directly modifying (dtime) is no longer an option in CESM-CAM5. Doing so can result in a silent error where the model changes coupling frequency in some places but not others, resulting in an imbalance in the net radiation fluxes. This problem has been fixed in more recent versions of CAM5.

      Part 2. Expert users may also try changing the dynamical substepping within dtime. Check the CAM5 documentation for information on nsplit (the number of dynamics timesteps per physics timestep), nspltrac (the number of tracer advection timesteps per physics timestep), and nspltvrm (number of vertical re-mapping timesteps per physics timestep). Also see the CESM Bulletin Board for more discussion (e.g., https://bb.cgd.ucar.edu/node/1002415). A change to nsplit might look like this:

      • nsplit = 8
      • nspltrac = 4
      • nspltvrm = 4

      You can also try changing the type of divergence damping and velocity diffusion. Consult the CAM user's guide for more guidance.

      • div24del2flag1 = 4

      1div24del2flag :: Chooses type of divergence damping and velocity diffusion.

    7. Other atmosphere forcing files:

      Absorption/Emissivity:
      The present day absorption/emissivity forcing dataset was built with wide constraints and is therefore flexible and can be used for paleoclimate cases.
      [CESM1.0 DEFAULT]
      Ozone:
      Typically, present day or pre-industrial ozone mixing ratio boundary forcing files are used for paleoclimate cases. Choice of dataset will depend on your control experiment.
      [CESM1.0 DEFAULT]

      Background:

      Modifying atmospheric aerosals for paleo simulations became considerably more complex in CESM1.2 than it was in earlier versions of the model.  Tauback (typically used for CCSM3 paleo simulations) is not available.  Christine Shields developed a new technique to define aerosols for user-specified geography within CESM1(CAM4/5).  Download the 2011 CCSM workshop presentation of her results.

      Recommendation:  You can run with bulk aerosols, but that is very expensive.  A better alternative is use the procedure described below.

      How to create a prescribed aerosol dataset for deep time paleo:

       
      1. turn off prescribed aeorsols, use bulk, i.e. trop_bam
      2. this gives us dust and sea salt (primary aerosols)
      3. for bam: create zonal distributions of oxid, dms, bc, and oc and soil erodiablity based on land
         i.e., avg modern grid points over ocean (where appropriate), avg modern grid pts over land, give
         avg values to paleo 2d data forcing files over respective lat and land
      4. create prescribed aerosol (radiative) set based on BAM run
      5. create prescribed aerosol (deposition) based on run BAM run

       

      For BAM run:

      --(1) create forcing data w/ncl scripts

      see cam.input_data_list for bulk aerosols:

      don't need deposition velocity stuff unless using chemistry.
      1) do nothing about depvel_monthly.nc, clim_soilw.nc, and season_wes.nc --not needed
      2) do nothing to  do about regrid_vegetation.nc -- not needed

      new datasets for:
      1) oxid: oxid_1.9x2.5_L26_1850clim_c091123.nc
      2) soil erod:  dst_48x96_c090203.nc
      3) so2:  aerocom_SO2_vertical_1750.c080807.nc lat/mtns?
               aerocom_SO2_surface_1750.c080807.nc  lat/mtns?
      4) so4:  aerocom_SO4_vertical_1750.c080807.nc
               aerocom_SO4_surface_1750.c080807.nc
      5) CB1:  aerocom_CB1_1750.c080807.nc  (lat dist)
      6) DMS:  aerocom_DMS_2000.c080417.nc (lat dist)
      7) OC1:  aerocom_OC1_1750.nosoa.c080807.nc (lat dist)

      create ncl scripts to read in template (default) file, and modify accordingly
      details: see fis/cgd/ccr/shields/permian/ccsm4/atm/bulk_aero_files/data/README.whatidid

      --(2) take output from BAM and create prescribed forcing aerosol (raditative)
            (from jf email)

              (a) ncra -h -v
      lat,lon,lev,time,date,datesec,hyam,hybm,hyai,hybi,PS,P0,T,CB1,CB2,OC1,OC2,SO4,SOA,
      DST01,DST02,DST03,DST04,SSLT01,SSLT02,SSLT03,SSLT04

             (b) then you concatenate all those into a single file (beware that sometime p0 becomes 0_

             (c) you probably need to overwrite date and time as those also get messed
                up with ncra.

              SCRIPT written: /fis/cgd/ccr/shields/permian/ccsm4/atm/presc_aero_files/aero_climo.csh

              (d) NOTE: does not need to be interpolated to fv2deg res (as default). model will accept
                  any resolution, (eaton), and interp, on the fly, if necessary. normally all model
                  configs use the fv2deg, but you can supply a file at the correct config resolution to
                  begin with...              

      ** although in theory (d) is true, code currently buggy and the aero file doesn't
                         work,  use aero_climo_interp.ncl to put onto fv2deg grid. (march 4 2011). bug
                         reported to b.eaton and f.vitt.

      --(3) branch basic default (BAM) run (or change in original) to include vars necessary for deposition
             to create aero dep file for prescribed aero run.
            (from jf email)

              (a) monthly avg hist needed:
              DF_CB1   (need to include in finc1)
              DF_CB2   (need to include in finc1)
              CB2SFWET  (default bam)
              DF_OC1    (need to include in finc1)
              DF_OC2    (need to include in finc1)
              OC2SFWET  (default bam)
              DST01DD   ("")
              DST01PP   ("")
              DST02DD  ("")
              DST02PP  ("")
              DST03DD  ("")
              DST03PP  ("")
              DST04DD  ("")
              DST04PP  ("")

              (b)  run dep_snow.f90 (from jf): original code: /fis/cgd/home/shields/ccsm4/aerodep
                                               workingdir code: this dir...
                                              /fis/cgd/ccr/shields/permian/ccsm4/atm/presc_aero_files

               (c)  overwrite time and date with 1850 default values, and add source run to global history
                    script to do this:                aerodep.nco.csh

      ncks --append -v date,time /fis/cgd/ccr/shields/permian/ccsm4/atm/presc_aero_files/default_1850/date_time_1850clim.nc aerosoldep_monthly_12-21_mean_b40.t31x3.pt.4.nc
      ncatted -a history,global,a,c,"b40.t31x3.pt.4.cam2.h0* files years 12-21 cshields 110303" aerosoldep_monthly_12-21_mean_b40.t31x3.pt.4.nc


              (d) this seems to work fine w/T31.


    (Return to top)



    Landuse/landcover

    1. The Land model

      The land component of CESM1.x is the Community Land Model, version 4.0 (CLM4) or version 4.5 (CLM4.5).  This documentation supports CLM4, version 4.0.  The CLM4 requires a surface dataset that defines the spatial distribution of vegetation, surface water, and land ice. This surface dataset is created offline, using CLM tools and the set of 'raw' datafiles, most of which are at half-degree resolution, that define the spatial distribution of vegetation types (expressed as plant function types or PFT), soil color, soil texture, leaf/stem areas and heights, inland lakes, urban area and land ice data.

      e.g., set fsurdat = ‘surfdata_0.9x1.25_simyr1850_c091006.nc’

      Many near-modern simulations are able to use the present day (default) surface dataset.  However, if you want to make changes to your land cover (e.g., by adding/removing land ice or by changing vegetation), you will need to create a new surface dataset to reflect these changes.  The surface dataset requires 'raw' data at 0.5 degree grid resolution netCDF files called 'mksrf' files.  These data reflect the spatial distribution of vegetation types (PFT), inland lakes, and land ice data for the land model. 

      NOTE:  If you plan to lower sea level and expose new land along the continental shelf, CLM4 will automatically define that new land as ‘wetland’. We provide a tool that will modify your mksrf files (PFT, soil color and LAI) using a nearest neighbor algorithm to fill in the new land points (see Table below).

      NOTE:  Modifying mksrf_pft.nc can be tricky and drastically changing vegetation may result in a climate signal that is larger than the forcing that you are testings.

    2. Changing land ice

      If your experiment requires a change in land ice, we provide a set of tools that will modify the default raw data files to reflect land surface changes in glaciers, lakes/wetlands, and PFTs.  The programs will also remove crops, and set harvest variables to zero. The modeler needs to provide a netCDF file of surface topography and land ice at 10min resolution.  NOTE:  If you have added new land (and/or ice-covered land) over ocean grid cells (e.g., Fenno-Scandia, Hudson Bay) you will also need to create new coupler mapping files to reflect the change to the land/sea mask.

       

       scriptdescription
      mk10minTopo.ncl 
      10min2_05deg.nclCreate 0.5 degree topo-ice file for convert_mksrf.F90

      convert_mksrf.F901

      (rewrite in ncl)

      		modify default (modern) raw mksrf files to be consistent w/ your new landice files.  Output: mksrf_lanwat.15ka.nc, mksrf_pft.15ka.nc
      mksrf_glacier.15ka.nc.  See usage below.
      remove_crops.nclset crops to 0. use nearest neighbor for cells where crop==100%; add req'd pft harvest variables; set harvest to 0.
      nn_fill.ncl2 (beta)use nearest neighbor interpolation to fill new land cells.  Notes:  soil color2, lai3
      create_mksrf_topo.nclcreate raw topo dataset.
      create_mksrf_urban.nclcreate raw urban dataset; set urban to 0.
      nn_fill.mapunits.ncl (WIP) -- SKIP --

      cesm1_2_0/models/lnd/clm/

      tools/shared/mkmapgrids

      		 SCRIPgrid_lgm_360x720.140801.nc

      cesm1_2_0/models/lnd/clm/

      tools/shared/mkmapdata

      		create land mapping file

      cesm1_2_0/models/lnd/clm/

      tools/clm4_0/mksurfdata_map

      		 

      mksurfdata_map.namelist.15ka4

        

       

      1 Usage:   convert_mksrf

      1.  cp convert_mksrf.template convert_mksrf.template.myrun 
      2.  modify convert_mksrf.template.myrun to point to your input files 
      3. cp convert_mksrf.template.myrun convert_mksrf.F90
      4.  compile (make -f Makefile.nwsc)
      5.  execute:  ./convert_mksrf

       2 We use the default soil color file because it (1) already assigns soilcolor = 15 to new land, and (2) the landmask is not used: pftlandusedyn.0.5x0.5.simyr1850-2005.c090630/mksrf_soilcol_global_c090324.nc

      3 Monthly_height_BOT = constant for given PFT; MONTHLY_HEIGHT_TOP = constant for given PFT; MONTHLY_LAI and MONTHLY_SAI:  interpolate from nearest neighbor.

      4Path:  /glade/p/cesm/palwg/cesm1_2_0/models/lnd/clm/tools/clm4_0/mksurfdata_map/; Usage: mksurfdata_map < mksurfdata_map.namelist.15ka

    3. Changing land cover

      CLM4 does not require an initial condition file and can be initialized with arbitrary initialization and the surface dataset created from your mksrf datafiles [finidat = ‘ ‘].  You can also restart from an existing simulation, using clm2.r files to initialize your new experiment. 

      However, if you have changed your land cover in your new simulation (for example, if you have changed your land ice distribution), you will first need to create a new clm2.r file that conforms to the new land cover assignments in your modified surface datafile.  Creating a new clm2.r file is a two step process.  Step 1:  Run a short (e.g., 5 day) startup simulation with arbitrary initial conditions and your new surface dataset. The 5 day simulation will produce a restart file that is consistent with the ice distribution in your new surface dataset, which is different from the original experiment that you wish to branch from.  Use the tool, interpinic, to re-map the restart data from the original simulation to the new restart file created by the 5-day run.

      1. Set up and run a 5-day startup simulation with your new surface dataset and arbitrary initialization to create a CLM restart file consistent with your new surface dataset.

        -- user_nl_clm

        finidat = ‘ ‘

        fsurdat = '/mypath/surfdata_RESOLN_myrun.nc'

      2. Map the data from the original restart file (original.clm.r.nc), onto the newly created restart file (my5day.clm.r.nc) using the tool interpinic, which is included with the CESM1 release.

        % interpinic -i original.clm.r.nc -o my5day.clm.r.nc

      3. Rename the newly remapped file to reflect its history.

        % mv my5day.clm.r.nc original.clm.r.IP.nc  (IP ~= interpinic)

      4. NOTE: CLM4 will not allow you to specify both a surface dataset and finidat in user_nl_clm. If you get an error when running preview_namelist, then comment out the finidat line in user_nl_clm, and edit Buildconf/clm.buildnml.csh to point explicitly to your new file:

        -- user_nl_clm:

        fsurdata = '/mypath/surfdata_RESOLN_myrun.nc'

        ! finidat = '/mypath/original.clm.r.IP.nc'  (comment out)

        -- Buildconf/clm.buildnml.csh:

        clm_startfile = "/mypath/original.clm.r.IP.nc"

    4. PFT-physiology dataset

      The CLM4 land model defines the physiology of each plant functional type (PFT) in an ASCII text file, called ‘pft-physiology’.  The default pft-physiology definitions are generally used for paleo experiments.  However, if you wish to change the characteristic of a specific CLM4 PFT you may need to edit this dataset. Please read the CLM4 documentation before altering this file and/or contact a CCSM paleo liaison for a consultation.

    5. Runoff directional dataset (rdirc)

      The River Transport Model (RTM) runs inside the land model on a fixed regular grid that is different from the parent CLM4 grid (the CLM4, CAM4 and CAM5 models typically use the same grid). The runoff directional dataset required for RTM is an ASCII file containing latitude, longitude, and an integer value describing the vector (direction) for runoff flow at each RTM grid point. The integer values are numbered from 1 to 8: 1=N, 2=NE (45o), 3=E (90o), 4=SE (135o), 5=S (180o), etc.   Most near-modern experiments are able to use the default runoff directional dataset (rdirc.05) pointed to in clm.buildnml.csh. 

    6. What are 'mksrf' files

      The surface dataset is constructed from a series of seven 'raw' datafiles. These datasets are named ‘mksrf_[*].nc’ and include surface data information for PFTs (plant functional types), soil color, soil texture, leaf/stem areas and heights (LAI), land water (lakes and wetlands), glaciers, and urban areas. Offline CESM tools use these 'raw' datasets to create the surface dataset (fsurdat), tailored to your land and ocean grids.

    7. Near Modern: How do I modify mksrf landuse/landcover files for a Near Modern simulation

      Near Modern simulations can use any software tool to modify the mksrf files (e.g., add glaciers, change vegetation, etc.). Users can also use convert_mksrf, a tool developed for use on NCAR machines, to modify existing mksrf files. NOTE: This code and it's Makefile were designed to run on NWSC machines: (yellowstone, geyser, caldera). Users are responsible for modifying the code for other platforms.

      TOOL: convert_mksrf.csh
      Source : Source

      INSTRUCTIONS
      1) cp convert_mksrf.template convert_mksrf.template.myCase
      2) edit convert_mksrf.template.myCase
      !-----------------------------------------------------------------
      !! point to your files
      !-----------------------------------------------------------------
      filei = '/public/topo/topo-ice.0.5degree.myCase.nc'
      fileig = '/inputdata/lnd/clm2/rawdata/mksrf_glacier.060929.nc'
      fileip = '/inputdata/lnd/clm2/rawdata/pftlandusedyn.0.5x0.5.simyr1850-2005.c090630/mksrf_landuse_rc1850_c090630.nc'
      fileil = '/inputdata/lnd/clm2/rawdata/mksrf_lanwat.050425.nc'
      fileog = '/public/rawdata/mksrf_glacier_lgm21ka.110106.nc'
      fileop = '/public/rawdata/mksrf_pft_lgm21ka.110106.nc'
      fileol = '/public/rawdata/mksrf_lanwat_lgm21ka.110106.nc'
      !-----------------------------------------------------------------
      3) cp convert_mksrf.template.myCase convert_mksrf.F90
      4) gmake -f Makefile.nwsc
      5) ./convert_mksrf

    8. Deep Time: How do I create mksrf landuse/landcover files for a deep Time simulation

      Deep Time modelers can create these files using the script: paleo_mkraw_cesm1.csh. The script reads a user-provided lat/lon map of LSM vegetation types in netCDF format (e.g., vegetation.nc) and current day soil texture profiles (mksrf_soitex.10level.nc) to create the ‘raw’ surface datafiles required by CLM4. These datasets are named ‘mksrf_[*].nc’ and include surface data information for PFTs (plant functional types), soil color, soil texture, leaf/stem areas and heights (LAI), land water (lakes and wetlands), glaciers, and urban areas. Offline CESM tools use these raw datasets to create the surface dataset (fsurdat), tailored to your land and ocean grids.

      TOOL: paleo_mkraw_cesm1.csh
      Source : Source

      Details:
      » Specify the resolution of your incoming LSM vegetation dataset by setting longitude/latitude in paleo_mkraw_cesm1_sed.F90. For example, if your LSM vegetation map is at 2x2 degree resolution, then nlon=180 and nlat=90, and your mksrf_[*].nc files will also be 2x2 degree. If your input vegetation resolution is 0.5 degree, nlon=720 and nlat=360 and your mksrf_[*].nc files will also be at 0.5 degree resolution.


      9. »NOTE: The paleo_mkraw_cesm1.csh script assumes that glaciers=urban=lakes=wetlands=0, soil texture =loam and soil color=4. If this does not suit your needs, you will need to alter paleo_mkraw_cesm1_sed.F90 to make any desired changes. For example, if you would like to add glaciers, you will need to edit the subroutine create_mksrf_glacier and add code to test for LSM type 1 (land ice). For each point equal to 1, assign pct_glacier values from 0 to 100%. See the Near-modern section for a discussion on adding glaciers to near-modern simulations.

        Creating raw mksrf files
        Shell Script paleo_mkraw_cesm1.csh
        Source code paleo_mkraw_cesm1_sed.F90
        inputs vegetation.nc
        mksrf_soitex.10levels.nc
        output mksrf_glacier.myrun.date.nc
        mksrf_pft.myrun.date.nc
        mksrf_lai.myrun.date.nc
        mksrf_soicol.myrun.date.nc
        mksrf_lanwat.myrun.date.nc
        mksrf_soitex.myrun.date.nc
        mksrf_urban.myrun.date.nc
        mk_ffrac.ncl mksrf_ffrac.myrun.date.nc

    9. Surface dataset

      Changing the land/sea mask for deep time model experiments requires that the modeler create a new land surface dataset.  The surface dataset is created offline in a series of three steps outlined below. Note that the offline process differs from CCSM3, where the surface dataset was created at runtime. We recommend that users review the newly created surface_data_[resolution].nc for accuracy. When creating this dataset, CLM4/CESM1 uses the ocean grid to compute the land/ocean mask and create the respective variables onto atm/lnd grid. When this initial mapping is done, there are often mismatches between the ocean grid and the atmosphere grid. If the ocean model views a grid point as land, and the land model has no information on that grid point (because on the atmosphere grid it was considered ocean), then CLM4 assigns this point to be wetland. This typically occurs along the coastlines and may not be desired.  The modeler will need to modify the surface_data_[resolution].nc file to correct for these spurious wetland points.

      NOTE: The offline process for creating the surface dataset for CLM4.0 is outlined below. The process requires three steps. The second and third steps rely on CESM/CLM path dependencies that require you to run the scripts within the framework of your personal CESM1.2.x sandbox. However, the paleo tools listed below are not included in the official CESM release code, and must be downloaded from the online PaleoToolKit.

    10. Step 1. mkmapgrids

      This processes uses an ncl script to create a SCRIP grid file for the user defined land/sea mask. For Deep Time users, this creates a SCRIPgrid file for the 2x2 rawdata files with the paleo landmask.

      srcdir: /cesm1_2_1/models/lnd/clm/tools/shared/mkmapgrids
      src: mkscripgrid_paleo.ncl
      in:   mksrf_lanwat_{myRun}.nc !! land mask, edges, centers
      out: SCRIPgrid_{myRun}_{RESOLUTION}.nc

      % Usage: ncl mkscripgrid_paleo.ncl

    11. Step 2. mkmapdata

      Now map the SCRIPgrid file to the CESM land grid. We use a generic SCRIP land grid because its mask == 1 everywhere.

      srcdir: /cesm1_2_1/models/lnd/clm/tools/shared/mkmapdata
      src 1: regridbatch_paleo.sh
      src 2: mkmapdata_paleo.sh

      INSTRUCTIONS:

      • Copy mkmapdata_paleo.sh to mkmapdata_myCase.sh
      • Copy regridbatch_paleo.sh to regridbatch_myCase.sh
      • Edit mkmapdata_myCase.sh (Search for "Change me")
        • grids_ID (e.g., 2x2_PT)
        • INGRID (e.g., SCRIPgrid_PT_90x180.130921.nc from mkmapgrid)

      • Edit regridbatch_paleo.sh to point to mkmapdata_myCase.sh

      • NOTE: regridbatch_myCase.sh calls mkmapdata_myCase.sh


      in1: SCRIPgrid_myRun_.nc
      in2: /inputdata/lnd/clm2/mappingdata/grids/1.9x2.5_c110308.nc    !! generic
      out: map__to__nomask_aave_da_c.nc

      GEYSER INSTRUCTIONS: NOTE:  Yellowstone users should run this as a BATCH JOB on geyser

      % Usage:       bsub < regridbatch_myCase.sh                  !! POSSIBLE BUG:  batch submission may not be automatic

      The variable $LSF_PJL_TYPE should be set automatically to give the batch directive. If it is not set, the run will not submit in batch mode as required.  Workaround:  manually add the -b flag.


    12. Step 3. mksurfdata

      This is the final step to create a new surface dataset

      srcDir: /cesm1_2_1/models/lnd/clm/tools/clm4_0/mksurfdata_map

      INSTRUCTIONS:

      • Copy mksurfdata_map.namelist to mksurfdata_map.namelist.myCase
      • Edit mksurfdata_map.namelist.myCase
      • Run mksurfdata_map

        % Usage: ./mksurfdata_map < mksurfdata_map.namelist.myCase

    13. How do I run the CLM4.0 model from arbitrary initial conditions.

      CLM4 does not require an initial condition file and can be initialized with arbitrary initialization (finidat=" "). However, arbitrary initialization starts the model from essentially bare ground, with vegetation, soil carbon, soil nitrogen, and soil moisture set to zero. The land model will spin up all variables at once, but will therefore require many hundreds of years to come into equilibrium.

    14. How can I restart from a previous run if I have changed the land/sea mask.

      Alternatively, if your new land/sea mask is relatively close to modern, you could use interpinic to interpolate the land model initial conditions from a previously spun up CESM simulation into your new land model initialization file. Note that interpinic will not work for Dynamic Vegetation (CNDV) simulations.

      TOOL: INTERPINIC
      Source : /CESMROOT/models/lnd/clm/tools/clm4_0/interpinic

      • At present, interpinic does not work for CNDV clm.r files.
      • interpinic on yellowstone:
      • module load netcdf/4.3.0-rc4
      • make LIB_NETCDF=$NETCDF/lib INC_NETCDF=$NETCDF/include

      Details
      This process maps land cover data from one CESM file (e.g., run1.clm2.i.001.nc; the input file) to another file (run2.clm2.i.001.nc; the output file) by overwriting the contents of the second file. This process is required if surface fields have changed (e.g., landmask, ice, pfts etc). When these fields change, the clm.i files are not interchangeable.The input and output files may be of any spatial resolution and gridcell/landunit/column/pft configuration. In this case, run2 is the clm file produced by a 5-day 'startup' simulation that has the landmask and landcover mapping for your paleo simulation.

      Definitions
      case1 = output from a spunup CESM/CLM4 simulation (e.g., a default PI control: run1.1850control.clm2.nc)
      case2 = output from a 5-day simulation with paleo landmask:

      % Usage:

        % interpinic -i case1_1850control.clm2.r.nc -o case2_5dayPaleo.clm2.r.nc

      Hint: Rename output file to document the provenance for the input data : (IP = interpinic)

        OLD: case2_cret.clm2.r.nc
        NEW: case1_1850control.clm2.r.IP.nc

    15. How do I initialize Carbon/Nitrogen pools

      To run the land model with in a prognostic carbon (CN) mode, you will need to spin up the carbon and nitrogen pools. A land model spinup can be accelerated by running an offline I-case (compset = ICN) simulation to spin up the biogeochemistry C and N model (CN Spinup), and using output from this I-case to initialize a fully coupled CESM simulation.

    16. How do I turn on CNDV (CLM4.0)

      To turn on CNDV, modify env_build.xml:

      CLM_CONFIG_OPTS = "-phys clm4_0 -bgc cndv"

      % Usage:   ./xmlchange -file env_build.xml -id CLM_CONFIG_OPTS -val '-phys clm4_0 -bgc cndv'

      See the CLM4.0 documentation for instructions on how to spin up the Carbon-Nitrogen Dynamic vegetation model.

    17. Plant Physiology

      CLM4 model defines the physiology of each plant functional type (PFT) in a netCDF files, called pft-physiology.clm40..nc. The default (i.e., modern) pft-physiology definitions are generally used for paleo experiments. However, if you wish to change the characteristic of a specific CLM PFT, and you cannot accomplish your goal by modifying paleo_mkraw_cesm1__sed.F90, you may need to edit this dataset. We recommend that you read the CLM documentation before altering this file.


    (Return to top)



    Sea Ice model (CICE)

    1. ICE FORCING FILES

      Forcing files required for the sea ice model (CICE) are the ocean grid and the ocean bathymetry. A requirement in CESM1 is that the ocean and sea ice model components share the same grid, which is an irregular POP dipole grid; deep time modelers typically use a nominally 1o ocean/ice grid (gx1v6).

    2. ICE INITIAL CONDITIONS

      Ice initial conditions files are not required for deep time paleoclimate cases. We recommend initializing the ice model with a ‘no ice’ initial state and allowing the model to simulate an ice state. Set ‘no ice’ in the ice model namelist (user_nl_cice).

      ice_ic = 'none'


    (Return to top)



    Coupler

    1. Setting orbital parameters

      To simulate changes in Earth orbital position, the model calculates the eccentricity, obliquity and precession based on Berger et al., (J. Geophys. Res.1993).

      Quaternary/Near Modern: The model sets these parameters automatically using a variable called orb_iyear, which is set in the coupler namelist (user_nl_cpl) and is defined in years before 1950.

      Deep Time: Since we have no definitive estimate of orbital variations beyond ~1Ma BP, eccentricity, obliquity, and the moving vernal equinox must be defined explicitly for pre-Quaternary experiments. The CESM default orbital year for the B1850C5CN pre-industrial compset is 1850.

      QUATERNARY ORBITAL SETTINGS
      AD: (e.g., 1800, 1900, 1950, 1990, 2000, etc.) are expressed in calendar years.
      BC: (e.g., 10ka, 130ka, 506ka) are expressed in years relative to 1950:
      Example for calculating the orbital year from PD:
      506ka BP: orb_iyear = (1950 - 506,000) = -504050
      4ka BP: orb_iyear = (1950 – 4000) = -2050
      COUPLER NAMELIST (USER_NL_CPL)
      Example for the Last Glacial Maximum (21ka BP)
      orb_iyear = -19050
      orb_mode = 'fixed_year'
      COUPLER DOCUMENTATION
      cesm1.2 -- http://www.cesm.ucar.edu/models/cesm1.2/cesm/doc/modelnl/nl_drv.html
      COUPLER DEFINITIONS
      orb_mode (char) NOTE: orb_mode may cause early CESM tags to crash. If so, remove orb_mode from cpl.buildnml.csh and resubmit. "Orb_mode" sets how the orbital mode will be configured. "fixed_year" uses the orb_iyear and other orb inputs are ignored. In this mode, the orbital parameters are constant and based on the year. "variable_year" uses the orb_iyear and orb_iyear_align. In this mode, the orbital parameters vary as the model year advances and the model year orb_iyear_align has the equivalent orbital year of orb_iyear. "fixed_parameters" uses the orb_eccen, orb_mvelp, and orb_obliq to set the orbital parameters which then remain constant through the model integration. set by ORBITAL_MODE in env_run.xml. [fixed_year, variable_year, fixed_parameters] default='fixed_year'. orb_iyear (int): year of orbit, used when orb_mode is fixed_year or variable_year. set by ORBITAL_YEAR in env_run.xml. default=unset
      orb_iyear_align (int): model year associated with orb_iyear when orb_mode is variable_year. set by ORBITAL_YEAR_ALIGN in env_run.xml. default=unset
      orb_eccen: eccentricity of orbit, used when orb_mode is fixed_parameters. default=unset
      orb_mvelp : location of vernal equinox in longitude degrees, used when orb_mode is fixed_parameters. default=unset
      orb_obliq :obliquity of orbit in degrees, used when orb_mode is fixed_parameters. default=unset


    (Return to top)



    Common namelist changes for paleoclimate


    POP2 Namelist Changes

    !-- Specify the grid type to avoid the model assumption of a uniform grid in the southern hemisphere (i.e., gx1v6).
    lat_aux_grid_type = 'user-specified'
    lat_aux_begin = -90.0
    lat_aux_end = 90.0
    n_lat_aux_grid = 180
    !-- Set the grid type to 'user-specified' to avoid the model assumption of a uniform grid in the southern hemisphere (i.e., gx1v6).
    moc_requested = .true.
    n_heat_trans_requested = .true.
    n_salt_trans_requested = .true.
    n_transport_reg = 1
    !-- dt_count sets the number of times the ocean is coupled per NCPL_BASE_PERIOD. Decreasing the ocean timestep can improve model stability, particularly in the early years of a simulation as the model is adjusting to new boundary conditions. The default ocean timestep is 23.
    dt_count = 23 (Default)
    dt_count = 30 (Lowered)
    !-- Overflow regions are hardcoded in the ocean model to present day bathymetry and must be turned off for deep time geographies.
    overflows_on = .false.
    overflows_interactive = .false.
    !--To initialize from an ocean depth/salinity profile: init_ts_option = 'mean'
    init_ts_file = '/glade/p/cesm/palwg/paleo_setup/ocn/ic/ts_init_b20.681_1100-01_s_35.60level.dat'
    init_ts_option = 'mean'
    !-- lhoriz_varying_bckgrnd (flag to allow horizontally-varying background (need bckgrnd_vdc2=0.0)), ldiag_velocity (flag to compute velocity diagnostics), overflows and tidal mixing all are geographically dependent and so present-day setups are not appropriate for deep time paleogeography.
    lhoriz_varying_bckgrnd = .false.
    ldiag_velocity = .false.
    ltidal_mixing = .false.
    !--The new background vertical velocity parameters were determined by Gokhan and Christine to increase Kappa-v in the deeper ocean in absence of tidal mixing. The tidal mixing normally would do this.
    bckgrnd_vdc1 = 0.524 (default=0.16)
    bckgrnd_vdc2 = 0.313 (default=0.0)

    POP2 » Near Modern (LGM example) CESM POP2 namelist options

    region_mask_file = '/mypath/modify_kmt/region_mask_gx1v6_LGM.ieeei4'
    topography_file = '/mypath/modify_kmt/kmt_gx1v6_LGM.ieeei4'

    POP2 » Deep Time (Permian example)

    horiz_grid_file = '/mypath/ocn/mk_ocn_grid/permian/grid.pop.da'
    topography_file = '/mypath/ocn/mk_ocn_grid/permian/kmt.da'
    region_mask_file = '/mypath/ocn/region_mask/region.permian.be.ieeei4'
    region_info_file = '/mypath/ocn/region_mask/perm_gx1v6_region_ids.permian'
    diag_transport_file = '/mypath/ocn/region_mask/perm_gx1v6_transport_contents.permian'
    lat_aux_grid_type = 'user-specified'
    lat_aux_begin = -90.0
    lat_aux_end = 90.0
    n_lat_aux_grid = 180
    moc_requested = .true.
    n_heat_trans_requested = .true.
    n_salt_trans_requested = .true.
    n_transport_reg = 1
    dt_count = 23
    overflows_on = .false.
    overflows_interactive = .false.
    lhoriz_varying_bckgrnd = .false.
    ldiag_velocity = .false.
    ltidal_mixing = .false.
    bckgrnd_vdc1 = 0.524
    bckgrnd_vdc2 = 0.313

    CAM5 Namelist Changes

    CAM5 » Near Modern and Deep Time

    bnd_topo = '/mypath/definesurf/my_topo_remap.DATE.nc'
    (CAM5) ncdata = '/glade/p/cesm/cseg/inputdata/atm/cam/inic/fv/cami_0000-01-01_1.9x2.5_L30_c070703.nc'
    (CAM4) ncdata = '/glade/p/cesm/cseg/inputdata/atm/cam/inic/fv/cami_0000-01-01_1.9x2.5_L26_c070408.nc'

    Greenhouse gases
    Example 1: Fixed GHG
    scenario_ghg = 'FIXED'
    co2vmr = 279e-6 (CO2 volume mixing ratio)
    ch4vmr = 674.6e-9 (CH4 volume mixing ratio)
    n2ovmr = 266.9e-9 (N20 volume mixing ratio)
    f11vmr = 0.0 (CFC11 volume mixing ratio)
    f12vmr = 0.0 (CFC12 volume mixing ratio)
    Example 2: Time varying GHG
    bndtvghg = '/glade/p/cesm/cseg//inputdata/atm/cam/ggas/ghg_pmip3_850-2007_annual_c100517.v2.nc'
    scenario_ghg = 'RAMPED'

    Solar Forcing
    Example 1: Time varying solar
    solar_data_file = '/glade/p/cesm/cseg/inputdata/atm/cam/solar/SOLAR_SPECTRAL_VK_Lean_849-2008_annual_c130909.nc'
    solar_data_type = 'SERIAL'
    Example 2: Fixed solar (year 850AD)
    solar_data_file = '/glade/p/cesm/cseg/inputdata/atm/cam/solar/SOLAR_SPECTRAL_VK_Lean_849-2008_annual_c130909.nc'
    solar_data_ymd = 08500101
    solar_data_type = 'FIXED'
    Example 3: Fixed solar (year 1850)
    solar_data_file = '/glade/p/cesmdata/cseg/inputdata/atm/cam/solar/SOLAR_SPECTRAL_Lean_1610-2008_annual_c090324.nc'
    solar_data_type = 'FIXED'
    solar_data_ymd = 18500101

    Volcanic Forcing (Default=OFF)
    Example 1: Volcanoes turned ON
    prescribed_volcaero_datapath = '/glade/p/cesmdata/cseg/inputdata/atm/cam/volc'
    prescribed_volcaero_file = 'IVI2LoadingLatHeight501-2000_L18_c20100518.nc'

    CLM4.0 Namelist Changes

    CLM4.0 » user_nl_clm » Near Modern

    fsurdat = '/mypath/mksurfdata_map/surfdata_0.9x1.25_YD13ka_90_lat.nc'
    finidat = " "
    urban_hac = 'OFF'

    CLM4.0 » user_nl_clm » Deep Time

    fsurdat = '/mypath/lnd/mksurfdata_map/surfdata_1.9x2.5_per.nc'
    finidat1 = " "
    urban_hac = 'OFF'

    1finidat (See Known Problems)

    RTM Namelist Changes

    RTM » user_nl_rtm » Near Modern and Deep Time

    frivinp_rtm = '/mypath/lnd/rdirc/rdirc.0.5x0.5.per.nc'
    finidat_rtm = ' '

    CICE Namelist Changes

    CICE » user_nl_cice » Near Modern

    kmt_file = '/mypath/modify_kmt/kmt_gx1v6_YD.ieeei4'

    CICE » user_nl_cice » Deep Time

    grid_file = '/mypath/ocn/mk_ocn_grid/permian/grid.3.pop.da'
    kmt_file = '/mypath/ocn/mk_ocn_grid/permian/kmt.3.da'
    ice_ic = 'none'
    xndt_dyn = 2

    CPL Namelist Changes

    CPL » user_nl_cpl » Near Modern example for Last Glacial Maximum (-19050 = 1950-21,000)

    orb_iyear = -19050
    orb_iyear_align = -19050
    orb_mode = 'fixed_year' (optional: 'variable_year')

    CPL » user_nl_cpl » Deep Time

    orb_iyear = 1990 (1950, 1850, etc.)


    (Return to top)



    Common XML changes for Paleo simulations using CESM1.2.0

    These XML changes will help configure the CESM1.2.x model for a paleoclimate simulation. The files pointed to in env_run.xml are created by the user, using tools provided in the paleoToolKit.

    xmlchanges » Near Modern

    • xmlchange -file env_run.xml -id STOP_OPTION -val nyears
    • xmlchange -file env_run.xml -id STOP_N -val 5
    • xmlchange -file env_run.xml -id DOUT_L_MSROOT -val '/CCSM/csm/$CASE'
    • xmlchange -file env_run.xml -id RUN_REFCASE -val 'b40.plio.FV1.003'
    • xmlchange -file env_run.xml -id GET_REFCASE -val FALSE
    • xmlchange -file env_run.xml -id RUN_TYPE -val 'startup'
    • xmlchange -file env_run.xml -id RUN_STARTDATE -val '0451-01-01'

    xmlchanges » Deep Time » Point to new mapping files.

    • xmlchange -file env_run.xml -id GET_REFCASE -val FALSE
    • xmlchange -file env_run.xml -id RUN_TYPE -val 'startup'
    • xmlchange -file env_run.xml -id ATM_DOMAIN_FILE -val 'domain.lnd.fv09_1.25_gx1v6perm.141028.nc'
    • xmlchange -file env_run.xml -id ATM_DOMAIN_PATH -val '/mypath/gen_domain'
    • xmlchange -file env_run.xml -id LND_DOMAIN_FILE -val 'domain.lnd.fv09_1.25_gx1v6perm.141028.nc'
    • xmlchange -file env_run.xml -id LND_DOMAIN_PATH -val '/mypath/gen_domain'
    • xmlchange -file env_run.xml -id OCN_DOMAIN_FILE -val 'domain.ocn.gx1v6perm.141028.nc'
    • xmlchange -file env_run.xml -id OCN_DOMAIN_PATH -val '/mypath/gen_domain'
    • xmlchange -file env_run.xml -id ICE_DOMAIN_FILE -val 'domain.ocn.gx1v6perm.141028.nc'
    • xmlchange -file env_run.xml -id ICE_DOMAIN_PATH -val '/mypath/gen_domain'
    • xmlchange -file env_run.xml -id OCN2ATM_FMAPNAME -val '/mypath/mapping/map_gx1v6perm_TO_fv09_1.25_aave.141028.nc'
    • xmlchange -file env_run.xml -id OCN2ATM_SMAPNAME -val '/mypath/mapping/map_gx1v6perm_TO_fv09_1.25_aave.141028.nc'
    • xmlchange -file env_run.xml -id ATM2OCN_FMAPNAME -val '/mypath/mapping/map_fv09_1.25_TO_gx1v6perm_aave.141028.nc'
    • xmlchange -file env_run.xml -id ATM2OCN_SMAPNAME -val '/mypath/mapping/map_fv09_1.25_TO_gx1v6perm_blin.141028.nc'
    • xmlchange -file env_run.xml -id ATM2OCN_VMAPNAME -val '/mypath/mapping/map_fv09_1.25_TO_gx1v6perm_patc.141028.nc'
    • xmlchange -file env_run.xml -id ROF2OCN_RMAPNAME -val '/mypath/mapping/map_r05_to_gx1v6perm_nnsm_e1000r300_141028.nc'
    • xmlchange -file env_run.xml -id ROF2OCN_FMAPNAME -val '/mypath/rof/map_r05_nomask_TO_gx1v6perm_aave.141028.nc'

    xmlchanges » Ocean Grid » This is an example of changing the ocean decomposition if you have changed the size of the ocean grid (EXPERT USERS ONLY)

    • xmlchange -file env_build.xml -id OCN_NY -val 394
    • xmlchange -file env_build.xml -id ICE_NY -val 394
    • xmlchange -file env_build.xml -id POP_AUTO_DECOMP -val false
    • xmlchange -file env_build.xml -id POP_BLCKY -val 33

    xmlchanges » Turn on Dynamic Vegetation

    • xmlchange -file env_build.xml -id CLM_CONFIG_OPTS -val '-phys clm4_0 -bgc cndv'

    xmlchanges » Turn on debugging

    • xmlchange -file env_build.xml -id DEBUG -val TRUE


    (Return to top)



    Modern vs Paleo Gotchas

    Land modeldescription + Solution
    urban waste_heat Default: urban_hac='ON_WASTEHEAT'
    paleo: urban_hac= 'OFF'
    pct_urban set to 0 in mksrf_urban
    Atm Model description + Solution
    aerosols aerosol forcing files are set to present day spatial distribution.
    Ocean Model description + Solution
    region mask Tip: keep at least one active cell for near modern simulations
    new ocean cells new ocean cells need to be initialized for T/S
    new/modified KMT check for closed basins, narrow channels, one cell bays (check literature for time period)
    IAGE bug The non-standard initialization of TEMP & SALT is not compatible with CESM's restart script mechanisms. Despite CONTINUE_RUN being TRUE in env_run.xml, the model tries to initialize TEMP & SALT with the same IC as was used in the first submission. On restart, the IAGE initialization is trying to read from the same file that TEMP & SALT are being read from, but IAGE is not in that file. This leads to an error. Solution: Modify user_nl_pop2: init_ts_option = 'ccsm_continue' Make this modification when you are restarting after the initial submission.
    ncview When ocean history files are viewed using ncview, the year appears to be one year greater than the filename indicates. e.g., year 896-01 will appear be displayed as year 897-01 in ncview.
    hdr file hybrid and branch runs MUST have an ocean header file (.hdr) with the same name as the restart file. Simulations that are missing the header file will give a warning message ("... missing hdr file...") but will appear to run. They will usually fail, however, within a few days. e.g.,
    myrun.pop.r.0801-01-01-00000.hdr (ASCII header file)
    myrun.pop.r.0801-01-01-00000 (binary restart file)
    POP2 binary files grid POP2 expects big_endian grid and KMT files, regardless of the native format of the machine on which you are running CESM. This affects grid, KMT, region_mask
    NCL "popLatLon" This NCL function is used to remap the ocean grid to a lat/lon coordinate system. NCL expects a filenaming syntax that no longer matches what cesm1.2 ESMF mapping tools produce:
    map_gx1pt_TO_fv19_25_blin.130925.nc (ESMF)
    map_gx1pt_to_fv19_25_bilin_da_130925.nc (popLatLon format)
    diagnostics.F90 5 diagnostic locations are hardcoded (diagnostics.F90). If these points fall over land they cause the model to fail.
    PD ocean details turn off overflows for Deep time (see recommended user_nl_pop2 settings)
    Banda Sea diffusivity
    velocites change over lat/lon grid box (change in user_nl_pop2)
    Modern: lhoriz_varying_bckgrnd = .true.
    Paleo: lhoriz_varying_bckgrnd = .false.
    tidal mixing - turn off for deep time; increase to 6 levels for debugging (vmix_kpp.F90)
    Ross Ice shelf is not hardwired in CESM1.2
    Mediterranean Sea
    If you create a rotated grid (e.g., for deep time) you will need to check the western boundary anisotropic viscosity to make sure still on western boundary. i.e. *.pop.hv. file.


    Known CESM bugs that commonly affect paleoclimate simulations


    BugReportProblemsolution
    (Bugzilla 699) Mismatch between regionmask and KMT.Check for exact match between regionmask and KMT
    (Bugzilla 1274) init_ts_option 'mean' or 'zonal' case fails to continue automatically.manually change from init_ts_option='mean' to init_ts_option='ccsm_continue' in user_nl_pop2.
    (Bugzilla 1870) This bug causes two problems for Paleo users:
    ocn build error:
    "Duplicate definitions ... "; domain_size.F90 and POP_DomainSizeMod.F90 are not handled correctly in SourceMods/. build error: "ocn.bldlog.141022-105640:Duplicate definitions of module domain_size in domain_size and gx1v6_domain_size_plioWAIS: Inappropriate ioctl for device"
    		Problem #1: You can't have multiple versions of ".F90" code in your SourceMods/src.pop2 directory, even if they are named something other than domain_size.F90, or they will all be copied over, confuse the build, and cause a 'Duplicate definitions' error.
    Fix: Place the modified domain files in a separate directory, modify them, and copy them back to SourceMods/src.pop2 with the appropriate pop2 names

    cp myDir/gx1v6_domain_size_myRun.F90 $CASEDIR/SourceMods/src.pop2/gx1v6_domain_size_myRun.F90
     cp myDir/gx1v6_POP_DomainSizeMod.F90 $CASEDIR/SourceMods/src.pop2/gx1v6_POP_DomainSizeMod.F90
    Problem #2: cesm1_2_0 still won't compile with this code modification; it will give the same error.
    Fix: This bug was fixed in cesm1_2_1 and cesm1_2_2.

    cp /cesm1_2_1/models/ocn/pop2/bld/pop2.buildexe.csh to $CASEDIR/Buildconf; rebuild
    (Bugzilla 1625) build-namelist ERROR:: Can NOT set both -clm_startfile option AND finidat on namelist. ERROR: clm.buildnml.csh failed

    Solution: This is a workaround for the situation (e.g., a paleo simulation) where you have had to modify and rename the CLM4.0 finidat file, and can't use the default restart or the $RUN_REFCASE restart file. You need to modify clm.buildnml.csh to point to your new file.
    cd $CASEROOT/Buildconf/clm.buildnml.csh
    cp clm.buildnml.csh clm.buildnml.csh.orig
    vi clm.buildnml.csh
    OLD: set clm_startfile = "-clm_startfile ${RUN_REFCASE}.clm2.r.${RUN_REFDATE}-${RUN_REFTOD}.nc"
    NEW: set clm_startfile = "myCase.IP.nc"



    Debugging tips for paleoclimate simulations

    Build Issue » Model won't build after adding or modifying SourceMods

    • Problem: Depends file
    • Solution: Check that the Depends file is not empty: (e.g., $case/bld/atm/obj/Depends)
    Runtime Issue » ERROR: Model dies almost immediately; may not have an error message.
    • Check to be sure you are assigning the correct mapping files. The atm to ocean STATE vars are the ONLY ones that use bilinear mapping. if you accidentally give the bilinear mapping (or area average mapping) the wrong assignment, the model will crash right away.
    • If you have created new mapping files (particularly important for Deep Time simulations) run scrip_test (section 5.1.3 in the Paleo Tech Note). This tool creates spatial maps in netCDF format from the files created by scrip. These files are easy to look at using ncview and can often be used to identify problems.
    • If you get any time steps in at all, write out an instantaneous cpl history file at every time step to look at the various variables. Sometimes the atm/ocn grid ratios at the poles are too large (or too small).
    • If the model is crashing at timestep 0, and you have correctly set the mapping files (#1), try setting info_debug in env_run.xml to the highest value. This will write extra coupler STDOUT information to the log file which might help identify a problem.
    Runtime Issue » ERROR: ANGLE is outside its expected range
    • Problem: POP2 ANGLE
    • Solution: Check the binary file for errors and resolution. The POP2 model may be reading bad data from the binary grid or topography file.
    Runtime Issue » ERROR: original kmt not equal to actual kmt; POP aborting... ERROR kmt inconsistency for overflows
    • Problem: The POP2 model may be reading bad data from the topography/bathymetry (KMT) file.
    • Solution: Check that the KMT file was compiled with a big_endian flag.
    Runtime Issue » filew failed e.g., 26: -4.168408887446482E-069 1.674944354524342E-093
    ERROR
    26: filew failed, worst i, j, qtmp, q = 1 81
    26: -4.168408887446482E-069 1.674944354524342E-093
    49: filew failed, worst i, j, qtmp, q = 1 161
    49: -5.766523308738317E-069 2.637668946517899E-082
    • Solution: Check for bad data coming from the input files. The atmosphere may be trying to write NaNs after receiving bad input values.
    Runtime Issue » clinic blocks exceed max: increase max to 4
    • Problem: POP2 decomposition
    • Solution: This error may affect users who increase the size of the ocean grid. Example: 384 » 394
      • Turn off the automatic decomposition routine because it is hardwired for the default 320x384 grid
      • env_build.xml: set POP_AUTO_DECOMP » .false.
      • env_build.xml: edit size of POP_BLCKY: 32 » 33
      • Note: "NTASKS_OCN" * "NTHRDS_OCN" = 120 !! must equal POP_NX_BLOCK * POP_NY_BLOCK
      • Note: you may have to load balance the PE layout.
    RunTime Issue - surfrd_get_data: surfdata/fatmgrid lon/lat mismatch #1
    • Problem: gen_domain; The north/south extent of the latitudinal variable (yc) in the land domain (LND_DOMAIN_FILE) must match that of the CAM initial file (ncdata).
    • solution: Extend the yc variable from +/-90° in the domain.lnd file.
      • Check gen_domain.F90 for correct code (early versions may need to be modified):
        • OLD: set_fv_pole_yc = ichar(trim(arg))
        • NEW: set_fv_pole_yc = ichar(trim(arg))-48
      • Rebuild the gen_domain executable
      • Turn on 'set_fv_pole_yc' by running gen_domain with the "-p 2" option.
      prompt> ./gen_domain -m map_gx1v6plio_TO_fv09_1.25_aave.141017.nc -o gx1v6plio -l fv09_1.25 -c pliocene -p 2

    RunTime Issue - surfrd_get_data: surfdata/fatmgrid lon/lat mismatch #2
    • ERROR: surfrd_get_data: surfdata/fatmgrid lon/lat mismatch error
    • Problem: surface dataset LATIXY dimension. The latitude variable (LATIXY) in the surface dataset (fsurdat) must match the latitudinal extent of the CAM initial file (ncdata).
      • solution: Extend the yc variable from +/-90° in the domain.lnd file.
      • Check LATIXY extent:
          ncdump -v LATIXY surfdata_file.nc
      • If LATIXY does not extend from +/-90°, use changeLATIXY.ncl to rewrite it to +/-90°.
        prompt> ncl changeLATIXY.ncl
    Tip - Write SALT and TEMP to 'pop.h.once' file for debugging
      This tip may help users who introduce their own initial conditions for TEMPERATURE and SALINITY and want to check them.
      1. cd $CASEDIR/SourceMods/src.pop2
      2. cp /$CESMROOT/models/ocn/pop2/input_templates/gx1v6_tavg_contents .
      3. edit gx1v6_tavg_contents:

        gx1vg_tavg_contents
        Variable Old Value New Value
        TEMP 1 3
        SALT 13
        SST 13
      4. build
      5. run until it fails then + check 'pop.once' file.
      6. REMEMBER » to remove the modified gx1v6_tavg_contents file from your SourceMods/src.pop2 directory and REBUILD before starting your production run.

    Tip - Perturbing the atmosphere model using 'pertlim'

    Pertlim is a CAM5 namelist parameter used by CESM modelers to perturb CAM without changing climate. It is often applied to a suite of simulations with the purpose of differentiating between individual ensemble members. Pertlim is activated on initial files only. When CESM is reading restart files (e.g, for branch runs, or anytime when CONTINUE_RUN = TRUE), pertlim is ignored.

    This document describes a runtime application where pertlim is used to perturb an unstable run by slightly changing the model trajectory, and - hopefully - sidestepping a model instability.

    Hybrid Option

    Because pertlim operates only on initial files, you must hybrid your case if you are trying to nudge a run past an instability using pertlim. If you use pertlim for this purpose, I strongly recommend saving the original CASE directory intact so that you can retrace your steps with confidence. If you are trying this for the first time, I also recommend moving the run and archive directory aside for safety. You can also perform these changes within the original CASE and RUN directories, especially if you need to perturb the run more than once; but don't forget to document your changes each time you perform this perturbation .

    Example for CASEID=b.e13.B1850C5CN.f19_g16.001; RESTART YEAR=1890-01-01

    1. Move the old case, run and archive directories out of the way.
      • mv b.e13.B1850C5CN.f19_g16.001 b.e13.B1850C5CN.f19_g16.001_1850-1889
    2. Recreate the case directory with the same name.
      • ./create_newcase -case /mypath/b.e13.B1850C5CN.f19_g16.001
        -clone /mypath/b.e13.B1850C5CN.f19_g16.001_1850-1889
    3. Make these XML changes, referring back to the original case name.
      xmlchange -file env_run.xml -id RUN_TYPE -val hybrid
      xmlchange -file env_run.xml -id RUN_REFCASE -val b.e13.B1850C5CN.f19_g16.001
      xmlchange -file env_run.xml -id BRNCH_RETAIN_CASENAME -val TRUE
      xmlchange -file env_run.xml -id RUN_STARTDATE -val "1890-01-01"
      xmlchange -file env_run.xml -id RUN_REFDATE -val "1890-01-01"
      xmlchange -file env_run.xml -id CONTINUE_RUN -val FALSE
    4. Set pertlim in user_nl_cam. The integer portion of pertlim can be any number: 1.d-14, 4.d-14, 9.d-14, etc.
      user_nl_cam: pertlim = 2.d-14
    5. Remove namelist references in user_nl_cam, user_nl_clm, and user_nl_rtm (ncdata, finidat, finidat_rtm).
    6. Copy the restart files into your new run directory (if needed).

    Additional options

    If you need to perform perturbations more than once within the same CASEDIR, reset the RUN_STARTDATE and RUN_REFDATA:

      xmlchange -file env_run.xml -id RUN_STARTDATE -val "1890-01-01"
      xmlchange -file env_run.xml -id RUN_REFDATE -val "1890-01-01"
      xmlchange -file env_run.xml -id CONTINUE_RUN -val FALSE

    Tip - How do I change the atmospheric timestep to improve model stability. [an error occurred while processing this directive]

    (Return to top)

    • © 2020 UCAR | Privacy Policy | Terms of Use | Copyright Issues | Sponsored by NSF | Managed by UCAR | Webmaster/Feedback

    Postal Address: P.O. Box 3000, Boulder, CO 80307-3000
    Shipping Address: 3090 Center Green Drive, Boulder, CO 80301