#The Intermediate Complexity Atmospheric Research Model (ICAR)

####Reference Gutmann, E. D., I. Barstad, M. P. Clark, J. R. Arnold, and R. M. Rasmussen (2015), The Intermediate Complexity Atmospheric Research Model, J. Hydrometeor, in revision.

ICAR is a simplified atmospheric model designed primarily for climate downscaling, atmospheric sensitivity tests, and hopefully educational uses.

To run the model 3D time-varying atmospheric data are required, though an ideal test case can be generated by the code for simple simulations as well.

For reference working with the model code, see the ICAR and Git workflow.

##Compiling the model:

Edit the makefile to set the path to your compiled NetCDF and FFTW libraries

Also to set the compiler for your machine if necessary (defaults to gfortran I think...)

make clean
    remove build by-products
    
make
    default (relatively high) optimization compile 

make install
    compile if necessary, then install in the install directory [~/bin]

###Options: MODE=fast more optimization, slower compile, WARNING:not safe optimizations MODE=profile set profiling options for gnu compiler in particular MODE=debug debug compile with optimizations MODE=debugslow debug compile w/o optimizations MODE=debugomp debug compile with optimizations and OpenMP parallelization MODE=debugompslow debug compile w/o optimizations but with OpenMP parallelization

make test
    compiles various test programs (mpdata_test, fftshift_test, and calendar_test)

add -jn to parallelize the compile over n processors 

###Example: make MODE=debug -j4 uses 4 processes to compile in debug mode

##Running the model:

###Required Input files/variables

####Primary settings file: icar_options.nml [other filename can be specified on the commandline e.g. icar your_options_file] This file specifies all other files and options. See the example in run/icar_options.nml

Other settings files can be defined in the primary settings file, or all settings can be included in one file

####Necessary netcdf files:

1. Boundary / Initial conditions file(s) (from e.g. wrf, reanalysis, or GCM output)

Must [optionally] contain:

QV      = Specific Humidity                         (kg/kg)
T       = Air Temperature                           (K with an optional offset)
P       = Pressure                                  (Pa with an optional [PB] offset)
U       = East-West wind                            (m/s)
V       = North-South wind                          (m/s)
HGT     = Terrain Height                            (m)
Z       = 3D model level heights                    (m)
LAT     = Latitude on mass (P/T/etc.) grid          (degrees)
LONG    = Longitude on mass (P/T/etc.) grid         (degrees)
[PB]    = Optional base pressure to be added to P   (Pa)
[QC]    = Optional cloud water content mixing ratio (kg/kg)
[QI]    = Optional cloud ice content mixing ratio   (kg/kg)
[LATU]  = Optional Latitude on the EW-wind grid     (degrees)
[LONGU] = Optional Longitude on the EW-wind grid    (degrees)
[LATV]  = Optional Latitude on the NS-wind grid     (degrees)
[LONGV] = Optional Longitude on the NS-wind grid    (degrees)

2. High-resolution file

Must [optionally] contain:

 HGT    = as in forcing file
 LAT    = as in forcing file
 LONG   = as in forcing file
 [LU]   = Land use cover classification for land surface model

Must be in a (nearly) constant dx,dy projection (e.g. Lambert Conformal Conic)

NB: Prior to ICAR 1.0, the namelist file in git repo is not always in sync with code! This usually just means it may not include all current options, it will usually run.

###Common errors:

1. Segmentation fault: Most likely due to your shell's stacksize limit (particularly with ifort).

To fix it try the following:

in bash:
    ulimit -s unlimited
in csh: 
    unlimit stacksize

NB: Some systems have a hard limit of 64MB (ulimit -s 65532), this may be enough. Reference: https://software.intel.com/en-us/articles/determining-root-cause-of-sigsegv-or-sigbus-errors