To : All SOCRATES users
From : Rashid Khosravi
Date: 1 March, 01 
--------------------------------------------------------------------------------------------------------

The following is intended to serve as a step by step guide on how to
download, run, and view the results of the NCAR 2-D model, SOCRATES.
This model was originally developed by Guy Brasseur, and it has been
improved and enhanced by several people over many years. The version
of the model that is described here has evolved over the last 2 1/2 
years from the version (socrates2) that Teresa Huang last worked on, 
and it is called socrates3.II65 in my version control system. However, 
for the sake of brevity, the (unofficial) release version is called 
socrates3.

For a detailed description of the physics, chemistry, I/O structure of 
the model, references, and other pertinent information see the following 
web site (or from ACD's home page follow the links from 'modeling'):

    http://www.acd.ucar.edu/models/SOCRATES/

Downloading and Running the Model
******************************************
To get the model code, click on the link 'socrates3.tar.gz' from the 
above page. This is a tar file (~ 6 MB) containing all the model 
source code, a Makefile, all the data files, and a UNIX script to 
run the model. To expand (untar) the file, do the following:

	gtar xpzf socrates3.tar.gz

This will create the following directories and subdirectories:
data, in, out/log, out/divar, out/save, out/arch, save, and src. The
sample input file for a 10-year baseline-atmosphere run is in the 
'in' directory, and the script file to run this case (called 'runsoc')
is in the main directory. To make (using the Makefile in ./src) and 
run the model, do the following

	runsoc

This will create a log file of the run in the ./out/log directory, 
with the (results) output file (netCDF format) archived to ./out/arch.

For reference, our 10-year, baseline-atmosphere output file that was
run on a DIGITAL alpha machine (ev56 cpu) using the above input
file is also provided on the above web site (arch.10yr.base.nc). 
This is a large binary file (~ 226 MB) that contains output for every
month of the 10-year simulation. 

Note that the makefile provided in the 'src' directory is specific to
the alpha ev56 architecture. It should therefore be modified 
appropriately if the model is to be run on a different platform.

NOTE
----
It is highly recommended that after successfully downloading and
making the model on your platform, a test case of the baseline 
atmosphere be run and the results compared with the above (10-yr)
reference output. The test case does not need to be run for 10
years; for a quick test, it can be run for 1 month (see the 'Model
Description' document on the above web site for help with setting up
the input file). The model output should of course be saved on the
same dates as those for which the reference output file were saved.
This is controlled in the input file, and can be done simply by
changing the value of 'simulation end time' (see 'Model Description').

Note that some (small) numerical differences between your test 
baseline and the reference baseline should be expected, if the model 
is run on a different platform than the alpha ev56 (including 
different alpha processors, depending on compiler version, options,
etc.).


Stability, Bugs, Portability, etc.
************************************
The model has been stabilized numerically to a large extent so that
running the baseline atmosphere case and the simulations described
in the manuscript mentioned below should proceed smoothly. However,
it is possible that changing some parameters/constants in the model 
or making modifications such as changing some parts of the algorithm
may cause the model to crash because of numerical instability in the
overall algorithm that solves the thermodynamic equation for T. We
have spent a lot of time trying to solve this problem, but it has 
proven to be very difficult to do so. The region of the atmosphere 
where this occurs is usually the mesosphere, where the numerical 
instability might cause the T to become negative. It may help to 
make the desired changes in small increments to avoid this problem. 

The person with the most expertise in this area of the model is 
Stacy Walters (stacy@ucar.edu).

Generally, the code is working well and no known bugs exist 
However, this is not an "official" release of a software 
product. That is, no "formal" effort has been made to debug and/or 
test the code systematically according to software engineering 
principles. Therefore, it is requested that any bugs or errors that
may be found be reported to Anne Smith (aksmith@ucar.edu) and 
Rashid Khosravi (rashid@ucar.edu).

Also, even though most of the code is written in FORTRAN 90, no 
formal effort has been made to make the code portable across all 
possible platforms. Therefore, any portability issues that may arise
should be addressed by the user at this time, but we encourage 
reporting these issues to us.


Model Evaluation
*******************
The version of the model released here is in the process of being 
published in the manuscript titled, 'Response of the mesosphere
to human-induced and solar variability calculated by a 2-D model'
(R. Khosravi, et al.). Although we have not formally "validated" the 
model, we have evaluated it and the model fields generally compare 
well with the measured fields; they capture the features found in 
the observed atmosphere to within measurement uncertainties. Also, 
the model results were included in a NASA inter-comparison project, 
the results of which are published in the document, NASA/TM-1999-
209554, titled, 'Models and Measurements Intercomparison II'.


How to View the Results
****************************
A GUI program to view the model output (archive and diurnal variation)
is provided on the above web site (view2d.tar.gz). The application is
called 'view2d' and it is written in IDL. To use the viewer, create 
a directory (e.g., view2d), copy the tar file to that directory, and
in that directory untar the file by doing the following:

	gtar xpzf view2d.tar.gz

Then edit the file 'preferences.pro' and change the I/O path names
according to your setup. To run the program, do the following (first
run IDL):

	IDL> view2d

The program will then prompt you to select a directory from which to 
load a SOCRATES (or other 2-D **netCDF**) output file. 

The application is generally intuitive, and it's easy to learn how to
use it by just playing with it. There are also guide files included in
the package that may be useful, which are: README.txt, USAGE.txt, and 
BUGS.txt. 


Good Luck!

RK