topogtools

Tools related to changing ocean model topography and regenerating dependent model inputs.

Below is a partial list of included tools and short documentation for each.

Russ' Fortran tools

Compile these by running build.sh. Usage examples can be found in https://github.com/COSIMA/make_1deg_topo and https://github.com/COSIMA/make_025deg_topo.

float_vgrid

Alter values in ocean_vgrid.nc so they can be used with both single- and double-precision topog.nc. Takes no arguments but requires ocean_vgrid.nc to be present.

gen_topo

Generate a new topography file topog_new.nc from GEBCO bathymetry. Takes no arguments but requires mosaic.nc, ocean_mosaic.nc, ocean_hgrid.nc and gebco_2014_rot.nc to be present.

deseas

Remove enclosed seas from topog.nc file. Usage:

./deseas topog_in.nc topog_out.nc

do_partial_cells

Adjust depths in topog.nc to specified partial cell parameters. Usage:

./do_partial_cells topog.nc min_thick min_frac

where min_thick is the minimum partial cell thickness in metres (e.g. 1.0) and min_frac is the minimum fractional cell thickness (e.g. 0.2). Requires ocean_vgrid.nc to be present. Overwrites input topog.nc.

min_depth

Set minimum depth to the depth at a specified level. Usage:

./min_depth topog_in.nc topog_out.nc level

where level is the minimum number of depth levels (e.g. 4). Requires ocean_vgrid.nc to be present. Can produce non-advective cells.

min_max_depth

Set minimum depth to the depth at a specified level (same as min_depth above), and also set maximum depth to the deepest in ocean_vgrid.nc. Usage:

./min_max_depth topog_in.nc topog_out.nc level

where level is the minimum number of depth levels (e.g. 4). Requires ocean_vgrid.nc to be present. Can produce non-advective cells.

check_nonadvective_mosaic

Check for cells that are nonadvective on a B grid. Doesn't detect choked channels in all cases - use non-advective.ipynb (below) to find non-advective edges. Usage:

./check_nonadvective_mosaic topog.nc

Requires ocean_vgrid.nc to be present, with all double precision numbers exactly representable as singles (use float_vgrid to guarantee this).

fix_nonadvective_mosaic

Fix cells that are non-advective on a B grid. Doesn't detect or fix choked channels in all cases - use non-advective.ipynb (below) to find non-advective edges. Usage:

./fix_nonadvective_mosaic topog_in.nc topog_out.nc

Requires ocean_vgrid.nc to be present, with all double precision numbers exactly representable as singles (use float_vgrid to guarantee this).

Python tools

editTopo

editTopo.py provides a GUI for hand-editing topog.nc files, recording every change, and applying these changes to other files. This is an updated version of Alistair Adcroft's editTopo.py from here and is under a LGPLv3 license. For usage details, do ./editTopo.py -h.

apply_mask

Apply mask from ocean_mask.nc to a topography file. Usage (also see apply_mask.py -h):

./apply_mask.py topog_in.nc ocean_mask.nc topog_out.nc

All ocean cells in topog_in.nc are converted to land cells in topog_out.nc if they are land cells in ocean_mask.nc. All land cells in topog_in.nc are converted to ocean cells in topog_out.nc if they are ocean cells in ocean_mask.nc, with a depth equal to the smallest positive nonzero depth in topog_in.nc.

bathymetry.ipynb

A Jupyter notebook with some checks on partial cells and minimum depth, and comparison between grids at particular locations. Originally from here.

non-advective.ipynb

A Jupyter notebook with some checks on non-advective edges (i.e. choked channels) and cells. This can catch some issues that check_nonadvective_mosaic and fix_nonadvective_mosaic don't detect/fix. Originally from here.

bulldozer

bulldozer.py is a simple tool to modify the MOM bathymetry/topography file, adding or removing land points.

It is used as follows:

echo -e "112, 246, 0.0, 50.0" | ./bulldozer.py topog.nc --new_topog new_topog.nc

The input is taken from stdin. The format of the input is a list of comma-separated line with the following values:

'i index', 'j index', 'original depth', 'new depth'

For example to run on a single point:

echo -e "112, 246, 0.0, 50.0" | ./bulldozer.py test/topog.nc

To run a whole file:

cat file.csv | ./bulldozer.py test/topog.nc

Where the contents of file could look something like this:

112, 246, 0.0, 50.0 113, 246, 0.0, 50.0

unmask

unmask.py removes the masked regions of a variable. For example it can fill in land with value from the nearest ocean point.

This is useful when bulldozer.py is used to modify the land-sea mask, potentially creating undefined values in masked initial conditions. e.g. an OASIS restart has 0's on land by default so when we change the mask some of these may become ocean points and cause the model to crash. In this case unmask.py would be used to remove all land points.

Example use:

./unmask.py test/test_data/i2o.nc test/test_data/kmt.nc kmt --output_file test/test_data/new_i2o.nc --flip_mask

topog2mask

topog2mask.py takes a topog file and outputs a mask.

Example use:

./topog2mask.py test/test_data/topog.nc test/test_data/new_kmt.nc