Building your ocean grid

Creating your Ocean grid for Deep Time

Note:  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
Tool:  mk_grid_cesm.csh/ns_dipole.f/paleotopo.f90

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
nx number of i grid lines grid resolution in E/W direction 320 100
ny number of j grid lines grid resolution in N/S direction 384 116
nlatn number of j gridlines in NH Grid distribution should reflect science priorities (PD grid has higher resolution in NH).    nlatn+nlats=ny.  Tip: Avoid even distribution 209 63
nlats number of j grid lines in SH    175 53
lonnp longitude of grid North Pole    --  --
latnp Latitude of grid North Pole Tip: 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)  --  --
lonsp Longitude of grid South pole  Time period dependent  --  --
latsp Latitude of grid South Pole  Time period dependent  --  --
dyeq dy in degrees at Equator  Tip:  CESM default ULAT at Equator. 0.26o  0.6o
dsig Gaussian e-folding scale at Equator

increasing this number widens the high resoln equatorial band



jcon number of rows of constant dy at poles increasing this number can move the pole landward if it is extending beyond the edge of the polar continent.  Recommended range:  10-20. 11 11
popgrid binary pop grid file Default POP2 expects BIG_ENDIAN binary format netCDF 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:  NCL

Refer to the Overview section regarding the Create the bathymetry (KMT) grid for guidance on how to improve your KMT data. There are a variety of tools the modeler can use to achieve this goal. 

  • 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.
  • Other Choices:

Ultimately, it is up to the modeler to decide how best to make the necessary modifications. If the modeler has a favorite tool or language, perhaps that will be the best method. Some paleo modelers have used Matlab with a GUI-interface to change the KMT values.


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 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: