OBCS tutorial

Introduction

The purpose of this tutorial is to introduce you to the OBCS (Open Boundaries) and PTRACERS (Passive Tracers) modules. It assumes that you're comfortable building and running the model, and using your chosen method of data visualization (gcmpy, ParaView, VisIt, etc.) It's recommended to run the other two tutorials first.

General Considerations

Remember that when using OBCS, opening or closing a boundary is a compile-time option which must be declared in OBCS_OPTIONS.h. In addition, every boundary needs a .bin file for each tracer diagnostic you're using (e.g. temperature, passive tracer). Failure to provide such a file will likely cause the model to break (an exception seems to be passive tracer in an outflow). Finally, with PTRACERS, the advection scheme for each tracer needs to be set manually in data.ptracers to match the one you're using, usually 33 or 77. Using differing advection schemes causes strange behavior and sometimes NaNs.

Case 1: Warm inflow

This tutorial uses a very simple setup, with an inflow in the north boundary and an outflow in the east boundary. The lake floor is sloped downwards in the direction of the outflow. Initial temperature is stratified between 10 and 20 °C, and the inflow temperature is 25 °C. The inflow is also configured to have some passive tracer coming in. Finally, wind is added in the direction of the outflow (the same script as in the SEAICE tutorial is used with only minor changes).

Take a look at the python scripts inflow_outflow.py and initial_tracers.py You'll need to run these (as well as the other python scripts in this folder) to generate the .bin files for the model to read. Note how the inflow and outflow temperatures are set for the entirety of the boundary. Whether the boundary is actually open depends on:

1) whether the boundary is opened in data.obcs; 2)whether the depth is set to zero (for a closed boundary) or subzero (for an open boundary) in the bathymetry .bin file at a particular point.

Now look at the bathymetry-generating script, rectangular_sloped_lake.py. Notice how the boundaries are opened in the location of inflows and outflows by setting the depth equal to the number of vertical points.

Finally, take a look at data.ptracers. Notice that some parameters are set globally, while others are tracer-specific (though only one tracer is used here). Keep in mind that if you want to use multiple tracers you cannot use more than the maximum specified in PTRACERS_SIZE.h, a compile-time option. Also note that naming your tracers seems important for data collection, even if you don't intend to do anything with the name.

Build and run the model-- remember you will need all the data.* files as well as eedata, the .bin files created by the python scripts, and the executable mitgcmuv. Note the model is configured to use 25 processors by default. Once it's finished, generate .nc files using

    python -m gcmpy.netCDFbinary T Rho U V SM

(SM is the passive tracer diagnostic).

For this tutorial in particular, it's recommended to use 3D modeling software such as ParaView as there's quite a bit of three-dimensional to the behaviour that isn't apparent using slicing.

Case 2: Cold inflow

For this case, the only things that have been changed are the initial stratification, which is now between 0 and 10 °C, and the inflow/outflow temperatures, which have been set to 0 °C. Simply repeat the steps of the first case; this is included mostly because it is of interest to compare an inflow of colder water to one of warmer water relative to the initial stratification. Also, try creating an isosurface of water around 4 °C— you will see interesting behaviour resulting from the fact that water is densest at this temperature!

Case 3: Adding SEAICE

For this case, we will add the SEAICE to see how ice would form on our model. Though it's been done for you here already, it's worth taking note of the sequence of steps needed to add a package to the model:

1) In the code directory, add the package name in all lower case (in this case, 'seaice') to packages.conf. This ensures that the package will be activated at compile-time, and is a preferable alternative to calling each package explicitly on the command line.

2)Copy any needed .h files from MITgcm/pkg/[package name] into your code directory. In this case, we bring over SEAICE_OPTIONS.h and SEAICE_SIZE.h. The MITgcm documentation is often helpful in determining which such files are essential and which are extraneous.

3)It's now safe to build the model. You'll also need to activate the package in data.pkg and add a data.[package name] file, as well as scripts to initialize any fields your package introduces— in this case, initial_ice.py. Also, make sure to add any new diagnostics you want to follow (in this case SIheff and SIarea to) to data.diagnostics!

Take a look at initial_ice.py. It's configured to add some circular ice floes at an arbitrary list of given points— try changing these or adding more! Other than that, the only changes are to again make the stratification colder, to decrease the air temperature, and to decrease the inflow/outflow temperatures. Because of the inclusion of ice, it may be worthwhile to try running this simulation longer with a lower diagnostic frequency.

Case 4: Try it yourself!

[TBA]