Spatial Modeling Environment
Copyright 1995 (TXU-707-542), Thomas Maxwell
"Distributed Modular Spatio-Temporal Modelling Environment" 

    This program is free software; you can redistribute it and/or modify
    it under the terms of the GNU General Public License as published by
    the Free Software Foundation; either version 2 of the License, or
    (at your option) any later version.

    This program is distributed in the hope that it will be useful,
    but WITHOUT ANY WARRANTY; without even the implied warranty of
    MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
    GNU General Public License for more details.

    You should have received a copy of the GNU General Public License
    along with this program; if not, write to the Free Software
    Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA  02111-1307  USA

This document is a minimal guide to installing and using the Spatial
Modelling Environment, version 3.0 beta 0. Refer to the documentation
to learn about the SME concepts.

-----------------------------------------------------------------------
INSTALLATION
-----------------------------------------------------------------------

The SME consists of four libraries, two executable programs, and a
bunch of C++ include files and MML files. To build and install the
SME, the following steps are needed:

	1) determine your requirements. SME can use a number of 
	   optional software packages. These are:

	- Gnome xml.  Required (included in many Unix installations.
	  You should install both the xml2 and xml2-devel libraries 
	  from www.xmlsoft.org and make sure xml2-config is in your 
	  PATH).

	- Java 1.2. Highly recommended, and required if you wish to 
	  use the java interfaces, help browsers, and install wizards. 

	- tcl 8.0 or later.  Highly recommended, and required if 
	  you wish to use the java interfaces or the simulation 
	  driver tcl shell.  

	- NCSA Hierarchical Data Format (HDF). Using it will 
	  enable the SME to use HDF files for input and output.
	  You will need to ftp and install HDF 4.0 or later. 

	- GRASS 4.1 or later. Using it will enable the SME to
	  read and write raster maps directly from GRASS.

	- MPI. This is needed if you plan to use distributed
	  processing over more than one CPU. 

	Retrieve and install the software you plan to use before
	configuring and building the SME.

	Linux Note: An rpm package has been provided for linux users.
	Before installing the sme rpms you should have java 1.2 or 
        greater and xml2/xml2-devel installed as packages. If you are
        do an rpm install then you can skip the following directions.

	2) Determine a directory for the installation. This should
	   be visible to all the users using the SME and needs to
	   be writable by the user doing the installation. If you
	   don't specify it it defaults to /usr/local. The installation
      	   procedure will create directories called bin, include, and 
	   lib if they do not exist. Users of the SME will need to
	   have SME_DIR/bin in their PATH.

	3) If you will be using the java interface you may need to download 
	   & install some standard java extensions:
	   - jaxp: http://www.javasoft.com/xml/download.html
	     This required package enables parsing of xml files.
	   - java3d:  http://www.blackdown.org/java-linux/jdk1.2-status/java-3d-status.html
     	     This optional package enables 3D visualization of simulation output.
           - javahelp: ( currently bundled with the SME ).

	4) Unpack the TAR archive, cd to the SME directory, and
           configure the SME. This can be accomplished by several methods:
	   3.1) Use the java install shell (when available).
	   3.2) Edit and execute the script install.sh in the root directory.
	   3.3) Use the GNU configure script directly. 
	   Typing 'configure -h' in the root directory
	   will tell you the available options. You'll need to
	   enable and specify the paths for all the optional 
	   software you want the SME to use. The --prefix=<dir>
	   options is used to specify an installation directory
	   different from /usr/local. You'll only need to specify
	   '--enable-java=yes' if you want to use the Java interfaces.

         Linux note: Linux users who have java 1.2 or greater and 
         xml2/xml2-devel installed as packages can do a default
         configuration by executing "configure --enable-rpm=yes --target=$INSTALL_DIR"
         Additional arguments can be added to enable optional features.
	
	5) Check for errors in the configure process.  The configure
           process should complete with the message "Configure completed 
	   successfully!".  If it does not, check for error messages.
           If you can't diagnose the errors yourself, then send mail to
	   maxwell@cbl.umces.edu.   

	6) OPTIONAL: Build dependencies by typing 'make depend'.
	   This step is needed only if you plan to make changes to the 
	   SME source code and rebuild.   Be sure you are using the 
	   X Windows version of makedepend (DON'T USE the openWin version). 
	   Warning messages stating that makedepend can't find standard
	   C++ header files such as iostream.h should be ignored.

	7) Build the SME by typing 'make install'.  
	   If you are installing over top of an old installation and 
	   have not built the dependencies ( step 4 ) then you should 
	   execute 'make clean' before executing 'make depend'.
	   If you run into problems, check the configuration and
	   if problems remain, email one of us (see email addresses
	   at the end of this document). 

