ReSCAL: a Real-Space Cellular Automaton Laboratory
--------------------------------------------------
Copyright (C) 2011


Description
-----------

This is ReSCAL, a cellular automaton modeling tool in real 3d space, 
primarily designed for geomorphology. However we believe it is 
sufficiently generic in its approach to deal with a wide range of 
applications. 
Basically, it simulates asynchronous first-neighbour interactions 
(see the papers in the References section). We refer to Markov 
chains and Poisson processes for the evolution of the physical time.

We also implemented a number of additional mechanisms that are 
relevant in usual geophysical models
- correlations (coupled processes)
- avalanches (granular processes)
- lattice gaz coupling (erosion)
- rotating table (multidirectional winds)
- map surrections (tectonic processes)


Content
-------

ReSCAL package comprises several programs:
- genesis: generation of a 3d cellular space (CSP or raw binary format)
- rescal: ReSCAL main application
- csp2png: PNG image generator from CSP-file
- bin2png: PNG image generator from BIN-file
- cspinfo: CSP metadata reader
- csp2bin: CSP to raw binary conversion tool
- regenesis: modification of a cellular space in raw binary format

Samples are present in the scripts directory, along with Matlab/octave
functions that support CSP format.


Requirements
------------

Needed libraries are glib-2.0, gtk+-2.0, gdk-pixbuf, pthread and gd2.
'genesis.py' uses NumPy, but it is possible to use C version of 
genesis instead.


Getting started
---------------

1) Build all programs by typing
./configure
make

(See also 'INSTALL' file for detailled instructions)

2) Go to the scripts directory and launch the 'run' script:
cd scripts
./run

This will open a window, with no menu, displaying a dunes simulation 
controlled by air flow. Note the initial phase of flow stabilization.

(See rescal command line options to customize display preferences
in the script)

3) Edit the 'run' script and change the value of PAR_FILE:
PAR_FILE="dun_rot.par"
Then launch rescal again:
./run

Now you have a similar execution, with rotations occuring regularly,
as if the wind was rotating. Again the flow needs to be stabilized
after each rotation.

4) Edit a parameter file, change some values and see what happens in 
your model.

For example, you can change the overall size by editing the 'H', 'L', 
'D' parameters in 'dun.par'.
H = heigth (vertical)
L = length (from east to west)
D = depth (from north to south)

Beware that a huge cellular space will slow down the simulation. When 
lattice gaz is enabled, the execution time is expected to vary roughly 
like H*L*D, while the duration of the initial stabilization is 
proportionnal to H*(L^2)*D, by default (and customizable with the 
Init_ncycl parameter).

5) Edit 'cellspace.py' to change the initial cellular space


Advanced usage
--------------

It is possible to select and/or modify any of the predefined models.
So far, this requires to edit some of the sources in python and C 
language. Here we briefly explain how to proceed. Ideally, we assume 
that the user have some notion of programming.

1) Edition of genesis sources

The genesis program is provided in python and C languages. These two
standalone versions are respectively located in 'scripts' and 
'rescal' directories. We suggest to look at 'cellspace.py' first,
as it is straightforward and easy to understand.

Note that for historical reasons, a cellular space is composed of 
vertical plans in the east-west direction. Each plan is a 
concatenation of horizontal lines from left to right. The very first 
cell corresponds to the north-upper-left corner.

When lattice gaz is used, a floor and a ceiling of DUM cells are 
required to prevent gaz particles from escaping the cellular space.

2) Edition of rescal sources

Select a model and its options, like boundary conditions, in 
'defs.h'. 

You may also add new transitions in 'modeles.c'. Basically, the 
syntax looks like

trans(direction, cel1_start, cel2_start, cel1_end, cel2_end, rate)

and you will get an oriented transition [cel1_start, cel2_start] -> 
[cel1_end, cel2_end] occuring at the specified rate.

A list of all transitions will be generated at run-time in 'TRANS.txt'
with the command-line option '-info'.

Feel free to have a look around and play with the existing mechanisms
in 'terre.c' and 'surface.c', or to suggest any improvement you would 
like to see. Obviously, there is still a lot left to do ! (See the 
next section for some plans)

A modified version can be freely distributed provided that you keep 
intact all the notices that refer to the license (See 'COPYING' file).

We would be grateful if you mention the use of this program in a 
related work or publication.


To be done (if we have time)
----------

*) user-friendly interface which makes it possible to modify options 
   and parameters interactively
*) templates of cellular spaces in genesis command-line arguments
*) support for CSP format in genesis.py
*) binary package, with no need to edit the sources in C language
*) comprehensive and complete documentation
*) add more samples for various models


References
----------

[1] On a small scale roughness of the core-mantle boundary
C. Narteau, J.L. Le Mouël, J.P. Poirier, E. Sepulveda and M. Shnirman
Earth and Planetary Science Letters, 191, 49-60 (2001).

[2] Setting the length and time scales of a cellular automaton dune 
model from the analysis of superimposed bedforms
C. Narteau, D. Zhang, O. Rozier and P. Claudin
Journal Geophysical Research, 114, F03006 (2009).

[3] Morphodynamics of barchan and transverse dunes using a cellular 
automaton model
D. Zhang, C. Narteau and O. Rozier
Journal Geophysical Research, 115, F03041 (2010).


========================================================================

ReSCAL 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. It is distributed in the hope that it will be useful, but WITHOUT
ANY WARRANTY WHATSOEVER.

Check the License for details. You should have received a copy of it, along
with the package; see the file 'COPYING'. If not, write to the Free Software
Foundation, Inc., 59 Temple Place - Suite 330, Boston, MA 02111-1307, USA.


