Home » CESM Models » CESM1.3 Public Release » POP2 » The CESM1.3 POP2 FAQ

CESM Models

The CESM1.3 POP2 FAQ

 


The CESM1.3 POP2 FAQ

Nancy J. Norton

Susan Bates

Michael Levy

Gokhan Danabasoglu

National Center for Atmospheric Research

December 2013

Contents

  1. Introduction

  2. POP2 Forcing Questions

  3. Configure- and Build-Time Questions

  4. Non-convergence, Timestep Size, and Other Run-Time Questions

  5. The CESM POP2 Output Files

  6. Post Processing

    1. I deactivated the MOC computation during my $CASE execution. How do I compute the MOC after the run is completed?
    2. Is there a diagnostics package I can use to post-process output from my CESM1 POP2 case?

  7. Developer's Questions

    1. How do I add a POP2 variable to the tavg output files? Case 3 -- code support does not exist
    2. As a POP2 developer, how do I add a new POP2 namelist to the build-namelist procedure?


Introduction


This FAQ contains a compilation of common CESM1 POP2 user inquiries. It is intended to supplement the detailed usage information for CESM1 POP2 that can be found in the POP User's Guide. A general familiarity by the user of the the terminology and concepts in the CESM1 User's Guide is assumed.

POP2 Forcing

  1. Is there an automatic option for setting up "hosing" experiments in POP2?

    No.

    Presently, there is no CESM POP2 "out-of-the-box" option to support hosing experiments, which are intended to model the climate effects from the addition of freshwater to an ocean region. However, the following general guidance may be useful to modellers interested in developing such experiments on their own.

    Freshwater added at the ocean surface

    The CESM POP2 forcing subroutines are rather complex and intertwined, with many dependencies among the forcing modules. For several years we have wanted to redesign these routines to cleanly support all of our forcing options, but resource limitations and higher priorities have prevented us from doing so.

    Although a hosing option is not supported per se, it is very likely that all the elements that one would need are already in the code. However, we do not recommend activating these by trial-and-error namelist modifications, because this approach may have some unintended consequences that may not be apparent to the casual user.

    Instead, we recommend the following: If you want to perform hosing experiments in fully coupled simulations, you can modify forcing_coupled.F90 module. The specific subroutine that needs to be modified is pop_set_coupled_forcing. Essentially, you need to add the "hosing" virtual salt fluxes to the following segment in proper units: 

          !$OMP PARALLEL DO PRIVATE(iblock)
      do iblock = 1, nblocks_clinic
        STF(:,:,2,iblock) = RCALCT(:,:,iblock)*(  &
                     (PREC_F(:,:,iblock)+EVAP_F(:,:,iblock)+  &
                      MELT_F(:,:,iblock)+ROFF_F(:,:,iblock)+IOFF_F(:,:,iblock))*salinity_factor &
                    + SALT_F(:,:,iblock)*sflux_factor)
      enddo
      !$OMP END PARALLEL DO

    If you plan to use time-independent perturbations, these can be incorporated in this subroutine. The grid information is already accessible from this module, so you can define a geographic region.

    If you plan to use a time-dependent perturbation, this gets a bit complicated. You can create a netCDF file and read it in the pop_init_coupled subroutine. Then, the field needs to be interpolated in time. For both reading the data set and time interpolation, you can mimic what is done elsewhere in other CESM POP2 forcing subroutines.

    Freshwater added below ocean surface

    If you want to add the freshwater at depth, then you may not need to modify the surface flux subroutines. The POP2 model allows interior restoring of T and S, the so-called robust diagnostics technique. The idea is to add source terms to the model T and S equations at any depth range, at any strength, and at any place you want. These can be time-dependent as well. So, take a look at forcing_s_interior.F90, where you should be able to incorporate your fluxes fairly easily.


