commit 4eee7d51b35756924d30a167666122a7404d30b3
parent ad48bf167091eb1656dd93ed82a409af8f4774fe
Author: Christophe Coustet <christophe.coustet@meso-star.com>
Date: Wed, 8 Apr 2020 09:58:22 +0200
Documentation improvement
Diffstat:
3 files changed, 251 insertions(+), 527 deletions(-)
diff --git a/doc/stardis-input.5.txt b/doc/stardis-input.5.txt
@@ -24,7 +24,7 @@ stardis-input - thermal system description for stardis(1)
DESCRIPTION
-----------
-*stardis-input* is the format used by the *stardis*(1) program to discribe a
+*stardis-input* is the format used by the *stardis*(1) program to describe a
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
@@ -45,105 +45,108 @@ applies to *stardis(1)* outputs as described in *stardis-output(5)*.
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
of the *-M* option.
-
+
GRAMMAR
-------
-
In what follows, some lines end in *\*. This is used as a convenience to
-continue the explanation next line. However, this caracter cannot be used in
+continue a description next line. However, this character 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 following the *#* character in
+descriptions, when not verbatim, is a comment and is not part of the
+description.
[verse]
_______
-<thermal-system> ::= <description-line>
- [ <thermal-system> ]
+<thermal-system> ::= <description-line>
+ [ <thermal-system> ]
+
+<description-line> ::= [ <medium-frontier> ... ]
+ [ <medium-boundary> ... ]
+ [ <media-connection> ... ]
-<description-line> ::= [ <medium-frontier> ... ]
- [ <medium-boundary> ... ]
- [ <media-connection> ... ]
-
-------------------------------------
-<medium-frontier> ::= <solid-frontier>
- | <fluid-frontier>
-
-<solid-frontier> ::= SOLID <medium-name> <lambda> <rho> <cp> <delta> \
- <initial-temperature> <volumic-power> <triangle-sides>
+<medium-frontier> ::= <solid-frontier>
+ | <fluid-frontier>
-<fluid-frontier> ::= FLUID <medium-name> <ka> <ks> <rho> <cp> \
- <initial-temperature> <triangle-sides>
+<solid-frontier> ::= "SOLID" <medium-name> <lambda> <rho> <cp> <delta> \
+ <initial-temp> <volumic-power> <triangle-sides>
+
+<fluid-frontier> ::= "FLUID" <medium-name> <ka> <ks> <rho> <cp> \
+ <initial-temp> <triangle-sides>
-------------------------------------
-<medium-name> ::= STRING # no space allowed
+<medium-name> ::= STRING # no space allowed
-<lambda> ::= REAL # in ]0, INF)
+<lambda> ::= REAL # in ]0, INF)
-<rho> ::= REAL # in ]0, INF)
+<rho> ::= REAL # in ]0, INF)
-<cp> ::= REAL # in ]0, INF)
+<cp> ::= REAL # in ]0, INF)
-<delta> ::= REAL # in ]0, INF)
+<delta> ::= REAL # in ]0, INF)
-<initial-temperature> ::= REAL # in [0, INF)
+<initial-temp> ::= REAL # in [0, INF)
-<volumic-power> ::= REAL # in (-INF , INF)
+<volumic-power> ::= REAL # in (-INF , INF)
-<ka> ::= REAL # in [0, INF)
+<ka> ::= REAL # in [0, INF)
-<ks> ::= REAL # in [0, INF)
+<ks> ::= REAL # in [0, INF)
-<triangle-sides> ::= <side-specifier> <file-name> [ <triangle-sides> ]
+<triangle-sides> ::= <side-specifier> <file-name> [ <triangle-sides> ]
-------------------------------------
-<side-specifier> ::= FRONT | BACK | BOTH
+<side-specifier> ::= "FRONT" | "BACK" | "BOTH"
-<file-name> ::= STRING # no space allowed
+<file-name> ::= STRING # no space allowed
-------------------------------------
-<medium-boundary> ::= <h-boundary-for-solid>
- | <h-boundary-for-fluid>
- | <t-boundary-for-solid>
- | <t-boundary-for-fluid>
- | <f-boundary-for-solid>
-
-<h-boundary-for-solid> ::= H_BOUNDARY_FOR_SOLID <boundary-name> <emissivity> \
- <specular-fraction> <hc> <external-temperature> <triangles>
+<medium-boundary> ::= <h-bound-for-solid>
+ | <h-bound-for-fluid>
+ | <t-bound-for-solid>
+ | <t-bound-for-fluid>
+ | <f-bound-for-solid>
+
+<h-bound-for-solid> ::= "H_BOUNDARY_FOR_SOLID" <bound-name> <emissivity> \
+ <specular-fraction> <hc> <external-temp> <triangles>
-<h-boundary-for-fluid> ::= H_BOUNDARY_FOR_FLUID <boundary-name> <emissivity> \
- <specular-fraction> <hc> <external-temperature> <triangles>
+<h-bound-for-fluid> ::= "H_BOUNDARY_FOR_FLUID" <bound-name> <emissivity> \
+ <specular-fraction> <hc> <external-temperature> <triangles>
-<t-boundary-for-solid> ::= T_BOUNDARY_FOR_SOLID <boundary-name> <temperature> <triangles>
+<t-bound-for-solid> ::= "T_BOUNDARY_FOR_SOLID" <bound-name> <temperature> <triangles>
-<t-boundary-for-fluid> ::= T_BOUNDARY_FOR_FLUID <boundary-name> <temperature> \
- <emissivity> <specular-fraction> <hc> <triangles>
+<t-bound-for-fluid> ::= "T_BOUNDARY_FOR_FLUID" <bound-name> <temperature> \
+ <emissivity> <specular-fraction> <hc> <triangles>
-<f-boundary-for-solid> ::= T_BOUNDARY_FOR_SOLID <boundary-name> <flux> <triangles>
+<f-bound-for-solid> ::= "T_BOUNDARY_FOR_SOLID" <bound-name> <flux> <triangles>
-------------------------------------
-<boundary-name> ::= STRING # no space allowed
+<bound-name> ::= STRING # no space allowed
-<emissivity> ::= REAL # in [0, 1]
+<emissivity> ::= REAL # in [0, 1]
-<specular-fraction> ::= REAL # in [0, 1]
+<specular-fraction> ::= REAL # in [0, 1]
-<hc> ::= REAL # in [0, INF)
+<hc> ::= REAL # in [0, INF)
-<external-temperature> ::= REAL # in [0, INF)
+<external-temp> ::= REAL # in [0, INF)
-<flux> ::= REAL # in (-INF , INF)
+<flux> ::= REAL # in (-INF , INF)
-<triangles> ::= <file-name> [ <triangles> ]
+<triangles> ::= <file-name> [ <triangles> ]
-------------------------------------
-<media-connection> ::= <solid-fluid-connection>
+<media-connection> ::= <solid-fluid-connect>
-<solid-fluid-connection> ::= SOLID_FLUID_CONNECTION <boundary-name> <emissivity> \
- <specular-fraction> <hc> <triangles>
+<solid-fluid-connect> ::= "SOLID_FLUID_CONNECTION" <bound-name> <emissivity> \
+ <specular-fraction> <hc> <triangles>
______________
@@ -155,18 +158,19 @@ first consider the direct triangle's normal (right-hand rule), then we define
the BACK side of a triangle to be the side this normal comes out from. That
means that a closed set of triangles with normals pointing outside should be
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
+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.
-Two different description lines can use the same name. However, computating
+Two different description lines can use the same name. However, computating
mean temperature in a given medium (*-m* option of *stardis*) has an undefined
-behaviour when the involved name has been used more than once in the system.
+behaviour when the medium name has been used more than once in the system
+description.
EXAMPLES
--------
diff --git a/doc/stardis-output.5.txt b/doc/stardis-output.5.txt
@@ -25,518 +25,238 @@ stardis-output - output format of stardis(1) results
DESCRIPTION
-----------
The *stardis-output* describes the output format of the *stardis*(1) program.
-All the data generated by a *stardis*(1) invocation are written in a single
-file or on the standard output whether an _output_ file is defined through the
-*-o* option or not, respectively. Note that submitting several sun directions
-to *stardis*(1), through the *-D* option, will produce as many outputs as sun
-directions. In other words, invoking *stardis*(1) with _N_ sun directions
-looks like calling *stardis*(1) _N_ times and concatenating their associated
+All the data generated by a *stardis*(1) invocation are written to the standard
output.
-The type of the data that are generated depends on the mode in which
-*stardis*(1) is invoked. By default, *stardis*(1) evaluates the power
-collected by the submitted solar plant. When invoked with the *-g* option,
-*stardis*(1) converts the solar plant geometries in a list of CAO files. The
-*-p* option is used to track the sampled radiative paths while, finally, the
-*-r* option allows to render an image of the solar facility.
+The type of the data that are generated depends on the option 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
+result. On the opposite, *stardis*(1) ouputs compound results when invoked with
+option *-S* or *-R*. Additionally, options *-g* and *-D* are output modifiers.
+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.
-GRAMMAR
+OPTIONS
-------
-The output values are mainly ASCII data formatted line by line. By convention,
-in the following grammar the line data are listed between quote marks. The
-grammar may use new lines for formatting constraints, but data are actually on
-the same line while a closed quote mark is not defined.
-[verse]
-_______
-<output> ::= <simulation-output>
- | <dump-geometry-output> # -g option
- | <dump-radiative-paths-output> # -p option
- | <rendering-output> # -r option
-
-<simulation-output> ::= <sun-direction>
- <counts>
- <global>
- [ <receivers-list> ]
- [ <primaries-list> ]
- [ <rcvXprims-list> ]
- [ <receiver-maps> ]
- [ <simulation-output> ... ]
-
-<dump-geometry-output>
- ::= <sun-direction>
- <geometry-data>
- [ <dump-geometry-output> ... ]
-
-<dump-radiative-paths-output>
- ::= <sun-direction>
- VTK-RADIATIVE-PATHS
- [ <dump-radiative-paths-output> ... ]
-
-<rendering-output> ::= <sun-direction>
- PPM-FILE # ASCII PPM with 8-bits per component [1]
- [ <rendering-output> ... ]
+Every top-level item of the output listed below is produced by one or more
+specific options of the *stardis*(1) program. The following list gives the
+correspondance:
--------------------------------------
+*-p* or *-P*: produce <probe-temp>
-<sun-direction> ::= "#--- Sun direction: <alpha> <beta> (<sun-vector>)"
+*-m*: produces <medium-temp>
-<counts> ::= "<#globals> <#receivers> <#primaries>
- <#samples> <#failed>"
+*-s*: produces <mean-temp>
-<#globals> ::= 7
-<#receivers> ::= INTEGER # in [0, INF)
-<#primaries> ::= INTEGER # in [0, INF)
-<#samples> ::= INTEGER # in [0, INF)
-<#failed> ::= INTEGER # in [0, INF)
+*-F*: produces <mean-flux>
-<global> ::= <potential-flux>
- <absorbed-flux>
- <cos-factor>
- <shadow-loss>
- <missing-loss>
- <materials-loss>
- <atmospheric-loss>
+*-p*, *-P*, *-m* or *-s* with *-g*: produce <green>
--------------------------------------
+*-p*, *-P*, *-m*, *-s*, *-S* or *-F* with *-D*: produce <thermal-paths>
+
+*-R*: produces <image-file>
-<receivers-list> ::= <receiver>
- [ <receiver> ... ]
+*-d*: produces <geometry-file>
-<receiver> ::= "<receiver-name> <receiver-id> <area>
- <front> <back>"
+GRAMMAR
+-------
+In what follows, some lines end in *\*. This is used as a convenience to
+continue a description next line. However, this character 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.
-<receiver-name> ::= <entity-identifier>
+[verse]
+_______
+<output> ::= <single-MC-result>
+ | <green-output>
+ | ....
-<receiver-id> ::= INTEGER
+_______
-<front> ::= <side>
-<back> ::= <side>
+SINGLE MONTE CARLO
+------------------
+When *stardis*(1) is used to produce a single Monte-Carlo result, either
+temperature or flux, this result is output first to standard output, possibly
+followed by some of the heat paths involved in the computation if option *-D*
+was used too.
-<side> ::= "<incoming-flux> <in-if-no-mat-loss>
- <in-if-no-atm-loss> <in-mat-loss> <in-atm-loss>
- <absorbed-flux> <abs-if-no-mat-loss>
- <abs-if-no-atm-loss> <abs-mat-loss> <abs-atm-loss>
- <efficiency>"
+[verse]
+_______
+<single-MC-result> ::= <probe-temp>
+ | <medium-temp>
+ | <mean-temp>
+ | <mean-flux>
-------------------------------------
-<primaries-list> ::= <primary>
- [ <primary> ... ]
+<probe-temp> ::= "Temperature at" <probe-position> <time> <MC-estimate>
+ <failures-report>
-<primary> ::= "<primary-name> <primary-id> <area> <#samples>
- <cos-factor> <shadow-loss>"
+<mean-temp> ::= "Temperature at boundary" <file-name> <time> <MC-estimate>
+ <failures-report>
-<primary-name> ::= <entity-identifier>
+<mean-flux> ::= "Temperature at boundary" <file-name> <time> <MC-estimate>
+ "Convective flux at boundary " <file-name> <time> \
+ <MC-estimate>
+ "Radiative flux at boundary" <file-name> <time> <MC-estimate>
+ "Total flux at boundary" <file-name> <time> <MC-estimate>
+ <failures-report>
-<primary-id> ::= INTEGER
+<medium-temp> ::= "Temperature in medium" <medium-name> <time> <MC-estimate>
+ <failures-report>
--------------------------------------
+<probe-position> ::= "[" <x-value> "," <y-value> "," <z-value> "]"
-<rcvXprims-list> ::= <rcvXprim>
- [ <rcvXprim> ... ]
+<time> ::= "at t=" <time-value> "="
-<rcvXprim> ::= "<receiver-id> <primary-id>
- <rcvXprim-front> <rcvXprim-back>"
+<MC-estimate> ::= <expected-value> "+/-" <standard-error>
-<rcvXprim-front> ::= <rcvXprim-side>
-<rcvXprim-back> ::= <rcvXprim-side>
+<failures-report> ::= "#failures:" <error-count> "/" <success-count>
-<rcvXprim-side> ::= "<incoming-flux> <in-if-no-mat-loss>
- <in-if-no-atm-loss> <in-mat-loss> <in-atm-loss>
- <absorbed-flux> <abs-if-no-mat-loss>
- <abs-if-no-atm-loss> <abs-mat-loss> <abs-atm-loss>"
+<file-name> ::= STRING # as provided in input data
+
+<medium-name> ::= STRING # as provided in input data
-------------------------------------
-<receiver-maps> ::= VTK-RECEIVER-MAP
- [ <receiver-maps> ... ]
+<x-value> ::= REAL
-<geometry-data> ::= OBJ-FILE
- [ ---
- <geometry-data> ... ]
+<y-value> ::= REAL
--------------------------------------
+<z-value> ::= REAL
-<area> ::= REAL # in ]0, INF)
-
-<real3> ::= REAL REAL REAL
-
-<alpha> ::= REAL # Degrees in [0, 360[
-<beta> ::= REAL # Degrees in [0, 90]
-<sun-vector> ::= <real3>
-
-<incoming-flux> ::= <estimate>
-<in-if-no-mat-loss> ::= <estimate>
-<in-if-no-atm-loss> ::= <estimate>
-<in-mat-loss> ::= <estimate>
-<in-atm-loss> ::= <estimate>
-<absorbed-flux> ::= <estimate>
-<abs-if-no-mat-loss> ::= <estimate>
-<abs-if-no-atm-loss> ::= <estimate>
-<abs-mat-loss> ::= <estimate>
-<abs-atm-loss> ::= <estimate>
-<cos-factor> ::= <estimate>
-<missing-loss> ::= <estimate>
-<materials-loss> ::= <estimate>
-<atmospheric-loss> ::= <estimate>
-<shadow-loss> ::= <estimate>
-<efficiency> ::= <estimate>
-
-<estimate> ::= <expected-value> <standard-error>
-<expected-value> ::= REAL
-<standard-error> ::= REAL # in [0, INF)
-
-<entity-identifier> # Defined in *stardis-input*(5)
-_______
+<time-value> ::= REAL # in [0, INF)
-SIMULATION
-----------
-
-A *simulation-output* begins with two header lines. The first one reports the
-sun direction used in the simulation (two angles in degrees, plus the
-corresponding sun vector),
-and the second one lists the numbers of global, per receiver and per
-primary results as well as the overall number of Monte-Carlo experiments used
-by the simulation and the number of experiments that failed due to unforeseen
-errors as numerical imprecisions. As soon as the number of failed experiments
-reaches 1% of the required number of Monte-Carlo experiments, the code exits
-with a "Error in integrating the solar flux" message, and the validity of
-subsequent results is questionable: estimates are produced using the number of
-Monte-Carlo experiments that have been successful, which is necessarily smaller
-than the required number of experiments.
-
-Global results
-~~~~~~~~~~~~~~
-
-After the 2 header lines, the output includes various *global* result lines,
-the exact number of lines being part of the headers. Currently this number is
-7. Each global result is a pair of real numbers: the expected value and its
-standard error. The global results are, in this order:
-
-- *potential-flux*: maximum flux that all the primary geometries could
- intercept if properly oriented and flat-shaped;
-- *absorbed-flux*: absorbed part of the flux reaching any receiver geometry.
- At most equal to the potential flux;
-- *cos-factor*: cos of the angle between the sun direction and the normal of
- the primary surfaces (average cos over all primary geometries);
-- *shadow-loss*: potential flux intercepted by another geometry before
- reaching a primary geometry;
-- *missing-loss*: part of the flux that reaches a primary geometry, follows a
- radiative path, but is not absorbed; this flux could have bounced on
- geometries, including receivers, but without being absorbed;
-- *materials-loss*: total flux absorbed by non-receivers along radiative
- paths; includes both surface and volume absorption;
-- *atmospheric-loss*: total flux extinction by the atmosphere along radiative
- paths.
-
-This results can be used to check conservation of energy:
-
-potential-flux * cos-factor and (absorbed-flux + shadow-loss +
-missing-loss + materials-loss + atmospheric-loss)
-should be equal within their respective uncertainty ranges.
-
-Per receiver results
-~~~~~~~~~~~~~~~~~~~~
-
-Following global results, the output includes various per-receiver lines, one
-line per receiver, the exact number of lines being part of the headers. The
-per-receiver results are sorted according to the order of the receivers as
-defined in the submitted *stardis-receiver*(5) file. Each line contains the
-following data:
-
-- *receiver-name*: name of the receiver, i.e. *entity-identifier* of the
- entity in which the receiving geometry is defined (see the
- *stardis-input*(5) format);
-- *receiver-id*: unique integer identifying the receiver;
-- *area*: area of the receiver;
-- *front*: estimated results for the front side of the receiver;
-- *back*: estimated results for the back side of the receiver.
-
-The estimates of the *front* and *back* sides are listed bellow. Note that
-each of the following estimates is actually a pair of real numbers: the
-expected value and its standard error.
-
-- *incoming-flux*: flux that reaches the receiver side;
-- *in-if-no-mat-loss*: incoming-flux if absorption on non-receivers is not
- taken into account;
-- *in-if-no-atm-loss*: incoming-flux if atmospheric extinction is not taken
- into account;
-- *in-mat-loss*: in-if-no-mat-loss - incoming-flux;
-- *in-atm-loss*: in-if-no-atm-loss - incoming-flux;
-- *absorbed-flux*: flux absorbed by the receiver side;
-- *abs-if-no-mat-loss*: absorbed-flux if absorption by non-receivers is not
- taken into account;
-- *abs-if-no-atm-loss*: absorbed-flux if atmospheric extinction is not taken
- into account;
-- *abs-mat-loss*: abs-if-no-mat-loss - absorbed-flux;
-- *abs-atm-loss*: abs-if-no-atm-loss - absorbed-flux;
-- *efficiency*: fraction of the potential flux absorbed by this receiver side.
-
-Both *front* and *back* side estimates are output, even if the receiver has
-only a single receiving side. In this case, the results of the non-receiving
-side are meaningless (invalid -1 value).
-
-Per primary results
-~~~~~~~~~~~~~~~~~~~
-
-Following the per-receiver results, the output includes various per-primary
-result lines, one line per primary geometry, the exact number of lines being
-part of the headers. Each line contains:
-
-- *primary-name*: name of the primary geometry, i.e. *entity-identifier* of
- the entity in in which the primary geometry is defined (see the
- *stardis-input*(5) format);
-- *primary-id*: unique integer identifying the primary geometry;
-- *area*: area of the primary geometry;
-- *#sample*: number of Monte-Carlo experiments sampled on the primary
- geometry;
-- *cos-factor*: cos of the angle between the sun direction and the normal of
- the primary surface (average cos on the primary geometry);
-- *shadow-loss*: potential flux intercepted by another geometry before reaching
- the primary geometry of interest.
-
-Per receiver and per primary results
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-
-Following the per-primary results, the output includes various result lines,
-each describing the contribution of a primary geometry to a given receiver.
-The total number of such lines is the number of receivers times the number of
-primary geometries. Each line contains:
-
-- *receiver-id*: identifier of the involved receiver;
-- *primary-id*: identifier of the involved primary geometry;
-- *rcvXprim-front*: estimated results for the receiver front side;
-- *rcvXprim-back*: estimated results for the receiver back side;
-
-The estimated values of *rcvXprim-front* and *rcvXprim-back* are listed
-bellow. Each of these estimates is actually a pair of real numbers: the
-expected value and its standard error.
-
-- *incoming-flux*: flux that reaches the receiver side;
-- *in-if-no-mat-loss*: incoming-flux if absorption on non-receivers is not
- taken into account;
-- *in-if-no-atm-loss*: incoming-flux if atmospheric extinction is not taken
- into account;
-- *in-mat-loss*: in-if-no-mat-loss - incoming-flux;
-- *in-atm-loss*: in-if-no-atm-loss - incoming-flux;
-- *absorbed-flux*: flux absorbed by the receiver side;
-- *abs-if-no-mat-loss*: absorbed-flux if absorption by non-receivers is not
- taken into account;
-- *abs-if-no-atm-loss*: absorbed-flux if atmospheric extinction is not taken
- into account;
-- *abs-mat-loss*: abs-if-no-mat-loss - absorbed-flux;
-- *abs-atm-loss*: abs-if-no-atm-loss - absorbed-flux;
-
-Both front and back side estimates are output, even if the receiver has only a
-single receiving side. In this case, the results of the non-receiving side are
-meaningless (invalid -1 value).
-
-Receiver map
-~~~~~~~~~~~~
-
-A receiver defined in the submitted *stardis-receiver*(5) file, can have a
-per-primitive estimate of its incoming flux density and/or absorbed flux
-density if its *per_primitive* flag is active. In this case, *stardis*(1)
-generates a *receiver-map* that is actually an ASCII VTK file [2] that stores
-the triangular mesh of the receiver and, for each triangle, the estimate of
-its associated incoming flux density and/or absorbed flux density. The
-"definition" of the receiver map is thus controlled by the discretisation of
-the receiver's shape, as described in the *stardis-input*(5) file. Note that
-to obtain a good estimate of the per-triangle flux densities, one have to
-ensure that the number of per-triangle experiments is sufficient regarding the
-targeted accuracy. Since only a small fraction of the overall sampled
-radiative paths reach a given triangle, the total number of experiments
-required through the *-n* option of *stardis*(1) should be increased
-significantly, as 1 or 2 order of magnitude.
-
-The number of written per-triangle flux density estimates depends on the
-receiver's parameters: both front and back sides of the receiver can be active
-and each side can produce an estimate both for the incoming flux density and
-for the absorbed flux density. As a consequence, the output can include up to
-4 different estimates that are written in the order: incoming front, absorbed
-front, incoming back, absorbed back. The following grammar gives a brief
-description of the formatting of a *VTK-RECEIVER-MAP*. Please refer to the VTK
-format specification [2] for more informations on the VTK file format.
+<error-count> ::= INTEGER # in [0, SAMPLES_COUNT]
-[verse]
-_______
-VTK-RECEIVER-MAP ::= # vtk DataFile Version 2.0
- <receiver-name>
- ASCII
- DATASET POLYDATA
- POINTS <#vertices> float
- <map-vertices>
- POLYGONS <#triangles> <#triangles*4>
- <map-triangles>
- CELL_DATA <#triangles>
- <map-triangle-data>
-
-<map-vertices> ::= <real3>
- [ <real3> ... ] # up to <#vertices>
-
-<map-triangles> ::= 3 <triangle-indices>
- [ 3 <triangle-indices> ... ] # up to <#triangles>
-
-<map-triangle-data> ::= <map-front-data>
- | <map-back-data>
- | <map-front-data> <map-back-data>
-
-<map-front-data> ::= <map-side-data>
-<map-back-data> ::= <map-side-data>
-
-<map-side-data> ::= <incoming-flux>
- | <absorbed-flux>
- | <incoming-flux> <absorbed-flux>
-
-<incoming-flux> ::= <flux-density-data>
-<absorbed-flux> ::= <flux-density-data>
-
-<flux-density-data> ::= SCALARS <side-and-flux-names> float 2
- LOOKUP_TABLE default
- <estimate>
- [ <estimate> ... ]
-
-<side-and-flux-names> ::= Front_faces_Incoming_flux
- | Front_faces_Absorbed_flux
- | Back_faces_Incoming_flux
- | Back_faces_Absorbed_flux
-
-<#triangles> ::= INTEGER
-<#vertices> ::= INTEGER
-<triangle-indices> ::= INTEGER INTEGER INTEGER
-_______
+<success-count> ::= INTEGER # in [0, SAMPLES_COUNT]
-DUMP GEOMETRY
--------------
+<expected-value> ::= REAL # depending on value semantics, range can be restricted
-A *dump-geometry-output* is generated when *stardis*(1) is invoked with the
-*-g* option. In this mode, for each submitted sun direction, *stardis*(1)
-converts the geometry of the submitted *stardis-input*(5) file in triangular
-meshes that are then written to the output with respect to the format provided
-by the *format* parameter of the *-g* option. The only format currently
-supported by *stardis*(1) is the Alias Wavefront OBJ [3] format. With no more
-sub-option, *stardis*(1) will thus generate one OBJ file containing the whole
-mesh of the solar plant. However, the *split* parameter of the *-g* option
-allows to generate several OBJ files: one description is generated per
-*geometry* or per *object*, as defined in the *stardis-input*(5) format,
-whether the *split* sub-option is set to *geometry* or *object*. In this
-situation, each OBJ description is followed by a line with 3 minus characters
-in order to identify the end of the current OBJ.
-
-Independently of the *split* strategy, each *stardis-input*(1) geometry is an
-OBJ group whose name is the *entity-identifier* of the entity in which it is
-encapsulated. Finally, the *dump-geometry-output* uses the *usemtl* directive
-of the OBJ format to associate to a mesh the name of its material type. The
-following grammar succinctly describes the formatting of an *OBJ-FILE*. Please
-refer to the OBJ format specification [3] for more informations on the OBJ file
-format.
+<standard-error> ::= REAL # in [0, INF)
-[verse]
_______
-OBJ-FILE ::= g <entity-identifier>
- <obj-mesh>
- [ <obj-mesh> ... ]
-<obj-mesh> ::= usemtl <material-type>
- <obj-vertices>
- <obj-faces>
+GREEN
+-----
-<obj-vertices> ::= v <real3>
- [ v <real3> ... ]
+The green function is generated when a green-compatible *stardis*(1) simulation
+option is used in conjuction with the *-g* option. For every successful heat
+path sampled carrying out the simulation, the solver records all the elements
+of the path history relevant to link the various imposed temperatures, fluxes
+and volumic powers to the simulation result.
-<obj-indices> ::= f <triangle-indices>
- [ f <triangle-indices> ... ]
+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.
-<material-type> ::= dielectric
- | matte
- | mirror
- | thin_dielectric
- | virtual
-_______
+DUMP GEOMETRY
+-------------
-DUMP RADIATIVE PATHS
---------------------
-
-For each sun direction, the *dump-radiative-paths-output* lists the geometric
-data of the radiative paths sampled during a simulation. Each path is colored
-with respect to its type: the path is yellow if its first segment, i.e.
-the ray starting from the sun towards a primary geometry, is occluded by a non
-virtual object. If not occluded, the path can be blue or turquoise whether it
-reaches a receiver or not, respectively. Finally, the path can also be red if
-it was canceled due to a topologically incoherent impact (i.e. an impact on a
-surface not at the boundary of the medium in which the rays was propagating).
-The following grammar describes the formatting of a *VTK-RADIATIVE-PATHS*
-file. Refer to the VTK format specification [2] for more informations on the
-VTK file format.
+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.
+
+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.
+
+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.
[verse]
_______
-VTK-RADIATIVE-PATHS ::= # vtk DataFile Version 2.0
- Radiative paths
- ASCII
- DATASET POLYDATA
- POINTS <#vertices> float
- <paths-vertices>
- LINES <#paths> <#paths+#vertices>
- <paths-lists>
- CELL_DATA <#paths>
- SCALAR Radiative_path_type float 1
- LOOKUP_TABLE path_type
- <paths-type>
- LOOKUP_TABLE path_type 5
- <color-error>
- <color-unused>
- <color-success>
- <color-missing>
- <color-occluded>
-
-<paths-vertices> ::= <real3>
- [ <real3> ... ] # up to <#vertices>
-
-<paths-lists> ::= <radiative-path>
- [ <radiative-path> ... ] # up to <#path>
-
-<radiative-path> ::= <#path-segments> <path-vertex-id> ...
-
-<paths-type> ::= <color-id>
- [ <color-id> ... ] # up to <#paths>
-
-<color-id> ::= 0.0 # Red: for error paths
- | 0.25 # Green: unused
- | 0.5 # Blue: for success paths
- | 0.75 # Turquoise: for missing paths
- | 1.0 # Yellow: for occluded paths
-
-<color-error> ::= 1.0 0.0 0.0 1.0
-<color-unused> ::= 0.0 1.0 0.0 1.0
-<color-success> ::= 0.0 0.0 1.0 1.0
-<color-missing> ::= 0.0 1.0 1.0 1.0
-<color-occluded> ::= 1.0 1.0 0.0 1.0
-
-<#paths> ::= INTEGER
-<#path-segments> ::= INTEGER
-<path-vertex-id> ::= INTEGER
+<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 image of the
-solar facility for each submitted sun direction. Each image is preceded by its
-associated sun direction and is saved with respect to the ASCII PPM file
-format [1]. The output images are actually greyscale images whose pixels store
-the average normalized radiance that reaches them.
+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 file format [1].
NOTES
-----
-1. Portable PixMap - <http://netpbm.sourceforge.net/doc/ppm.html>
-2. VTK file format -
+1. VTK file format -
<http://www.vtk.org/wp-content/uploads/2015/04/file-formats.pdf>
-3. OBJ file format -
- <http://www.martinreddy.net/gfx/3d/OBJ.spec>
+2. Portable PixMap - <http://netpbm.sourceforge.net/doc/ppm.html>
SEE ALSO
--------
*stardis*(1),
-*stardis-input*(5),
-*stardis-receiver*(5)
+*stardis-input*(5)
diff --git a/doc/stardis.1.txt.in b/doc/stardis.1.txt.in
@@ -32,7 +32,7 @@ DESCRIPTION
-----------
*stardis* solves coupled thermal systems under the linear assumption. Here
coupled refers to conductive, convective and radiative transfers, and linear
-means that each phenomena is represented using a model that is linear
+means that each phenomena is represented using a model that is linear
with temperature. *stardis* can deal with complex geometries as well as
high-frequency external solicitations over a very long period of time,
relative to the characteristic time of the system.
@@ -51,13 +51,13 @@ information on the system in an unbiased and very-fast statistical model.
In addition of the aforementioned computations, *stardis* provides three
other functionalities. The *-d* option can be used to convert the
*stardis-input*(5) geometry into a VTK file. The *-D* option saves the sampled
-thermal paths used by the estimates, allowing to visualise them externally
+heat paths used by the estimates, allowing to visualise them externally
which may be of a great help to identify issues. Finally, the *-R* option
can be used to render an infrared image of the submitted system.
The provided system should be described in the *stardis-input*(5) format
and can be split over any number of files, each being submited through the
-*-M* option.
+*-M* option.
Stardis' algorithms are based on state-of-the-art Monte-Carlo method applied
to radiative transfer physics (Delatorre [1]) combined with conduction's
@@ -71,7 +71,7 @@ by Intel® Rendering Framework: Embree.
Everytime the linear assumption is relevant, this theoretical framework allows
to encompass all the heat transfer mecanisms (conductive-convective-radiative)
in an unified statistical model. Such systems can be solved by a Monte-Carlo
-approach just by sampling thermal paths. This can be seen as an extension of
+approach just by sampling heat paths. This can be seen as an extension of
Monte-Carlo algorithms that solve radiative transfer by sampling optical paths.
A main property of this approach is that the resulting algorithms does not rely
on a volume mesh of the system.
@@ -107,9 +107,9 @@ EXCLUSIVE OPTIONS
closest interface.
*-m* _medium_name[,time]_::
- Compute the mean temperature in a given medium at a given time. By default
- compute time is @STARDIS_ARGS_DEFAULT_COMPUTE_TIME@. The medium doesn't need
- to be connex.
+ Compute the mean temperature in a given medium at a given time. The medium
+ name must be part of the system description. By default compute time is
+ @STARDIS_ARGS_DEFAULT_COMPUTE_TIME@. The medium doesn't need to be connex.
*-s* _file[,time]_::
Compute the mean temperature on a given 2D region at a given time, the
@@ -151,12 +151,12 @@ EXCLUSIVE OPTIONS
**spp=**_samples-count_;;
Number of samples per pixel.
- By default, use @STARDIS_ARGS_DEFAULT_RENDERING_SPP@ samples per pixel.
+ By default, use @STARDIS_ARGS_DEFAULT_RENDERING_SPP@ samples per pixel.
**t=**_time_;;
Rendering time. By default _time_ is @STARDIS_ARGS_DEFAULT_RENDERING_TIME@
- seconds.
-
+ seconds.
+
**tgt=**_x_**,**_y_**,**_z_;;
Position targeted by the camera. By default, it is set to
{@STARDIS_ARGS_DEFAULT_RENDERING_TGT@} or it is automatically computed to
@@ -177,16 +177,16 @@ OTHER OPTIONS
*-d*::
Write the geometry to _standard output_ in VTK format along with various
- properties, including possible errors. If this option is used, no
+ properties, including possible errors. If this option is used, no
computation occurs.
+
Using this option in conjunction with an option that
specifies a compute region (-s, -S, -F) has the effect to include the
region in the output. This option cannot be used in conjunction with other
-options that write to _standard output_ (-R, -g, -D, -h, -v).
+options that write to _standard output_ (-R, -g, -D, -h, -v).
*-D* _type_::
- Write thermal paths of the given *type* to _standard output_ in VTK format.
+ Write heat paths of the given *type* to _standard output_ in VTK format.
Possible values are *error* (write paths ending in error), *success*
(write successful paths),*all* (write all paths).
+
@@ -201,14 +201,14 @@ with other options that write to _standard output_ (-R, -d, -g, -h, -v).
*-g*::
Write the green function at a steady state to _standard output_ after the
- specified computation.
+ specified computation.
+
This option can only be used in conjonction with one these options: -p, -P,
-m, -s. Any provided compute time is silently ignored.
*-h*::
Output short help and exit.
-
+
*-n* _samples-count_::
Number of Monte-Carlo samples. By default _samples-count_ is set to
@STARDIS_ARGS_DEFAULT_SAMPLES_COUNT@.
