This README.txt file was generated on 10 JAN 2024 by Sam Kelly

------------------------
GENERAL INFORMATION
------------------------

These are the configuration files for the MIT general circulation model (MITgcm, v 1.1936 2013/11/05, http://mitgcm.org/). The model is extensively documented online. 

There are three sub-folders within the MITgcm folder that contain all the setup information needed for the run:
(1) build: all compile-time options for the MITgcm (read with model is compiled)
(2) input: all run-time options for the MITgcm (read when model is executed)
(3) matlab: all Matlab codes used to create input files (gendata.m) and process the output files (post_process.m)

Only the Matlab scripts and functions are unique and documented here.

------------------------------------
SCRIPT DESCRIPTION OF gendata.m
------------------------------------

Writes input files that are read when MITgcm is executed.

Function dependencies: 
none

Input files:
bathy.mat
WW.mat
HRRR.nc

Output files:
data.mat
forcing_1km.nc

Binary output files (read by MITgcm):
delXvar
delYvar
delZvar
tRefvar
topog.init
T.init
uwind.exf
vwind.exf
apressure.exf


------------------------------------
SCRIPT DESCRIPTION OF post_process.m
------------------------------------

Post-processes all of the MITgcm ouput files. Combines relevant data into a MAT file that can be easily read and plotted. 

Function dependencies: 
none

Input:
folder (MITgcm output directory path)

Input files:
MITgcm NetCDF output files
data.mat (produced by gendata.m)
modes.mat 

Output files:
post_proc.mat

------------------------------------
DATA FILE DESCRIPTION OF WW.mat
------------------------------------

In situ data collected from a WireWalker located at WM. Data is used to initialize the model with a "typical" summer stratification in Lake Superior. 

Structure: 
WW
	fields:
	z (281 x 1) [m] depth
	yday (3865 x 1) [days] days since 00:00:00 1-Jan-2017
	T (281 x 3865) [C] water temperature

------------------------------------
DATA FILE DESCRIPTION OF HRRR.nc
------------------------------------

Atmospheric reanalysis from https://rapidrefresh.noaa.gov/hrrr/ in NetCDF format. Metadata are included in the file and documented on the HRRR website.

------------------------------------
DATA FILE DESCRIPTION OF bathy.mat
------------------------------------

Structure:
data
	fields:
	X (1 x 400) [m] longshore grid cell coordinates
	Y (1 x 150) [m] cross-shore grid cell coordinates
	Z (60 x 1) [m] vertical grid cell coordinates
	T (1 x 9000) [] unnecessary 
	N2 (60 x 1) [1/s^2] buoyancy frequency squared
	H (400 x 150) [m] depth
	W (1 x 1) [m] amplitude of bump
	L (1 x 1) [m] width of bump
	U0 (1 x 1) [m/s] amplitude of forcing velocity 
	x0 (1 x 1) [m] location of the start of the bump
	omega (1 x 1) [1/s] forcing frequency 
	f (1 x 1) [1/s] inertial frequency
	wall (1 x 1) [] flag indicating whether the bump uses a vertical wall (1) or translated slope (2)
	strat (1 x 1) [] flag indicating whether there was density stratification (1) or not (0)

------------------------------------
DATA FILE DESCRIPTION OF modes.mat
------------------------------------

Rotating basin modes output from PR.m using the same 1 km x 1 km grid as the MITgcm

Structure:
modes
	fields:
	x (1 x 568) [m] distance east
	y (1 x 262) [m] distance north 
	f (1 x 1) [1/s] inertial frequency  
	H (568 x 262) [m] depth
	area (1 x 1) [m^2] Area of lake
	omega (10 x 1) [1/s] frequencies of modes
	T (10 x 1) [hr] periods of modes
	eta (568 x 262 x 10) [] Surface displacement modal shapes (complex)
	M (568 x 262 x 10) [] East transport modal shapes (complex)
	N (568 x 262 x 10) [] north transport modal shapes (complex)
	
Note: several other unused fields are output from PR.m that are not documented here.