This directory contains the 2.6 release of the University of Victoria
Earth System Climate Model (UVic_ESCM).

When you "untarred" this file it should have created a directory structure
similar to what we use here.

This version of the model requires "perl" to use the "mk" script which 
automatically "makes" and runs the model. The model also requires linking to a 
netcdf library as most of the I/O is now in netcdf without the option of 
unformatted I/O.


To set up the model for the first time:
1) Set your PATH environment variable to include the UVic_ESCM directory.
   For example: "set path = ($path /usr/local/models/UVic_ESCM)" if you are in 
   a csh or a tcsh and you have the UVic_ESCM directory in /usr/local/models.
   Although not absolutely necessary this will do two things. It will allow you
   to have access to the mk script, which is in UVic_ESCM, and it will allow 
   mk to find the version directory you want without having to specify the full
   path. You may then need to re"source" your system variables for your system
   to find mk. For example: "source ~/.cshrc" if you are in a csh or a tcsh. 
2) Find where perl is located on your machine. The command "which perl" may 
   locate it. It is often located in /usr/bin or /usr/local/bin. If you can not
   locate it, you will need to install it on your system. Almost all systems 
   have perl. Try http://www.perl.com for downloading perl. If perl is located 
   somewhere other than /usr/local/bin, you can edit the first line of the mk 
   file (which is in UVic_ESCM) to point to the right location (recommended if
   all systems have it in the same location) or set up a link to perl in 
   /usr/local/bin (dangerous if you do it incorrectly).
3) The model also requires some form of preprocessing. This is usually done by 
   the c preprocessor cpp but the model can be set up to use the preprocessing 
   of many fortan compilers. If you want to use cpp, you will need to make sure
   it is installed on your system. Most systems have cpp but you may need to set 
   the location or options in your UVic_ESCM/2.6/run/mk.ver file later (see 
   step 6 below).
4) The mk script will also make use of a few system variables. You may want to
   check if $HOME, $HOST or $HOSTNAME and $OSTYPE are defined. The script will
   work without these settings but you may find it more limited.
5) Look for the netcdf library file "libnetcdf.a". Try looking looking in 
   /usr/lib/. If netcdf is not installed on your system you will need to get a 
   copy of libnetcdf.a for your system or compile one from source code. Try 
   http://www.unidata.ucar.edu/packages/netcdf to download netcdf source code or
   binaries. Once you have located the libnetcdf.a file, either copy it to 
   UVic_ESCM/2.6/lib or create a link to it in UVic_ESCM/2.6/lib. If you are 
   using a file system that is shared by many different machines, you may want 
   to create directories of libraries for different machine types. For example 
   "UVic_ESCM/2.6/lib/lib_aix" and "UVic_ESCM/2.6/lib/lib_linux".
6) Edit the file "UVic_ESCM/2.6/run/mk.ver" to set the default options for your 
   system. There are many settings that are recognised by mk. It may help to 
   type "mk h" and read the resulting log file to understand what can be set in
   "mk.in" or "mk.ver" files. If you have a system other than aix or linux (or
   a different compiler), you can do the following: type "echo $OSTYPE" or 
   "echo $HOST", copy and/or edit an existing section of definitions (eg. aix or
   linux) making sure you change the identifier (eg. aix or linux) to your own 
   $OSTYPE or $HOST. If you use $OSTYPE all machines that use the operating 
   system will use the definitions but if you use $HOST or $HOSTNAME only that 
   specific machine will use the definitions. Any settings that are in the 
   mk.ver file may also be set in your local mk.in file or a mk.in file in your
   home directory. The priority is: local mk.in, your home mk.in and then the 
   mk.ver file.
7) If you wish to run jobs from a queue, you can look at the example run files 
   and modify a copy of one for your system. The linux example does not actually
   queue a job but it does allow the model to be run in job steps. Run files can
   also be set up to be operating system or machine dependent.

To recreate the main example directory:
1) Create and change to a model directory (eg. my_example)
2) Type "mk r 2.6"
   "2.6" should either include the full path to 2.6 or you should add the 
   directory which holds 2.6 to your PATH variable. The "2.6" portion is only 
   needed once. Once a mk.in file is created in your example directory you can
   rerun mk without having to specify the model version directory.

This should make and run the model on the local machine with output as in the 
directory UVic_ESCM/2.6/example


For mk options just type "mk" and for more help try "mk h".


A very quick description of available uvic options:
Note: not all options or combinations of options are well tested!

