please note that while this is the readme file

for the complete release, only the binaries have

been included in this tar file. to install simply

unzip and untar, disregard the installation instructions

written below. the program descriptions do apply.

to unzip: gunzip shalstab.tar.gz

to untar: tar xvf shalstab.tar



----------- original readme file below -------

this release comes in a compressed tar file,



shalstab.tar.gz



to install, create your shalstab directory,

copy the file in it, unzip it, and untar it:



mkdir shalstab

cp shalstab.tar.gz shalstab

cd shalstab

gunzip shalstab.tar.gz

tar xvf shalstab.tar

rm shalstab.tar



it will create 3 directories: src, lib, inc.

the library and library source code is in

the lib directory, the include files are

all in the inc directory, the main programs

(source and executables) are in the src

directory. object files are in the same

directory as their respective source files.



to rebuild, first cd to the lib directory

and run make, then cd to the src directory

and run make again. executables will be in

the src directory (i didn't make a fancy 

that installs the executables somewhere

else). to build this release i have used 

the gnu c++ compiler, gcc, and the make and

ranlib utilities.



the programs are:



- shalstab



description:

	this is the main program, it does all the steps and can optionally write

	all the intermediate grids. it produces a grid containing the log10(q/t)

	values, except for those cells which contain no data in input, and for

	those cells that have chronic characteristics (where the slope is either

	too steep or too flat) which are labeled with special values (-10 for

	chronically unstable areas, 10 for chronically stable areas). the nodata

	value is -9999 in the arcinfo format, and 1.70141e+38 for the surfer

	format. typical values for the required parameters are shown in the 

	example below. there is a whole validation aspect of this model that is

	not part of this package (it will be in the arcview release), but should

	be taken into consideration.

usage:

        shalstab <elevation grid> <saturation constant> <critical angle> [<sink

	removed grid> <slope grid> <area grid> <format>]

formats:

        0 = arcinfo ascii (default)

        1 = surfer ascii

examples:

        shalstab elev.grd 1700 45 > qovert.grd

        shalstab elev.grd 1700 45 remove.grd slope.grd area.grd > qovert.grd



- removesinks



description:

	a separate implementation of the first step of the shalstab program.

	fills sinks. note that for our implementation of area computation (8

	way distribution, not maximum fall) a sink is defined to be a cell

	with elevation less or equal to all of its neighbours. other sink

	filling routines differ in that a sink is such only if strictly less

	than its neighbours. make sure that things like oceans are not part

	of the input elevation grid, or it will go crazy trying to raise it.

usage:

        removesinks <elevation grid> [<increment> <max. passes> <format>]

defaults:

        elevation increment = 0.1m

        maximum passes = 100

formats:

        0 = arcinfo ascii (default)

        1 = surfer ascii

example:

        removesinks elev.grd > remove.grd



- slope



description:

	a separate implementation of the second step of the shalstab program.

	computes local slope using a 3x3 window. the user can select the type

	of output.

usage:

        slope <elevation grid> [<mode> <format>]

modes:

        0 = theta, radians (default)

        1 = tan(theta), radians

        2 = sin(theta), radians

        3 = cos(theta), radians

        4 = theta, degrees

        5 = tan(theta), degrees

formats:

        0 = arcinfo ascii (default)

        1 = surfer ascii

example:

        slope elev.grd > slope.grd



- area

 

description:

        a separate implementation of the third step of the shalstab program.

	computes drainage area (or A/b), based on an 8 direction distribution

	(proportional to the local slope in each direction). it differs from

	many other programs as it does not hand off all the area in the maximum

	flow direction.

usage:

        area <elevation grid> [<mode> <format>]

modes:

        0 = area/cell size (default)

        1 = area

formats:

        0 = arcinfo ascii (default)

        1 = surfer ascii

example:

        area elev.grd > area.grd



- qovert

 

description:

        a separate implementation of the fourth step of the shalstab program,

	computes the log10(q/t) values based on two parameters, rho (the 

	density of saturated soil in kg/m^3, the algorithm uses the rho ratio

	of soil/water densities with water equal to 1000), and phi (the critical

	angle, in degrees). see the description of the shalstab program for

	further details.

usage:

        qovert <slope grid> <area grid> <saturation constant> <critical angle> [

<format>]

formats:

        0 = arcinfo ascii (default)

        1 = surfer ascii

example:

        qovert slope.grd area.grd 1700 45 > qovert.grd



- curvature:

	like the slope program, only it computes curvature on a 3x3 window,

	based on the standard polynomial representation. for the following

	cell layout:

	abc

	def

	ghi

	curvature at cell 'e' is defined as:

	(2 * (f + d + b + h) + (c + a + g + i) - 12 * e) / (4 * xsize * ysize)

usage:

        curvature <elevation grid> [<format>]

formats:

        0 = arcinfo ascii (default)

        1 = surfer ascii

example:

        curvature elev.grd > curv.grd



there are also a few utilities:



- arc2surf



description:

	converts a grid from arcinfo ascii format to surfer ascii format

usage:

        arc2surf <input grid>

example:

        arc2surf arcinfo.grd > surfer.grd



- surf2arc



description:

	converts a grid from surfer ascii format to arcinfo ascii format

usage:

        surf2arc <input grid>

example:

        surf2arc surfer.grd > arcinfo.grd



- testsinks



description:

	checks a grid for sinks (test only, no filling)

usage:

        testsinks <elevation grid> [<format>]

formats:

        0 = arcinfo ascii (default)

        1 = surfer ascii

example:

        testsinks elev.grd



- mkgrid



description: 

	a grid (arcinfo grids only) making utility, useful for creating

	test grids.

usage: 

	mkgrid <rows> <columns> <cell size> <type> [<values>]

types:

        0 - nodata grid

        1 - constant <value> grid

        2 - <value1> grid, 1 in <value2> prob. of <value3>, <value4> (odd) box

        3 - y = x * <value1> + <value2>

        4 - y = x * x * <value1> + <value2>

        5 - y = x * x * <value1> + x * <value2> + <value3>

        6 - z = (x^2 + y^2)^0.5 * <value1> + <value2>

        7 - z = (x^2 + y^2) * <value1> + <value2>

        8 - z = (x^2 + y^2) * <value1> + (x^2 + y^2)^0.5 * <value2> + <value3>

example:

	mkgrid 10 10 1 1 0 > zero.grd



- mktable



Description: 

	a table (from arcinfo grids only) making utility, very handy to

	corrollate data.

Usage: 

	mktable <control grid> <data grid> [<data grid 2> ...]

Example:

	mktable slides.grd elev.grd slope.grd area.grd qovert.grd > table.out





the next step is to port this code to windows as is,

with the library implemented as a windows dll, so 

that it can be used mainly with surfer, a cheap and

common gis program for pc's. we are also developing

arcview code (in avenue) which in a successive release

will provide a gis environment, a gui, and ready made

tools to display and test the results. future developments

also include a similar version that takes into account

cohesion with a constant soil depth, as well as a more 

complex version that coupled with a soil production /

transport model will take into account a spatially

variable soil depth.

