Chapter 14: SISIM & SISIM3D  


Sisim is a graphical user interface (GUI) for sisim3d an indicator kriging and conditional stochastic simulation program for discrete data (non-continuous data: e.g. clay, sand, gravel) developed at Stanford University by Gómez-Hernández and Srivastava (ISIM3D, 1990) and modified at the Colorado School of Mines by McKenna (1994) to utilize soft data (Discussed in Chapter 8 Mathematics section). Up to eight indicators can be modeled in a single simulation. In its basic form sisim3d can be awkward to use, particularly when many simulations are required based on varying semivariogram models. This interface assists the user in handling data files, input parameters, coordinating multiple simulation, tasking jobs to other computers, calculating simulation statistics, and visualizing results.

This chapter goes into the details of using sisim as an interface for sisim3d. The documentation supplied with sisim3d is limited, and this program will try to clarify some of the points.

The sisim application is composed of two sections; the main menu-bar and the log-status text area. The menu-bar is used to select all sisim commands, and the log/status area is used by the program to report important messages and results. The log/status area may also be used to personally enter important comments or notes; it is a simple text editor.

NOTE: Sisim and sisim3d are different programs. Sisim is merely a GUI for sisim3d and if desired, sisim3d can be run independently. The information created by each program is passed between program mainly using data files. Sisim also passes some information to sisim3d using command line arguments (Sisim executes sisim3d). The two programs also communicate during run-time using UNIX network protocols. This only contains information about the status of the programs (% completion, etc.) and nothing about the data required for the simulation.


Menu Items
Examples
Command Line Arguments
File Formats
Mathematics
Bibliography

The Main Menu:

The main menu controls nearly all the program operations; files can be opened and saved, help can be requested, and the results can be sent to the printer. For sisim there are nine items on the main menu: Project, Packages, Simulator, Network, Run, Statistics, View, Log, and Help (Figure 14.1). Project controls project handling (opening, saving), and allows the user to quit the application. Data is used to view and select the X-Y-Z-indicator data file. Packages allows the user to open, save, or create the data files needed for sisim3d. Simulator defines the number of simulations, seed values, and output file names. Network is used to specify which computers in the network will participate in solving the models. Run creates required files, executes sisim3d on appropriate computers, and monitors model completion's. Statistics is used after models have been calculated to evaluate basic statistics about individual simulations or series of simulations. View is used to view individual model simulations or statistical compilations. Log is used to save, print, or view any message information printed in the log/status window. Help gives the user a selection of pop-up help topics. Each menu item is fully described below with all the available options.

(14-1)Figure 14.1

[TOP] [SYNTAX]


Project:

The Project menu options control project file handling, and exiting the program. The options include Open Project, View Project, Save Project, Save as, Save Preferences, Quit, and Quit Without Saving. A project file contains the names of all the files required to run a set of simulations, the number of simulations to be run, the names of the result files, and the names of the computers used to calculate the models.

Open Project:

Project:Open Project generates a pop-up dialog which allows the user to select an existing project file. The dialog functions as the File:Open dialog in Figure 5.2 (Plotgraph - Chapter 5). The default project file name extension, though is "*.prf".

View Project:

Project:View Project pops up a simple screen editor with the last saved version of the opened or saved project file.

Save Project:

Project:Save Project saves the names of the appropriate files and computers, and various simulation parameters to the named project file (See Sisim Output Data File section for file format). If no project file name exists, the user will be queried for a file name. The dialog functions as the File:Open dialog in Figure 5.2, except that the file name does not have to pre-exist. For a description of how to use the dialog, see the File:Save section in Chapter 5.

Save Project as:

Project:Save as is used to save the project to a new file. A pop-up dialog similar to that used in File:Open (Figure 5.2) is created. This option is the same as Project:Save Project except that a project file name must be selected.

Quit:

File:Quit terminates the program, but if additions have been made to the project or any project sub-files, the user will first be queried to supply a file to save the changes in.

Quit Without Saving:

File:Quit Without Saving terminates the program regardless of any additions to the project. Once pressed there is no option to change your mind.

[TOP] [SYNTAX]


Packages:

To run sisim3d, several data files or packages are required. Some of these can be created with the sisim interface, but all must be loaded or defined so that sisim can correctly task out and run the simulations (Sisim executes sisim3d). There are five required files. They include the 1), configuration, 2) data, 3) geometry, 4) semivariogram, and 5) soft data uncertainty files. These are each described below. Note, unless all these files are defined, no simulations can be run.

Configuration:

The configuration file specifies several limiting characteristics about the simulation calculation. Features present in the data set can be temporarily turned off for testing or debugging.

Open Configuration:

Packages:Configuration:Open Geometry generates a pop-up dialog which allows the user to select and existing configuration file. The dialog functions as the File:Open dialog in Figure 5.2 (Plotgraph - Chapter 5). The default project file name extension, though is "*.set".

View Configuration:

Packages:Configuration:View Geometry pops up a simple screen editor with the last saved version of the opened or saved geometry file.

Save:

Packages:Configuration:Save saves the current configuration parameter specifications to the configuration file (See Sisim Input Data File section for file format). If no geometry file name exists, the user will be queried for a file name. The dialog functions as the File:Open dialog in Figure 5.2, except that the file name does not have to pre-exist. For a description of how to use the dialog, see the File:Save section in Chapter 5.

Save as:

Packages:Configuration:Save as is used to save the geometry to a new file. A pop-up dialog similar to that used in File:Open (Figure 5.2) is created. This option is the same as Project:Save Project except that a project file name must be selected.

Modify:

Packages:Configuration:Modify generates the pop-up dialog shown in Figure 14.2. This dialog allows the user to define several things about what data is treated in the simulation. These generally effect the speed with which the simulation will run. The options can also be set, so that the simulation will ignore certain data. This saves having to build new data sets. The Grid Dimension can be either 2D or 3D. Hard Data Only can be used; if the data set includes soft data, it will be ignored. No Type B Data is in the data set. If this is set, it will improve the efficiency of some calculations. Coarse Simulation Only allows only the first pass of the simulation to be run. Sisim3d normally uses two passes to create a simulation grid. One pass makes a coarse grid, and the second pass makes a finer grid using the results from the first pass. Often it is worth running the coarse grid only on the first simulation. This allows the user to fine basic logic errors, without having to wait for a full simulation to complete.

(14-2)Figure 14.2

Data:

The input file containing the X, Y, Z, and indicator data must be read in before any other operations can be done (Project files can be opened, because they open a data file). This is because other portions of the program depend on the extents of the data set.

NOTE: There is currently no way within sisim to edit the data file.

Select Data File:

Packages:Data:Select Data File generates a pop-up dialog which allows the user to select and existing data file. The dialog functions as the File:Open dialog in Figure 5.2 (Plotgraph - Chapter 5). The default project file name extension, though is "*.dat".

View Data File:

Packages:Data:View Data File pops up a simple screen editor with the last saved version of the opened data file.

Geometry:

The geometry file in sisim3d specifies details about the model grid, and how search parameters for finding data points near the location being evaluated. The following options allow the user to load and edit an existing geometry file or create a new file.

Open Geometry:

Packages;Geometry:Open Geometry generates a pop-up dialog which allows the user to select and existing geometry file. The dialog functions as the File:Open dialog in Figure 5.2 (Plotgraph - Chapter 5). The default project file name extension, though is "*.geom".

View Geometry:

Packages;Geometry:View Geometry pops up a simple screen editor with the last saved version of the opened or saved geometry file.

Save:

Packages;Geometry:Save saves the current geometry parameter specifications to the geometry file (See Sisim Input Data File section for file format). If no geometry file name exists, the user will be queried for a file name. The dialog functions as the File:Open dialog in Figure 5.2, except that the file name does not have to pre-exist. For a description of how to use the dialog, see the File:Save section in Chapter 5.

Save as:

Packages;Geometry:Save as is used to save the geometry to a new file. A pop-up dialog similar to that used in File:Open (Figure 5.2) is created. This option is the same as Project:Save Project except that a project file name must be selected.

Modify:

Packages;Geometry:Modify generates the pop-up dialog shown in Figure 14.3. This dialog is used to specify all of the parameters needed for the model geometry, and the search parameters required to locate appropriate data points when evaluating a location. Parameters that need to be defined are: (1) the X, Y, and Z coordinates model grid Origin; (2) the size of each node (Delta X, Y, Z), coarse and fine;

(14-3)Figure 14.3

NOTE: The dimensions of the coarse grid, must be an integer multiple of the fine grid. The coarse grid is used on the first pass, the fine grid uses the coarse grid when calculating the fine and final simulation grid.

(3) the number of Nodes in each direction; (4) which nodes will be evaluated during this simulation (From-To -- this option is used to debug sub-regions of the model); (5) the shape and size of the search ellipsoid (data points within the search ellipsoid around the node being evaluated will be used); and (6) details about the search direction rotation. Details about the extents of the data set are also provided.

The Direction Cosine's and the Rotation Flag define the orientation of the search ellipsoid, and are important to define when the semivariogram models are not isotropic. Under isotropic conditions the Direction Cosine matrix is an identity matrix (1's on the diagonal, 0's elsewhere), and the No rotation Rotation Flag is used. For two-dimensional and some three-dimensional data sets it may be adequate to do a rotation about a single axis; with more complicated models though it may be necessary to perform a General rotation about all three axes. The values for the Direction Cosine matrix can be calculated by pressing the Calculate Direction Cosine button. This will create the pop- up dialog shown in Figure 14.4. Rotation angles should be entered in degrees. You can also enter the direction cosine values directly. Depending on the Rotation Flag, they are based on the following matrix's (Foley et al, 1990):

(14-4)Figure 14.4

No rotation - identity matrix (14-1) (14-1)

Rotation around X-axis (14-2) (14-2)

Rotation around Y-axis (14-3) (14-3)

Rotation around Y-axis (14-4) (14-4)

General rotation

(14-5) (14-5)

NOTE: More complicated the rotation matrix's add significantly to the model solution time.

Semivariogram:

With sisim there are two methods of defining the model semivariograms, Single and Latin-Hypercube Solutions. Single is the most common approach. Latin-Hypercube Solutions are used only when the threshold or indicator semivariograms have been calculated using the jackknifing option in vario (Chapter 8) and the latin-hypercube sampling option in variofit (Chapter 9). This option, on a practical basis is only applied when there is very little hard and soft data.

NOTE & WARNING: Normally, the term indicator semivariogram is used define a semivariogram that was based on one cutoff between two indicators. For the remainder of this chapter, these models will be refered to as threshold semivariograms. The use of the term indicator semivariogram will be reserved for semivariogram models that were based a single indicator vs. all other indicators. Functionally, the threshold semivariogram only uses a high cut-off and an indicator semivariogram uses a high and a low cutoff.

