This is the Transport Matrix Method (TMM) code repository. It includes both 
the core TMM time-stepping driver code (under driver/), as well as various 
biogeochemical models (under models/) adapted to the TMM framework. The driver 
code and interface to models are written using the PETSc framework 
(http://www.mcs.anl.gov/petsc/) but you don't need this code to use the TMM. 
Simply skip to step (3) below. Otherwise keep reading and if you have any 
questions feel free to email: Samar Khatiwala <samar.khatiwala@earth.ox.ac.uk>

How to cite: If you use the TMM, please cite Khatiwala et al. (2005; https://doi.org/10.1016/j.ocemod.2004.04.002) 
and Khatiwala (2007; https://doi.org/10.1029/2007GB002923). If you use any of my transport matrices or related 
data please cite this GitHub page as the source, as well as Khatiwala (2007) and the relevant papers listed here: 
http://kelvin.earth.ox.ac.uk/spk/Research/TMM/TransportMatrixConfigs/. Furthermore, if you use this code please 
also cite Khatiwala (2018; https://doi.org/10.5281/zenodo.1246300). Thank you!

IMPORTANT: Please do NOT post the TMM code or any data files downloaded from this or related 
websites on your own github or other website. You do NOT have permission to do so.

------------------------------------------------------------------------------------------------

For a quick overview of the TMM and the PETSc driver also have a look at this excellent 
presentation by Iris Kriest: https://ftp.geomar.de/users/ikriest/TMM/MOPS-TMM-2016-June.pdf

Quick-start instructions:

1) Install PETSc (http://www.mcs.anl.gov/petsc/) and set the PETSC_DIR and PETSC_ARCH 
environment variables. The TMM driver code is compatible with PETSc version 3.16.x 
(as of Jan 20, 2022). For the older version of the TMM code compatible with PETSc 3.6.x, 
you can checkout branch petsc3.6.

2) Download Matlab scripts and add to your Matlab path:
http://kelvin.earth.ox.ac.uk/spk/Research/TMM/tmm_matlab_code.tar.gz

3) Download transport matrices and related data for the ocean model of your 
choice: http://kelvin.earth.ox.ac.uk/spk/Research/TMM/TransportMatrixConfigs/
Currently, there are 3 configurations of MITgcm available online (and several 
others based on the UVic Earth System Model that I am happy to make available). 
For each, download the TMs and other associated data (e.g., MITgcm_ECCO.tar). 
Unpack. Make a note of the path to this directory (e.g., /mydisk/somewhere/MITgcm_ECCO). 
We will need it later. For some experiments you may also find it useful to download 
some miscellaneous data here (and adjust paths accordingly in the provided Matlab scripts): 
http://kelvin.earth.ox.ac.uk/spk/Research/TMM/MiscData/

4) Make a local directory and checkout the TMM driver and model codes:
cd $HOME
mkdir TMM
cd TMM/
git clone https://github.com/samarkhatiwala/tmm.git

Set the environment variable TMMROOT to point to the top level of the TMM directory.

5) For each model, e.g., $TMMROOT/models/current/mops2.0/ there is model-specific code (in src/); 
Matlab script(s) in matlab/ to generate input data (e.g., make_input_files_for_mops_model.m) and 
read model output (e.g., load_output.m); and run scripts and other runtime data such as 
namelists in runscripts/. 

To try out one of these models, make a directory, e.g., Test/, and copy the following to it:

cp -p $TMMROOT/models/current/mops2.0/src/Makefile .

(If there is a file *_TMM_OPTIONS.h in src/ copy that as well, e.g.,
cp -p $TMMROOT/models/current/mobi2.0/src/MOBI_TMM_OPTIONS.h .
Edit this file to set compile-time C/Fortran preprocessor options.)

Compile the code:
(For some models you may have to first set additional environment variables as described 
in the corresponding Makefile.)

make mops

Copy the matlab and run scripts:

cp -p -R $TMMROOT/models/current/mops2.0/matlab/* .
cp -p $TMMROOT/models/current/mops2.0/runscripts/* .

Change the variable base_path at the very top of the make_input*.m and load_output*.m scripts 
to point to the top level of any of the transport matrix configurations you downloaded in #3 
above. Execute the make_input* script (e.g., make_input_files_for_mops_model.m). It should 
generate all necessary input data. With luck! (If there is missing data email me for it.)

Execute model using the example run scripts.

Load output using the example load_output.m script.