From cbfce83654679d8d88a34a4ba651cc517c1de314 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?St=C3=A9phane=20Del=20Pino?= <stephane.delpino44@gmail.com>
Date: Wed, 27 Apr 2022 14:19:06 +0200
Subject: [PATCH] Improve example 1 and prepare next section
---
doc/userdoc.org | 104 ++++++++++++++++++++++++++++++------------------
1 file changed, 65 insertions(+), 39 deletions(-)
diff --git a/doc/userdoc.org b/doc/userdoc.org
index 8764d39d9..6e957604c 100644
--- a/doc/userdoc.org
+++ b/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}
- \cos(\theta(\mathbf{x})) & -\sin(\theta(\mathbf{x})) \\
- \sin(\theta(\mathbf{x})) & \cos(\theta(\mathbf{x}))
- \end{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{equation*}
- ~T~ is the vector field $T$ defined by
- $$
- T: \mathbb{R}^2 \to \mathbb{R}^2, \quad\mathbf{x} \mapsto (I+M(\mathbf{x}))\mathbf{x}
- $$
+ \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
--
GitLab