doc

Author: gtheler

README4academics.md

@@ -17,7 +17,7 @@ It does not require the users to write a weak form of the PDE they want to solve
 The user chooses from a set of built-in PDEs using the [`PROBLEM`](https://www.seamplex.com/feenox/doc/feenox-manual.html#problem) definition which internally resolves (at run time) a set of function pointers to the appropriate locations which will build the elemental objects which correspond the to chosen PDE.
 The list of available PDEs can be peeked by executing the `feenox` binary with the `--pdes` option:
 
-```
+```terminal
 $ feenox --pdes
 laplace
 mechanical

README4hackers.md

@@ -64,9 +64,8 @@ Unlike these other FEA tools, FeenoX provides...
     thermal
     $ 
     ```
-    
    The decision of extensibility through compiled code is, as the choice of making FeenoX a program and not a library, a thoughtful one. See [FeenoX for academics](./README4academics.md) for more details about how the extensibility mechanism works.
-    
+
  * continuous integration (using [Github actions](https://github.com/seamplex/feenox/actions)), an issue tracker (using [Github issues](https://github.com/seamplex/feenox/issues) and a discussion page (using [Github discussions](https://github.com/seamplex/feenox/discussions))
 
  * a mechanism to [expand command-line arguments as literal strings in the input file](https://www.seamplex.com/feenox/doc/sds.html#sec:run-time-arguments) so as to allow [parametric](https://www.seamplex.com/feenox/doc/sds.html#sec:parametric) (and/or [optimization](https://www.seamplex.com/feenox/doc/sds.html#sec:optimization)) loops. For instance, if an input file `print.fee` looks like
@@ -75,7 +74,7 @@ Unlike these other FEA tools, FeenoX provides...
    PRINT 2*${1}
    ```
    then
-   
+
    ```terminal
    $ for i in $(seq 1 5); do feenox print.fee $i; done
    2
@@ -85,7 +84,7 @@ Unlike these other FEA tools, FeenoX provides...
    10
    $ 
    ``` 
-   
+
  * the possibility to provide the input from `stdin` (so as to use it as a Unix pipe) by passing `-` as the input file path:
 
    ```terminal
@@ -95,10 +94,13 @@ Unlike these other FEA tools, FeenoX provides...
    6
    8
    10
-   $ 
-   ``` 
+   $
+   ```
 
  * flexibility to handle many workflows, including [web-based interfaces](https://www.caeplex.com) and [thin command-line clients](https://www.seamplex.com/feenox/doc/sds.html#cloud-first).
+   - In particular, FeenoX is particularly well suited to be incldued in workflows involving LLMs and/or AI agents.
+   
+ * official Debian and Ubuntu packages built on Salsa from the source tarballs.
 
 The [input file](https://seamplex.com/feenox/doc/sds.html#sec:input)...
 
@@ -107,6 +109,7 @@ The [input file](https://seamplex.com/feenox/doc/sds.html#sec:input)...
  - allows the user to enter [algebraic expressions whenever a numerical value is needed](https://seamplex.com/feenox/doc/sds.html#sec:expression) (everything is an expression)
  - understands [definitions (nouns) and instructions (verbs)](https://seamplex.com/feenox/doc/sds.html#sec:nouns_verbs). FeenoX has an actual instruction pointer that loops over the instruction set (there might even be [conditional blocks](https://www.seamplex.com/feenox/doc/feenox-manual.html#if)).
  - is [simple for simple files](https://seamplex.com/feenox/doc/sds.html#sec:simple) (but might get [more complicated for more complex problems](https://seamplex.com/feenox/doc/sds.html#sec:complex)). Remember [Alan Kay](https://en.wikipedia.org/wiki/Alan_Kay)'s quote: ["simple things should be simple and complex things should be possible."](https://www.quora.com/What-is-the-story-behind-Alan-Kay-s-adage-Simple-things-should-be-simple-complex-things-should-be-possible)
+ - can be created using assistance from LLMs and AI agents.
 
 
 Following the Unix rule of silence, [the output is 100% user-defined](https://seamplex.com/feenox/doc/sds.html#sec:output): if there are not explicit output instructions, FeenoX will not write anything. And probably nothing will be computed (because FeenoX is smart and will not compute things that are not actually needed).

doc/100-introduction.md

@@ -1,14 +1,14 @@
 
 A computational tool (herein after referred to as _the tool_) specifically designed to be executed in arbitrarily-scalable remote servers (i.e. in the cloud) is required in order to solve engineering problems following the current state-of-the-art methods and technologies impacting the high-performance computing world.
 This (imaginary but plausible) Software Requirements Specification document describes the mandatory features this tool ought to have and lists some features which would be nice the tool had.
-Also it contains requirements and guidelines about architecture, execution and interfaces in order to fulfill the needs of cognizant engineers as of the 2020s. 
+Also it contains requirements and guidelines about architecture, execution and interfaces in order to fulfill the needs of cognizant engineers as of the 2020s. In particular, it should be designed and implemented in such a way to explicitly allow and encourage LLMs to be able to provide assistance with the problem set up, model debugging and analysis of results.
 
 On the one hand, the tool should allow to solve industrial problems under stringent efficiency (@sec:efficiency) and quality (@sec:qa) requirements. It is therefore mandatory to be able to assess the source code for
 
  * independent verification, and/or
  * performance profiling, and/or
  * quality control
- 
+
 by qualified third parties from all around the world.
 Hence, it has to be _open source_ according to the definition of the Open Source Initiative.
 

doc/110-objective.md

@@ -11,7 +11,7 @@ The main objective of the tool is to be able to solve engineering problems which
  * computational fluid dynamics
  * ...
 
-on one or more mainstream cloud servers, i.e. computers with hardware and operating systems (further discussed in @sec:architecture) that allows them to be available online and accessed remotely either interactively or automatically by other computers as well. Other architectures such as high-end desktop personal computers or even low-end laptops might be supported but they should not the main target (i.e. the tool has to be cloud-first but laptop-friendly). 
- 
+on one or more mainstream cloud servers, i.e. computers with hardware and operating systems (further discussed in @sec:architecture) that allows them to be available online and accessed remotely either interactively or automatically by other computers as well. Other architectures such as high-end desktop personal computers or even low-end laptops might be supported but they should not the main target (i.e. the tool has to be cloud-first but laptop-friendly).
+
 The initial version of the tool must be able to handle a subset of the above list of problem types.
 Afterward, the set of supported problem types, models, equations and features of the tool should grow to include other models as well, as required in @sec:extensibility.

doc/TODO.md

@@ -2,12 +2,13 @@
 
  * FeenoX focuses on:
 
-    a. cloud-firtness
+    a. cloud-firstness
     b. parametric runs: script-friendly through command-line arguments and ASCII files
     c. material properties: everything is an expression
+    d. LLM-friendlyness
 
  * NAFEMS LE10 & LE11: keep a single case in `differences` and create a new one in `cases` with a full parametric run
-   
+
    ```
    READ_MESH le10-$1.msh
    ...

doc/sds-appendices.md

@@ -2,6 +2,10 @@
 
 # Appendix: Downloading and compiling FeenoX
 
+## Debian & Ubuntu packages
+
+To be explained
+
 ## Binary executables
 
 ```include

doc/source.md

@@ -1,4 +1,4 @@
-To compile the source tarball, proceed as follows. This procedure does not need `git` nor `autoconf` but a new tarball has to be downloaded each time there is a new FeenoX version.
+To compile the source tarball, proceed as follows. This procedure does not need `git` nor `autoconf` but a new [source tarball]() has to be downloaded each time there is a new FeenoX version.
 
  1. Install mandatory dependencies
 
@@ -8,16 +8,15 @@ To compile the source tarball, proceed as follows. This procedure does not need
     ```
 
     If you cannot install `libgsl-dev`, you can have the `configure` script to download and compile it for you. See point\ 4 below.
-    
+
  2. Install optional dependencies (of course these are _optional_ but recommended)
- 
+
     ```terminal
     sudo apt-get install libsundials-dev petsc-dev slepc-dev
     ```
 
  3. Download and un-compress FeenoX source tarball. Browse to <https://www.seamplex.com/feenox/dist/src/> and pick the latest version:
- 
- 
+
     ```terminal
     wget https://www.seamplex.com/feenox/dist/src/feenox-v1.1.tar.gz
     tar xvzf feenox-v1.1.tar.gz

src/flow/init.c

@@ -351,26 +351,33 @@ int feenox_init_special_objects(void) {
   feenox_special_var_value(static_steps) = 1;
 
 
-///va+end_time+desc Final time of the transient calculation, to be set by the user. 
-///va+end_time+detail The default value is zero, meaning no transient calculation.
+///va+end_time+desc Final time of the transient calculation. 
+///va+end_time+detail Set this variable to a positive value to ask for a transient calculation.
+///va+end_time+detail For some PDEs, the default might be a quasi-static problem instead of an actual transient one.
+///va+end_time+detail For instance, setting a non-zero `end_time` in `PROBLEM mechanical` starts a quasi-static computation
+///va+end_time+detail but a real transient one for `PROBLEM thermal`.
+///va+end_time+detail The default value is zero, meaning a static problem.
   feenox_special_var(end_time) = feenox_get_or_define_variable_get_ptr("end_time");
 
 
-///va+t+desc Actual value of the time for transient calculations.
-///va+t+detail This variable is set by FeenoX, but can be written by
-///va+t+detail the user for example by importing it from another
-///va+t+detail transient code by means of shared-memory objects.
-///va+t+detail Care should be taken when solving DAE systems and overwriting `t`.
+///va+t+desc Actual value of the time for transient or quasi-static calculations.
+///va+t+detail This variable can be `PRINT`ed and used in expressions involving time and/or
+///va+t+detail as arguments of time-dependent functions.
+///va+t+detail It stars equal to zero and it is updated by FeenoX according to
+///va+t+detail the time-stepping scheme. At the end, it is exactly equal to `end_time`.
+
   feenox_special_var(t) = feenox_get_or_define_variable_get_ptr("t");
   feenox_special_var_value(t) = 0;  
 
 
-///va+dt+desc Actual value of the time step for transient calculations.
-///va+dt+detail  When solving DAE systems,
-///va+dt+detail this variable is set by feenox. It can be written by the user for example by importing it from another
-///va+dt+detail transient code by means of shared-memory objects. Care should be taken when
-///va+dt+detail solving DAE systems and overwriting `t`. Default value is DEFAULT_DT, which is
-///va+dt+detail a power of two and roundoff errors are thus reduced.
+///va+dt+desc Actual value of the time step for transient or quasi-static calculations.
+///va+dt+detail This variable can be `PRINT`ed and used in expressions involving time and/or
+///va+dt+detail as arguments of time-dependent functions.
+///va+dt+detail The initial time step can be set by assigning a non-zero value to `dt_0`.
+///va+dt+detail Do not set `dt` explicitly in an assignment.
+///va+dt+detail If you want to have a constant time step set both `min_dt` and `max_dt` to the same value.
+///va+dt+detail Default initial time step is DEFAULT_DT, which is
+///va+dt+detail a power of two and round-off errors are thus reduced.
   feenox_special_var(dt) = feenox_get_or_define_variable_get_ptr("dt");
   feenox_special_var_value(dt) = DEFAULT_DT;
 
@@ -381,10 +388,10 @@ int feenox_init_special_objects(void) {
   feenox_special_var(dae_rtol) = feenox_get_or_define_variable_get_ptr("dae_rtol");
   feenox_special_var_value(dae_rtol) = DEFAULT_DAE_RTOL;
 
-///va+min_dt+desc Minimum bound for the time step that feenox should take when solving DAE systems.
+///va+min_dt+desc Minimum bound for the time step that FeenoX should take when solving transient problems.
   feenox_special_var(min_dt) = feenox_get_or_define_variable_get_ptr("min_dt");
 
-///va+max_dt+desc Maximum bound for the time step that feenox should take when solving DAE systems.
+///va+max_dt+desc Maximum bound for the time step that FeenoX should take when solving transient systems.
   feenox_special_var(max_dt) = feenox_get_or_define_variable_get_ptr("max_dt");
 
 ///va+i+desc Dummy index, used mainly in vector and matrix row subindex expressions.
@@ -393,7 +400,7 @@ int feenox_init_special_objects(void) {
 ///va+j+desc Dummy index, used mainly in matrix column subindex expressions.
   feenox_special_var(j) = feenox_get_or_define_variable_get_ptr("j");
 
-///va+pi+desc A double-precision floating point representation of the number $\pi$
+///va+pi+desc A double-precision floating· point representation of the number $\pi$
 ///va+pi+detail It is equal to the `M_PI` constant in `math.h` .
   feenox_special_var(pi) = feenox_get_or_define_variable_get_ptr("pi");
   feenox_special_var_value(pi) = M_PI;

tests/pellet-nonlinear-transient-from-initial.fee

@@ -1,6 +1,7 @@
 PROBLEM thermal 3D
 READ_MESH pellet.msh
 
+dt_0 = 1e-3
 end_time = 3  # small time to run the test faster [seconds]
 
 # https://www.nuclear-power.com/nuclear-engineering/heat-transfer/thermal-conduction/thermal-conductivity/thermal-conductivity-of-uranium-dioxide/