Skip to content
Snippets Groups Projects
Commit 34e41cbb authored by Stéphane Del Pino's avatar Stéphane Del Pino
Browse files

Improve introduction

parent 381415ad
No related branches found
No related tags found
1 merge request!145git subrepo clone git@gitlab.com:OlMon/org-themes.git packages/org-themes
......@@ -4,13 +4,13 @@
#+PROPERTY: header-args :comments no
#+OPTIONS: timestamp:nil
#+OPTIONS: h:3 num:t toc:3
#+TITLE: Pugs User Manual
#+TITLE: The pugs user manual
#+OPTIONS: author:nil date:nil
#+OPTIONS: tex:t
#+LANGUAGE: en
#+ATTR_LATEX: :width 4cm
#+HTML_HEAD_EXTRA: <style> pre.src-pugs:before { content: 'Pugs'; } </style>
#+HTML_HEAD_EXTRA: <style> pre.src-pugs:before { content: 'pugs'; } </style>
#+LATEX_CLASS_OPTIONS: [10pt]
#+LATEX_HEADER: \usepackage[hmargin=2.5cm,vmargin=1.5cm]{geometry}
......@@ -141,61 +141,192 @@ already be discussed.
** Concepts and design
*** TODO A C++ toolbox driven by a user friendly language
- Why? divide and conquer
- the language is used to assemble the provided C++ tools
- small independent C++ methods are easy to test/validate.
As it was already stated ~pugs~ can be viewed as a collection of
numerical methods or utilities that can be assembled together, using a
user friendly language, to build simulation scenarios.
Utilities are tools that are often used in numerical
simulations. Examples of such utilities are mesh manipulations,
definition of initial conditions, post-processing, error
calculations,...
*** A C++ toolbox driven by a user friendly language
Numerical simulation packages are software of a particular
kind. Generally, in order to run a calculation, one has to define a
set of data and parameters. This can simply be definition of a
discretization parameter such as the mesh size. One can also specify
boundary conditions, equations of state, source terms for a specific
model. Choosing a numerical method or even more setting the model
itself is common in large code.
In ~pugs~, all these "parameters" are set through a
DSL[fn:DSL-def]. Thus, when ~pugs~ is launched, it actually executes the
provided script. A ~C++~ function is associated to each instruction of
the script. The ~C++~ components of ~pugs~ are completely unaware of the
other ones. ~pugs~ interpreter is responsible of data flow between the
components: it manages the data transfer between those ~C++~ components
and ensure that the workflow is properly defined.
**** Why?
In this section we motivate the choice of a language and not of a more
standard approach.
***** Data files are evil
There are lots of reasons not to use data files. By data file, we
refer to a set of options that describe physical models, numerical
methods or their settings.
- Data files are not flexible. This implies in one hand that
application scenarios must be known somehow precisely to reflect
possible options combinations and on the other hand even defining a
specific initial data may require the creation of a new option and
the associated code (in ~C++~ for instance). \\
It is quite common to fix the last point by adding a local
interpreter to evaluate user functions for instance.
- Data files may contain irrelevant information. Actually, it is quite
common to allow to define options that are valid but irrelevant to a
given scenario. This policy can be changed but it is generally not
an easy task and require more work from the user (which can be a
good thing).
- It is quite common that data files become obsolete. An option was
not the right one, or its type depended of a simpler context... This
puts pressure on the user.
- Even worst options meaning can depend on other
options. Unfortunately, it happens quite easily. For instance, a
global option can change implicitly the treatment associated to
another one. This is quite dangerous since writing or reading the
data file requires an important knowledge of the code internals.
- Another major difficulty when dealing with data files is to check
the compatibility of provided options.
***** Embedded "data files" are not a solution
Using directly the general purpose language (~C~, ~C++~, ~Fortran~,...) used
to write the code can be tempting. It has the advantage that no
particular treatment is necessary to build a parser (to read data
files or a script), but it presents several drawbacks.
- The first one is probably that it allows to much freedom. While
defining the model and numerical options, the user has generally
access to the whole code and can change almost everything, even
things that should not be changed.
- Again, easily one can have access to irrelevant options and it
requires a great knowledge of the code to find relevant ones.
- With that regard, defining a simulation properly can be a difficult
task. For instance, in the early developments of ~pugs~ (when it was
just a raw ~C++~ code) it was tricky to change boundary conditions for
coupled physics.
- Another difficulty is related to the fact that code's internal API
is likely to change permanently in a research code. Thus valid
constructions or setting may become rapidly obsolete. In other
words keeping up to date embedded "data file" might be difficult.
- Finally it requires recompilation of pieces of code (which can be
large in some cases) even if one is just changing a simple
parameter.
***** Benefits of a DSL
Actually, an honest analysis cannot conclude that a DSL is the
solution to all problems. However, it offers some advantages.
- First it allows a fine control on what the user can or cannot
performed. In some sense it offers a chosen level of flexibility.
- It allows to structure the code in the sense that new developments
have to be designed not only focusing on the result but also on the
way it should be used (its interactions with the scripting language).
- In the same idea, it provides a framework that should ease the
definition of "do simple things and do it well".
- There are no hidden dependencies between numerical options: the code
is easier to read and it is more difficult to get obsolete (this is
not that true in early development since the language itself and
some concepts are still likely to change).
- The simulation scenario is *defined* by the script, it is the
responsibility of the user in some sense and not to the charge of
the code to check its meaning.
**** ~pugs~ language purpose
~pugs~ language is used to assemble ~C++~ tools which are well
tested. These tools should ideally be small pieces of ~C++~ code that
do one single thing and do it well.
Another purpose of the language is to allow perform high-level
calculations. In other words, the language defines a data flow and
checks that each ~C++~ piece of code is used correctly. Since each piece
of code acts as a pure function (arguments are unchanged by calls),
the context is quite easily checked.
Finally it aims at simplifying the definition of new methods since
common utilities are available directly in simple scipts.
**** TODO The framework (divide and conquer)
- small independent C++ methods
- easy to test/validate
- do simple things the right way
- new numerical method brings a new C++ code: not a patched code.
A previously validated method is unchanged!
- much more difficult to introduce bugs in existing methods
- existing methods performances are a unchanged by new
- existing methods performances are likely to be unchanged by new
developments
- Why not python or any other scripting language?
- provide a language close to the application: a DSL is made for
that
- utilities are not developed again and again:
- safer code
- important code is not polluted by environment instructions (data
initialization, error calculation, post-processing,...)
**** TODO Why not python or any other scripting language?
- provide a language close to the application: a DSL is made for that.
- general purpose languages offer to much freedom: it is not easy to
protect data
- do not deal with the difficulty of parallelism within the
scripting language
- Following the success of ~FreeFEM~
- python is ugly
*** TODO A high-level language
Defining a suitable language
**** TODO Keep it simple
**** Keep it simple
**** TODO Performances and parallelism
**** Performances and parallelism
The language *does not allow* low-level manipulations of high-level type
variables. This means that for instance, one cannot access or modify
specific cell or node value. A consequence of such a choice is that
this *constrained framework* allows to write algorithms (within the pugs
language) that can be executed in parallel naturally. To achieve that,
there should *never* be parallel instructions or instructions that
require *explicit parallel* actions in the ~pugs~ language.
- The language *does not allow* low-level manipulations of high-level
type variables. This means that for instance, one cannot access or
modify specific cell or node value. A consequence of such a choice
is that this *constrained framework* allows to write algorithms
(within the pugs language) that can be executed in parallel
naturally. To achieve that, there should *never* be parallel
instructions or instructions that require *explicit parallel* actions
in the ~pugs~ language.
- Not providing low-level instruction simplifies the code and reduces
the risks of errors
* TODO Language
** TODO Variables
*** TODO Types<<variable-types>>
**** TODO Basic types
** Variables
**** TODO High-level types
*** Types<<variable-types>>
*** TODO Life time
**** Basic types
** TODO Statements
**** High-level types
** TODO Functions<<functions>>
**** Tuples
*** TODO User-defined functions
*** Lifetime
*** TODO Builtin functions
** Statements
** Functions<<functions>>
*** User-defined functions
*** Builtin functions
[fn:pugs-def] ~pugs~: Parallel Unstructured Grid Solvers
[fn:MPI-def] ~MPI~: Message Passing Interface
......
0% Loading or .
You are about to add 0 people to the discussion. Proceed with caution.
Please register or to comment