From 62ea9315356e3e131d10870bd124245c8a5b96a8 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?St=C3=A9phane=20Del=20Pino?= <stephane.delpino44@gmail.com> Date: Wed, 4 May 2022 13:52:23 +0200 Subject: [PATCH] Fill 'framework' paragraph --- doc/userdoc.org | 74 ++++++++++++++++++++++++++++++++++++++----------- 1 file changed, 58 insertions(+), 16 deletions(-) diff --git a/doc/userdoc.org b/doc/userdoc.org index 2d4626d3b..dce8ecc83 100644 --- a/doc/userdoc.org +++ b/doc/userdoc.org @@ -262,22 +262,64 @@ 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 likely to be unchanged by new - developments -- utilities are not developed again and again: - - safer code - - important code is not polluted by environment instructions (data - initialization, error calculation, post-processing,...) +common utilities are available directly in scripts. + +**** The framework: divide and conquer + +~pugs~ is a research oriented software, thus generally the user is also +a developer. If this paragraph is indeed more dedicated to the +developer, reading it, the user will understand better the choices and +policy that drive the code. + +Actually the development framework imposed by the DSL tends to guide +writing of new methods. + +- A natural consequence is that the developer is encourage to write + small independent ~C++~ methods (even it does not forbid to write big + monolithic pieces of code). However as already said, one should try + to respect the following precept: write small piece of code to 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 + create *new functions in the language*. Moreover, if a new method is + close to an existing one, it is generally *better* to use completely + new underlying ~C++~ code than to patch existing methods. Starting + from a *copy* of the existing code is *encouraged* for + developments. This may sound weird since classical development + guidelines encourage inheritance or early redesign. Actually, this + policy is the result of the following discussion. + - Using this approach, one *separates* clearly the *design* of a + numerical method and the *design* of the code! + - From the computer science point of view, early design for new + numerical methods is generally wrong: usually one cannot + anticipate precisely enough eventual problems or method + corrections. + - It is much more difficult to introduce bugs in existing methods, + since previously validated methods are unchanged! + - For the same reason, existing methods performances are naturally + unchanged by new developments. + - Also, when comparing methods, it is better to compare to the + original existing code. + - If the new method is abandoned or simply not kept, the existing + code is not polluted. + - Finally when a method is validated and ready to integrate the + mainline of the code, it is easier to see differences with + existing ones and *at this time* one can redesign the ~C++~ code + checking that results are unchanged and performances not + deteriorated. At this time, it is likely that the numerical method + design if finished, thus (re)designing the code makes more sense. +- Another consequence is that utilities are not be developed again and + again. + - This implies an /a priori/ safer code: utilities are well tested and + validated. + - It saves development time obviously. + - Numerical methods code is not polluted by environment instructions + (data initialization, error calculation, post-processing,...) + - The counterpart is somehow classical. In the one hand, the + knowledge of existing utilities is required, this document tries + 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 + others to check if it could benefit to the others to determine if + it should integrate rapidly or not the main development branch. **** TODO Why not python or any other scripting language? -- GitLab