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 four programs:
- genesis: generation of a 3d cellular space (binary format)
- rescal: ReSCAL main application
- bin2png: PNG image generator
- regenesis: modification of a cellular space

Samples are present in the scripts directory.


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

Needed libraries are glib, GTK+2.0, gdk-pixbuf, pthread and gd.
'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) Make a copy of a parameter file, change the value of one parameter, 
and see what happens to 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 
'genesis' directories. We suggest to look at 'cellspace.py' file first,
as it is straightforward and easy to understand.

Note that for historical reasons, a binary 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.

2) Edition of rescal sources

Choose the same model and some predefined 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
*) binary package, with no need to edit the sources in C language
*) structured format of cellular space with meta-data in a header
*) comprehensive and complete documentation


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.


