This README.txt file was generated on 23 NOV 2020 by Sam Kelly

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

These are the "csw.h" header files for the Coupled-mode Shallow Water mode (CSW). The simulations can be re-run using the instructions and source code at https://bitbucket.org/smkelly/. The model is described most recently by Savage et al. (2020; JPO). 

The order of operations for replicating the simulations in Kelly et al. (2020; GRL) is:

(1) Obtain the "input" data sets for the CSW model, which might include TPXO surface tides, GEBCO bathymetry, World Ocean Atlas stratification, etc.

(2) Run the pre-processing scripts to create CSW model input files from the "raw" input datasets. 

(3) Use the desired header file (included here) for a given simulation. Change the header files name to "csw.h" and compile the CSW model

(4) Run the CSW model using the correct MPI processor partitioning (as specified in the csw.h) file

(5) Post-process the NetCDF output files using the matlab scripts included with the CSW source code

(6) Rename "out.mat", which is the post-processed matlab data summary file, to match the original name of the header file (e.g., "best.h" should produce "best.mat")

After those steps, the Matlab post processing and plotting scripts in the other two directories should work. 

---------------------------------
SAMPLE FILE DESCRIPTION FOR csw.h
---------------------------------

These header files specify all the parameters in each CSW simulation. CSW is written in C using MPI. In practice it is easier and faster to re-compile the model each time a parameter is changed than to open Matlab and modify a run-time parameter file. The use of header files also allows any unnecessary code to be completely removed from the executable during compilation. The sections of the C header files that can be altered are:

// Input/output files
These are the files that will be read or written during CSW execution. The files that will be read, must be written using the pre-processing matlab scripts included with the CSW code. 

// Grid spacing
This specifies the horizontal resolution of the model

// Grid size
This specifies the number of grid points per slab (processor) and number of processors. It also controls the number of vertical modes that are included, along with the number of vertical modes that will be written to the output file. 

// Time steps
These parameters specify how long each model time step is, and how often standard and diagnostic output is written. 

// Dissipation 
These parameters specify simple dissipation parameters, such as horizontal viscosity, linear drag, etc. Commenting these parameters removes the relevant code and will decrease the computations required to run CSW.   

// Set minimum depths for dynamics, forcing, and topographic coupling
These minimum depths are primarily chosen to maintain numerical stability.

// Flags for dynamics (These could be written to the input file, but it's quicker to compile than run MATLAB)
These flags determine which portions of the source code are compiled. 

// Flags to write snapshots
These flags turn on routine snapshots of transport and pressure. 

// Flags to write time-averaged diagnostics
These flags turn on diagnostic calculations of energy, conversion, energy flux, etc. It is much more efficient to compute these during the simulation execution than during post processing. 

Additional commands at the bottom of the csw.h header file should not be altered. They primarily constitute function prototypes, and global variables and structure definitions.