When using indicator semivariograms there will be the same number of indicators as semivariogram models. When using threshold semivariograms there will be one less semivariogram model then the number of indicators.

Single:

Packages:Single model semivariograms and needed for each threshold/indicator in the indicator model, and there are one fewer thresholds than indicators. This section allows the user to open, save, and edit the sisim3d semivariogram file. Note that one file contains all of the threshold model semivariogram definitions.

Open Semivariogram:

Semivariogram:Single:Open Semivariogram generates a pop-up dialog which allows the user to select and existing semivariogram file. The dialog functions as the File:Open dialog in Figure 5.2 (Plotgraph - Chapter 5). The default project file name extension, though is "*.var".

View Semivariogram:

Packages:Semivariogram:Single:View Semivariogram pops up a simple screen editor with the last saved version of the opened or saved semivariogram file.

Save:

Packages:Semivariogram:Single:Save saves the current semivariogram parameter specifications to the semivariogram file (See Sisim Input Data File section for file format). If no semivariogram file name exists, the user will be queried for a file name. The dialog functions as the File:Open dialog in Figure 5.2, except that the file name does not have to pre-exist. For a description of how to use the dialog, see the File:Save section in Chapter 5.

Save as:

Packages:Semivariogram:Single:Save as is used to save the semivariogram to a new file. A pop-up dialog similar to that used in File:Open (Figure 5.2) is created. This option is the same as Project:Save Project except that a project file name must be selected.

Modify:

Packages:Semivariogram:Single:Modify first generates the pop-up dialog shown in Figure 14.5. This dialog allows the user to define the Solution Type (Threshold, the must commonly used, or Indicator), the Number of Thresholds/Indicators that will be used in the simulation and therefore the number of required semivariogram models. It also allows the user to specify which Threshold Semivariogram is to be edited. Under the Cumulative Distribution Function the Threshold cutoff (values less then this threshold and greater than lesser thresholds will be evaluated with this semivariogram model) and the Prior cdf (cumulative distribution function) must be defined. The Prior cdf represents the decimal percent of the data set with values less than the cutoff (histo (Chapter 6) can be used to calculate these values). The semivariogram model definition allows up to four nested structures (sisim3d allows more, and the data file can be edited independently, but it is felt that more than this many structures is unrealistic, except in the most unusual circumstances). For each structure, Range, Sill, Semivariogram Model, and X, Y, and Z Anisotropy's must be defined. The model Nugget must also be defined, and if a Power model is used, C Maximum must be defined. The model specifications are aligned vertically from left to right (1, 2, 3, 4). Note, if higher order nests are not used, be sure to mark None for the Semivariogram Model type.

(14-5)Figure 14.5

When calculating the anisotropy's assume the major semivariogram model axis is the X-axis, and the Y or Z-axis is the minor axis. The X anisotropy's will then be 1.0, and the Y and Z anisotropy's will be the X anisotropy divided by the Y or Z anisotropy (With this approach, anisotropy's will be greater or equal to 1.0). Using this approach, the model semivariogram must also be rotated accordingly. The Direction Cosine matrix should be defined using equations 14-1, 14-2, 14-3, 14-4 and 14-5 or the dialog shown in Figure 14.4.

Latin-Hypercube Solutions:

When there is not enough data to adequately define a model semivariogram, latin-hypercube sampling can be used to define a range of reasonable model semivariograms (See variofit Mathematics section, Chapter 9). Simulations can then be run on each model semivariogram for each threshold.

NOTE: If latin-hypercube semivariogram models are used for one threshold, they must be used for all thresholds. A latin-hypercube series of model semivariograms, however can be made up of a single model semivariogram (i.e., for that threshold, there is negligible uncertainty).

Because of the complexity of this data set, it is best to let variofit (Chapter 9) build the data file. Refer to Chapter 9 for the data file format if interested.

Open Semivariograms:

Packages:Semivariogram:Latin-Hypercube Solutions:Open Semivariogram generates a pop-up dialog which allows the user to select and existing latin-hypercube semivariograms file. The dialog functions as the File:Open dialog in Figure 5.2 (Plotgraph - Chapter 5). The default project file name extension, though is "*.lhc".

View Semivariograms:

Packages:Semivariogram:Latin-Hypercube Solutions:View Semivariogram pops up a simple screen editor with the last saved version of the opened or saved latin- hypercube semivariograms file.

Uncertainty:

The uncertainty file describes the probability distributions for the soft data. Even if no soft data is used still file is required, though it is very simple.

NOTE: There is currently no way within sisim to create or edit the uncertainty file.

Select Uncertainty File:

Packages:Uncertainty:Select Uncertainty File generates a pop-up dialog which allows the user to select and existing uncertainty file. The dialog functions as the File:Open dialog in Figure 5.2 (Plotgraph - Chapter 5). The default project file name extension, though is "*.dat".

View Uncertainty File:

Packages:Uncertainty:View Uncertainty File pops up a simple screen editor with the last saved version of the opened data file.

[TOP] [SYNTAX]


Simulator:

Simulator:Modify generates the pop-up dialog shown in Figure 14.6. This dialog used to specify parameter related to the number of model simulation calculated, the destination file name, and the random number used to start each simulation. The starting Random Number Seed is used for defining the path through the model grid and making random picks from the cdf to determine a node value. The seed is incremented by a constant amount (Seed Increment) for each simulation.

