Adam's Flexible CAM-SE Diagnostic Package
April 2018
*email bugs and/or requested modifications to adamrhster@gmail.com

Overview
#---------------------------------------
A collection of user-friendly, flexible scripts, supporting the 'simple models' compsets in the upcoming release of CESM2. These scripts will work whether history fields are on the native CAM-SE grid (time,lev,ncol), or a lat-lon grid (time,lev,lat,lon). They also work regardless of grid resolution (currently only for CAM-SE). By default, all scripts will dump out a netcdf with the variables computed in the scripts. 

Instructions
#---------------------------------------
Install this package through executing the command: git clone https://github.com/adamrher/ncl-scripts.git adams-git-scripts

Modify all .sh files through setting the variables 'data_dir' to the directory where you keep all your runs (usually a scratch directory) and set 'ncl_dir' to the path where the ncl scripts live ("<path-to-adams-git-scripts>/ncl/"). The scripts exploit CESM's standard directory structures (i.e., your data is assumed to live at "data_dir/<case-name>/run/") and history file naming convention (e.g., the ".cam.h2.0001-06.nc" modifier added to the end of the case name).

*Note* this package only works on NCAR machines. There are currently six ncl scripts that may be executed. It is recommended (but not required) that you adjust the line at the top of the ncl-scripts: load "/glade/p/work/aherring/se_func_lib.ncl", with load "<path-to-adams-git-scripts>/ncl/se_func_lib.ncl".

*Note* if by executing these scripts, you get booted off of NCAR's login nodes, then run an interactive job on a geyser node. Enter "execgy -a $ACCOUNT -t 01:00:00 -n 1 -m 100G" where $ACCOUNT refers to a project number. You may request up to 1000 GB of memory (!).

#---------------------------------------
(1) all-diags.ncl
Computes global time-mean integrals (also does the deep Tropics) of relevant quantaties. Required fields: PRECC, PRECL, TMQ, PBLH, CLDTOT, PS, T, TS, U10, U (FREQZM is easy to toggle on, if you have it).

To execute, first go into the directory you wish to output the plots. 
Then execute the command: "source <path-to-adams-git-scritps>/glob-diags.sh <case-name> <fincl-number>"
<case-name> is the name of your case
<fincl-number> requires an 'h' followed by a number, indicating which history files have the data required by the script.

e.g., "source $work/CESM2/git-ncl-scripts/glob-diags.sh camtrunk_180328_QPC6_ne30_180330 h0"

#---------------------------------------
(2) omg-diags.ncl
Computes global time-mean integrals (also does the deep Tropics) of omega statistics. It computes the components of the global-mean-omega = omg-up*frac-up + omg-dw*frac_dw. Calculation requires instantaneous output (not averages).

to execute, type: "source <path-to-adams-git-scritps>/glob-omg-diags-inst.sh <case-name> <fincl-number>"
e.g., "source $work/CESM2/git-ncl-scripts/glob-omg-diags-inst.sh camtrunk_180328_QPC6_ne30_180330 h1"

#---------------------------------------
(3) dzonal_prec_diff2case.ncl
Computes zonal average PRECT for two cases, as well as their difference. 95% significance is shaded. Requires variables PRECC and PRECL. It is recommened (though not required) that the history fields are monthly means, and already on a lat-lon grid. The two cases do not have to be the same grid resolution.

(4) dzonal_hgt_diff2case.ncl
Computes a time-mean zonal-height profile of the relative humidity, with the meridional mass stream function overlain. Also plotted are the differences. The wmo-tropopause is overlain. Required fields: T,Q,V,PS. It is recommended that the history fields are monthly means (this is strongly recommended), and already on a lat-lon grid. The two cases do not have to be the same grid resolution.

These two scripts are executed together with the command: 
"source <path-to-adams-git-scritps>/diff-2-case.sh <case1-name> <fincl-number> <case2-name> <fincl-number>" 
e.g.,"source $work/CESM2/git-ncl-scripts/diff-2-case.sh camtrunk_180328_QPC5_ne30_180330 h0 camtrunk_180328_QPC5_ne60_180330 h0"

#---------------------------------------
(5) tropD-diags.ncl
Estimates the latitude where the Hadley Cell terminates using various metrics, through translating the MATLAB scripts developed by Ori Adam to NCL. Required fields are U,V and PS (PRECT and LHFLX will be required soon). The relevant citation is:

Adam O., K. M. Grise, P. State, I. Simpson, S. M. Davis, N. A. Davis, D. W. Waugh, and T. Birner, 2018: The TropD software package: standardized methods for calculating Tropical Width Diagnostics. Geoscientific Model Development. 

to execute, type: "source <path-to-adams-git-scritps>/tropD-diags.sh <case-name> <fincl-number>"
e.g., "source $work/CESM2/git-ncl-scripts/tropD-diags.sh camtrunk_180328_QPC6_ne30_180330 h1"

#---------------------------------------
(6) baroclinic_wave_2case.ncl
Contour plot of a single time-slice, for two different cases, of a variable of your choosing and the FKESSLER compset in CESM2. This compset refers to a moist version of the Jablonowski baroclinic wave, and includes a Terminator test case. Supported variables: PS, PRECL, PTTEND, CLDLIQ, Q, CL, CL2, iCL, iCL2, iCLy. Relevant citations:

Ullrich, P. A., T. Melvin, C. Jablonowski, and A. Staniforth (2014), A proposed baroclinic wave test case for deep and shallow-atmosphere dynamical cores, Quart. J. Royal Meteor. Soc., 140(682), 1590–1602.

Lauritzen, P. H., A. J. Conley, J.-F. Lamarque, F. Vitt, and M. A. Taylor, 2015: The terminator "toy" chemistry test: A simple tool to assess errors in transport schemes. Geosci. Model Dev., 8, 1299–1313.

to execute, type: "source <path-to-adams-git-scritps>/fkessler-2case.sh <case-name1> <fincl-number1> <case-name2> <fincl-number2> <VAR>"
e.g., "source $work/CESM2/git-ncl-scripts/fkessler-2case.sh camtrunk_180328_FKESSLER_ne30_180330 h1 camtrunk_180328_FKESSLER_ne60_180330 h1 PRECL"