Building your ocean grid

Tools:  found in setup_tools.tar

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.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.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. We include kmtEd and NCL scripts in the setup_tools, but 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. Makefiles for AIX systems are included in the setup_tools.tar file.  The scripts are designed to follow a directory structure similar to what is found in preStage.csh (See Appendix). The modeler will need to edit the scripts to point to her/his code, data, and executables.

STEP 1: Creating the ocean grid
Tool:  mk_grid.csh/ns_dipole.f

The script mk_grid.csh sets many variables in the top portion of the script. These variables control settings in ns_dipole.f90, paleotop.f90, and grid_nc2bin.f90 with detailed explanations in STEPS 1-3.

Edit mk_grid.csh for the following variables which control ns_dipole.f90 information:

nx number of i grid lines  
nlatn number of j gridlines in NH  
nlats number of j grid lines in SH  
lonnp longitude of grid North Pole  
latnp Latitude of grid North Pole  
lonsp Longitude of grid South pole  
latsp Latitude of grid South Pole  
dyeq dy in degrees at Equator1 grid box length at equator
dsig Gaussian e-folding scale at Equator1  
jcon number of rows of constant dy a poles  
pltgrid name of binary plotting grid file2 output
popgrid name of binary pop grid file3 output



STEP 2: Creating the KMT file
Tool:  create0.5degree.ncl)/mk_grid.csh/paleotopo.f90

 The Fortran program paleotopo.f90 requires the bathymetry data be in 0.5x0.5 degree format. In the setup_tools.tar file, we provide an NCL script to interpolate to .5 degrees if necessary.  Otherwise, the modeler will need to modify the Fortran code.

Run create0.5degree.ncl



Edit mk_grid.csh for the following information which control paleotopo.f90 information:

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

Once the KMT binary file has been created, it can be converted to netCDF for visualization and modification.

  • Choice a: mk_grid.csh/grid_bin2nc.f90

The mk_grid.csh script calls the Fortran program grid_bin2nc.f90 to create a netCDF file acceptable for the GUI-interface tool kmtEd. 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.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, feel free to 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).

You will not be able to use kmtEd if you choose this option.

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:  kmtEd/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. 

  • Choice a: kmtEd for low resolution grids

At NCAR, we typically use kmtEd for the gx3v5 grid size.  kmtEd code and sample build/makefile information can be found in the setup_tools.tar file. kmtEd generates a 3D-sphere graphical interface for viewing/editing grid KMT values. This tool is based on eCubed and was developed at Los Alamos National Laboratory (LANL) by John Davis. The latest version of this tool is called G-cubed (GGG) and handles tripole grids. (CCSM3 uses a dipole grid for the POP model). For further documentation see the LANL website:

Installing kmtEd requires prior installation of VTK freeware (http:/

Although there is a fair amount of leg work to install kmtEd, it is an extremely powerful tool to edit the KMT data. The GUI interface is easy to manipulate and the modeler can edit the data with ease.  (If you are using kmtEd on the NCAR machines, contact the deep time paleo liaison for location).  Once kmtEd is installed, to run, simply type

kmtEd –i –o

Enter  kmt when queried for your input variable (elevation is default), and simply hit return for the dimension defaults. Consult Section 8.7 for the quick guide on how to operate the GUI.  (or see kmtEd/include/controls.h comments) in the code.

Your is the netCDF file generated by grid_bin2nc.f90. If you do not run grid_bin2nc.f90 and instead opt to use the NCL tool to create the netCDF KMT file, you will not be able to use kmtEd.

  • Choice b: NCL for high resolution grids

This option is recommended for high resolution grids (such as gx1v3) because kmtEd could be too slow on front-end processing computers. 

In the setup_tools.tar file, we provide a sample NCL script to hand edit your KMT file. This technique requires coding the desired 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_template), it creates the diagnostic input_template for locales 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.

You will need to edit mk_ocninput to specify your code and data locale, to specify 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 locations are required. The modeler can also specify whether the section is meridional or zonal and assigns a section name. For examples of the present day transport_contents file, go to the POP source code under input_templates.

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: