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 gas coupling (erosion)
- rotating table (multidirectional winds)
- map surrections (tectonic processes)


Content
-------

ReSCAL package comprises several programs:
- rescal: ReSCAL main application
- genesis: generation of a 3d cellular space (CSP or raw binary format)
- regenesis: modification of a cellular space
- 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

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 and pthread.
'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 'bench' script:
cd scripts
./bench

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

The environment variable OMP_NUM_THREADS lets you set the number of
OpenMP threads in the computation of the flow. You can get optimal 
speed by setting this variable according to the number of available 
CPU cores.

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


Simulation of an elongating linear dune
---------------------------------------
Type:
cd scripts
./run_linear

By default, the execution does not use a graphical interface. This
may be changed in the 'run_linear' file . To modify the influx,
change the parameter Lambda_I in 'finger.par'. To generate flux data, 
edit the file 'finger.par' by setting:
Use_trace_flux = YES


References
----------

[1] 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).

[2] 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.