(14-6)Figure 14.6

WARNING: If the Seed Increment is zero, every simulation will be identical!

If a Starting Simulation Number other than 1 is used, the Random Number Seed will be incremented accordingly. This allows simulations to be rerun individually without having the user calculate the appropriate seed. After the simulations are run, the simulation results will be saved to files based on the Output File Name selected here. If "example.junk" is specified, for 5 simulations, starting at simulation 5. The output files would be named:

	Coarse Grid			Fine Grid
	example.junk.cor.5.sim		example.junk.5.sim
	example.junk.cor.6.sim		example.junk.6.sim
	example.junk.cor.7.sim		example.junk.7.sim
	example.junk.cor.8.sim		example.junk.8.sim
	example.junk.cor.9.sim		example.junk.9.sim

These files are saved in NODE CENTERED GRID format (See Chapter 11, Data File Format section).

[TOP] [SYNTAX]


Network:

Sisim is designed to work in a stand-alone networked environment. Because of the number of simulations computed, even though each one is fairly fast, it can take a long time to complete all of the simulations. Were resources permit, it may be better to distribute the processes over a number of different machines (parallelize). This uses up the computational resources of more computers, but it gets the job done faster. Depending on the site, these jobs can be timed to run during low use periods to reduce the impact to other users (They are automatically set to run at the lowest priority). At many locations, though, jobs will have to be run only on the machine currently being used (there is no network; you don't have the rights, privileges, or priority to use other computers).

NOTE & WARNING: To run programs over the network, in the users login directory, there must be a .netrc file on each computer used. This file is a list of computer names, and the user name, and the user password for each computer. This file allows the user to remotely run processes on other computers in the list. Also note, this file has the user password spelled out; it is not encrypted! Make sure that file protections are set for this file so that only the user can read it! Also note, anyone with root privilege can read this file regardless of the privileges!

Mode:

Network:Mode allows the user to select between Single computer mode (no network connection required) or between Multiple networked computer mode.

Select Computer List:

Network:Select Computer List generates a pop-up dialog which allows the user to select and existing file which specifies what computers are available to be used. This list does not specify that any of the listed computers will be used. The dialog functions as the File:Open dialog in Figure 5.2 (Plotgraph - Chapter 5). The default project file name extension, though is "*.net".

View Computer List:

Network:View Computer List pops up a simple screen editor with the last opened version of the computer list file.

Select Computers:

Network:Select Computers generates the pop-up dialog shown in Figure 14.7. This option is only valid when sisim is in the Multiple Mode. This shows a list of the computers available for use (The list comes from the loaded *.net file. It is the user's responsibility to insure this file is correct). By default no computers are used. Select the computers which are available. All computers on the list can be marked, but there are several thing to keep in mind:

1). Each selected computer is a client. The computer running sisim and managing the other computers, is the server. The computer running sisim can also be selected to run sisim3d processes, in which case it is also a client.
2). If only a few simulations are required, you might want to use only the fastest machines.
3). If other people are using a given computer, if possible it should be avoided.

(14-7)Figure 14.7

When using other computers, consider your job priority versus that of other user's!

[TOP] [SYNTAX]


Run:

Run:Now will start the simulation process. The dialog in Figure 14.8 will be displayed while any simulation is still being executed. To stop the simulations, press the Stop Remaining Simulations button. When all the simulations are complete, the dialog will disappear. During the simulation process, a number of things occur, these are listed below:

(14-8)Figure 14.8

[TOP] [SYNTAX]


Statistics:

After one simulation is complete, or after all the simulations are complete, it may be useful to examine statistically simulation results; i.e. what is the distribution of indicators for an entire simulation, or what is the probability a particular cell will be occupied with a particular indicator.

Model Summary:

Model Summary is used to determine the distribution frequency, and frequency variance and standard deviation for each indicator in a single simulation, or in all on the simulations.

Individual Simulation:

Statistics:Model Summary:Individual Simulation will generate the pop-up dialog in Figure 14.9. This dialog will allow the user to specify which simulation series is of concern and which simulation in the series will be evaluated. The statistics when calculated (Press View Statistics) will be display in a pop-up dialog similar to Figure 14.10. The statistics can also be echoed to the log/status window if the Print Statistics to Log/Status Window toggle is set. In this dialog, for each indicator, the cell count and frequency of occurrence is displayed. The cumulative count and frequency, mean, median, and mode are also displayed.

(14-9)Figure 14.9

(14-10)Figure 14.10

All Simulations:

Statistics:Model Summary:All Simulation will generate the pop-up dialog in Figure 14.11. This dialog will allow the user to specify which simulation series is of concern, the output file name prefix, and which simulations (from-to) in the series will be evaluated. The statistics when calculated (Press Calculate Map & View Statistics) will be display in a pop-up dialog similar to Figure 14.12. The statistics can also be echoed to the log/status window if the Print Statistics to Log/Status Window toggle is set. In this dialog, for each indicator, the frequency of occurrence, variance, and standard deviation is displayed. The cumulative frequency, mean, median, and mode are also displayed. Calculated and created with the statistics, are several maps. The Probability Map Files specify the calculated probability that the given indicator will be present in each cell (Figures 14.13a, 14.13b, and 14.13c). The Certainty Map File indicates the maximum probability of occurrence of any indicator at every cell location (Figure 14.14). This map highlights zones of good and poor data control. It, however cannot be used to identify what indicator is present. The final map created is the Best-Guess Map. This map will determine which indicator is the most probable at each cell location, and assign the appropriate indicator value (Figure 14.15). If enough simulations were run, this map should appear nearly identical to an indicator kriged map which always selected the best-guess (0.50) cdf indicator.

