#######################################################################
#                                                                     #
#                              OCamlP3l                               #
#                                                                     #
#                  projet Estime, INRIA-Rocquencourt                  #
#                                                                     #
#  Copyright 2003-2007 INRIA.                                         #
#  Institut National de Recherche en Informatique et en Automatique.  #
#  All rights reserved. This file is distributed only by permission.  #
#                                                                     #
#  Francois Clement <Francois.Clement@inria.fr>,                      #
#  Pierre Weis <Pierre.Weis@inria.fr>.                                #
#                                                                     #
#######################################################################

$Id: README,v 1.11 2007/01/23 15:58:18 weis Exp $


OVERVIEW

This is the first use of the OCamlP3l system in the field of Computing Science.

The main application consists in solving the 2D Poisson's equation using an
additive Schwarz algorithm (domain decomposition with overlapping and simple
Dirichlet communications). The solver in each subdomain is written in C (see
"poisson.c"). The coupling between the subdomains is written in OCaml and uses
the skeleton-based parallelism capabilities of OCamlP3l (see "coupling.ml").
It also uses the module Rdec for the manipulation of 2D regular rectangular
grids (see "rdec.mli"). 


CONTENTS

README: this file
Makefile:
configure: configure script
poisson.c rdec.mli rdec.ml gnuplot.ml coupling.ml:
     source files for the main application (needs OCamlP3l, gnuplot)
mk_config_files.sh: script to generate configuration files
config* rdec*.cfg: configuration files


USAGE

Type "./configure". This should update the file gnuplot.ml and create the
directory resu for numerical files.
Then type "make seq" (resp. "make par") to compile the sequential
(resp. parallel) version, and type "./coupling.seq" (resp. "./coupling.par") to
run it.

By default, the example uses the configuration files "config" and "rdec.cfg"
(see respectively "coupling.ml" and "rdec.mli" for the content of these files).
To change the size of the example, other configuration files can be generated
by using the script "mk_config_files.sh" (try its -help option).

The output types "window" and "ps" (in "config") needs Gnuplot graphical
capabilities.


TIPS

Here are a few rules of thumb to tune the numerical parameters in the
configuration files (see "rdec.mli" for basic constraints).

Let N (= Nx = Ny) be the total number of grid points in each direction and let
Nsbd (= Nsbdx = Nsbdy) be the number of subdomains in each direction. Then, the
local number of grid points in each direction for the subdomains (without
overlapping) is n (= nx = ny) = N / Nsbd.

Half the overlapping of the subdomains in each direction should be linear with
respect to n, say p (= px = py) = n / 5. Then the average number of grid
points in each direction for the subdomains is n + 2 * p.

The number of local iterations in each subdomain should be linear with respect
to n, say nit = n / 3 * 10, and the number of fix point iterations should be
quadratic with respect to Nsbd, say Nit = (5 * Nsbd - 1) * Nsbd / 2 + 4.

Finally, the overall complexity of the computation, i.e. the total number of
floating point operations (adds and multiplies), is
    C = 9 * (n + 2 * p) ^ 2 * nit * Nsbd ^ 2 * Nit
      = 9 * (n + 2 * n / 5) ^ 2 * n / 3 * 10 * Nsbd ^ 2 * Nit
      = 6 * 49 / 5 * n ^ 3 * Nsbd ^ 2 * Nit
      ~= 6 * 49 / 5 * N ^ 3 / Nsbd * 5 / 2 * Nsbd ^ 2
      = 147 * N ^ 3 * Nsbd.

Always check that the relative error is small enough, e.g. about 1%. This is
mainly driven by the values of Nsbd, p and Nit. And check also that the
relative stagnation is even smaller, e.g. less than 1e-4. This one is mainly
driven by the values of n and nit.


COPYRIGHT

(c) 2003-2005 INRIA (Institut National de Recherche en Informatique et en
Automatique), Estime and Cristal Project-Teams.
