Transport Matrix Method

These are some instructions and suggestions for using the Transport Matrix Method. For details of the TMM see:

[1] Khatiwala, S., M. Visbeck, and M. A. Cane (2005). Accelerated simulation of passive tracers in
ocean circulation models. Ocean Modelling, 9, 51-69. (PDF)

[2] Khatiwala, S. (2007). A Computational Framework for Simulation of Biogeochemical Tracers
in the Ocean. Glob. Biogeochem. Cycles, 21,GB3001, doi:10.1029/2007GB002923. (PDF)

For more details on how to use the TMM (beyond the sketchy information provided below), or access to transport matrices extracted from other model configurations (including ECCO-GODAE), feel free to email me (

Samar Khatiwala

Last updated: 6/4/09

NOTE: The code here hasn't been updated in a while. To get the latest, and significantly improved, version please email me.

To start, download the following:

This contains the annual and monthly mean TM's for a coarse resolution configuration of the MITgcm, and some example code. This is my 'workhorse' configuration. If you want TM's from a higher resolution model, just email me. All the example codes included are for relatively simple problems with linear source/sink/boundary conditions, where the goal is to find a steady state solution. To use the TMM for more complex, nonlinear problems, including time-dependent ones, email me for details.

Next, download the following Matlab scripts (unarchive and place them in your Matlab path):

Now untar and uncompress MIT_Matrix_Global_2.8deg.tar.gz. You should get the following:


I highly recommend maintaining this directory structure. It will facilitate exchange of scripts and new TM's.

- The directory Matrix5/ contains explicit and implicit TM's and other related files. Key files are:
    Matrix5/Scripts/matrix_nocorrection_annualmean.mat contains the annual mean TM's
    Matrix5/Scripts/matrix_nocorrection.mat contains the monthly mean TM's
    Matrix5/Data/boxes.mat contains various geometry-related arrays (e.g., the volume of
    grid box, etc.)
- The directory Matrix10/ contains an annual mean "fully explicit" TM meant primarily for use as a
   preconditioner for solving for equilibrium solutions. (By "fully explicit" I mean that the TM
   represents a transport tendency matrix that includes vertical mixing.) Key files are:
   Matrix10/Scripts/matrix_nocorrection.mat contains the annual mean TM (the variable 'Aexpms')
   Matrix10/Data/boxes.mat contains various geometry-related arrays (e.g., the volume of
   grid box, etc.)
- The directory MIT/ contains data files used to spin-up the GCM and compute the TM's. Key files are:
   GCM Forcing data (all 32 bit, direct access binary files)
    MIT/input/lev_monthly_temp.bin  monthly mean SST for restoring
    MIT/input/lev_monthly_salt.bin  monthly mean SSS for restoring
    MIT/input/shi_qnet.bin  monthly mean heat flux

   GCM output (all 32 bit, direct access binary files)
    MIT/SeasonalDST3/Ttave*  monthly mean temperature
    MIT/SeasonalDST3/Stave*  monthly mean salinity
- BiogeochemData/ contains useful biogeochemical data on the model grid (provided by Stephanie Dutkiewicz  
  at MIT).

Additional notes:

1) MIT_Matrix_Global_2.8deg is the 'toplevel' directory. It represents a specific configuration of the MIT GCM.

2) Create any new experiment within this toplevel directory as a new directory. As examples, I provide the following:

I tag each experiment (e.g., PaTh_Matrix5_1) with the TM (e.g., Matrix5 here) and experiment version (e.g., "1").

3) The file "basepath.mat" contains a single string variable "base_path" that is the absolute path (on your machine) of the toplevel directory. (You will of course have to change it.) All my scripts load this file and use the variable "base_path" to reference all other directories/files. So by simply changing basepath.mat your scripts should work on any machine without change. (Within the experiment directory, I make a softlink to basepath.mat: ln -s ../basepath.mat .  )

As an example of how to exploit this (and more generally how to setup an experiment), see the file: PaTh_Matrix5_1/calc_steady_state_PaTh.m. If you follow this procedure, it will greatly facilitate the exchange of scripts and data between us (and others who use the TMM).

4) The code in KielBiogeochem_NDOP_Matrix5_4/ is meant to illustrate the matrix-free Newton-Krylov method for fast spinup of ocean biogeochemical models. See KielBiogeochem_NDOP_Matrix5_4/Readme for detailed instructions. (See also KielBiogeochem_NDOP_Matrix5_4/Readme_cg.)

5) KielBiogeochem_NDOP_Matrix5_4/ also contains my PETSc code for simulating biogeochemical tracers using the TMM. The code is comprised of a set of generic driver routines (implemented in C) and the actual biogeochemical model (implemented in FORTRAN). You can use this code as a template for using your own biogeochemical model with the TMM. For details on the implementation, see Appendix B in ref. [2].