(14-11)Figure 14.11

(14-12)Figure 14.12

(14-13a)Figure 14.13a, (14-13b)Figure 14.13b and (14-13c)Figure 14.13c

(14-14)Figure 14.14

(14-15)Figure 14.15

[TOP] [SYNTAX]


View:

View:Map generates the pop-up dialog shown in Figure 14.16. This dialog allows the user to view individual simulation results. The simulation series name and the simulation number must be specified. Pressing the Block Map will pass the desired simulation to block (Chapter 13). Individual simulation examples are shown in Figures 14.17a and 14.17b.

(14-16)Figure 14.16

(14-17a)Figure 14.17a and (14-17b)Figure 14.17b

[TOP] [SYNTAX]


Log:

The Log menu option is supplied to allow the user to save, view, or print all text which has been written to the log/status window by the program or added by the user (The log window is also a simple text editor). The options include View Log, Save, Save as, and Print. View Log, Save, and Save as are similar in operation to the menu options under File described above.

[TOP] [SYNTAX]


Help:

Help lists topics about the program for which there is help. When a item is selected a pop-up dialog with a scrolled text area is generated which is similar to Figure 5.15 with the desired information.

NOTE: Only one help window may be open at a time. Help files are editable ASCII data files; for further information see Appendix D.

[TOP] [SYNTAX]

Example of Using Sisim:

An example Sisim and sisim3d model is included in the demo directory. There is one project file, three.prj. This projects was used to create the maps shown in Figures 14.13, 14.14, 14.15, 14.16 and 14.17.

To run the correct or actual solution, run sisim, and load the project file three.prj (Use the Project:Open Project menu-bar option). Opening the project will load several files into the application. These files are display in the log/status window and are also listed below:

	three.dat	: DATA PACKAGE
	three.geom	: GEOMETRY PACKAGE
	three.var	: SEMIVARIOGRAM PACKAGE
	three.set	: CONFIGURATION PACKAGE
	three.unc	: UNCERTAINTY PACKAGE

Next, pop-up the Simulator:Modify dialog (Figure 14.6). The maps shown were based on 100 simulations, but those runs took several hours. Just select three simulations. Everything else in the dialog can stay the same. Even these three simulations will take some time. To speed the process, we can just run the coarse simulations. To go this, bring up the Packages:Configuration:Modify dialog (Figure 14.2), and Set Coarse Simulation Only to TRUE. Next, save the file to a new file (Packages:Configuration:Save as). Any file name will do; junk.set would be good.

At this point, everything is set to run in single computer mode. To execute sisim3d with these modules, select the Run:Now menu-bar option. Sisim will determine what files are needed, and tell the UNIX operating system to execute sisim3d. In the log/status lots of messages will be printed regarding the status of the simulation executions. Eventually, the follow message will appear:

All Simulations Complete.

Once Sisim is complete, statistics and maps for each simulation and all simulations can be created. To view the statistics for an individual simulation, select the Statistics:Model Summary:Individual Simulation option. A dialog similar to Figure 14.9 will be created. Set the Series prefix to junk.cor (We only ran the coarse portion of the simulation). When the View Statistics button is pressed, another dialog will appear (Figure 14.10). This dialog summarizes the statistics for simulation one (or which ever one was selected). To view the statistics for all three simulations, select the Statistics:Model Summary:All Simulations option. A dialog similar to Figure 14.11 will be created. Set the Last Simulation to 3, and press the Calculate button at the bottom of the dialog. The summary statistics will be displayed in a new dialog (Figure 14.12). To examine the Probability, Certainty, or Best-Guess Map, you just need to press the Block, Contour or Surface buttons. These will start the appropriate program with the appropriate file. To view an individual simulation, select the desired simulation number from the View:Map dialog (Figure 14.16).

[TOP]


Running From the Command Line:

In many cases it is more convenient to run the application completely from the command line, or at least pass some parameter values in from the command line. The options listed below allow the user to accomplish almost anything that is possible from within the X-windows application from the command line (adding lines from different files is not currently supported). This feature can be useful when the user does not have a X-windows/Motif terminal available, or when many models need to be processed quickly, and the operation can be completed in batch mode without user interaction.

Syntax: sisim [project file]

NOTE: Parameters in [] brackets are optional.

[TOP]


Command Line Options for Running ISIM3D:

Sisim3d can be run by sisim or it can be run separately; it is a independent program. Sisim executes sisim3d using UNIX system calls and passes input parameters on the command line (sisim and sisim3d also communicate using socket protocols). The command line options available are:

Syntax:

sisim3d [-client " "] [-cou " "] [-data " "] [-dbg " "] [-geom " "] [-help] [-out " "] [-seed #] [-serv #] [-set " "] [-sim #] [-unc " "] [-var " "]

Meaning of flag symbols:

# = integer
#.# = float
" " = character string.

NOTES:

1). All parameters in [] brackets are optional.
2). Quotes must be used around character strings.

If no entry is required for flag, flag command executed.

Flag Definitions:

