Skip to content
GitLab
Explore
Sign in
Primary navigation
Search or go to…
Project
pugs
Manage
Activity
Members
Labels
Plan
Issues
Issue boards
Milestones
Wiki
Code
Merge requests
Repository
Branches
Commits
Tags
Repository graph
Compare revisions
Snippets
Build
Pipelines
Jobs
Pipeline schedules
Artifacts
Deploy
Releases
Model registry
Operate
Environments
Monitor
Incidents
Analyze
Value stream analytics
Contributor analytics
CI/CD analytics
Repository analytics
Model experiments
Help
Help
Support
GitLab documentation
Compare GitLab plans
GitLab community forum
Contribute to GitLab
Provide feedback
Keyboard shortcuts
?
Snippets
Groups
Projects
Show more breadcrumbs
code
pugs
Commits
3af64fc3
Commit
3af64fc3
authored
May 23, 2022
by
Stéphane Del Pino
Browse files
Options
Downloads
Patches
Plain Diff
Fix a set of typos
parent
95f9e18d
No related branches found
No related tags found
1 merge request
!145
git subrepo clone git@gitlab.com:OlMon/org-themes.git packages/org-themes
Changes
1
Show whitespace changes
Inline
Side-by-side
Showing
1 changed file
doc/userdoc.org
+48
-44
48 additions, 44 deletions
doc/userdoc.org
with
48 additions
and
44 deletions
doc/userdoc.org
+
48
−
44
View file @
3af64fc3
...
@@ -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 function
s
: *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 ensure
s
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 require
s
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
relev
ant ones.
requires a great knowledge of the code to find
import
ant 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
perform
ed
. 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
de
finition
of "do simple things and do
i
t well".
de
sired principle
of "do simple things and do t
hem
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 development
s
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 eas
ily
check
ed
.
the
calling
context is quite eas
y 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 it
s
prevent the user to
modify
[[high-level-types]]). It is important since it prevent
s
the user to
data in
an
inconsistent way. Also, one must keep in mind that
modify
data in inconsistent way
s
. 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 instanc
e
data is a good illustration.
For instance, meshes or discret
e
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 allow
s
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
...
...
This diff is collapsed.
Click to expand it.
Preview
0%
Loading
Try again
or
attach a new file
.
Cancel
You are about to add
0
people
to the discussion. Proceed with caution.
Finish editing this message first!
Save comment
Cancel
Please
register
or
sign in
to comment