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. 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 is square with side length 2 km, and the floor is sloped downwards in the direction of the outflow from 0 to 10 m. 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 at a point depends on:

1) whether the entire boundary is opened in data.obcs;

2) whether the depth is set to zero (for a closed boundary) or below zero (for an open boundary) in the bathymetry .bin file at that 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.

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-dimensionality 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!

[WIP]

In this case, you'll make changes to the input and data files yourself using the previous case as a starting point. A sample solution has been provided. Try out these changes, in several configurations as time permits:

• Move the inflow from the south boundary to the north boundary. Remember you will need to change the sign on inflow velocity when you do this.
• Add some initial tracer near the outflow to see what happens in this area before the inflow really takes effect. Make this a different tracer from the first, the one in the inflow. You will need to change the maximum number of allowed tracers in PTRACERS_SIZE.h and recompile.
• Decrease the air temperature by 10 degrees and both longwave and shortwave radiation by about 100 W/m^2
• Make the inflow sporadic, so there is inflow for half the period and none for the other half. The way to do this is analogous to time-variable meteorological forcing. That is, one must specify a period for each boundary in data.exf. Then, a time index must be added to the inflow arrays. This determines the inflow rate over the indexed period.
• Change the outflow temperature to be stratified, the same as the initial temperature of the lake.

As before, feel free to experiment with running the model longer, changing input values, and modifying data files.

Appendix: Adding Tracers to an Existing Case

To add tracer to an existing model, first follow the steps to enable the package PTRACERS as described under case 3. The only .h file you'll need for most implementations is PTRACERS_SIZE.h, so that you can change the maximum number of tracers, PTRACERS_num. Note that while in theory arbitrarily many tracers can be added, using the DIAGNOSTICS package to track them sets a limit of 99.

For your data.ptracers file, the one provided in the tutorial cases is a good starting point. Note that the important parameters to set are as follows:

• PTRACERS_Iter0: tick number at which the tracer experiment is initialized. Set globally for all tracers.
• PTRACERS_numInUse: number of tracers used. Can be less than (but must not exceed) PTRACERS_num set at compile time.
• PTRACERS_diffKh(n), PTRACERS_diffKr(n) , PTRACERS_diffK4(n): diffusivity constants. Should be set to small but nonzero numbers if diffusion isn't desired (10^-9 seems to be a good choice). Set individually for each tracer.
• PTRACERS_names(n): tracer name. Needs to be set for data collection even if you don't intend to do anything with it.
• PTRACERS_initialFile(n): .bin file from which the initial tracer concentration will be read. The expected format is exactly analogous to temperature, an Nx*Ny*Nz array written in the usual way.
• PTRACERS_advScheme(n): tracer advection scheme. Should be set to match the advection scheme used in data as mentioned earlier.

Finally, you'll want to be able to actually trace your tracers. In data.diagnostics, you can track diagnostics with field names TRAC01, TRAC02 etc. PTRACERS offers many other diagnostics, including flux of different materials-- check the documentation here for more information.