User's Guide
[please note that topo software works for regional grids]
- The instructions below assume you have cloned this repository and are in the repository directory. For example:
% git clone https://github.com/NCAR/Topo
% cd Topo
- Code to generate topography data is in:
% cd cube_to_target
- Compile code (on NCAR's Derecho or Casper cluster). Any specific compiler options can be changed in machine_settings.make)
% module load gcc # load the module for access to gfortran (module load intel also an option)
% module li # verify that you have loaded the necessary modules
% gmake -f Makefile clean # verify the new files do what you expect
% gmake -f Makefile
- To test that code works properly you may run one of the fast regression tests:
% source regr_test1.sh
- If the regression test passed you should see
SUMMARY of cprnc:
A total number of 22 fields were compared
of which 0 had non-zero differences
and 0 had differences in fill patterns
and 0 had different dimension sizes
A total number of 0 fields could not be analyzed
A total number of 3 fields on file 1 were not found on file 2.
A total number of 0 fields on file 2 were not found on file 1.
diff_test: the two files DIFFER only in their field lists
- For a quick look at the variables on the topo file:
% module load ncl
% source plot.sh
which produces the file raster.pdf
The topo software operates in terms of command line namelist variables, e.g.,
./cube_to_target --grid_descriptor_file ../regression-test-data/ne30pg3.nc --intermediate_cs_name /glade/campaign/cgd/amp/pel/topo/cubedata/gmted2010_modis_bedmachine-ncube3000-220518.nc --output_grid ne30pg3 --smoothing_scale 100.0 --name_email_of_creator 'Peter Hjort Lauritzen, pel@ucar.edu'
The software is configured so that it by default will produce topography files suitable for CAM (in terms of amount of smoothing, variables, etc.).
The final topo file will (by default) be written to the output/ directory. The default setup uses a Laplacian smoother to smooth topography (geopotential, PHIS) on the intermediate cubed-sphere grid (typically ~3km grid that is used to separate scales for SGH and SGH30). The reason why the smoothing is applied on the high-resolution intermediate grid (and not on target grid) is that the sub-grid-scale ridge scheme requires the smoothed PHIS on this grid. The smoother is not active over ocean to prevent the topography from "leaking" into ocean. The "lost" topographic volume is added back to PHIS by scaling PHIS uniformly by the amount lost: (total volume of intermediate cubed-sphere topography / total volume of smoothed topography)*PHIS. See https://github.com/NCAR/Topo/issues/39#issuecomment-1152704058 for more details. By default the computation of sub-grid-scale ridge variables is turned on.
| Namelist | Type | Description |
|---|---|---|
| grid_descriptor_file | <str> | specify either SCRIP or ESMF format grid-descriptor file |
| intermediate_cs_name | <str> | specify intermediate cubed-sphere file (default on Cheyenne shown above) |
| output_grid | <str> | grid identifier (recommend to follow standard CIME naming convention) |
| smoothing_scale | <real> | specify amount of smoothing; standard smoothing level used in CAM is 100.0km for 1 degree applications, 50.0km for 1/2 degree, and so on. For rougher topography at a specific resolution reduce smoothing scale |
| name_email_of_creator | <str> | your name and Email address (for meta data on final netCDF file) |
| Namelist | Type | Description |
|---|---|---|
| rrfac_max | <int> | maximum refinement level, e.g., for grids refining from 1 degree to 1/4 degree rrfac_max=4 [required for var res]. Variable is used to choose stable iteration number for Laplacian smoother and (if rrfac_manipulation=True) used to bound the refinement factor |
| rrfac_manipulation | enable manipulation of rrfac (used for spectral-element grids), that is, bound rrfac between 1 and rrfac_max as well as applying smoothing to rrfac (used for spectral-element refined grids where grids transition regions are not smooth) |
[These namelist variables are usually only used by developers or for special applications!]
Please note that the Laplacian smoother is used by default.
| Namelist | Type | Description |
|---|---|---|
| smoothing_over_ocean | do not restrict smoother to only smooth over land (i.e. equal smoothing everywhere) | |
| smooth_phis_numcycle | <int> | number of sub-cycles for Laplacian smoother (for stability) |
[These namelist variables are usually only used by developers or for special applications!]
| Namelist | Type | Description |
|---|---|---|
| distance_weighted_smoother | enable distance weighted smoother (default is Laplacian smoother) | |
| use_prefilter | ||
| fine_radius | <int> |
[These namelist variables are usually only used by developers or for special applications!]
| Namelist | Type | Description |
|---|---|---|
| no_ridges | do not compute sub-grid scale variables related to orientation of ridges | |
| ridge2tiles | ??? | |
| output_data_directory | <str> | directory where final topography file is placed (WARNING: software does not check if directory exists!). Default is output/ |
| stop_after_smooth | stop after smoothing | |
| development_diags | enable development diagnostics (for developers) | |
| smooth_topo_file. | <str> | use pre-computed smooth topo file |
| write_rrfac_to_topo_file | write refinement factor (rrfac) to final topo file (usually for debugging) | |
| source_data_identifier | <str> | source topo data identifier (default gmted2010_modis_bedmachine) |
| grid_descriptor_file_gll | <str> | grid descriptor file for dual grid configurations (separate physics grid configurations) |
| interpolate_phis | bilinear interpolate PHIS to target grid (instead of remapping) | |
| jmax_segments | <int> | specify number of overlap segments (estimated by software by default) |
Please note that the meta data for a topography file generated with this tool will have the command used to generate the topography file.
For example, on NCAR's supercomputer Derecho or Casper executing
ncdump -h /glade/campaign/cesm/cesmdata/inputdata/atm/cam/topo/se/ne30pg3_gmted2010_modis_bedmachine_nc3000_Laplace0100_noleak_20240117.nc | less
should result in
If one lookes for :data_script = "./cube_to_target --grid_descriptor_file ../regression-test-data/ne30pg3.nc --intermediate_cs_name /glade/campaign/cgd/amp/pel/topo/cubedata/gmted2010_modis_bedmachine-ncube3000-220518.nc --grid_descriptor_file_gll ../regression-test-data/ne30np4.nc --output_grid ne30pg3 --smoothing_scale 100.00000000000000 --name_email_of_creator Peter" one can see the command.
The grid descriptor file for supported CESM applications can also be found in the CESM input data directory:
/glade/campaign/cesm/cesmdata/inputdata/share/meshes/
The topography softare supports SCRIP and ESMF formats.
The intermediate cubed-sphere grid data (intermediate_cs_name) does not need to be changed unless the user would like to use a different surface topography dataset. This dataset uses GMTED2010 dataset merged with Bedmachine data for the polar regions.
The --grid_descriptor_file_gll file is only for spectral-element applications that use a separate physics grid.
--output_grid is just the grid identifier and can be freely chosen by the user.
--smoothing_scale is the smoothing scale which, for standard climate applications, usually matches the resolution of the grid in kilometers.
For more details see desciption above.
For low resolution topography files (used for testing not science) we recommend using a low resolution intermediate cubed-sphere grid (otherwise the smoothing takes a very long time). The low resolution data is in this repository:
Topo/regression-test-data/gmted2010_bedmachine-ncube0540-220518.nc
Command, on Derecho/Casper, to generate a standard 1 degree (~120km) MPAS topography file is
./cube_to_target --grid_descriptor_file /glade/campaign/cesm/cesmdata/inputdata/share/meshes/mpasa120z32_ESMFmesh_cdf5_c20210120.nc --intermediate_cs_name /glade/campaign/cgd/amp/pel/topo/cubedata/gmted2010_modis_bedmachine-ncube3000-220518.nc --output_grid mpasa120 --smoothing_scale 100.0 --name_email_of_creator Peter Hjort Lauritzen, pel@ucar.edu --output_data_directory output/"
For larger jobs please submit job with
qcmd -l walltime=4:00:00 -l select=1:ncpus=1 -A your_project_number -- ./cube_to_target --grid_descriptor_file /glade/campaign/cesm/cesmdata/inputdata/share/meshes/mpasa120z32_ESMFmesh_cdf5_c20210120.nc --intermediate_cs_name /glade/campaign/cgd/amp/pel/topo/cubedata/gmted2010_modis_bedmachine-ncube3000-220518.nc --output_grid mpasa120 --smoothing_scale 100.0 --name_email_of_creator Peter Hjort Lauritzen, pel@ucar.edu --output_data_directory output/
If one would like to produce a 1/2 degree topography file, change smoothing radius to ~50km (--smoothing_scale 50.0) and point to the 1/2 degree grid descriptor file (/glade/campaign/cesm/cesmdata/inputdata/share/meshes/mpasa60_ESMFmesh-20210803.nc):
./cube_to_target --grid_descriptor_file /glade/campaign/cesm/cesmdata/inputdata/share/meshes/mpasa60_ESMFmesh-20210803.nc --intermediate_cs_name /glade/campaign/cgd/amp/pel/topo/cubedata/gmted2010_modis_bedmachine-ncube3000-220518.nc --output_grid mpasa60 --smoothing_scale 50.0 --name_email_of_creator Peter Hjort Lauritzen, pel@ucar.edu --output_data_directory output/"
Coarse resolution is ~100km and fine resolution is ~12.5km. In this case we set smoothing scale to what is appropriate for the coarse region (recommended value 100km) and then we have to set the max refinement factor which in this case is 8 (in terms of namelist that is "--rrfac_max 8"). For NCAR Cheyenne compute system the command for generating the CONUS topography file would be:
qcmd -l walltime=4:00:00 -l select=1:ncpus=1 -A your_project_number -- ./cube_to_target --rrfac_manipulation --grid_descriptor_file='/glade/p/acom/MUSICA/musica_repo/ne0np4.CONUS.ne30x4/grids/CONUS_ne30x4_np4_SCRIP.nc' --intermediate_cs_name='/glade/p/cgd/amp/pel/topo/cubedata/gmted2010_modis_bedmachine-ncube3000-220518.nc' --output_grid='ne0CONUSne30x4' --name_email_of_creator="Peter Hjort Lauritzen, pel@ucar.edu" --rrfac_max=4 --smoothing_scale=100.0
If one wanted a 1/2 degree topography file change