commit 3b16590b1ba5c85e0dab3235e1fa338057bc0be6
parent 412178a6d65184d53c808aecab4d2922d934efa7
Author: Christophe Coustet <christophe.coustet@meso-star.com>
Date: Wed, 26 Jan 2022 18:59:18 +0100
Additions to the man related to programmed stuff
Diffstat:
2 files changed, 135 insertions(+), 95 deletions(-)
diff --git a/doc/stardis-input.5.txt b/doc/stardis-input.5.txt
@@ -13,6 +13,8 @@
// You should have received a copy of the GNU General Public License
// along with this program. If not, see <http://www.gnu.org/licenses/>.
+:sharp: #
+
:toc:
stardis-input(5)
@@ -28,49 +30,35 @@ DESCRIPTION
thermal system. It relies on a line-based ad-hoc syntax.
A thermal system is composed of lines of text, each one describing either a
+program (an user-provided shared object), a
medium (solid or fluid) frontier, a boundary (limit condition or connection
-between two media), or the scale of the geometry. In the medium or boundary
+between two media), the scale of the whole geometry, or the radiative
+temperature around the system. In the medium or boundary
cases, description lines include a list of file names that constitute the
-limit or boundary. The current version of *stardis* only accepts triangle
-mesh geometry files in *STL* format. If a scale is specified, it defines the
+limit or boundary. The current version of *stardis(1)* only accepts triangle
+mesh geometry files in *STL* format. If a scale is specified, it defines the
scaling factor to apply to the geometry to have it expressed in meters (e.g.
1e-3 if the geometry is in mm).
-A medium limit or a boundary description can be split accross files and a
+A medium limit or a boundary description can be split across files and a
single file or description line can describe more than one frontier (more than
one connex region). The main semantic constraint on descriptions is that any
enclosure must be defined by a single description line, to ensure that any
part in the system is made from a single medium.
Finally, description lines can be submitted to the *stardis*(1) program in
-any order and can be split accross more than one file, through multiple use
+any order, with the exception of programs that must be defined before use,
+and can be split across more than one file, through multiple use
of option *-M*.
-UNITS
------
-Any physical quantity involved in descriptions is expected in the
-International System of Units (second, metre, kilogram, kelvin, watt, joule);
-the same applies to *stardis(1)* outputs as described in *stardis-output(5)*.
-
-However, the geometry provided to *stardis*(1) can be described in any unit,
-multiple of meters or not, as long as the scaling factor is provided.
-
-TINIT VS TIMPOSED
------------------
-Media's descriptions, either solids or fluids, include two possible
-temperatures: initial and imposed. If imposed temperature is set (that is not
-"UNKNOWN"), initial temperature must be defined at the same value. In other
-words, one cannot define a medium with an imposed temperature that changes at
-t=0.
-
GRAMMAR
-------
In what follows, some lines end in *\*. This is used as a convenience to
continue a description next line. However, this trick cannot be used in
actual description files and actual description lines must be kept single-line.
Also, text appearing between quote marks has to be used verbatim in the input,
-except the quote characters. Finally, text introduced by the *#* character in
-descriptions, when not verbatim, is a comment and is not part of the
+except the quote characters. Finally, text introduced by the *{sharp}* character
+in descriptions, when not verbatim, is a comment and is not part of the
description.
[verse]
@@ -80,14 +68,17 @@ _______
<description-lines> ::= <description-line>
[ <description-lines> ]
-<description-line> ::= [ <medium-frontier> ] [ <comment> ]
+<description-line> ::= [ <program> ] [ <comment> ]
+ | [ <medium-frontier> ] [ <comment> ]
| [ <medium-boundary> ] [ <comment> ]
| [ <media-connection> ] [ <comment> ]
- | [ <scaling-factor> ] [ <comment> ] # at most once
- | [ <radiative-temps> ] [ <comment > ] # at most once
+ | [ <scaling-factor> ] [ <comment> ] {sharp} at most once
+ | [ <radiative-temps> ] [ <comment > ] {sharp} at most once
-------------------------------------
+<program> ::= "PROGRAM" <prog-name> <library-path> [ <lib-arguments> ]
+
<medium-frontier> ::= <solid-frontier>
| <fluid-frontier>
| <prog-solid-frontier>
@@ -107,7 +98,7 @@ _______
| <prog-solid-fluid-connect>
| <prog-solid-solid-connect>
-<comment> ::= "#" Any text introduced by the # character
+<comment> ::= "{sharp}" Any text introduced by the {sharp} character
<solid-frontier> ::= "SOLID" <medium-name> <lambda> <rho> <cp> <delta> \
<initial-temperature> <imposed-temperature> \
@@ -137,30 +128,30 @@ _______
<solid-solid-connect> ::= "SOLID_SOLID_CONNECTION" <connect-name> \
<contact-resistance> <triangles>
-<prog-solid-frontier> ::= "SOLID_PROG" <medium-name> <library> <triangle-sides> \
- [ "PROG_PARAMS" [ <lib-arguments> ] ]
+<prog-solid-frontier> ::= "SOLID_PROG" <medium-name> <prog-name> <triangle-sides> \
+ [ "PROG_PARAMS" [ <desc-arguments> ] ]
-<prog-fluid-frontier> ::= "FLUID_PROG" <medium-name> <library> <triangle-sides> \
- [ "PROG_PARAMS" [ <lib-arguments> ] ]
+<prog-fluid-frontier> ::= "FLUID_PROG" <medium-name> <prog-name> <triangle-sides> \
+ [ "PROG_PARAMS" [ <desc-arguments> ] ]
-<prog-t-bound-for-solid> ::= "T_BOUNDARY_FOR_SOLID_PROG" <bound-name> <library> \
- <triangle-sides> [ "PROG_PARAMS" [ <lib-arguments> ] ]
+<prog-t-bound-for-solid> ::= "T_BOUNDARY_FOR_SOLID_PROG" <bound-name> <prog-name> \
+ <triangle-sides> [ "PROG_PARAMS" [ <desc-arguments> ] ]
-<prog-h-bound-for-solid> ::= "H_BOUNDARY_FOR_SOLID_PROG" <bound-name> <library> \
- <triangle-sides> [ "PROG_PARAMS" [ <lib-arguments> ] ]
+<prog-h-bound-for-solid> ::= "H_BOUNDARY_FOR_SOLID_PROG" <bound-name> <prog-name> \
+ <triangle-sides> [ "PROG_PARAMS" [ <desc-arguments> ] ]
-<prog-h-bound-for-fluid> ::= "H_BOUNDARY_FOR_FLUID_PROG" <bound-name> <library> \
- <triangle-sides> [ "PROG_PARAMS" [ <lib-arguments> ] ]
+<prog-h-bound-for-fluid> ::= "H_BOUNDARY_FOR_FLUID_PROG" <bound-name> <prog-name> \
+ <triangle-sides> [ "PROG_PARAMS" [ <desc-arguments> ] ]
-<prog-f-bound-for-solid> ::= "F_BOUNDARY_FOR_SOLID_PROG" <bound-name> <library> \
- <triangle-sides> [ "PROG_PARAMS" [ <lib-arguments> ] ]
+<prog-f-bound-for-solid> ::= "F_BOUNDARY_FOR_SOLID_PROG" <bound-name> <prog-name> \
+ <triangle-sides> [ "PROG_PARAMS" [ <desc-arguments> ] ]
<prog-solid-fluid-connect> ::= "SOLID_FLUID_CONNECTION_PROG" <connect-name> \
- <library> <triangle-sides> [ "PROG_PARAMS" [ <lib-arguments> ] ]
+ <prog-name> <triangle-sides> [ "PROG_PARAMS" [ <desc-arguments> ] ]
<prog-solid-solid-connect> ::= "SOLID_SOLID_CONNECTION_PROG" <connect-name> \
- <library> <triangle-sides> [ "PROG_PARAMS" [ <lib-arguments> ] ]
+ <prog-name> <triangle-sides> [ "PROG_PARAMS" [ <desc-arguments> ] ]
<scaling-factor> ::= "SCALE" <scale> [ <comment> ]
@@ -168,74 +159,111 @@ _______
-------------------------------------
-<medium-name> ::= STRING # no space allowed, must not be a keyword nor a
- # number, including INF and others
+<prog-name> ::= STRING {sharp} no space allowed, must not be a keyword nor a
+ {sharp} number, including INF and others
+
+<library-path> ::= FILEPATH {sharp} the path can be absolute
+ {sharp} or relative to the running directory and must be valid
+
+<lib-arguments> ::= STRING {sharp} if not empty, the whole string is send to the
+ {sharp} stardis_create_library_data() optional function
+ {sharp} it is an error to provide arguments to a program if
+ {sharp} the associated library doesn't define this function
+ {sharp} note that the {sharp} character consistently ends
+ {sharp} arguments by starting a comment
-<lambda> ::= REAL # conductivity in W/(m.K); in ]0, INF)
+<medium-name> ::= STRING {sharp} no space allowed, must not be a keyword nor a
+ {sharp} number, including INF and others
-<rho> ::= REAL # volumic mass,in kg/m3; in ]0, INF)
+<lambda> ::= REAL {sharp} conductivity in W/(m.K); in ]0, INF)
-<cp> ::= REAL # capacity, in J/(kg.K) or kg.m2/(s2.K)
- # in ]0, INF)
+<rho> ::= REAL {sharp} volumic mass,in kg/m3; in ]0, INF)
-<delta> ::= "AUTO" # delta is automatically set to V/6A (V and A
- # being respectively the solid volume and its
- # boundary area)
- | REAL # delta*scaling_factor in m; in [0, INF)
+<cp> ::= REAL {sharp} capacity, in J/(kg.K) or kg.m2/(s2.K)
+ {sharp} in ]0, INF)
-<initial-temperature> ::= REAL # in K; in [0, INF)
+<delta> ::= "AUTO" {sharp} delta is automatically set to V/6A (V and A
+ {sharp} being respectively the solid volume and its
+ {sharp} boundary area)
+ | REAL {sharp} delta*scaling_factor in m; in [0, INF)
-<imposed-temperature> ::= "UNKNOWN" # temperature has to be solved
- | REAL # in K; in [0, INF)
+<initial-temperature> ::= REAL {sharp} in K; in [0, INF)
-<outside-temperature> ::= REAL # in K; in [0, INF)
+<imposed-temperature> ::= "UNKNOWN" {sharp} temperature has to be solved
+ | REAL {sharp} in K; in [0, INF)
-<volumic-power> ::= REAL # in W/m3; in (-INF , INF)
+<outside-temperature> ::= REAL {sharp} in K; in [0, INF)
+
+<volumic-power> ::= REAL {sharp} in W/m3; in (-INF , INF)
<triangle-sides> ::= <side-specifier> <file-name> [ <triangle-sides> ]
-<bound-name> ::= STRING # no space allowed, must not be a keyword nor a
- # number, including INF and others
+<bound-name> ::= STRING {sharp} no space allowed, must not be a keyword nor a
+ {sharp} number, including INF and others
-<connect-name> ::= STRING # no space allowed, must not be a keyword nor a
- # number, including INF and others
+<connect-name> ::= STRING {sharp} no space allowed, must not be a keyword nor a
+ {sharp} number, including INF and others
-<Tref> ::= REAL # in [0, inf)
+<Tref> ::= REAL {sharp} in [0, inf)
-<emissivity> ::= REAL # in [0, 1]
+<emissivity> ::= REAL {sharp} in [0, 1]
-<specular-fraction> ::= REAL # in [0, 1]
+<specular-fraction> ::= REAL {sharp} in [0, 1]
-<hc> ::= REAL # in W/(m2.K); in [0, INF)
+<hc> ::= REAL {sharp} in W/(m2.K); in [0, INF)
-<contact-resistance> ::= REAL # in m2.K/W in [0, INF)
+<contact-resistance> ::= REAL {sharp} in m2.K/W in [0, INF)
-<flux> ::= REAL # in W/m2; in (-INF , INF)
+<flux> ::= REAL {sharp} in W/m2; in (-INF , INF)
<triangles> ::= <file-name> [ <triangles> ]
-<scale> ::= REAL # scaling factor to apply to the geometry
- # in ]0 INF)
-
-<library> ::= FILEPATH # the path must be valid in the running directory
+<scale> ::= REAL {sharp} scaling factor to apply to the geometry
+ {sharp} in ]0 INF)
-<lib-arguments> ::= STRING # the whole string is send to the init()
- # function when the description is created
- # note that the '#' character consistently ends
- # arguments by starting a comment
+<desc-arguments> ::= STRING {sharp} the whole string is send to the stardis_create_data()
+ {sharp} function when the description is created
+ {sharp} note that the '{sharp}' character consistently ends
+ {sharp} arguments by starting a comment
-<radiative-temp> ::= REAL # in [0, inf)
+<radiative-temp> ::= REAL {sharp} in [0, inf)
-<radiative-temp-ref> ::= REAL # in [0, inf)
+<radiative-temp-ref> ::= REAL {sharp} in [0, inf)
-------------------------------------
<side-specifier> ::= "FRONT" | "BACK" | "BOTH"
-<file-name> ::= STRING # no space allowed
+<file-name> ::= STRING {sharp} no space allowed
______________
+PROGRAMS
+--------
+Programs are user-provided shared objects (compiled libraries). They allow to
+provide *stardis(1)* with user defined properties. Depending on the type of
+description they are used with, programs must export a given list of
+mandatory functions. They can also export some other optional functions.
+The exact list with names and types can be found in the stardis-prog.h public
+header file that is installed at the same time as the *stardis(1)* binary.
+
+UNITS
+-----
+Any physical quantity involved in descriptions is expected in the
+International System of Units (second, metre, kilogram, kelvin, watt, joule);
+the same applies to *stardis(1)* outputs as described in *stardis-output(5)*.
+
+However, the geometry provided to *stardis*(1) can be described in any unit,
+multiple of meters or not, as long as the scaling factor is provided.
+
+TINIT VS TIMPOSED
+-----------------
+Media's descriptions, either solids or fluids, include two possible
+temperatures: initial and imposed. If imposed temperature is set (that is not
+"UNKNOWN"), initial temperature must be defined at the same value. In other
+words, one cannot define a medium with an imposed temperature that changes at
+t=0.
+
TRIANGLE SIDES
--------------
Side descriptions in side specifiers rely on the following convention: we
@@ -246,29 +274,39 @@ used with the FRONT side specifier to describe inside medium.
NAMES
-----
-Names, either file names, medium names or boundary names, are a sequence of
-one or ore ASCII characters, including numbers and special characters like
-*.* *_* *-* as one may consider using in standard file names, *without any
-spacing* either escaped or not. Names are case-sensitive and two different
-description lines, either in the same description file or from different
-description files, cannot use the same name. Additionaly, medium and boundary
-names cannot be parsable as a number, nor be one of the few keywords defined
-by the present grammar (AUTO, BACK, BOTH, FLUID, FRONT, F_BOUNDARY_FOR_SOLID,
-H_BOUNDARY_FOR_FLUID, H_BOUNDARY_FOR_SOLID, SCALE, SOLID,
-SOLID_FLUID_CONNECTION, T_BOUNDARY_FOR_FLUID, T_BOUNDARY_FOR_SOLID, UNKNOWN) or
-their lowercase counterparts.
+Names, either file names or description names (program names, medium names or
+boundary names), are a sequence of one or ore ASCII characters, including
+numbers and special characters like *.* *_* *-* as one may consider using in
+standard file names, *without any spacing* either escaped or not. Description
+names are case-sensitive and two different description lines, either in the
+same description file or from different description files, cannot use the same
+name. Additionally, description names cannot be parsable as a number, nor be one
+of the few keywords defined by the present grammar (AUTO, BACK, BOTH, FLUID,
+FLUID_PROG, FRONT, F_BOUNDARY_FOR_SOLID, F_BOUNDARY_FOR_SOLID_PROG,
+H_BOUNDARY_FOR_FLUID, H_BOUNDARY_FOR_FLUID_PROG, H_BOUNDARY_FOR_SOLID,
+H_BOUNDARY_FOR_SOLID_PROG, PROGRAM, PROG_PARAMS, SCALE, SOLID, SOLID_PROG,
+SOLID_FLUID_CONNECTION, SOLID_FLUID_CONNECTION_PROG, SOLID_SOLID_CONNECTION,
+SOLID_SOLID_CONNECTION_PROG, TRAD, T_BOUNDARY_FOR_SOLID,
+T_BOUNDARY_FOR_SOLID_PROG, UNKNOWN) or their lowercase counterparts.
EXAMPLES
--------
-Define a solid named Cube with a h boundary. The cube geometry is read from
+Define a solid named Cube, a h boundary, and their radiative environment.
+The cube geometry is read from
the file cube.stl and the solid medium properties are lambda=0.1, rho=25, cp=2.
The numerical parameter delta, that is used for solid conductive walks, is
-0.05. The initial temperature of the cube is 0°K and its volumic power is 0.
-The boundary properties are emisivity=0, specular-fraction=0, h=10 and
+0.05. The initial temperature of the cube is 0°K, its temperature is unknown
+(*stardis(1)* needs to solve it), and its volumic power is 2.5 W/m3.
+The boundary properties are emissivity=0, specular-fraction=0, h=10 and
external-temperature = 100°K.
+The cube radiative environment is at 300°K.
+Finally, when the Picard method linearises radiative transfer involving the HdT
+boundary, the reference temperature is set to 310°K, while it is set to 330°K
+when linearisation involves the radiative environment.
.......
-SOLID Cube 0.1 25 2 0.05 0 0 FRONT cube.stl
-H_BOUNDARY_FOR_SOLID HdT 0 0 10 100 cube.stl
+SOLID Cube 0.1 25 2 0.05 0 UNKNOWN 2.5 FRONT cube.stl
+H_BOUNDARY_FOR_SOLID HdT 310 0 0 10 100 cube.stl
+TRAD 300 330
.......
SEE ALSO
diff --git a/doc/stardis.1.txt.in b/doc/stardis.1.txt.in
@@ -95,7 +95,9 @@ MANDATORY OPTIONS
-----------------
*-M* _file_::
Read a text file containing a possibly partial description of the system.
- Can include both media enclosures and boundary conditions, in any order.
+ Can include programs, media enclosures and boundary conditions. Media and
+ boundaries can appear in any order, but programs must be defined before their
+ first reference. Refer to *stardis-input(5)* for details.
Can be used more than once if the description is split across different
files.
