Improve example 1 and prepare next section

doc/userdoc.org

@@ -28,7 +28,7 @@
 
 * Introduction
 
-~pugs~[fn:pugs-def] is a general purpose solver collection designed to
+~pugs~[fn:pugs-def] is a general purpose solver collection built to
 approximate solutions of partial differential equations. It is mainly
 (but not only) designed to deal with hyperbolic problems using
 finite-volume methods.
@@ -42,7 +42,7 @@ assembled together through a high-level language (a DSL[fn:DSL-def]
 close to the mathematics) to build more complex solvers. This approach
 is inspired by the success of [[http://freefem.org][FreeFEM]], which use a similar approach.
 
-Before detailing the leading concepts and choices we have made to
+Before detailing the leading concepts and choices that we have made to
 develop ~pugs~, we give a simple example that should illustrate the
 capabilities of the code.
 
@@ -58,7 +58,7 @@ mesh nodes according to a user defined vector field $T: \mathbb{R}^2
   import writer;
 
   let pi:R, pi = acos(-1);
-  let theta:R^2 -> R, x -> 0.5*pi*(x[0]+1)*(x[0]-1)*(x[1]+1)*(x[1]-1);
+  let theta:R^2 -> R, x -> 0.5*pi*(x[0]*x[0]-1)*(x[1]*x[1]-1);
   let M:R^2 -> R^2x2, x -> (cos(theta(x)), -sin(theta(x)),
                             sin(theta(x)),  cos(theta(x)));
   let T: R^2 -> R^2, x -> x + M(x)*x;
@@ -68,25 +68,31 @@ mesh nodes according to a user defined vector field $T: \mathbb{R}^2
 
   write_mesh(gnuplot_writer("transformed", 0), m);
 #+END_SRC
-The example is quite easy to read:
-- first, some *modules* are loaded: the ~mesh~ module, which contains
-  some mesh manipulation functions. The ~math~ module which provides a
-  set of classical mathematical functions ($\sin$, $\cos$,
-  ...). The ~writer~ module is used to save meshes or discrete functions
-  to files using various formats.
+The example is quite easy to read.
+- First, some *modules* are loaded: the ~mesh~ module, which contains some
+  mesh manipulation functions. The ~math~ module provides a set of
+  classical mathematical functions ($\sin$, $\cos$, ...). The ~writer~
+  module is used to save meshes or discrete functions to files using
+  various formats.
 - The second block of data defines variables of different kind
   - ~pi~ is a real value that is initialized by an approximation of $\pi$.
   - ~theta~ is the real value function $\theta$ defined by
-        $$\theta: \mathbb{R}^2 \to \mathbb{R},\quad\mathbf{x} \mapsto \frac{\pi}{2} (x_0+1)(x_0-1)(x_1+1)(x_1-1) $$
+    \begin{equation*}
+      \theta: \mathbb{R}^2 \to \mathbb{R},\quad\mathbf{x} \mapsto
+      \frac{\pi}{2} (x_0^2-1)(x_1^2-1)
+    \end{equation*}
   - ~M~ is the $\mathbb{R}^{2\times2}$  matrix field $M$ defined by
-        $$M: \mathbb{R}^2 \to \mathbb{R}^{2\times2},\quad\mathbf{x} \mapsto \begin{pmatrix}
+    \begin{equation*}
+      M: \mathbb{R}^2 \to \mathbb{R}^{2\times2},\quad\mathbf{x} \mapsto
+      \begin{pmatrix}
         \cos(\theta(\mathbf{x})) & -\sin(\theta(\mathbf{x}))  \\
         \sin(\theta(\mathbf{x}))  & \cos(\theta(\mathbf{x}))
-     \end{pmatrix}$$
+      \end{pmatrix}
+    \end{equation*}
   - ~T~ is the vector field $T$ defined by
-    $$
+    \begin{equation*}
       T: \mathbb{R}^2 \to \mathbb{R}^2, \quad\mathbf{x} \mapsto (I+M(\mathbf{x}))\mathbf{x}
-    $$
+    \end{equation*}
   - Finally ~m~ is defined as the uniform Cartesian mesh grid of
     $]-1,1[^2$. The last argument: ~(20,20)~ sets the number of cells in
     each direction: $20$.
@@ -95,7 +101,7 @@ The example is quite easy to read:
   variable ~m~, the old one was not modified in the process. It is
   important to already have in mind that the ~pugs~ language *does not
   allow* the modifications of values of *non-basic* types. This is
-  discussed in the section [[basics]].
+  discussed in the section [[variable-types]].
 - Finally, the last block consists in saving the obtained mesh in a
   ~gnuplot~ file. The result is shown on Figure [[fig:intro-example]].
 
@@ -117,31 +123,51 @@ The example is quite easy to read:
 #+ATTR_HTML: :width 300px;
 #+RESULTS: intro-transform-mesh-img
 
-*  Basics<<basics>>
+Even if this first example is very simple, some key aspects can
+already be discussed.
+- There is no predefined constant in ~pugs~. Here a value is provided
+  for ~pi~.
+- There are two kinds of variable in ~pugs~: variables of basic types
+  and variable of high-level types. This two kinds of variable behave
+  almost the same but one must know their differences to understand
+  better the underlying mechanisms and choices that we made. See
+  [[variable-types]] for details.
+- Also, there are two types of function: *user-defined* functions and
+  *builtin* functions. In this example, ~theta~, ~M~ and ~T~ are user-defined
+  functions. All other functions (~cos~, ~cartesian2dMesh~,...) are
+  builtin functions and are generally defined when importing a
+  module. These functions behave similarly, one should refer to
+  [[functions]] for details.
+- The language does not allow low-level manipulations of high-level
+  type variables. This means that for instance, one cannot modify a
+  specific cell value of a piecewise constant function. This allows to
+  write algorithms (within the pugs language) that can be executed in
+  parallel naturally. Observe that the resulting mesh of the previous
+  does not depend on the number of ~MPI~ processes nor on the number of
+  threads used while running ~pugs~.
 
-** Hello world!
+*  Language
+
+** Variables
+
+*** Types<<variable-types>>
+
+**** Basic types
+
+**** High-level types
+
+*** Life time
+
+** Statements
+
+** Functions<<functions>>
+
+*** User-defined functions
+
+*** Builtin functions
 
-*** Python
-#+BEGIN_SRC python :exports both :results output
-  print ("hellow orld!")
-#+END_SRC
 
-*** Pugs
-In this simple example, one defines the function $f:\mathbb{R} \to \mathbb{R}, x \mapsto 2\sin(x)$
-#+NAME: hello-world
-#+BEGIN_SRC pugs :exports both :results output
-  import math;
-  let f: R -> R, x -> 2*sin(x);
-  cout << "Hello world!\n";
-  cout << "f(12) = " <<  f(12) << "\n";
-#+END_SRC
-Then one prints ~Hello world!~ and the evaluation of $f$ at position $12$.
-#+RESULTS: hello-world
-* The end
 
-#+BEGIN_SRC python :exports both :results output
-  print ("hello world!")
-#+END_SRC
 
 [fn:pugs-def] ~pugs~: Parallel Unstructured Grid Solvers
 [fn:MPI-def] ~MPI~: Message Passing Interface