-client = hostname of computer running sisim3d default = " "
-cou = coarse simulation file default = "sisim3d.cou"
-data = X-Y-Z-indicator data file default = "sisim3d.dat"
-geom = debug file default = "sisim3d.dbg"
-geom = geometry file default = "sisim3d.geom"
-help = give this help menu
-out = output file default = "sisim3d.out"
-seed = simulation random seed default = "-1"
-serv = specifies server type default = 0
0
1
2
=
=
=
no inter-client communication
internet protocol (local sisim)
internet protocol (remote sisim)
-set = configuration setup file default = "sisim3d.set"
-sim = simulation number default = 1
-unc = soft data uncertainty file default = "sisim3d.unc"
-var = semivariogram file default = "sisim3d.var"
[TOP]

Sisim Input Data Files:

There are eight data file type used by sisim and sisim3d (Gómez-Hernández and Srivastava, 1990, and McKenna, 1994) for data input. These are project, configuration, data, geometry, semivariogram, latin-hypercube semivariograms, uncertainty, and computer list. The configuration, data, geometry, semivariogram, and uncertainty file formats are specified by sisim3d. Each file format is described below.

Project Files:

The project tells sisim what file need to be loaded for input, what file names will be for output, the seed, the seed increment, the starting simulation number, the number of simulations that will be run, and the list of computers that will be used for the model calculations. The format is specified below:

configuration file name
hard conditioning data file name
geometry file name
semivariogram file name
uncertainty file name
latin-hypercube semivariogram file name (NA if not used)
debug file name
simulation output file name prefix
computer list file name
seed
seed increment
starting simulation number
number of simulations
list of computers used (one name per line)

An example file is three.prj.

Configuration Files (sisim3d):

The configuration file specifies information about the grid dimensions, what type of data will be used, and whether both the fine and coarse simulation grids will be made. The format is specified below:

record 1:
Rotation (0 = some rotation type, 1 = no rotation)
record 2:
Model Dimension (0 = 3D, 1 = 2D)
record 3:
Soft Data (0 = Yes, 1 = None)
record 4:
Grid Calculation (0 = Coarse & Fine, 1 = Coarse Only)
record 5:
Type B Data (0 = Yes, 1 = None)

Data Files (sisim3d):

