USGS - science for a changing world
Header graphic spacer
Watershed Modeling
 
Home | People | Research Topics | Publications | Software | Training | Related Links | FAQs

 

 

INSTALLATION

 

Obtaining MMS

MMS is available via the MMS internet homepage at http://wwwbrr.cr.usgs.gov/mms. MMS has been pre-compiled for a wide variety of platforms. Each platform is clearly identified as part of the tar file name. If the desired platform tar file is not present, MMS may be compiled from the mms-x.x.tar.gz version. All tar files contain the full source code regardless of any additional pre-compiled files. Software and hardware requirements are discussed in Attachment 1.

 

Installation Overview

The MMS directory structure is based on the use of two distinct directory areas. One is the MMS master directory area and the second is the MMS user workspace directory area (fig. 2.1). The master directory area is a read-only area that contains the basic system programs and files. This area also contains those modules of the module library, and selected models, that have received some level of quality control as defined by the using organization. All users share the files, libraries, modules, models, and other executables in the master directory area. Changes or additions to this area should be made only by persons familiar with system structure. New modules and models may be added as they receive the required testing and approval.

Figure 2.1 MMS master and user directories for a system of three users.

The user workspace directory area is where a user stores and manages individual data and parameter files, modules, models, and selected modifications to the MMS graphical user interface. A user workspace directory can be created for each individual using the system. The user workspace directory should not be created under the master directory because the master directory and its subdirectories are read-only.

The installation procedures involve the creation of one master directory and as many user workspace directories as needed. A set of scripts are provided for the installation of each directory type to assist the user in installing MMS. The installation scripts and procedures for each directory type are discussed in detail in the following sections.

 

Creating the MMS Master Directory

The MMS master directory may be created in any parent directory on the workstation system. However, all MMS users must be able to read from that location. Put the tar file in the desired parent directory. The tar file must be uncompressed before it can be extracted. Tar files with the extension ".Z" need the utility uncompress, whereas those with a ".gz" extension need gzip -d. MMS should be extracted from the tar file with the Unix command tar -xvf <mms.platform>.tar where <mms.platform> is the manufacturer name of the workstation hardware. For example, SUN4.tar is the precompiled version of MMS for a SUN workstation using the SUN OS4.1.x operating system. The directories should be extracted such that all MMS users have read access.

The major directories in the master directory area and their contents are:

The bin directory:

  • the model builder xmbuild
  • the workspace installation script mms_workspace
  • the post-processing programs XMGR, pdraw, and GISanimator
  • the file conversion scripts control_update, param_update, and data_update
  • the executable code for selected models that have received some level of quality control as defined by the using organization.
The help directory:
  • the MMS system documentation.
The lib directory:
  • the MMS libraries libXbae.a, libUNtil.a, libmms.a, libutil.a, and libPlotW.a.
The make directory:
  • the makelist file
  • test C programs
  • test FORTRAN programs
  • scripts called by the setup script.
The man directory:
  • Unix style man pages for the MMS library functions.
The modules directory:
  • all modules that are selected to be read-only. A subdirectory is defined for each process type.:
The src directory:
  • subdirectories with the source code for the components of MMS.
The workarea directory:
  • a template of the directories that are copied to the user's work area by the mms_workspace script.

The src directory contains all the source code subdirectories for MMS. Each subdirectory has a makefile that is used to compile the source code in that directory and place the results into either the bin or lib directories. If changes are made to the source code in one of these subdirectories, only the makefile in that subdirectory needs to be executed to update MMS.

Also located in the src directory is an include subdirectory that contains a number of include files that are used by source code in one or more of the src subdirectories. If a change is made to any of these include files, then all the src subdirectories whose source code use the modified include files must be remade using the appropriate makefiles.

There is a makefile in the mms directory that will execute the make command in all of the src subdirectories. Running this makefile will build the entire MMS system. Prior to using this make option, a make clean command should be executed from the mms directory. This command removes all object code, libraries, and executables.

The modules directory is a read-only directory in order to provide a method to distribute tested or quality assured module code that is intended to remain constant within the system. However, if modification of one or more of these modules is desired, this is still possible. The user can copy these modules to a user workspace, modify them as desired, and construct a new model using any combination of modules from the master directory and the user workspace directory.

 

The MMS Setup Script

The MMS setup script is located in the mms directory. The primary function of this script is to create the makelist file in the mms/make directory. This file is included by every makefile in MMS; thus, it will be referenced every time an MMS library, executable, or model is compiled. The purpose of the makelist file is to provide a common, consistent, and unambiguous set of instructions for compilation of MMS regardless of specific hardware, operating system, or window system installations.

