commit 5d37123f1b41a2fad0194bdcaca4040775097194
parent 0db7951db0bae88d2c361809a8c3a70981c85d67
Author: Christophe Coustet <christophe.coustet@meso-star.com>
Date: Wed, 22 Apr 2020 16:48:07 +0200
Documentation improvement
Diffstat:
2 files changed, 146 insertions(+), 96 deletions(-)
diff --git a/doc/stardis-input.5.txt b/doc/stardis-input.5.txt
@@ -28,7 +28,7 @@ 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
-medium (solid or fluid) a frontier, or a boundary (limit condition or
+medium (solid or fluid) frontier or a boundary (limit condition or
connection between two media). In either case, a description line includes a
list of file names that constitute the limit or boundary. The current version
of *stardis* only accepts triangle mesh geometry files in *VTK* format.
@@ -171,14 +171,14 @@ the same name.
EXAMPLES
--------
-Define a solid cube with a h boundary. 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.
+Define a solid named Cube with a h boundary. 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
external-temperature = 100°K.
.......
-SOLID CUBE 0.1 25 2 0.05 0 0 FRONT cube.stl
+SOLID Cube 0.1 25 2 0.05 0 0 FRONT cube.stl
H_BOUNDARY_FOR_SOLID HdT 0 0 10 100 cube.stl
.......
diff --git a/doc/stardis-output.5.txt b/doc/stardis-output.5.txt
@@ -24,24 +24,26 @@ stardis-output - output format of stardis(1) results
DESCRIPTION
-----------
-The *stardis-output* describes the output format of the *stardis*(1) program.
+*stardis-output* describes the output format of the *stardis*(1) program.
All the data generated by a *stardis*(1) invocation are written to _standard
output_.
-The type of the data that are generated depends on the option used when
+The type of the data that are generated depends on the options used when
*stardis*(1) is invoked. When invoked with one of the basic computation options
-(*-p*, *-P*, *-m*, *-s* or *-F*), *stardis*(1) output a single Monte-Carlo
+(*-p*, *-P*, *-m*, *-s* or *-F*), *stardis*(1) outputs a single Monte-Carlo
result. On the opposite, *stardis*(1) ouputs compound results when invoked with
option *-S* or *-R*. Additionally, options *-g* and *-D* are output modifiers.
+Most if not all complex data output are in VTK [1] format that can be displayed
+and manipulated by the open-source software Paraview [2].
Finaly, some special options (*-v*, *-h* or *-d*) that does not involve any
computation produce output including information on the *stardis*(1) software
-(their ouput will not be described thereafter) or the provided thermal system.
+(their ouputs will not be described thereafter) or the provided thermal system.
UNITS
-----
-As for values in *stardis-input*(5), any physical quantity in output is in the
-International System of Units (second, metre, kilogram, kelvin).
+As with the values in *stardis-input*(5), any physical quantity in output is in
+the International System of Units (second, metre, kilogram, kelvin).
OPTIONS
-------
@@ -59,7 +61,7 @@ correspondance:
*-p*, *-P*, *-m* or *-s* with *-g*: produce <green>
-*-p*, *-P*, *-m*, *-s*, *-S* or *-F* with *-D*: produce <thermal-paths>
+*-p*, *-P*, *-m*, *-s*, *-S* or *-F* with *-D*: produce <heat-paths>
*-R*: produces <image-file>
@@ -72,16 +74,19 @@ continue a description next line. However, this trick is not part of the
actual output, that continues on a single line. On the other hand, multiple
lines not using the *\* convenience in multi-lines descriptions are truly
different lines of output. Also, text appearing between quote marks is a
-verbatim part of the output, except the quote characters. Finally, text
-following the *#* character in description, when not verbatim, is a comment
-and is not part of the description.
+verbatim part of the output, except the quote characters, *<#something>*
+denotes a count (the number of something), and the math symbols '*\+*'
+and '***', when not verbatim, are used with the usual meaning (like in
+1+<#something>). Finally, text following the *#* character in a description,
+when not verbatim, is a comment and is not part of the output.
[verse]
_______
+
<output> ::= <single-MC-result>
| <green-output>
- | ....
-
+ | <geometry-dump>
+ | <infrared-image>
_______
SINGLE MONTE CARLO
@@ -160,107 +165,151 @@ The output in green mode is a made of tables containing the different media and
boundaries and their imposed temperatures, fluxes and volumic powers, followed
by the paths' history.
-DUMP GEOMETRY
+GEOMETRY DUMP
-------------
A *geometry-file* is generated when *stardis*(1) is invoked with the *-d*
option. In this mode, *stardis*(1) outputs the system geometry, as submitted
in *stardis-input*(5) description, to _standard output_ in the VTK [1] format.
The output geometry is not the concatenation of the various geometry files
used in *stardis-input*(5) description. It is the result of a deduplication
-process that removes duplicate and degenerated triangles.
+process that removes duplicate and degenerated triangles in the submited
+geometry.
Additionaly, as permitted by the VTK [1] format, the output geometry is
decorated with many different properties provided to help users understand
the description processing, including possible errors.
+If errors are detected, some optional error-related data fields are included
+in the geometry file. Some errors report a by-triangle error status, other
+errors report a by-enclosure error status.
+
+
+INFRARED IMAGE
+--------------
+
+When invoked with the *-R* option, *stardis*(1) generates an infrared image of
+the system and write it to _standard output_ in VTK [1] file format. The image
+is on an XY plane with coordinates in the [0 pixel_count[ range. By convention,
+the origine (0,0) pixel is at the top-left corner of the image.
+
+The result not only includes the computed temperature image, but also includes
+a per-pixel computation time image as well as a per-pixel path error count
+image and per-pixel standard deviation images for both temperature and
+computation time.
+
+[verse]
+_______
+<infrared-image> ::= "# vtk DataFile Version 2.0"
+ "Infrared Image"
+ "ASCII"
+ "DATASET STRUCTURED_POINTS"
+ "DIMENSIONS" <image-width> <image-height> "1"
+ "ORIGIN 0 0 0"
+ "SPACING 1 1 1"
+ "POINT_DATA" <image-width>*<image-height>
+ "SCALARS temperature_estimate float 1"
+ "LOOKUP_TABLE default"
+ <temperatures>
+ "SCALARS temperature_std_dev float 1"
+ "LOOKUP_TABLE default"
+ <temp_std_devs>
+ "SCALARS computation_time float 1"
+ "LOOKUP_TABLE default"
+ <computation_times>
+ "SCALARS computation_time_std_dev float 1"
+ "LOOKUP_TABLE default"
+ <com_time_std_devs>
+ "SCALARS failures_count unsigned_long_long 1"
+ "LOOKUP_TABLE default"
+ <failures_counts>
+
+<temperatures> ::= REAL # in [0, INF)
+ <temperatures> # <image-width> * <image-height> temperatures
+
+<temp_std_devs> ::= REAL # in [0, INF)
+ <temperature_std_devs> # <image-width> * <image-height> std_devs
+
+<computation_times> ::= REAL # in [0, INF)
+ <computation_times> # <image-width> * <image-height> times
+
+<comp_time_std_devs> ::= REAL # in [0, INF)
+ <comp_time_std_devs> # <image-width> * <image-height> std_devs
+
+<failures_counts> ::= INTEGER # in [0, SAMPLES_COUNT]
+ <failures_counts> # <image-width> * <image-height> failures_counts
+_______
DUMP HEAT PATHS
---------------
-When the *stardis*(1) option *-D* is used some of the termal paths (either
-successful paths, erroneous paths, or both) sampled carrying out the simulation
-are written to _standard output_ after to the computation result. The various
-path are written in VTK [1] format, one VTK file per path separated by a
-special text line.
+When the *stardis*(1) option *-D* is used, some of the heat paths (successful
+paths, erroneous paths, or both) sampled during the simulation are written to
+files. Each path is written in VTK [1] format, one VTK file per path. The path
+description includes vertices' time it it makes sense, that is if the
+computation time is not INF.
[verse]
_______
-<heat-paths> ::= "---"
- <heat-path>
- [ <heat-paths> ]
-
-<heat-path> ::= "# vtk DataFile Version 2.0"
- "Heat paths"
- "ASCII"
- "DATASET POLYDATA"
- "POINTS" <#vertices> "double"
- <path-vertices>
- "LINES 1" 1+<#vertices>
- <heat-path>
- "POINT_DATA" <#vertices>
- "SCALARS Vertex_Type float 1"
- "LOOKUP_TABLE vertex_type"
- <vertices-types>
- "LOOKUP_TABLE vertex_type 3"
- <color-conduction>
- <color-convection>
- <color-radiative>
- "SCALARS Weight double 1"
- "LOOKUP_TABLE default"
- <weigths>
- "SCALARS Time double 1"
- "LOOKUP_TABLE default"
- <durations>
- "CELL_DATA 1"
- "SCALAR Path_type float 1"
- "LOOKUP_TABLE path_type"
- <path-type>
- "LOOKUP_TABLE path_type 2"
- <color-error>
- <color-success>
-
-<path-vertices> ::= <real3>
- <path-vertices> # <#vertices> vertices
-
-<heat-path> ::= <#vertices> "0" "1" ... <#vertices>-1
-
-<vertices-types> ::= <vertice-type>
- <vertices-types> # <#vertices> types
-
-<weigths> ::= REAL
- <weigths> # <#vertices> weigths
-
-<durations> ::= REAL # in [0, INF)
- <durations> # <#vertices> durations
-
-<real3> ::= REAL REAL REAL
-
-<vertice-type> ::= 0.0 # for conduction step
- | 0.5 # for convection step
- | 1.0 # for radiative step
-
-<path-type> ::= 0.0 # for error path
- | 1.0 # for success path
-
-<color-error> ::= "1.0 0.0 0.0 1.0" # Red
-<color-success> ::= "0.0 0.0 1.0 1.0" # Blue
-
-<color-conduction> ::= "0.0 1.0 1.0 1.0" # Magenta:
-<color-convection> ::= "1.0 1.0 0.0 1.0" # Yellow
-<color-radiative> ::= "1.0 0.0 1.0 1.0"# Purple
-_______
-RENDERING
----------
-When invoked with the *-R* option, *stardis*(1) generates an infrared image
-file of the system and write it to _standard output_ in the VTK [1] file
-format.
+<heat-path> ::= "# vtk DataFile Version 2.0"
+ "Heat path"
+ "ASCII"
+ "DATASET POLYDATA"
+ "POINTS" <#vertices> "double"
+ <path-vertices>
+ "LINES 1" 1+<#vertices>
+ <heat-path>
+ "POINT_DATA" <#vertices>
+ "SCALARS Vertex_Type unsigned_char 1"
+ "LOOKUP_TABLE default"
+ <vertices-types>
+ "CELL_DATA 1"
+ "SCALAR Path_type unsigned_char 1"
+ "LOOKUP_TABLE default"
+ <path-type>
+ "SCALARS Weight double 1"
+ "LOOKUP_TABLE default"
+ <weigths>
+ [ <vertices-time> ]
+
+<path-vertices> ::= <real3>
+ <path-vertices> # <#vertices> vertices
+
+<heat-path> ::= <#vertices> "0" "1" ... <#vertices>-1
+
+<vertices-types> ::= <vertice-type>
+ <vertices-types> # <#vertices> types
+
+<weigths> ::= REAL
+ <weigths> # <#vertices> weigths
+
+<vertices-time> ::= "SCALARS Time double 1"
+ "LOOKUP_TABLE default"
+ <durations>
+
+-----------------
+
+<real3> ::= REAL REAL REAL
+
+<durations> ::= REAL # in [0, INF)
+ <durations> # <#vertices> durations
+
+<vertice-type> ::= 0 # CONDUCTION
+ | 1 # CONVECTION
+ | 2 # RADIATIVE
+
+<path-type> ::= 0 # SUCCESS
+ | 1 # FAILURE
+
+_______
NOTES
-----
1. VTK file format -
<http://www.vtk.org/wp-content/uploads/2015/04/file-formats.pdf>
-2. Portable PixMap - <http://netpbm.sourceforge.net/doc/ppm.html>
+
+2. Paraview softawre -
+ <https://www.paraview.org/>
SEE ALSO
--------
*stardis*(1),
-*stardis-input*(5)
+*stardis-input*(5)
+\ No newline at end of file
