VisualCaseGen: Ridge World

!!! This page is under construction !!!

This example provides step-by-step guidance on how to generate a coupled idealized configuration that consists of an aquaplanet with land caps at the pole and a narrow land ridge extending between the two poles, similar to the configuration used in Wu et al (2021).  In the example given below, the visualCaseGen GUI is used to guide users through choosing their CESM components, setting up all the ocean input files, setting up all the land input files, and finally setting up and configuring their case.

Step 1: Install and launch VisualCaseGen and select "Custom" case

Download and install the VisualCaseGen tool following the instructions here.  Once you have launched VisualCaseGen and executed the first cell you should see something like this:

Here we are not running a basic predefined case with CESM.  We are modifying the configuration substantially by changing the ocean grid, ocean bathymetry, continental geometry and land surface properties, so you should select "Custom" here.

Step 2: Select model components

Having selected custom mode, you should now see a cell like the one below that allows you to select the time period of simulation (1850's forcing, 2000's forcing, transient historical) as well as the different model components to use and any special options within those components

Here we will select to run an 1850 case by clicking on the "1850" button.  Then we select the following component options: cam as the atmosphere; clm as the land component; cice as the ice component; mom as the ocean component, srof (i.e., stub run off) as the river component; sglc (i.e., stub land ice) as the land ice component; and, swav (i.e. stub wave) as the wave component.  In general, the "s" component options indicate "stub" components that are not active.

As you choose options, VisualCaseGen will cross out options that are incompatible with your choices.  In the end, our choices for this case look like this:

The "Physics and Options" tabs below this allow you to specify the physics and other options for your case.  Since we're following the setup of Wu et al (2021) we'll choose CAM4 as the CAM physics option

and we'll select CLM5 as the land surface option with satellite phenology (SP) mode which means that aspects of the land model such as leaf-area index are prescribed as opposed to being prognosed interactively by the land biogeochemistry.

For the other components, we'll just use the default settings.

Step 3: Select the model grid

After you have selected your model components, you'll see a section where you can select our model grid.  This can either be a "predefined" grid i.e., a grid that's already available and used within CESM, or it can be a "Custom" grid.  Here we are defining our own ocean grid and we're going to change the bathymetry and land mask, so we need to select the "Custom" option.  When you select "Custom" you'll see three tabs: one for selecting the atmosphere (ATM) grid; one for selecting the ocean (MOM6) grid; and, one for selecting the land (CLM) grid.

For the atmosphere, you are expected to choose an existing atmosphere grid within CESM.  Here, we'll choose the standard 1 degree resolution"0.9x1.25"

For the ocean, we're going to define our own ocean grid, starting from scratch, as opposed to modifying an existing grid.  This will open up the option to select whether your ocean is zonally reentrant or not as well as specify the resolution in the zonal (x) and meridional (y) directions.  Note that CAM cannot run in a regional configuration, so since we have selected CAM4 as our atmospheric component, the "Regional" grid extent option is not available to us.

So, to set up a 1 degree grid, that is zonally reentrant we will select the "Global" grid extent and "True" for zonally reentrant.  We'll specify 360 cells in the x direction and 180 cells in the 7 direction and specify the length of the grid in the x direction to be 360 degrees and the length of the grid in the y direction to be 180 degrees.  Note that the grid length expected here is the total length across all grid cells as opposed to the length of an individual grid cell. 

Now we can press the green "Launch mom6_bathy" button.  This will launch the mom6_bathy tool that in a separate jupyter window and this can be used to set up the ocean bathymetry, land mask, and associated ocean model input files.  Upon launching the mom6_bathy tool, it will likely ask you to select a python kernel.  Make sure to select the VisualCaseGen environment.

Step 4: Configure the ocean bathymetry

Once the mom6_bathy tool has been launched by VisualCaseGen, you should see a jupyter notebook that looks something like this

The first two cells here have already been populated automatically by the visualCaseGen tool.  You can see in the "Create horizontal grid" cell that our choices for the grid resoltion have already been populated there e.g., we have 360 grid cells in the longitude direction and 180 grid cells in the latitude direction along with total grid lengths of 360 degrees in the longitude direction and 180 degrees in the latitude direction and a zonally reentrant ocean since cyclic_x = True.