This setup script should be run whenever (1) MMS is initially installed, (2) the MMS master directory is moved, (3) there is a change in the FORTRAN or C compilers, or (4) there is an update in the X11 or Motif libraries.

The setup script is written in the Korn shell. For operating systems that do not support the Korn shell, the script may be run under the Bourne shell by changing the first line in the file from:

#!/bin/ksh

to

#!/bin/sh

The script will ask questions about compilers and libraries. It will verify responses and insure that they are valid before proceeding onto the next question. Once the script is running, it may be terminated using a control-C command at any time without any adverse affects, if the proper response is not known or an incorrect response has been provided. The makelist file is written (or overwritten) only after all questions are answered satisfactorily. In addition, once all questions are answered, the script will inquire about compiling the MMS libraries and executables. Versions of MMS with pre-compiled libraries and executables do not need to be remade. The following is an example application of the setup script:

(ksh) runoff.pts% setup
This is the MMS system level installation script.
Installing to MMS master directory /home1/mms.

If this is not the correct location for MMS, exit the script now using a control-C command and move the MMS directory to the correct location. Restart the script.

You are running SunOS release 5.6
Please check your path for the placement of `/usr/ucb'.

This directory must come after the other important solaris directories for proper installation of MMS.

ARC flag has been set to SOLARIS

The script will then determine the machine type and operating system. Environment variables and default values for subsequent questions will be set based on the system architecture.

C compiler to use [gcc]: cc
C compiler looks good.

A C compiler is required for MMS. The system is written in portable C code, but some of the C library include files may vary from compiler to compiler. The compiler used to develop MMS was the Gnu C compiler gcc. However, in the example, the compiler was switched to the solaris C compiler to take advantage of debugging tools.

FORTRAN compiler to use [f77]: <return>
make/main.f:
MAIN test:
FORTRAN compiler looks good.

FORTRAN is not necessarily required for MMS, but the demonstration models included in the tar file and described in the help files all require a FORTRAN compiler. However, modules written entirely in C may be compiled into models without the need of a FORTRAN compiler.

Checking your compiler for ANSI compliance.

You are OK.

Found X11 include path -- /usr/openwin/share/include

X include path to use [/usr/openwin/share/include]: <return>
XINCPATH=/usr/openwin/share/include
Found Motif Include path -- /usr/dt/include

Motif Include path to use [/usr/dt/include]: <return>
XMINCPATH=/usr/dt/include
Found The X11 library -- /usr/openwin/lib

X11 library path to use [/usr/openwin/lib]: <return>
Found The Intrinsics library -- /usr/openwin/lib

Intrinsics library path to use [/usr/openwin/lib]: <return>
Found The Motif library -- /usr/dt/lib Motif library path to use [/usr/dt/lib]: <return>

X11 and Motif must be installed on the system. If the system does not have these include files, it is not possible to recompile the MMS system executables. If the system does not have these libraries, it is not possible to make any models with MMS. If the files are not located in the standard locations, it is necessary to supply the paths to the script.

Specify the flags to be passed to the C-compiler.
RETURN - to accept defaults.
COMPILE_FLAGS [-O -DSOLARIS -DSYSV -DUSE_DIRENT]: <return>

Change the "-O" to "-g" for a debuggable version of MMS.

I will check the compile flags now
Please watch for error messages
Check complete
Any problems? n
COMPILE_FLAGS = -O -DSOLARIS -DSYSV -DUSE_DIRENT

The script will compile a test file with the specified C flags. If there is an error, correct it by resetting the flags to the proper values for the target system.

Specify the flags to be passed to the FORTRAN compiler.
RETURN - to accept defaults.
FORTRAN_FLAGS [-u]: <return>
I will check the FORTRAN flags now
Please watch for error messages
12522.f:
MAIN test:
Check complete
Any problems? n
COMPILE_FLAGS = -u

The script will compile a test file with the specified FORTRAN flags. If there is an error, correct it by resetting the flags to the proper values for the target system.

Specify the flags to be passed to the loader (ld).
RETURN - to accept defaults.
LDFLAGS [-s]:<return>
LDFLAGS = -s
Specify the flags to be passed to the compiler that are
required specifically for X Window-based programs. Some systems
require extra compiler flags to increase the symbol table size,
when compiling for X Windows.
RETURN - to accept defaults.
XCFLAGS []: <return>
I will check the loader flags now
Please watch for error messages
Check complete
Any problems? n
XCFLAGS =
Specify the flags to be passed to the loader (ld) that are
required specifically for X Window-based programs. Some systems
require extra loader flags when compiling for X Windows.
RETURN - if no flags are to be specified.
XLDFLAGS []: <return>
XLDFLAGS =
Some system require additional libraries when compiling X Window pro
grams.
Specify the additional libraries needed when compiling X Window pro
grams.
Consult your installation guide if you are unsure of the need for these
libraries.
RETURN - if there are no extra libraries needed.
XEXTRALIBS [-lsocket -lnsl]: <return>
Checking -lsocket -lnsl. Please watch for any errors

Check complete
Any problems? n

Default values for these "extra" X Window flags and libraries will be set when the operating system type is set. Always try the default values first. If additional compiler options are necessary, specify them here.

Specify the math library.
RETURN - to accept defaults.
MATHLIB [-lm]: <return>
MATHLIB = -lm
Some system require additional libraries when compiling FORTRAN code.
Specify the additional libraries needed when compiling FORTRAN.
Consult your FORTRAN manual for necessary libraries.
RETURN - to accept defaults.
FORTRANLIBS [-L/opt/SUNWspro/SC3.0.1/lib -lM77 -lF77 -lsunmath -lsocket
-lnsl -L/usr/local/ccs/lib -lgen -lm]: <return>
Checking -L/opt/SUNWspro/SC3.0.1/lib -lM77 -lF77 -lsunmath -lsocket
-lnsl -L/usr/local/ccs/lib -lgen -lm. Please watch for any errors
Check complete
Any problems? n
FORTRANLIBS = /usr/lang/SC2.0.1/values-Xt.o -L/usr/lang/SC2.0.1 -lM77
-lF77 -lansi
Now that you have defined everything, please name the file
to store this information in.
Makelist file [makelist]: <return>
HEADER = makelist
Creating makelist file
Makelist file /home/markstro/mms/make/makelist created

The makelist file is written at this point - compilation follows.

Updating the scripts...
cp mms_workspace /home/markstro/mms/bin
cp control_update /home/markstro/mms/bin
cp control.var /home/markstro/mms/bin
cp control.param /home/markstro/mms/bin
cp data_update /home/markstro/mms/bin
cp param_update /home/markstro/mms/bin
cp param.param /home/markstro/mms/bin
cd /home/markstro/mms/bin; sed -e "s#<MMSMD>#/home/markstro/mms#"
mms_workspace > tmp; mv -f tmp mms_workspace; chmod 755 mms_workspace;
cd /home/markstro/mms/bin; sed -e "s#<MMSMD>#/home/markstro/mms#"
control_update > tmp; mv -f tmp control_update; chmod 755
control_update;
cd /home/markstro/mms/bin; sed -e "s#<MMSMD>#/home/markstro/mms#"
data_update > tmp; mv -f tmp data_update; chmod 755 data_update;
cd /home/markstro/mms/bin; sed -e "s#<MMSMD>#/home/markstro/mms#"
param_update > tmp; mv -f tmp param_update; chmod 755 param_update;
The MMS libraries seem to exist.
Remake them anyway [no] -->n
Not making MMS libraries now.
You can always make them later by running make in /home/markstro/mms
The MMS executables seem to exist.
Remake them anyway [no] -->n

If the script finds that the libraries and executables already exist, the default will be not to make them. If the mms/bin and mms/lib directories are empty, the default will be to make them.

Not making MMS executables now.
You can always make them later by running make in /home/markstro/mms
MMS Setup completed

 

Creating the MMS User Workspace Directory

Before any user-created models can be built or run, a workspace directory must be created. Separate directory areas for each user help to keep work organized and separate from other users. The user workspace directory area must be in place before any of the MMS programs can be run.

The user workspace directory area can be located in almost any user-specified directory and is set up by executing the mms_workspace script. The user directory is created from a template directory in the master directory located in mms/workarea. A workspace should never be created anywhere in the mms/workarea directory as this will corrupt all workspaces created thereafter.

The directories in the user directory area and their contents are:

The models directory:

  • the executable models that the user has created
  • the model schematic files
  • the model html file
The control directory:
  • the environment file (mms.env)
  • the control file(s) (mms.control)
  • the resource script file (setmms)
  • the app-defaults files
  • the workspace.path file
The input directory:
  • the data directory that contains the simulation data files
  • the params directory that contains the parameter files
  • the vars directory that contains variable files that were saved at the end of user-selected model runs.
The make directory:
  • the files generated by the xmbuild program
The modules directory:
  • FORTRAN and C module source code;
The output directory:
  • model output files
  • variable and parameter print files
  • optimization and sensitivity analysis files
  • ESP output files
  • statistical analysis work file statvar.dat

The mms_workspace script is located in the mms/bin directory in the master directory. The script has two main functions. These are to copy the template workspace directories to the user's workspace directory and to update the paths in the workspace files. This script should be run whenever the user wants to create a new workspace.
The mms_workspace script is written in the Korn shell. For operating system which do not support the Korn shell, the script may be run under the Bourne shell by changing the first line in the file from:

#!/bin/ksh

to

#!/bin/sh

The script will ask questions about a location and system type. Once the questions are finished, the script starts copying the directories. For successful installation, it should not be interrupted. If the need arises to start over, all contents of the workspace directory should be removed and the mms_workspace script should be re-run. The script must be allowed to run all the way through uninterrupted to insure that all files and directories are present and not corrupted.
For best results, create the user workspace directory first, change to this directory, and then run the mms_workspace script. The workspace directory may be named anything. For the following example, it is called work:

(ksh) rose.p2% pwd
/home/markstro
(ksh) rose.p2% mkdir work
(ksh) rose.p2% cd work

From this directory, run the mms_workspace script. The script will ask several questions. The following is an annotated example run of the mms_workspace script:

(ksh) rose.p2% mms_workspace
**********************************************************
* Welcome to *
* MMS Workspace installation *
**********************************************************
Your current path is /home/markstro/work
Please type the FULL path of the user workspace directory.
RETURN - to use the current path.
<return>

Type return to use the current directory. The script will echo the location of the new workspace. If the path is wrong, exit the script using the control-C command, correct the path, and start over.

Installing workspace in /home/markstro/work
You are running SunOS release 5.6
Your current architecture is SOLARIS. Using SOLARIS as target architec
ture.
/home/markstro/work found...
Workspace directories copied to /home/markstro/work...
Updating paths...
Finished with paths...
Installation completed.

If everything is properly installed, listing the workspace directory contents using the ls command will produce the following list of subdirectories:

(ksh) rose.p2% ls
control/ make/ modules/
input/ models/ output/

The control directory contains a resource script file named setmms (or setmms.ksh) that must be run prior to the execution of any model or xmbuild. setmms merges the MMS app-default files with the current app-default file and sets several operating system environmental variables. This only needs to be done once at each login. This can be accomplished in one of two ways. One is for the user to manually execute a source command with the full path to the setmms script each time they login. An example source command is:

source /home/markstro/work/control/setmms

A second way is for the user to put the source command in their .cshrc or .login file so that it is automatically initiated at every login.
One other addition to the .cshrc file that may be desirable is the <user_workspace>/models directory path to the path environment variable. This will enable the execution of user-created models from any place on the system.

 

Moving the User Workspace

It is generally not desirable to move a user workspace once it has been created. There are many files with hard coded paths that are set at installation time. Thus, moving the directory will result in many errors caused by these incorrect paths. However, if it becomes necessary to move a workspace, there are two different strategies that can be adopted. The first option is to create a new user workspace using the procedure described above and then manually copy the necessary files from the old to the new workspace. The second option is to move the old workspace to the new location and manually edit all of the path references.

The steps for creating a new workspace using option one are as follows:

Create the new user workspace using the procedure described above.

Copy the contents of the old_work/input/data, old_work/input/params, and old_work/input/vars to the corresponding new_work/input directories.

Copy the contents of the old_work/models directory to the new_work/models directory. Any schematic files that contain references to modules that have moved must be edited to reflect their new locations.

Copy the contents of the old_work/modules/src and old_work/modules/hier directories to the corresponding new_work/modules directories.

Update the new_work/control/workspace.path file to contain the paths to the modules specified in the model schematic files.

The steps for moving a workspace to a new location using option two are as follows:

Update the control files (mms.control) in the work/control directory. Change the paths to the data files(s) and parameter file.

Update the work/control/mms.env file.

Update the work/control/setmms script.

Update the work/control/workspace.path file to reflect the new locations of the modules.

Update the work/make/make.template file.

Update all the schematic and html files in the work/models directory.

Generally, the first procedure works better when there has not been much work done in the workspace. As more data and model files are created, the second procedure should be given more consideration.

 

Installing Modules

A tar file with a fixed directory structure is used to distribute the source code modules and the module documentaton for complete models. This file can be installed in the user's workspace directory or in the master MMS directory. When this file is untared, the directory <user's workspace>/modules/src/<model_name> or <MMS master directory>/modules/src/<model_name> will be created and the source code modules will be written here. A second directory <user's workspace>/modules/doc/<model_name> or <MMS master directory>/modules/doc/<model_name> will also be created and the documetation for each module, in html format, will be written here.

In order for the documentation system to work correctly, each module source code file must have it's corresponding html documentation in the modules/doc directory.

 

 

USA.gov logo   Take Pride in America 
button