Interannual Forcing (IAF) Compsets

  1. What are the interannual forcing (IAF) compsets?

    The interannual forcing (IAF) compsets are those compsets that use the data atmosphere model (datm) to provide CESM1 ocean-only(C), ice-only(D), or ocean-ice(G) cases with forcing from version 2 of the Coordinated Ocean-ice Reference Experiments (COREv2) datasets.

    The IAF compsets include

    • CIAF (active-ocean-only with interannual forcing)
    • DIAF (active-ice-only with interannual forcing)
    • GIAF (active-ocean-ice with interannual forcing)

  2. What are the COREv2 datasets?

    For additional information on the COREv2 forcing datasets, see http://www.clivar.org/organization/wgomd/resources/core/core-ii

  3. Where can I get the COREv2 data?

    If you are running IAF cases on the NCAR machine yellowstone, you do not need to download the COREv2 data.

    If you are running IAF cases elsewhere, you do. See the full CESM1.2 instructions below.

  4. What versions of CESM recognize the IAF compsets?

    The IAF compsets are available in the CESM Release Version 1.0.4 (CESM1.0.4) and higher, including all versions of CESM1.1 and CESM1.2.

  5. If I create an IAF case on yellowstone, will it run out of the box?

    Yes, as long as you use CESM1.0.4 or higher, or any version of CESM1.1 or CESM1.2, to create your case.

  6. If I create an IAF case elsewhere, what do I need to do to get it to run?

    Before you can set up and run your IAF case on a machine other than NCAR's yellowstone, you will need to first download the forcing datasets onto your own disk location, then make modifications to the CESM so that it knows how to locate the data.

    You will be downloading a lot of data (~85-90 Gbytes), so make sure your disk is large enough to hold all of the data. Also, this disk must be visible from your case's execution directory.

    Here's how you can do this:

    1. Download your own copy of CESM1.2 (or higher versions) from the CESM website (follow the CESM Releases link from the main page ). The location where you download the code is called your $CCSMROOT directory.
    2. Download the interannual data (COREv2) from the GFDL website (http://data1.gfdl.noaa.gov/nomads/forms/mom4/COREv2.html). You want to download the "un-Corrected" data. When using the CESM, corrections to the data are made within the data atmosphere, so please be sure to get the uncorrected data. To learn more about this data, see the GFDL website.
    3. Let the model know where the downloaded files from the previous step reside:
      • Change all occurrences of the string '/ccsm/ocn/iaf' in the 
           /$CCSMROOT/models/atm/datm/bld/datm.template.streams.xml
        file (there are 10 of them) to match the directory name where you put your data. Do this BEFORE you issue the create_newcase command. This way, any case you create from this $CCSMROOT will find the data.
      • Let the model know where the CORE2.t_10.ArcFactor.T62.1997-2004.nc file resides. In the same file that you previously edited, 
           $CCSMROOT/models/atm/datm/bld/datm.template.streams.xml,
        find the filename and change the directory listed three lines above this (in between the indicators) to match the directory where you put your downloaded data.
    4. Issue the create_newcase command, referencing an IAF compset, from your modified $CODEROOT/scripts directory. Configure, build, and submit your job as usual. If you have followed the above steps, your new IAF cases will be configured to properly run on your machine.

  7. What are the differences when running IAF cases with CESM1.1 or CESM1.2 release code and previous model versions?

    TIPS FOR RUNNING INTERANNUALLY-FORCED CASES

    Because a user can run a simulation using any number of years from the IAF data, there are two subtle issues that can potentially affect a user. This first will be encountered if you are performing a comparison between cases in which you have used different cycle lengths to force the model. The second will be encountered if you are branching a new simulation from a simulation that was forced with a different cycle length.

    Because the IAF data now extend two more years (to 2009 rather than 2007), a user may easily encounter these two issues when using the default setup for the model. The examples below show ways to avoid mismatches between simulations using the new, 62-year data and simulations using the older, 60-year long data; however, these same principles may be applied to any simulations in which the forcing cycle length may differ. These examples also illustrate how to create simulations with varying forcing cycle lengths.

    COMPARISON

    Be aware that any new CESM1.1- or CESM1.2- release generated simulations have longer cycles (1948-2009) than simulations generated by older model versions, whose cycles include 1948-2007. If you would like to use the CESM1.2 release to compare with an older (pre CESM1.1) simulation, you can use the new code and force it to cycle over 1948-2007. To do this, input stream information into the user_nl_d*** files as indicated below.

    Here are the changes you need to add to user_nl_datm (for CIAF,GIAF,and DIAF): 

    streams = "datm.streams.txt.CORE2_IAF.GCGCS.PREC       $STARTYEAR 1948 2007",
          "datm.streams.txt.CORE2_IAF.GISS.LWDN        $STARTYEAR 1948 2007",
          "datm.streams.txt.CORE2_IAF.GISS.SWDN        $STARTYEAR 1948 2007",
          "datm.streams.txt.CORE2_IAF.GISS.SWUP        $STARTYEAR 1948 2007",
          "datm.streams.txt.CORE2_IAF.NCEP.DN10        $STARTYEAR 1948 2007",
          "datm.streams.txt.CORE2_IAF.NCEP.Q_10        $STARTYEAR 1948 2007",
          "datm.streams.txt.CORE2_IAF.NCEP.SLP_        $STARTYEAR 1948 2007",
          "datm.streams.txt.CORE2_IAF.NCEP.T_10        $STARTYEAR 1948 2007",
          "datm.streams.txt.CORE2_IAF.NCEP.U_10        $STARTYEAR 1948 2007",
          "datm.streams.txt.CORE2_IAF.NCEP.V_10        $STARTYEAR 1948 2007",
          "datm.streams.txt.CORE2_IAF.CORE2.ArcFactor  $STARTYEAR 1948 2007",
          "datm.streams.txt.presaero.clim_2000 1 1 1"

    Here are the changes you need to add to user_nl_dice (only for CIAF): 

    streams = "datm.streams.txt.CORE2_IAF.GCGCS.PREC $STARTYEAR 1948 2007",

    Here are the changes you need to add to user_nl_drof (for CIAF,GIAF,and DIAF): 

    streams=''drof.streams.txt.rof.diatren_iaf_rx1 $STARTYEAR 1948 2007''

    where $STARTYEAR is your model start year. If you are branching from a older model version simulation, please see #2b below.

    BRANCHING

    If you are branching a new IAF case using CESM1.2 from an IAF case run with an older, pre-CESM 1.1 model version, the reference years for the data will be different. For example, the five cycles will correspond to model years as follows:

    Cycle Older Model Versions CESM1.1
    1 years 1-60 years 1-62
    2 years 61-120 years 63-124
    3 years 121-180 years 125-186
    4 years 181-240 years 187-248
    5 years 241-300 years 249-310

    Let's say that you are going to re-run Cycle 5 of a previous run with some changes using the new code. The model reference year is 241, which corresponds to 1948 in the older versions. The $RUN_REFDATE in env_run.xml will need to be set to 0241 so that the model reads the correct restart files (from the old simulation); however, because the new code has the above reference years for the cycles, 241 would correspond to data year 2002, rather than 1948. To correct this, you must make the corresponding stream changes (see COMPARISON CAVEAT above) to the user_nl_datm, user_nl_dice, user_nl_docn, and user_nl_drof (depending on compset) using a $STARTDATE corresponding to the CESM1.1 data reference years.

    This modification ONLY applies if you are branching from a simulation created with an older version of the model. If you are running a 'startup' simulation with the CESM1.2 release, this modification is not needed.

(Return to top)


Configure- and Build-Time Questions

Return to top


Non-convergence, Timestep Size, and Other Run-Time Questions

(Return to top)


The CESM1 POP2 Output Files


(Return to top)


Post Processing

  1. I deactivated the MOC computation during my $CASE execution. How do I compute the MOC after the run is completed?

    There is "off-line" post-processing code written in NCL that computes the MOC using POP2 output files. This post-processing tool will work with the newer CESM code and with either the gx* or tx0.1v2 grids. With some modifications, this code can also be made to work with CCSM3 POP1 output as well.

    The documentation for that code is here: http://www.ncl.ucar.edu/Document/Functions/Built-in/moc_globe_atl.shtml

    The documentation also includes an example NCL script to make use of this function.

  2. Is there a diagnostics package I can use to post-process output from my CESM1 POP2 case?

    The CESM Ocean Model Working Group (OMWG) has diagnostics packages to assess both spatial and temporal characteristics of ocean model simulations. We perform such assessments routinely for output from both forced ocean and fully-coupled experiments. The use of these packages includes evaluating the validity and climate state of a particular coupled model simulation, assessment of whether new capabilities in any component model, when coupled to the entire coupled model system (i.e., a new model code base), have impacted the ocean, and validating long coupled control simulations.

    We expect to announce a new version of the OMWG diagnostics package with feature enhancements by the end of 2013.

    See the CESM Ocean Component (POP2) Metrics and Diagnostics page for a discussion of the POP2 diagnostics.

(Return to top)


Developer's Questions

  1. How do I add a POP2 variable to the tavg output files?
    Case 3 -- no code support exists

    First, search the CESM POP2 Fortran modules to see if your variable, VARNAME, is a model variable. If the model variable exists, but the tavg "handle" (tavg_VARNAME) associated with the model variable does not, you will need to add new code to the POP2 model.

    Suppose you are interested in putting the time average of the U velocity at level five into a POP2 time-averaged output file. You've already searched the gx1v6_tavg_contents file, but U velocity at level five is not on the list. Next, you've searched the POP2 modules, and although you found references to UVEL, tavg_UVEL, tavg_U1_8, and lots of tavg_U* variables, you've found nothing that looks like U velocity at level five.

    Because under this scenario you have not found what you want, you will need to modify the POP2 code. Note that in this example, you could also just extract level five from the 3D UVEL that is already written out to the $CASE.pop.h.yyyy* file, but let's just go with this example for now, assuming that you have good reason to want just U velocity at level five as a separate output variable.

    In adding support for new tavg output variables, it is easiest to mimic developments for similar variables, so let's use tavg_U1_8, the vertical average of U velocity over model levels one through eight, as our template. To instrument the POP2 code to write out our new varible, U velocity at level five, do the following:

    • $cd $CASE/SourceMods/src.pop2
    • cp $CODEROOT/models/ocn/pop2/source/baroclinic.F90 .
    • edit baroclinic, using tavg_U1_8 as a guide, adding the following lines in the appropriate places: 
                integer (int_kind) :: tavg_U5_5  ! U velocity in layer five


          call define_tavg_field(tavg_U5_5,'U5_5',2,                          &
                                 long_name='Zonal Velocity lvls 5-5',         &
                                 units='centimeter/s', grid_loc='2221')
          if (k == 5)  &
          call accumulate_tavg_field(UVEL(:,:,k,curtime,iblock),tavg_U5_5,iblock,k)
    • cd $CASE
    • build (or rebuild), then run your $CASE
    • examine your $CASE.pop.h.yyyy-mm.nc file, where you should find your new variable, U5_5.

  2. As a POP2 developer, how do I add a new POP2 namelist to the build-namelist procedure?

    There are two files that you must modify in order to introduce a new namelist into the POP2 build-namelist procedure, and then there are two options for how to populate the namelist.

    Suppose you have introduced the following namelist into the POP2 source code: 

    real (r8)            :: varname1
logical (log_kind)   :: varname2
integer (int_kind)   :: varname3
character (char_len) :: varname4
character (char_len) :: varname5
character (char_len) :: varname6

namelist / abc_nml /  &
           varname1,  &
           varname2,  &
           varname3,  &
           varname4,  &
           varname5,  &
           varname6

    To illustrate many different ways to handle values, we also work under the following assumptions:

    1. varname4 is a regular string,
    2. varname5 depends on a CESM environment variable, and
    3. varname6 is a filename for something located in the inputdata/ directory that is only used for a specific resolution.

    You will need to make the following changes to models/ocn/pop2/bld/ (or in $CASEROOT/SourceMods/src.pop2) to have &abc_nml appear in pop2_in:

    1. Edit namelist_files/namelist_definition_pop2.xml

    You need to add definitions to namelist_files/namelist_definition_pop2.xml for all 6 of the &abc_nml variable names.

    NOTES:

    1. In this file, the Default: value is for documentation purposes only. It has NO effect on the actual setting of the variable value in the pop2_in file.
    2. The entry for varname6 uses the attribute input_pathname="abs" to add the path of the CESM inputdata root directory.

    --- begin addition to namelist_definition_pop2.xml --- 

    <!------------------------------------->
<!---group abc_nml                 ---->
<!------------------------------------->

<entry
id="varname1"
type="real"
category="pop2"
group="abc_nml" >
A brief description about varname 1.

Default: 
</entry>

<entry
id="varname2"
type="logical"
category="pop2"
group="abc_nml" >
A brief description about varname 2.

Default: 
</entry>

<entry
id="varname3"
type="integer"
category="pop2"
group="abc_nml" >
A brief description about varname 3.

Default: 
</entry>

<entry
id="varname4"
type="char*256"
category="pop2"
group="abc_nml" >
A brief description about varname 4.

Default: 
</entry>

<entry
id="varname5"
type="char*256"
category="pop2"
group="abc_nml" >
A brief description about varname 5.

Default: 
</entry>

<entry
id="varname6"
type="char*256"
category="pop2"
group="abc_nml"
input_pathname="abs" >
A brief description about varname 6.

Default: 
</entry>

    --- end addition to namelist_definition_pop2.xml ---

    2. Edit build-namelist

    You need to add abc_nml to the build-namelist groups array (search for the string "my @groups"; you want the one with the comment "Set namelist groups to be written out"). This tells build-namelist that &abc_nml should appear in pop2_in. Note that the order of the listing in @groups determines the order that the namelists appear in pop2_in.

    --- begin addition to build-namelist --- 

    my @groups = qw(domain_nml
                  ...
                abc_nml
                  ...
                passive_tracers_on_nml);

    --- end addition to build-namelist ---

    While these first two steps tell the build-namelist script that &abc_nml exists and contains varname1 ... varname6, it does not actually add anything to pop2_in. There are two different ways to populate the namelist:

    3.1 Short-term solution (user_nl_pop2)

    After you create and configure your case, set all 6 variables in user_nl_pop2 by adding the following lines: 

    varname1 = 0.5
varname2 = .true.
varname3 = 15
varname4 = "abc123"
varname5 = "/dir/otherdir/netcdf_file.nc"
varname6 = "/glade/p/cesm/cseg/inputdata/other_netcdf_file.nc"

    This is the "short-term" solution because it requires updating user_nl_pop2 every time you create a new case that needs to read &abc_nml. It is a good way to run tests while you decide what variables need to be in &abc_nml, but it is not a permanent plan.

    NOTE:

    • You must specify the full pathname for varname6 in this case because build-namelist will not prepend "$DIN_LOC_ROOT/" to the value (and "$DIN_LOC_ROOT" will NOT be interpretted correctly from the user_nl_pop2 file, so you must type the path explicitly).
    3.2 Long-term solution (use the namelist_defaults_pop2.xml file)

    You can set default values in namelist_files/namelist_defaults.xml and then call the add_defaults() routine in build-namelist to read these values and add them to pop2_in. Sometimes variables need to be set directly by the add_defaults() routine, these should not included in the defaults file. In this simple example, varname5 is one such variable.

    NOTE:

    • Dependencies on grids should be specified in the defaults file rather than in build-namelist (functionally there is no difference but reducing the amount of logic tests in build-namelist both makes the script easier to read and reduces the likelihood of introducing a bug).

    --- begin addition to namelist_defaults_pop2.xml --- 

    <!---------------------------->
<!--abc_nml                 -->
<!---------------------------->

<varname1>0.5</varname1>

<varname2 ocn_grid="gx3v7"  >.false.</varname2>
<varname2 ocn_grid="gx1v6"  >.true. </varname2>
<varname2 ocn_grid="tx1v1"  >.false.</varname2>
<varname2 ocn_grid="tx0.1v2">.false.</varname2>

<varname3>15</varname3>

<varname4>abc123</varname4>

<varname6 ocn_grid="gx1v6">input_file.nc</varname6>

    --- end addition to namelist_defaults_pop2.xml ---

    --- begin addition to build-namelist --- 

    ##################################
# namelist group: abc_nml        #
##################################

add_default($nl, 'varname1');
add_default($nl, 'varname2');
add_default($nl, 'varname3');
add_default($nl, 'varname4');
add_default($nl, 'varname5', 'val'=>"${RUNDIR}/${output_d}o");

add_default($nl, 'varname6','nofail'=>1);
if (not $nl->get_value('varname6')) {
	add_default($nl, 'varname6', 'val'=>'unknown_abc_cell','noprepend'=>1);
}

    --- end addition to build-namelist ---

(Return to top)


2013-10-09 (njn01)

© 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