The data file specifies the number of hard conditioning data points, and the X, Y, and Z coordinate, and value for each conditioning point. This is a standard sisim3d data file. The format is specified below (This is the file format given in sisim3d's smain22.c program module):

record 1:
ndata, number of hard conditioning data
record 2:
to record ndata+1: x, y, z, value, coordinates and value of each conditioning data.

An example file is sisim3d.dat.

Geometry Files (sisim3d):

The geometry file contains the following information in the format specified below (This is the file format given in sisim3d's main.c program module):

record 1:
delta.x, delta.y, delta.z, spacing in the x,y,z directions of the simulation grid (in units of length)
record 2:
coarse_delta.x, coarse_delta.y, coarse_delta.z spacing of that he simulation over the coarse grid, it has to be a multiple integer of the spacing over the final grid (in units of length)
record 3:
origin.x, origin.y, origin.z, coordinates of simulation grid (the center of the front left (SW) bottom cell) point (1,1,1) (in units of length)
record 4:
n_nodes.x, n_nodes.y, n_nodes.z, the number of nodes in the x,y,z directions of the simulation grid (adimensional)

NOTE:

for debugging and testing purposes, it is useful to be able to limit the simulation to some particular sub- area of the entire grid. The following parameters specify a rectangular area for the actual simulation. If a complete simulation is required, then from(x,y,z) should be set to 1 and to(x,y,z) to the total number of nodes.

record 5:

from.x, from.y, from.z, x,y and z indices of the beginning of the simulation sub-area (adimensional)
record 6:
to.x, to.y, to.z, x,y,z indices of the end of the simulation sub-area (adimensional)
record 7:
radius.x, radius.y, radius.z, search ellipsoid radii. Special care should be taken in setting these radii since the speed of the search will be dependent on the number of cells contained within the ellipsoid. Also the memory required is proportional to to the product of the three radii. (in units of length)
record 8:
coarse_radius.x,coarse_radius.y,coarse_radius.z, search ellipsoid radii for the coarse simulation. By setting a coarse grid spacing large enough, a large search radius can be used over the coarse grid without containing a disordinate number of cells. (in units of length)
record 9, 10, and 11:
direction cosines of the rectangular system of search axes.Same for all structures and all variograms. (adimensional)
record 12:
rotation, flag indicating a particular case of the rotation matrix, this record is the result of the procastination of the author who could have written a small routine to find out with respect to which axis is the rotation of the search ellipsoid. In any case, this value is required to optimize the storage of the information associated with the search.

rotation = 0, (no rotation; identity matrix)
rotation = 1, (rotation around the x axis)
rotation = 2, (rotation around the y axis)
rotation = 3, (rotation around the z axis)
rotation = 4, (general rotation)

record 13:

orig_max_per_octant_1, new_max_per_octant, octant_percent, orig_max_per_octant_2 and new_max_per_octant_2, maximum number of original hard data points and other conditioning points per octant to be retained for kriging, the percent completion at which to switch from the 1 flags to the 2 flags.
record 14:
kriging flags, 1st one is for the first part of the simulation (up tp krig_percent completion), 2nd one is for the remainder of the simulation. 0 = SK, 1 = OK. Krig_percent, percentage completion at which to switch from flag1 to flag2.
record 15:
Maximum and minimum weight to be applied to the global prior cdf in the estimation of the local posterior cdfs and the maximum number of points found in the search neighborhood for which the prior global cdf will be used as the local posterior cdf. Standard simulation practice would set all three variables to zero.
record 16:
ok flag, dbg, the ok flag specifies the number of data points necessary within the search neighborhood to use ordinary kriging (assuming record 14 is set to 1), the debugging flag is generally set to 0, if set to 3 or higher, a _large_ amount of information is output, this option should be used only if the simulation subarea is very small. (adimensional)

An example file is three.geom.

Semivariogram Files (sisim3d):

The semivariogram file specifies the parameters for each semivariogram at each threshold. This is a standard sisim3d semivariogram file. The format is specified below (This is the file format given in sisim3d's main.c program module):

record 0:
model_type, 0 = THRESHOLD MODEL: semivariogram model based on threshold between indicators (standard method); 1 = INDICATOR MODEL: semivariogram model based on indicator distribution.
record 1:
nind, and prior cdf flag, the number of thresholds (equal to the number of discretization classes minus one) (adimensional) and the flag indicating which variable soft or hard is used as the true cdf in the cokriging. A "0" means the prior cdf differences at each threshold are given as "hard cdf - soft cdf", a "1" means "soft cdf - hard cdf". "0" assumes the hard data cdf is the best estimate of the true cdf and "1" assumes the soft data cdf is closer to the true estimate.

NOTE:

the different variograms for each indicator variable are input in order starting with the indicator corresponding to the smaller threshold.

record 2:

threshold value associated with first indicator variable and the differences in the hard and soft cdf at this threshold calculated according to the flag in record 1.
record 3:
prior cdf and difference between the primary and secondary variable cdf the prior cdf is used in case that simple kriging estimation is required, or if OK is used and no data points are found in the search neighborhood.
record 4:
nugget, of the indicator variogram
record 5:
cmax, an upper bound of the maximum value that the variogram can reach within the limits of the search neighborhood. To be used with power variograms only, although a value must be input for all variogram models
record 6:
num_struct, number of nested structures in the variogram
record 7:
type, of each nested structure

1: spherical
2: exponential
3: gaussian
4: power

record 8:

sill, of each structure (scaling coefficient for the power model)
record 9:
, range of each structure (power for the power model) (in units of length)

NOTE:

it is assumed that all the nested structures have the same axes of anisotropy although they can have different anisotropy ratios. The anisotropy ratio is the value that multiplied by the range in that direction gives the range input in record 8.

record 10:

anis.x, anisotropy ratio of each structure in the x direction after rotation of the cartesian axes (adimensional)
record 11:
anis.y,anisotropy ratio of each structure in the y direction after rotation of the cartesian axes
record 12:
anis.z,anisotropy ratio of each structure in the z direction after rotation of the cartesian axes
record 13,14,15:
direction cosines of the rectangular system of anisotropy axes.

records 2 to 15 are repeated for each of the remaining indicator variables.

An example file is three.var.

Uncertainty Files (sisim3d):

The uncertainty file specifies the probability distributions for the soft data (This is the file format given in sisim3d's main.c program module):

record 1:
num_A, the number of different sets of p1 and p2 values
record 2:
num_C, the number of different prior pdfs entered (record 1 and 2 are both on the first line)
record 3:
type A data index (can range from 2 to +infinity)
record 4
thru 10: each record holds the p1 and p2 values for that type A set (records 3 thru 10 are repeated num_A times) (may not have to input all the way to record 10, only up to nind-1)
record 11:
the type C data index (range from -2 to -infinity)
record 12
thru 18: each record holds the prior pdf value for that thresh.

(records 11 thru 18 are repeated num_C times)

An example file is three.unc.

Latin-Hypercube Semivariogram Files:

Refer to the variofit Output Data File Format section in Chapter 9.

An example file is well.aniso.4.lhc.

Computer List Files:

The computer file list, is simply a list of the internet names of computers available for use. The full internet name can be used, or if it is a local machine, only the local name is required (e.g. pikes.mines.colorado.edu equals pikes in a local network). The file format is simply a list of the computer name, with one name per line. An example file is computer.net.

.netrc:

The .netrc file is a UNIX system which allows a user application to run processes on remote computers. This file must be on each computer used in the user's login directory. This file is a list of computer names, and the user name, and the user password for each computer. The file format is:

machine computer name login user name password user password

One entry is needed for every computer. An example file might look like:

machine amazon login wwingle password mypasswd
machine bierstadt login wwingle password mypasswd
machine castle login wwingle password mypasswd
machine orlo login wwingle password mypasswd
machine pikes login wwingle password mypasswd

WARNING: This file has the user password spelled out; it is not encrypted! Make sure that file protections are set for this file so that only the user can read it! Also note, anyone with root privilege can read this file regardless of the privileges!

[TOP]


Sisim Output Data Files:

There are three output file type used by sisim and sisim3d (Gómez-Hernández and Srivastava, 1990). These are debug, block, and sisim3d output. Each is discussed below.

Debug:

Depending on the debug level set, sisim3d will list out more or less detail about the simulation calculations. The output is in a free format.

Block & sisim3d Output:

Sisim model simulation output is in block format. Refer to the Setting up the Input File-Equal Dimensions section in Chapter 13.

[TOP]


Sisim Mathematics:

Kriging and Indicator Kriging:

Kriging is a statistical estimation technique used to assign property values at locations where no data exists (where data exists it is exactly honored). The theory of kriging will not be discussed here, but the refinement of theory used in indicator, and Bayesian kriging will be discussed.

Once the semivariograms have been developed, the sample data can be indicator kriged or Bayesian kriged at each cutoff. The process of determining the weight of sample values at the point being estimated is identical to that used in ordinary kriging whether blocks or points are being evaluated:

F(gc) = S wii(xi) ; for indicator kriging estimates. (14-6)
Z*(x) = S bixi ; for ordinary kriging estimates. (14-7)

where wi and bi are weights, gc is the global distribution, F(gc) and Z*(x) are kriged estimates, and the summations are from 1 to the number of data points (n). Note that these are basically the same equations except that equation 14-7 is multiplied by the indicator value (0 or 1). To determine the indicator value at the prescribed point, a cumulative distribution function (cdf) is developed. In Figure 14.18, a simple example is shown for defining the cdf for an individual block. In this case, five samples are equally distant from the block (and within the range of influence), and therefore the weights are equal (w1 = w2 = w3 = w4 = w5 = 0.20). Cutoffs were set at 0.02, 0.10, 0.13, and 0.26. Only one point is less than or equal to the first cutoff (0.02) so there is a 20% probability the value at the point is less then 0.02, 40% probability of being less then 0.10, 60% probability of being less then 0.13, and an 80% probability of being less then 0.26.

(14-18)Figure 14.18

From this point several tacks may be taken in evaluating the indicator data based on the cdf; 1) maps can be made defining the best estimate of parameter values (value defined equal the value equal to the 50% probability), 2) maps can define the probability that the value of a parameter is above or below some specified level, 3) maps can define the parameter value above or below given a specified probability, or 4) realization maps can be made where the values are determined by randomly selecting the indicator for each location from the cdf; this last option is a stochastic simulation.