If you want to use both the serial and parallel versions of the SME,
repeat the configuration and installation twice, one with
--enable-mpi=no, the other with yes. The libraries installed will have
different names, so the installations will coexist.

-----------------------------------------------------------------------
USING THE SME
-----------------------------------------------------------------------

The SME runs a spatial model whose unitary specification is written in
the MML description language. You can either write a model in MML
using a text editor, or use an external modelling package and
translate its output into MML. Currently the only supported translator
is meant to be used with STELLA models. Refer to the documentation for
naming conventions and hints on how to export a proper STELLA
equations file. This section assumes you are familiar with the SME
concept and you know what a 'project' and a 'model' are in this
context.

Building projects and models is accomplished by means the SME script,
installed by the 'install' target of the makefile.

SME maintains a 'current' project, a 'current' project directory,
a 'current' model, and a 'current' scenario that are written into 
$HOME/.sme_project. These are accessed and changed through the SME 
script: the file is not meant to be modified manually. A summary of 
the usage of the script (a more complete list is obtained through 
'SME -h' ) is as follows:

Usage: SME [options] { project | model | scenario | import | build | run } [args]

   options:

    -h   print usage help
    -p   parallel (MPI) code

   arguments:

    project <pname> [pdir]        -- Sets current proj/workspace
                                     Create workspace if missing
    model   <mname> [spec_file]   -- Sets current model
                                     Uses [spec_file] if specified
    scenario <sname> [def_scen]   -- Sets current scenario
                                     Copies configuration from [def_scen] if specified
    import <STELLA file>          -- import STELLA file
                                     into current model.
    build                         -- create/build model.
    run                           -- run current model.
    clean                         -- delete files of current model.


If you run SME alone it will tell you the current directory and
project. The -p flag tells it to use MPI code (error messages result
if an MPI version of the SME has not been installed). To create a new
project, execute:

	SME project <projname> [projdir]

If you supply projdir this becomes the current root directory of the
projects. This directory is not project-specific: the actual project
will be created in a directory <projname> under it. If you do not
supply projdir, the current one is used if set, otherwise the program
will ask you if you want to use the current directory.

If you have already created a project, typing SME project <projname>
will make projname the current one.

To create a new model, execute:

	SME model <modelname> [def_model]

Here def_model (if used) specifies the name of na existing model whose MML or SMML files will be copied to provide the initial specification of the new model.  If you do not specify a default model to copy from, then you should import a STELLA configuration file, or build the model from scratch in the SME. 

To create a new scenario, execute: 

	SME scenario <sname> [def_scenario]

Here def_scenario (if used) specifies the name of an existing scenario whose config file will be copied to provide the initial specification of the new scenario.  

To 'import' a specification for the current model from a STELLA equation file, execute:

	SME import <STELLA equation file>

which will run a translator to create the corresponding SMML/MML files, which
will be put in the Models/ directory under the project workspace.

To create and/or build the current model, execute:

	SME build 

which invodes 'make' to build the model driver (MPI multiprocessing is 
used if it is installed and you supply the -p option).  The makefile will 
take care of all the dependencies and invoke the MML and C++ compilers as needed.

To run the current model, execute 'SME run'. The correct driver
will be invoked for MPI or serial, according to the -p option. Refer
to the documentation about configuration, data formats, and use of the
SME driver command-line interface.

To run the model using the java interface, with both interface and
driver running on localhost, you type 'SME -java local run' 

The command 'SME clean' will delete the object files and the
drivers. It will not delete the MML file or any file that you import,
so that you can run 'SME build' again after running 'SME clean'.
 
------------------------------------------------------------------------
The SME is being developed and maintained by Thomas Maxwell
(maxwell@cbl.cees.edu).  

