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

Fix a set of typos

parent 95f9e18d
No related branches found
No related tags found
1 merge request!145git subrepo clone git@gitlab.com:OlMon/org-themes.git packages/org-themes
...@@ -107,8 +107,8 @@ The example is quite easy to read. ...@@ -107,8 +107,8 @@ The example is quite easy to read.
mesh. Observe that if the resulting mesh is stored in the same mesh. Observe that if the resulting mesh is stored in the same
variable ~m~, the old one was not modified in the process. It is 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 important to already have in mind that the ~pugs~ language *does not
allow* the modifications of values of *non-basic* types. This is allow* the modifications of values of variables of *non-basic*
discussed in the section [[high-level-types]]. types. This is discussed in the section [[high-level-types]].
- Finally, the last block consists in saving the obtained mesh in a - Finally, the last block consists in saving the obtained mesh in a
~gnuplot~ file. The result is shown on Figure [[fig:intro-example]]. ~gnuplot~ file. The result is shown on Figure [[fig:intro-example]].
...@@ -140,7 +140,7 @@ already be discussed. ...@@ -140,7 +140,7 @@ already be discussed.
almost the same but one must know their differences to understand almost the same but one must know their differences to understand
better the underlying mechanisms and choices that we made. See better the underlying mechanisms and choices that we made. See
section [[basic-types]] and [[high-level-types]] for details. section [[basic-types]] and [[high-level-types]] for details.
- Also, there are two types of function: *user-defined* functions and - Also, there are two types of functions: *user-defined* functions and
*builtin* functions. In this example, ~theta~, ~M~ and ~T~ are user-defined *builtin* functions. In this example, ~theta~, ~M~ and ~T~ are user-defined
functions. All other functions (~cos~, ~cartesian2dMesh~,...) are functions. All other functions (~cos~, ~cartesian2dMesh~,...) are
builtin functions and are generally defined when importing a builtin functions and are generally defined when importing a
...@@ -174,7 +174,7 @@ provided script. A ~C++~ function is associated to each instruction of ...@@ -174,7 +174,7 @@ provided script. A ~C++~ function is associated to each instruction of
the script. The ~C++~ components of ~pugs~ are completely unaware of the the script. The ~C++~ components of ~pugs~ are completely unaware of the
other ones. ~pugs~ interpreter is responsible of data flow between the other ones. ~pugs~ interpreter is responsible of data flow between the
components: it manages the data transfer between those ~C++~ components components: it manages the data transfer between those ~C++~ components
and ensure that the workflow is properly defined. and ensures that the workflow is properly defined.
**** Why? **** Why?
...@@ -197,16 +197,17 @@ methods or their settings. ...@@ -197,16 +197,17 @@ methods or their settings.
- Data files may contain irrelevant information. Actually, it is quite - Data files may contain irrelevant information. Actually, it is quite
common to allow to define options that are valid but irrelevant to a 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 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 an easy task and requires more work from the user (which can be a
good thing). good thing).
- It is quite common that data files become obsolete. An option was - 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 not the right one, or its type changed to allow other
puts pressure on the user. contexts... This puts pressure on the user.
- Even worst options meaning can depend on other - Even worst, options meaning can depend on other
options. Unfortunately, it happens quite easily. For instance, a options. Unfortunately, it happens quite easily. For instance, a
global option can change implicitly the treatment associated to global option can change implicitly the treatment associated to
another one. This is quite dangerous since writing or reading the another one. This is quite dangerous since writing or reading the
data file requires an important knowledge of the code internals. data file requires an important and up to date knowledge of the
code's internals.
- Another major difficulty when dealing with data files is to check - Another major difficulty when dealing with data files is to check
the compatibility of provided options. the compatibility of provided options.
...@@ -221,8 +222,8 @@ files or a script), but it presents several drawbacks. ...@@ -221,8 +222,8 @@ files or a script), but it presents several drawbacks.
defining the model and numerical options, the user has generally defining the model and numerical options, the user has generally
access to the whole code and can change almost everything, even access to the whole code and can change almost everything, even
things that should not be changed. things that should not be changed.
- Again, easily one can have access to irrelevant options and it - Again, one can easily have access to irrelevant options and it
requires a great knowledge of the code to find relevant ones. requires a great knowledge of the code to find important ones.
- With that regard, defining a simulation properly can be a difficult - With that regard, defining a simulation properly can be a difficult
task. For instance, in the early developments of ~pugs~ (when it was 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 just a raw ~C++~ code) it was tricky to change boundary conditions for
...@@ -240,20 +241,20 @@ files or a script), but it presents several drawbacks. ...@@ -240,20 +241,20 @@ files or a script), but it presents several drawbacks.
Actually, an honest analysis cannot conclude that a DSL is the Actually, an honest analysis cannot conclude that a DSL is the
solution to all problems. However, it offers some advantages. solution to all problems. However, it offers some advantages.
- First it allows a fine control on what the user can or cannot - First, it allows a fine control on what the user can or cannot
performed. In some sense it offers a chosen level of flexibility. perform. In some sense, it offers a chosen level of flexibility.
- It allows to structure the code in the sense that new developments - 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 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). way it should be used (its interactions with the scripting language).
- In the same idea, it provides a framework that should ease the - In the same idea, it provides a framework that should ease the
definition of "do simple things and do it well". desired principle of "do simple things and do them well".
- There are no hidden dependencies between numerical options: the code - There are no hidden dependencies between numerical options: the DSL
is easier to read and it is more difficult to get obsolete (this is code is easier to read (than data files) and it is more difficult to
not that true in early development since the language itself and get it obsolete (this is not that true in early developments since
some concepts are still likely to change). the language itself and some concepts are still likely to change).
- The simulation scenario is *defined* by the script, it is the - The simulation scenario is *defined* by the script, it is to the
responsibility of the user in some sense and not to the charge of responsibility of the user and not to the charge of the code to
the code to check its meaning. check its meaning.
***** ~pugs~ language purpose ***** ~pugs~ language purpose
...@@ -266,7 +267,7 @@ Another purpose of the language is to allow perform high-level ...@@ -266,7 +267,7 @@ Another purpose of the language is to allow perform high-level
calculations. In other words, the language defines a data flow and calculations. In other words, the language defines a data flow and
checks that each ~C++~ piece of code is used correctly. Since each piece 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), of code acts as a pure function (arguments are unchanged by calls),
the context is quite easily checked. the calling context is quite easy to check.
Finally it aims at simplifying the definition of new methods since Finally it aims at simplifying the definition of new methods since
common utilities are available directly in scripts. common utilities are available directly in scripts.
...@@ -275,17 +276,19 @@ common utilities are available directly in scripts. ...@@ -275,17 +276,19 @@ common utilities are available directly in scripts.
~pugs~ is a research oriented software, thus generally the user is also ~pugs~ is a research oriented software, thus generally the user is also
a developer. If this paragraph is indeed more dedicated to the a developer. If this paragraph is indeed more dedicated to the
developer, reading it, the user will understand better the choices and developer, by reading it, the user will have a better understanding of
policy that drive the code. the development choices and the underlying policy that that the code
follows.
Actually the development framework imposed by the DSL tends to guide Actually the development framework imposed by the DSL tends to guide
writing of new methods. writing of new methods.
- A natural consequence is that the developer is encourage to write - A natural consequence is that the developer is encourage to write
small independent ~C++~ methods (even it does not forbid to write big small independent ~C++~ methods (even if it does not forbid to write
monolithic pieces of code). However as already said, one should try big monolithic pieces of code). However as already said, one should
to respect the following precept: write small piece of code to ease try to respect the following precept: write small piece of code to
their testing and validation, try to do simple things the right way. ease their testing and validation, try to do simple things the right
way.
- Also, in the process of writing a *new numerical methods*, one must - Also, in the process of writing a *new numerical methods*, one must
create *new functions in the language*. Moreover, if a new method is create *new functions in the language*. Moreover, if a new method is
close to an existing one, it is generally *better* to use completely close to an existing one, it is generally *better* to use completely
...@@ -309,11 +312,12 @@ writing of new methods. ...@@ -309,11 +312,12 @@ writing of new methods.
- If the new method is abandoned or simply not kept, the existing - If the new method is abandoned or simply not kept, the existing
code is not polluted. code is not polluted.
- Finally when a method is validated and ready to integrate the - Finally when a method is validated and ready to integrate the
mainline of the code, it is easier to see differences with mainline sources of the code, it is easier to see differences with
existing ones and *at this time* one can redesign the ~C++~ code existing ones and *at this time* one can redesign the ~C++~ code
checking that results are unchanged and performances not checking that results are unchanged and performances not
deteriorated. At this time, it is likely that the numerical method deteriorated. At this time, it is likely that the numerical method
design if finished, thus (re)designing the code makes more sense. design is finished, thus (re)designing the source code makes more
sense.
- Another consequence is that utilities are not be developed again and - Another consequence is that utilities are not be developed again and
again. again.
- This implies an /a priori/ safer code: utilities are well tested and - This implies an /a priori/ safer code: utilities are well tested and
...@@ -325,16 +329,17 @@ writing of new methods. ...@@ -325,16 +329,17 @@ writing of new methods.
knowledge of existing utilities is required, this document tries knowledge of existing utilities is required, this document tries
to address a part of it. In the other hand, if the developer to address a part of it. In the other hand, if the developer
requires a new utility, a good practice is to discuss with the requires a new utility, a good practice is to discuss with the
others to check if it could benefit to the others to determine if others to check if it could benefit to them. Then one can
it should integrate rapidly or not the main development branch. determine if it should integrate rapidly or not the main
development branch.
***** Why not python or any other scripting language? ***** Why not python or any other scripting language?
As it was already pointed out above, general purpose languages offer As it was already pointed out above, general purpose languages offer
to much freedom: it is not easy to protect data. For instance in the to much freedom: it is not easy to protect data. For instance in the
~pugs~ DSL, non basic variables are constant (see paragraph ~pugs~ DSL, non basic variables are constant (see paragraph
[[high-level-types]]). It is important since its prevent the user to modify [[high-level-types]]). It is important since it prevents the user to
data in an inconsistent way. Also, one must keep in mind that modify data in inconsistent ways. Also, one must keep in mind that
constraining the expressiveness is actually a strength. As said constraining the expressiveness is actually a strength. As said
before, one can warranty coherence of the data, perform calculations before, one can warranty coherence of the data, perform calculations
without paying attention to the parallelism aspects,... Observe that without paying attention to the parallelism aspects,... Observe that
...@@ -367,8 +372,9 @@ programmer knows that writing the code is only the first step of a ...@@ -367,8 +372,9 @@ programmer knows that writing the code is only the first step of a
much longer process which requires rigorous tests and validations, the much longer process which requires rigorous tests and validations, the
enrichment of a non-regression database. Generally one also desires to enrichment of a non-regression database. Generally one also desires to
ensure that the development is used within the correct bounds which ensure that the development is used within the correct bounds which
requires to implement some checking. In a perfect world, an up-to-date requires to implement checking and data verification. In a perfect
documentation of the functionality and its domain of validity. world, an up-to-date documentation of the functionality and its domain
of validity.
This is even more true when defining a language (or a DSL). Enriching This is even more true when defining a language (or a DSL). Enriching
a language syntax (or grammar) is not something that must be done to a language syntax (or grammar) is not something that must be done to
...@@ -385,10 +391,10 @@ If the grammar of ~pugs~ is still likely to be extended, it should *never* ...@@ -385,10 +391,10 @@ If the grammar of ~pugs~ is still likely to be extended, it should *never*
integrate low-level instructions. Low-level instructions give too much integrate low-level instructions. Low-level instructions give too much
freedom and thus are a source of errors. Several things are already freedom and thus are a source of errors. Several things are already
done to forbid this kind of evolution. The constness of high-level done to forbid this kind of evolution. The constness of high-level
data for instance is a good illustration. In practice for instance data is a good illustration. For instance, meshes or discrete
meshes or discrete functions *cannot* be modified. This is not only a functions *cannot* be modified. This is not only a security to protects
security that protects the user from doing "dangerous" manipulations, the user from doing "dangerous" manipulations, but it also permits to
but that also permits to define high-level optimizations. define high-level optimizations.
- Since meshes are constant objects, one can for instance compute - Since meshes are constant objects, one can for instance compute
geometric data on demand. These data are kept into memory as long as geometric data on demand. These data are kept into memory as long as
the mesh lives. the mesh lives.
...@@ -405,7 +411,7 @@ write errors. ...@@ -405,7 +411,7 @@ write errors.
** Variables ** Variables
In order to simplify the presentation, before going further, we In order to simplify the presentation, before going further, we
introduce the construction that allow to print data to the introduce the construction that allows to print data to the
terminal. It follows ~C++~ streams construction for convenience. For terminal. It follows ~C++~ streams construction for convenience. For
instance instance
#+NAME: cout-preamble-example #+NAME: cout-preamble-example
...@@ -452,7 +458,7 @@ For instance to declare a real variable ~x~, one writes ...@@ -452,7 +458,7 @@ For instance to declare a real variable ~x~, one writes
The instructions that follow the declaration of a variable can use it The instructions that follow the declaration of a variable can use it
while defined in the same scope, but it cannot be used before. Also, while defined in the same scope, but it cannot be used before. Also,
after its declaration, one cannot declare another variable with the after its declaration, one cannot declare another variable with the
same name in the same scope. same name in the same scope (see [[blocks-and-life-time]]).
#+NAME: redeclare-variable #+NAME: redeclare-variable
#+BEGIN_SRC pugs-error :exports both :results output #+BEGIN_SRC pugs-error :exports both :results output
let x:R; // first declaration let x:R; // first declaration
...@@ -1136,8 +1142,6 @@ they follow a few rules. ...@@ -1136,8 +1142,6 @@ they follow a few rules.
*** TODO Tuples types *** TODO Tuples types
*** TODO blocks and variables lifetime
** TODO modules ** TODO modules
** TODO Statements ** TODO Statements
......
0% Loading or .
You are about to add 0 people to the discussion. Proceed with caution.
Please register or to comment