Stochastic Simulation:

There is a distinct difference between ordinary kriging (and most other estimation methods) and Bayesian Kriging with conditional simulation. Most techniques tend to average or smooth the data to achieve a best estimate of conditions between measured points. Conditional simulation provides a means of representing the variability of observed in nature, while still honoring the field data (Figure 14.19). Conditional simulation does not produce a best estimate of reality, rather it yields equiprobable models with characteristics similar to those observed in reality.

(14-19)Figure 14.19

The process of stochastic simulation, described by Gómez-Hernández and Srivastava (1990), takes advantage of cdf's determined by indicator kriging, and Monte- Carlo techniques. To generate an individual realization, or a stochastic simulation, a search grid is selected (Figure 14.20). Starting with the first indicator range (e.g. clay), grid blocks at hard data locations are defined as "1" (clay) or another indicator type (e.g. "2" = sand, "3" = gravel; in kriging calculations these values are treated as "0" if another indicator is being evaluated or as "1" if it is the indicator currently under consideration). At soft data locations, blocks are defined with the aid of a random number generator. A random number between 0.0 and 1.0 is generated. If the value is less than the probability the property exists, the location is defined as the given indicator type; if the random number is greater than the probability, the indicator exists, then the block is defined with an alternate indicator type (for example, if the location has a 70% probability of being clay, 20% sand, and 10% gravel, and a random number of 0.87 is generated, the location is defined as sand, "2"). Because many realizations are created, at this location, clay will be present about 70% of the time, sand 20%, and gravel 10%. When all the hard and soft data are entered, a random starting location within the model grid is selected and the location is kriged based on the indicator cdf and a new random number. The cdf, at this point is based only of the hard and soft data, where the soft data are treated as hard or exact (It has been defined and is now known). If the random number is less then the probability, the indicator value exists, a "1" is assigned (i.e. clay is present at the grid location), otherwise a "0" is defined (another indicator is present). Next, another random grid location for which an indicator has not been defined is considered, and its indicator value is determined based on the hard and soft data, and the previously kriged indicators at other locations (now considered a hard data values for the remainder of the simulation). This process of selecting random grid locations and kriging them, based on the hard, soft, and previously kriged data, is continued until all grid locations are defined and a map of "1's" (clay) and "0's" (not clay) is created. The next indicator range is then selected (sand) and all the locations still containing "0's" are re-kriged (here the cdf is based only on the possibility the parameter value is sand or gravel). This re-kriging process is repeated until all the indicator ranges have been evaluated and the map is composed of all "1's."

(14-20)Figure 14.20

To create another realization, the process is repeated. Soft data locations are re- evaluated, cdf's are calculated, a new random path through the grid is selected and each grid location is re-kriged and simulated. Alternative realizations can be created following this process until the desired number of simulations are created.

Each realization honors the statistics of the original data, and has equal probability of existing. These realizations can be used as maps of parameters for modeling of the site.

[TOP]


Bibliography (sisim):

Foley, J.D., A. Van Dam, S.K. Feiner, and J.F. Hughes, 1990, Computer Graphics, Principles and Practice, Addison-Wesley, Reading, Massachusetts.

Gómez-Hernández, J.J. and R.M. Srivastava, 1990, ISIM3D: An ANSI-C Three Dimensional Multiple Indicator Conditional Simulation Program, Computers in Geoscience, Vol.. 16, No. 4, pp. 395-440.

McKenna, S.A., 1994, Utilization of Soft Data for Uncertainty Reduction in Groundwater Flow and Transport Modeling, Ph.D. Dissertation, Colorado School of Mines.

[TOP]


Table of Contents
Previous Chapter
Beginning of this Chapter
Next Chapter