Execute these first two cells to update the MOM6 supergrid.

The third section of mom6_bathy can be used to set up the bathymetry.  The default options are to produce an ocean of depth 2000m with a minimum depth of 10m but we are going to instead generate an ocean that resembles the ridge world case of Wu et al (2020) which has a depth 4000m with some sinusoidal fluctuations at the surface, a land ridge of width 1 degree longitude and the most poleward 10 degrees latitude at the poles set to land.  There are three different ways in which you can achieve this: (1) specifying this analytically with python code within mom6_bathy; (2) reading this ocean set up in from a file; or (3) using the point and click feature of the mom6_bathy tool.  We now outline how to use each of these different methods.

Option 1: Specify the bathymetry using python formulae

Withiin the section of mom6_bathy called "3. Configure bathymetry" you can first instantiate the bathymetry object and then modify the depth of the bathymetry as outlined below.  Makre sure to remove the code that already exists within this section other than what you want, so that it should end up looking something like this

In this code we have set up the 4000 m deep option, with sinusoidal fluctuations and set the depth of the ocean to 0 at all latitudes at 50 degrees east and at all longitudes over the 10 degrees latitude range at the poles.  You will need to execute these cells and if you plot the bathymetry using the last cell, you should see something like this:

where we have a very narrow (1 degree wide) land ridge at 50 degrees and polar land caps with sinusoidal fluctuations along the 4000 m deep ocean floor.

Option 2: Read in your bathymetry from a file

!!! coming soon !!!

Option 3: Use the point-and-click bathymetry selection option in mom6_bathy

!!! coming soon !!!

Step 5: Save the ocean bathymetry files

The final section of mom6_bathy (4. Save the grid and bathymetry files) can be executed to save the MOM6 supergrid file, the MOM6 bathymetry file, the CICE grid file and the ESMF mesh file.  By default, this saves the files into the VisualCaseGen directory, but you can alter this.  For our case, we're going to refer to the grid as "ridge_1x1" i.e., a 1 degree ridge world case and we'll save them in the directory /glade/work/islas/CSSI/ridge_1x1/config_files/ so we modify the cell in this step to the following:

If it has completed successfully, then you should see the line that begins "SUCCESS! " upon executing this cell and you should see four files have been created in the location you specified.  Now you can return to the VisualCaseGen GUI to configure the land surface.

Step 6: Configure the land surface properties

Return back to the VisualCaseGen GUI and click on the CLM tab within the grids section

We need to select the base CLM grid.  Since we chose the standard 1 degree resolution in the atmosphere, we'll select that for the land as well i.e., the option "0.9x1.25" in the drop down menu for "Base CLM grid".  Based on this choice VisualCaseGen will now populate the "Input Surface Dataset" with the appropriate file e.g.,

 The "fsurdat" file controls the land surface properties and their time evolution (where relevant).  You can read more about fsurdat files here.  The remainder of this section of VisualCaseGen can be used to specify the land surface properties over our idealized land regions.  Since we are modifying the whole planet, we can specify the region to modify using the "via corner coords" and modify from 90 degrees South to 90 degrees North over longitudes from 0 degrees to 360 degrees.  We'll also use the "Idealized" option.  

We need to set the land surface properties by specifying the plant functional type (PFT).  The PFT numbers and names may change depending on which model version or configuration you're using, but you can look at the "paramfile" for a default case using your resolution and forcing period to find out the numbers that correspond to different PFTs for your case (See section 2.2 here).  We'll use the PFT of zero which for this case corresponds to bare ground.  Note that Wu et al (2021) actually specified the land surface to  be wetland but this option is not yet available within VisualCaseGen.  

We'll also specify the soil color to be 10, the standard deviation of elevation to be zero and the max fraction of saturated are to be zero.  We will keep "Include non-vegetation land" as True since we want to set the surface to bare ground in this case.  You can leave the specification of leaf area index, stem area index, canopy top and bottom as the defaults because this will have no effect in a case where we are setting all the land to be bare ground without vegetation.  

Finally you have to specify a file location for the modified fsurdat file.  We'll put the file in the directory /glade/work/islas/CSSI/ridge_1x1/config_files/ and call it fsurdat_ridge_1x1.nc.

Overall, we'll use the following settings within VisualCaseGen to set up the land surface properties:

Now you can press the green "Run fsurdat_modifier" button to generate the fsurdat file.  This can take some time. 

Step 7: Set up and configure the case

The final step is to create your case and to configure it to use your new ocean files and fsurdat files.  You have two options for doing this through the final "Launch" section of the GUI.  

If you have run VisualCaseGen from within the CESM tag and on the machine that you would like to use to run the simulation then you can simply specify the case path in the "Select New Case Path" section and VisualCaseGen will run create_newcase and all the commands to configure the case to use your new MOM6 files and fsurdat file.  Otherwise, you can click on the "Show commands" button to see the commands you would need to execute to set up this case using the tag that you would like on the machine you would like.  You'll still need to select the case path if you're using the "Show commands" option.

If you press the show commands button you'll see the following:

Run create case command...

  > /glade/work/islas/cesm2_3_alpha16e_gui/cime/scripts/create_newcase --res custom --compset 1850_CAM40_CLM50%SP_CICE_MOM6_SROF_SGLC_SWAV --case /glade/scratch/islas/b.e34_f09_1x1_ridgeworld.001 --machine casper --run-unsupported --project P04010022

Apply xml changes...

  > ./xmlchange OCN_DOMAIN_MESH=/glade/work/islas/CSSI/ridge_1x1/config_files/ESMF_mesh_ridge_1x1_20231202.nc
  > ./xmlchange ICE_DOMAIN_MESH=/glade/work/islas/CSSI/ridge_1x1/config_files/ESMF_mesh_ridge_1x1_20231202.nc
  > ./xmlchange MASK_MESH=/glade/work/islas/CSSI/ridge_1x1/config_files/ESMF_mesh_ridge_1x1_20231202.nc
  > ./xmlchange OCN_NX=360
  > ./xmlchange OCN_NY=180
  > ./xmlchange ICE_NX=360
  > ./xmlchange ICE_NY=180
  > ./xmlchange ATM_GRID=0.9x1.25
  > ./xmlchange ATM_DOMAIN_MESH=/glade/p/cesmdata/inputdata/share/meshes/fv0.9x1.25_141008_polemod_ESMFmesh.nc

Run ./case.setup ...

Add parameters to user_nl_mom ...

  INPUTDIR = ./INPUT
  TRIPOLAR_N = False
  NIGLOBAL = 360
  NJGLOBAL = 180
  GRID_CONFIG = mosaic
  TOPO_CONFIG = "file"
  MAXIMUM_DEPTH = 4400.0
  MINIMUM_DEPTH = 10.0
  REENTRANT_X = True
  REENTRANT_Y = False
  DT = 1800.0
  NK = 20
  COORD_CONFIG = "none"
  REGRIDDING_COORDINATE_MODE = "Z*"
  ALE_COORDINATE_CONFIG = "UNIFORM"
  TS_CONFIG = "fit"
  T_REF = 5.0
  FIT_SALINITY = True
  GRID_FILE = ocean_grid_ridge_1x1_20231202.nc
  TOPO_FILE = ocean_topog_ridge_1x1_20231202.nc

Add parameters to user_nl_cice ...

  grid_format = "nc"
  grid_file = "/glade/work/islas/CSSI/ridge_1x1/config_files/cice_grid.ridge_1x1_20231202.nc"
  kmt_file = "/glade/work/islas/CSSI/ridge_1x1/config_files/cice_grid.ridge_1x1_20231202.nc"

Copy input files...

  > cp /glade/work/islas/CSSI/ridge_1x1/config_files/ocean_grid_ridge_1x1_20231202.nc ${RUNDIR}/INPUTDIR
  > cp /glade/work/islas/CSSI/ridge_1x1/config_files/ocean_topog_ridge_1x1_20231202.nc ${RUNDIR}/INPUTDIR

Done.
[ ]:

This explains how to perform the following steps:

• Set up the case using the create_newcase command
• Change directories into your case directory to configure the case !!! this isn't there !!!
• Run the xml commands to tell the case about your new mesh files for the various components and the configuration of the ocean grid
• Set up the case.
• Once you have set up the case, the namelist files for each component will be produced in your case directory.
• You then need to add the namelist parameters into user_nl_mom and user_nl_cice as described above.