# general options
uvic_global_sums = diagnostic for heat and fresh water in coupled components
uvic_min_window = use minimum memory window
uvic_sbc_in_memory = boundary conditions kept in memory
uvic_io_multiple_files = models and time slices to separate files
uvic_io_single = unformatted I/O written in single precision
uvic_io_single_file = multiple run output to a single file
uvic_read_kmt_map = reads ascii map of kmt rather than netcdf file
uvic_save_flxadj = writes flux adjustment if coupled and using restorst
uvic_replacst = replaces ocean surface tracers with data

# embm options
uvic_embm = main embm option
uvic_embm_even_fluxes = every other flux used for conservative coupling
uvic_embm_running_average = write annual average sat
uvic_embm_adv_q = advect moisture
uvic_embm_no_mountains = no mountains
uvic_embm_no_rivers = river runoff distributed evenly along coast

# embm forcing options
uvic_embm_co2_exp = exponentially increasing co2
uvic_embm_co2_lin = linearly increasing co2 
uvic_embm_berger_transient = changing orbital parameters
uvic_embm_annual = annual mean solar forcing
uvic_embm_astress = wind stress feedback

# embm solver options
uvic_embm_2d_diff = use 2d array for diffusion coefficients
uvic_embm_adi = adi atmospheric solver 
uvic_embm_slap = slap atmospheric solver 
uvic_embm_essl = essl atmospheric solver 
uvic_embm_mgrid = mgrid atmospheric solver 
uvic_embm_explicit = explicit atmospheric solver 
uvic_embm_explicit_q = explicit solver just for q
uvic_embm_difadv_t = advection and diffusion of t
uvic_embm_solve2x = half resolution solver in x
uvic_embm_solve2y = half resolution solver in y

# embm land options
uvic_embm_land = land surface model
uvic_embm_landice = land ice data (not functional in this release)
uvic_embm_snow_transient = no limit on snow accumulation

# ice options
uvic_ice = main ice option
uvic_ice_evp = evp dynamics
uvic_ice_cpts = main cpts model option
uvic_ice_cpts1 = 1 category
uvic_ice_cpts3 = 3 categories
uvic_ice_cpts5 = 5 categories
uvic_ice_cpts10 = 10 categories
uvic_ice_cpts_roth_press = uses roth pressure
uvic_ice_cpts_simple_growth = not sure
uvic_ice_cpts_warnings = gives warnings

# mom options
uvic_mom = main mom option
uvic_tbt = netcdf tracer term balances
uvic_convect_brine = convect separately under ice categories
uvic_save_convection = save some convection diagnostics
uvic_read_my_stf = read surface fluxes for ocean

# ice sheet option
ubc_cidm = ubc ice sheet dynamic model (not functional in this release)

# 2.5 compatibility options
uvic_old_albedo = surface albedo set to 1
uvic_old_rest = reads old unformated restarts writes old and new
uvic_old_ws = calculates wind speed from wind stress
uvic_old_adv_q = uses extra diffusion for t with advection of q

# obsolete or not very useful options
uvic_regional_overturning
uvic_regional_overturning_timavgper
uvic_no_statfunc
uvic_ice_albh


There are also a few new variables that can be set in the namelist file:

In diagn:
tsiper = period over which time step integrals are averaged in time
In io:
uvic_mk = true/false to write all mk variables to the printout file
mrot = region for tsi max/min overturning streamfunction (only used to limit i)
isot1 = first starting index in i for overturning (not used if mrot > 0)
ieot1 = first ending index in i for overturning (not used if mrot > 0)
isot2 = second starting index in i for overturning (not used if mrot > 0)
ieot2 = second ending index in i for overturning (not used if mrot > 0)
jsot = starting index in j for tsi max/min overturning streamfunction
jeot = ending index in j for tsi max/min overturning streamfunction
ksot = starting index in k for tsi max/min overturning streamfunction
keot = ending index in k for tsi max/min overturning streamfunction
In co2:
co2ccn = co2 concentration (initial if varying)
co2yri = year of change from initial value
co2yrf = final year of change
co2rate = rate of increase (ppm/year for linear or %/100/year for exponential)
co2for = radiative forcing factor
In ice:
dampice = relaxation time for sst to approach freezing under sea ice

To get the overturning in the North Atlantic (rather than the global values) 
for the example model configuration you could add: mrot=1, jsot=65, jeot=90,
 ksot=3, keot=17 to the "io" namelist section of the control.in file. If you 
would like a yearly average of max/min overturning (and all other tsi 
variables), set tsiper to 365 (tsiint must also be set >= tsiper).


If you have any problems or suggestions, let me know.

Cheers,
Michael Eby 

School for Earth and Ocean Sciences   telephone: (250) 472-4017
University of Victoria, PO Box 1700   facsimile: (250) 472-4013
Victoria, BC, Canada, V8W 2Y2         internet:  eby@uvic.ca
