commit 8505c8c0125a11b742ae22bc89fe429f46c69e2b
parent 746e2dd93b79c1332d112e4898a807eb5f99f5b2
Author: Vincent Forest <vincent.forest@meso-star.com>
Date: Mon, 22 May 2017 18:40:15 +0200
Convert the solstice-output man from ronn to asciidoc
Diffstat:
3 files changed, 472 insertions(+), 450 deletions(-)
diff --git a/cmake/doc/CMakeLists.txt b/cmake/doc/CMakeLists.txt
@@ -40,7 +40,8 @@ endif()
# Copy doc files
################################################################################
set(MAN_NAMES
- solstice-input.5)
+ solstice-input.5
+ solstice-output.5)
if(A2X OR ASCIIDOC)
set(MAN_FILES)
diff --git a/doc/solstice-output.5.ronn b/doc/solstice-output.5.ronn
@@ -1,449 +0,0 @@
-solstice-output(5) -- output format of `solstice`(1) results
-============================================================
-
-## DESCRIPTION
-
-The `solstice-output` describes the output format of the `solstice`(1) program.
-All the data generated by a `solstice`(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 `solstice`(1), through the `-D` option, will produce as many outputs as sun
-directions. In other words, invoking `solstice`(1) with N several sun
-directions looks like calling `solstice`(1) N times and concatenating their
-associated output.
-
-The type of the data that are generated depends on the mode in which
-`solstice`(1) is invoked. By default, `solstice`(1) evaluates the power
-collected by the submitted solar plant. When invoked with the `-g` option,
-`solstice`(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.
-
-## GRAMMAR
-
-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.
-
- <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> ... ]
-
- ----------------------------------------
-
- <sun-direction> ::= "#--- Sun direction: <azimuth> <elevation> (<real3>)"
-
- <counts> ::= "<#globals> <#receivers> <#primaries>
- <#samples> <#failed>"
-
- <#globals> ::= 7
- <#receivers> ::= INTEGER # in [0, INF)
- <#primaries> ::= INTEGER # in [0, INF)
- <#samples> ::= INTEGER # in [0, INF)
- <#failed> ::= INTEGER # in [0, INF)
-
- <global> ::= <potential-irradiance>
- <absorbed-irradiance>
- <cos-factor>
- <shadow-loss>
- <missing-loss>
- <reflectivity-loss>
- <absorptivity-loss>
-
- ----------------------------------------
-
- <receivers-list> ::= <receiver>
- [ <receiver> ... ]
-
- <receiver> ::= "<receiver-name> <receiver-id> <area>
- <front> <back>"
-
- <receiver-name> ::= <entity-identifier>
-
- <receiver-id> ::= INTEGER
-
- <front> ::= <side>
- <back> ::= <side>
-
- <side> ::= "<absorbed-irradiance> <irradiance>
- <reflectivity-loss> <absorptivity-loss>
- <efficiency>"
-
- ----------------------------------------
-
- <primaries-list> ::= <primary>
- [ <primary> ... ]
-
- <primary> ::= "<primary-name> <primary-id> <area> <#samples>
- <cos-factor> <shadow-loss>"
-
- <primary-name> ::= <entity-identifier>
-
- <primary-id> ::= INTEGER
-
- ----------------------------------------
-
- <rcvXprims-list> ::= <rcvXprim>
- [ <rcvXprim> ... ]
-
- <rcvXprim> ::= "<receiver-id> <primary-id>
- <rcvXprim-front> <rcvXprim-back>"
-
- <rcvXprim-front> ::= <rcvXprim-side>
- <rcvXprim-back> ::= <rcvXprim-side>
-
- <rcvXprim-side> ::= "<absorbed-irradiance> <irradiance>
- <reflectivity-loss> <absorptivity-loss>"
-
- ----------------------------------------
-
- <receiver-maps> ::= VTK-RECEIVER-MAP
- [ <receiver-maps> ... ]
-
- <geometry-data> ::= OBJ-FILE
- [ ---
- <geometry-data> ... ]
-
- ----------------------------------------
-
- <area> ::= REAL # in ]0, INF)
-
- <real3> ::= REAL REAL REAL
-
- <azimuth> ::= REAL # Degrees in [0, 360[
- <elevation> ::= REAL # Degrees in [0, 90]
-
- <potential-irradiance>::= <estimate>
- <absorbed-irradiance> ::= <estimate>
- <absorptivity-loss> ::= <estimate>
- <cos-factor> ::= <estimate>
- <irradiance> ::= <estimate>
- <missing-loss> ::= <estimate>
- <reflectivity-loss> ::= <estimate>
- <shadow-loss> ::= <estimate>
-
- <estimate> ::= <expected-value> <standard-error>
- <expected-value> ::= REAL
- <standard-error> ::= REAL # in [0, INF)
-
- <entity-identifier> # Defined in solstice-input(1)
-
-## SIMULATION
-
-A `simulation-output` begins with two header lines. The first one reports the
-sun direction used in the simulation (azimuth and elevation angles, in
-degrees), 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.
-
-### 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 estimate of the value and
-its standard deviation. The global results are, in this order:
-
-* `potential irradiance`: the maximum irradiance that all the primary
- geometries could intercept if properly oriented,
-* `absorbed irradiance`: the absorbed part of the irradiance hitting any
- receiver geometry. At most equal to potential irradiance,
-* `cos factor`: the fraction of incoming irradiance not intercepted by the
- primary geometries due to their orientation,
-* `shadow loss`: the irradiance lost before hitting primary geometries due to
- another geometry's shadow,
-* `missing loss`: the irradiance having hit primary geometries, but not
- absorbed by a receiver; this irradiance could have been blocked along its
- path, can have missed the receivers, or can have hit a receiver but without
- being absorbed,
-* `reflectivity loss`: the additional irradiance that could have been absorbed
- by receivers if reflections had occured on materials with reflectivity 1.0,
-* `absorptivity loss`: the irradiance that could have been absorbed by
- receivers if atmospheric absorption had not been taken into account.
-
-### Per receiver results
-
-After the global results, the output includes various per-receiver result
-lines, one line per receiver, the exact number of lines being part of the
-headers. Each line contains:
-
-* `name`: the name of the receiver, from the input file,
-* `ID`: an unique integer identifying the receiver,
-* `area`: area of the receiver,
-* `front absorbed irradiance`: the irradiance absorbed by the receiver's front
- face, and its standard deviation (2 real numbers),
-* `front irradiance`: the irradiance hitting the receiver's front face, and its
- standard deviation (2 real numbers),
-* `front reflectivity loss`: the irradiance that could have been absorbed by
- the receiver's front face if reflections had occured on materials with
- reflectivity 1.0, and its standard deviation (2 real numbers),
-* `front absorptivity loss`: the irradiance that could have been absorbed by
- the receiver's front face if atmospheric absorption had not been taken into
- account, and its standard deviation (2 real numbers),
-* `front efficiency`: the fraction of incoming irradiance absorbed by
- the receiver's front face, and its standard deviation (2 real numbers),
-* `back absorbed irradiance`: the irradiance absorbed by the receiver's back
- face, and its standard deviation (2 real numbers),
-* `back irradiance`: the irradiance hitting the receiver's back face, and its
- standard deviation (2 real numbers),
-* `back reflectivity loss`: the irradiance that could have been absorbed by
- the receiver's back face if reflections had occured on materials with
- reflectivity 1.0, and its standard deviation (2 real numbers),
-* `back absorptivity loss`: the irradiance that could have been absorbed by
- the receiver's back face if atmospheric absorption had not been taken into
- account, and its standard deviation (2 real numbers),
-* `back efficiency`: the fraction of incoming irradiance absorbed by
- the receiver's back face, and its standard deviation (2 real numbers)
-
-Both front face and back face results are output, even if the receiver has only
-a single receiving face. In this case, outputs relative to the non-receiving
-face are meaningless (invalid -1 value).
-
-### Per primary results
-
-After 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:
-
-* `name`: the name of the primary geometry, from the input file,
-* `ID`: an unique integer identifying the primary geometry,
-* `area`: area of the primary geometry,
-* `sample count`: the number of Monte-Carlo experiments sampled on the primary
- geometry,
-* `cos factor`: the fraction of incoming irradiance not intercepted by the
- primary geometry due to its orientation, and its standard deviation (2 real
- numbers),
-* `shadow loss`: the irradiance lost before hitting the primary geometry due to
- another geometry's shadow, and its standard deviation (2 real numbers).
-
-### Per receiver and per primary results
-
-After 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`: the ID of the involved receiver,
-* `primary ID`: the ID of the involved primary geometry,
-* `front absorbed irradiance`: the irradiance absorbed by the receiver's front
- face coming from the primary geometry, and its standard deviation (2 real
- numbers),
-* `front irradiance`: the irradiance hitting the receiver's front face coming
- from the primary geometry, and its standard deviation (2 real numbers),
-* `front reflectivity loss`: the irradiance that could have been absorbed by
- the receiver's front face coming from the primary geometry if reflections
- had occured on materials with reflectivity 1.0, and its standard deviation (2
- real numbers),
-* `front absorptivity loss`: the irradiance that could have been absorbed by
- the receiver's front face coming from the primary geometry if atmospheric
- absorption had not been taken into account, and its standard deviation (2
- real numbers),
-* `back absorbed irradiance`: the irradiance absorbed by the receiver's back
- face coming from the primary geometry, and its standard deviation (2 real
- numbers),
-* `back irradiance`: the irradiance hitting the receiver's back face coming
- from the primary geometry, and its standard deviation (2 real numbers),
-* `back reflectivity loss`: the irradiance that could have been absorbed by
- the receiver's back face coming from the primary geometry if reflections
- had occured on materials with reflectivity 1.0, and its standard deviation (2
- real numbers),
-* `back absorptivity loss`: the irradiance that could have been absorbed by
- the receiver's back face coming from the primary geometry if atmospheric
- absorption had not been taken into account, and its standard deviation (2
- real numbers).
-
-Both front face and back face results are output, even if the receiver has only
-a single receiving face. In this case, outputs relative to the non-receiving
-face are meaningless (invalid -1 value).
-
-### Receiver map
-
-A receiver defined in the submitted `solstice-receiver`(5) file, can have a
-per-primitive irradiance estimate if its `per_primitive` flag is active. In
-this case, `solstice`(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 irradiance. The "definition" of the
-receiver map is thus controlled by the discretisation of the receiver's shape,
-as described in the `solstice-input`(5) file. Note that to obtain a good
-estimate of the per-triangle irradiance, 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 `solstice`(1) should be increased significantly, as 1 or 2 order of
-magnitude.
-
-If only the front or the back side of the receiver is active, then only one set
-of per triangle irradiance estimate is written. If the `side` attribute of
-the receiver is set to `FRONT_AND_BACK`, the irradiance estimate for the
-front facing triangles are written before to the estimate of the back facing
-ones. 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.
-
-
- 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> ::= CELL_DATA <#triangles>
- SCALARS <side-name> float 2
- LOOKUP_TABLE default
- <irradiance>
- [ <irradiance> ... ]
-
- <map-side-name> ::= Front_faces | Back_faces
-
- <#triangles> ::= INTEGER
- <#vertices> ::= INTEGER
- <triangle-indices> ::= INTEGER INTEGER INTEGER
-
-## DUMP GEOMETRY
-
-A `dump-geometry-output` is generated when `solstice`(1) is invoked with the
-`-g` option. In this mode, for each submitted sun direction, `solstice`(1)
-converts the geometry of the submitted `solstice-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 `solstice`(1) is the Alias Wavefront OBJ [3] format. With no more
-sub-option, `solstice`(1) will thus generate an OBJ file containing the whole
- solar plant mesh. 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 `solstice-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
-description boundaries.
-
-Independently of the `split` strategy, each `solstice-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.
-
- OBJ-FILE ::= g <entity-identifier>
- <obj-mesh>
- [ <obj-mesh> ... ]
-
- <obj-mesh> ::= usemtl <material-type>
- <obj-vertices>
- <obj-faces>
-
- <obj-vertices> ::= v <real3>
- [ v <real3> ... ]
-
- <obj-indices> ::= f <triangle-indices>
- [ f <triangle-indices> ... ]
-
-
-## 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 trajectory: the path is blue or yellow whether it reaches
-or not a receiver, respectively. A path can be red if its first segment, i.e.
-the ray starting from the sun toward a primary geometry, is occluded by a non
-virtual object. 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.
-
- 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 3
- <color-occlude>
- <color-success>
- <color-missing>
-
- <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 # occlude
- | 0.5 # success
- | 1.0 # missing
-
- <color-occlude> ::= 1.0 0.0 0.0 1.0
- <color-success> ::= 0.0 0.0 1.0 1.0
- <color-missing> ::= 1.0 1.0 0.0 1.0
-
- <#paths> ::= INTEGER
- <#path-segments> ::= INTEGER
- <path-vertex-id> ::= INTEGER
-
-## NOTES
-
-* [1]:
- Portable PixMap - <http://netpbm.sourceforge.net/doc/ppm.html>
-* [2]:
- 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>
-
-## SEE ALSO
-`solstice`(1),
-`solstice-input`(5),
-`solstice-receiver`(5)
diff --git a/doc/solstice-output.5.txt b/doc/solstice-output.5.txt
@@ -0,0 +1,470 @@
+// Copyright (C) CNRS 2016-2017
+//
+// This is free documentation: you can redistribute it and/or modify
+// it under the terms of the GNU General Public License as published by
+// the Free Software Foundation, either version 3 of the License, or
+// (at your option) any later version.
+//
+// This manual is distributed in the hope that it will be useful,
+// but WITHOUT ANY WARRANTY; without even the implied warranty of
+// MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
+// GNU General Public License for more details.
+//
+// You should have received a copy of the GNU General Public License
+// along with this program. If not, see <http://www.gnu.org/licenses/>.
+:toc:
+
+solstice-output(5)
+==================
+
+NAME
+----
+solstice-output - output format of solstice(1) results
+
+DESCRIPTION
+-----------
+The *solstice-output* describes the output format of the *solstice*(1) program.
+All the data generated by a *solstice*(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 *solstice*(1), through the *-D* option, will produce as many outputs as sun
+directions. In other words, invoking *solstice*(1) with N several sun
+directions looks like calling *solstice*(1) N times and concatenating their
+associated output.
+
+The type of the data that are generated depends on the mode in which
+*solstice*(1) is invoked. By default, *solstice*(1) evaluates the power
+collected by the submitted solar plant. When invoked with the *-g* option,
+*solstice*(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.
+
+GRAMMAR
+-------
+
+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> ... ]
+
+-------------------------------------
+
+<sun-direction> ::= "#--- Sun direction: <azimuth> <elevation> (<real3>)"
+
+<counts> ::= "<#globals> <#receivers> <#primaries>
+ <#samples> <#failed>"
+
+<#globals> ::= 7
+<#receivers> ::= INTEGER # in [0, INF)
+<#primaries> ::= INTEGER # in [0, INF)
+<#samples> ::= INTEGER # in [0, INF)
+<#failed> ::= INTEGER # in [0, INF)
+
+<global> ::= <potential-irradiance>
+ <absorbed-irradiance>
+ <cos-factor>
+ <shadow-loss>
+ <missing-loss>
+ <reflectivity-loss>
+ <absorptivity-loss>
+
+-------------------------------------
+
+<receivers-list> ::= <receiver>
+ [ <receiver> ... ]
+
+<receiver> ::= "<receiver-name> <receiver-id> <area>
+ <front> <back>"
+
+<receiver-name> ::= <entity-identifier>
+
+<receiver-id> ::= INTEGER
+
+<front> ::= <side>
+<back> ::= <side>
+
+<side> ::= "<absorbed-irradiance> <irradiance>
+ <reflectivity-loss> <absorptivity-loss>
+ <efficiency>"
+
+-------------------------------------
+
+<primaries-list> ::= <primary>
+ [ <primary> ... ]
+
+<primary> ::= "<primary-name> <primary-id> <area> <#samples>
+ <cos-factor> <shadow-loss>"
+
+<primary-name> ::= <entity-identifier>
+
+<primary-id> ::= INTEGER
+
+-------------------------------------
+
+<rcvXprims-list> ::= <rcvXprim>
+ [ <rcvXprim> ... ]
+
+<rcvXprim> ::= "<receiver-id> <primary-id>
+ <rcvXprim-front> <rcvXprim-back>"
+
+<rcvXprim-front> ::= <rcvXprim-side>
+<rcvXprim-back> ::= <rcvXprim-side>
+
+<rcvXprim-side> ::= "<absorbed-irradiance> <irradiance>
+ <reflectivity-loss> <absorptivity-loss>"
+
+-------------------------------------
+
+<receiver-maps> ::= VTK-RECEIVER-MAP
+ [ <receiver-maps> ... ]
+
+<geometry-data> ::= OBJ-FILE
+ [ ---
+ <geometry-data> ... ]
+
+-------------------------------------
+
+<area> ::= REAL # in ]0, INF)
+
+<real3> ::= REAL REAL REAL
+
+<azimuth> ::= REAL # Degrees in [0, 360[
+<elevation> ::= REAL # Degrees in [0, 90]
+
+<potential-irradiance>::= <estimate>
+<absorbed-irradiance> ::= <estimate>
+<absorptivity-loss> ::= <estimate>
+<cos-factor> ::= <estimate>
+<irradiance> ::= <estimate>
+<missing-loss> ::= <estimate>
+<reflectivity-loss> ::= <estimate>
+<shadow-loss> ::= <estimate>
+
+<estimate> ::= <expected-value> <standard-error>
+<expected-value> ::= REAL
+<standard-error> ::= REAL # in [0, INF)
+
+<entity-identifier> # Defined in *solstice-input*(1)
+_______
+
+SIMULATION
+----------
+
+A *simulation-output* begins with two header lines. The first one reports the
+sun direction used in the simulation (azimuth and elevation angles, in
+degrees), 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.
+
+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 estimate of the value and
+its standard deviation. The global results are, in this order:
+
+- *potential-irradiance*: the maximum irradiance that all the primary
+ geometries could intercept if properly oriented;
+- *absorbed-irradiance*: the absorbed part of the irradiance hitting any
+ receiver geometry. At most equal to potential irradiance;
+- *cos-factor*: the fraction of incoming irradiance not intercepted by the
+ primary geometries due to their orientation;
+- *shadow-loss*: the irradiance lost before hitting primary geometries due to
+ another geometry's shadow;
+- *missing-loss*: the irradiance having hit primary geometries, but not
+ absorbed by a receiver; this irradiance could have been blocked along its
+ path, can have missed the receivers, or can have hit a receiver but without
+ being absorbed;
+- *reflectivity-loss*: the additional irradiance that could have been absorbed
+ by receivers if reflections had occured on materials with reflectivity 1.0;
+- *absorptivity-loss*: the irradiance that could have been absorbed by
+ receivers if atmospheric absorption had not been taken into account.
+
+Per receiver results
+~~~~~~~~~~~~~~~~~~~~
+
+After the global results, the output includes various per-receiver result
+lines, one line per receiver, the exact number of lines being part of the
+headers. Each line contains:
+
+- *receiver-name*: the name of the receiver, from the input file;
+- *receiver-id*: an unique integer identifying the receiver;
+- *area*: area of the receiver;
+- *front*: estimates for the receiver front side;
+- *back*: estimates for the receiver back side.
+
+The *front* and *back* estimates are:
+
+- *absorbed-irradiance*: the irradiance absorbed by the receiver's side and
+ its standard deviation (2 real numbers);
+- *irradiance*: the irradiance hitting the receiver's side, and its standard
+ deviation (2 real numbers);
+- *reflectivity-loss*: the irradiance that could have been absorbed by
+ the receiver's side if reflections had occured on materials with
+ reflectivity 1.0, and its standard deviation (2 real numbers);
+- *absorptivity-loss*: the irradiance that could have been absorbed by
+ the receiver's side if atmospheric absorption had not been taken into
+ account, and its standard deviation (2 real numbers);
+- *efficiency*: the fraction of incoming irradiance absorbed by
+ the receiver's side, and its standard deviation (2 real numbers);
+
+Both front and back side results are output, even if the receiver has only a
+single receiving side. In this case, outputs relative to the non-receiving
+side are meaningless (invalid -1 value).
+
+Per primary results
+~~~~~~~~~~~~~~~~~~~
+
+After 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*: the name of the primary geometry, from the input file;
+- *primary-id*: an unique integer identifying the primary geometry;
+- *area*: area of the primary geometry;
+- *#sample*: the number of Monte-Carlo experiments sampled on the primary
+ geometry;
+- *cos-factor*: the fraction of incoming irradiance not intercepted by the
+ primary geometry due to its orientation, and its standard deviation (2 real
+ numbers);
+- *shadow-loss*: the irradiance lost before hitting the primary geometry due to
+ another geometry's shadow, and its standard deviation (2 real numbers).
+
+Per receiver and per primary results
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+After 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*: the ID of the involved receiver;
+- *primary-id*: the ID of the involved primary geometry;
+- *rcvXprim-front*: estimates for the receiver front side;
+- *rcvXprim-back*: estimates for the receiver back side;
+
+The *rcvXprim-front* and *rcvXprim-back* estimates are:
+
+- *absorbed-irradiance*: the irradiance absorbed by the receiver's side coming
+ from the primary geometry, and its standard deviation (2 real numbers);
+- *irradiance*: the irradiance hitting the receiver's side coming from the
+ primary geometry, and its standard deviation (2 real numbers);
+- *reflectivity-loss*: the irradiance that could have been absorbed by the
+ receiver's side coming from the primary geometry if reflections had occured
+ on materials with reflectivity 1.0, and its standard deviation (2 real
+ numbers);
+- *absorptivity-loss*: the irradiance that could have been absorbed by
+ the receiver's side coming from the primary geometry if atmospheric
+ absorption had not been taken into account, and its standard deviation (2
+ real numbers).
+
+Both front face and back sides are output, even if the receiver has only a
+single receiving side. In this case, outputs relative to the non-receiving
+side are meaningless (invalid -1 value).
+
+Receiver map
+~~~~~~~~~~~~
+
+A receiver defined in the submitted *solstice-receiver*(5) file, can have a
+per-primitive irradiance estimate if its *per_primitive* flag is active. In
+this case, *solstice*(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 irradiance. The "definition" of the
+receiver map is thus controlled by the discretisation of the receiver's shape,
+as described in the *solstice-input*(5) file. Note that to obtain a good
+estimate of the per-triangle irradiance, 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 *solstice*(1) should be increased significantly, as 1 or 2 order of
+magnitude.
+
+If only the front or the back side of the receiver is active, then only one set
+of per triangle irradiance estimate is written. If the *side* attribute of
+the receiver is set to *FRONT_AND_BACK*, the irradiance estimate for the
+front facing triangles are written before to the estimate of the back facing
+ones. 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.
+
+[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> ::= CELL_DATA <#triangles>
+ SCALARS <side-name> float 2
+ LOOKUP_TABLE default
+ <irradiance>
+ [ <irradiance> ... ]
+
+<map-side-name> ::= Front_faces | Back_faces
+
+<#triangles> ::= INTEGER
+<#vertices> ::= INTEGER
+<triangle-indices> ::= INTEGER INTEGER INTEGER
+_______
+
+DUMP GEOMETRY
+-------------
+
+A *dump-geometry-output* is generated when *solstice*(1) is invoked with the
+*-g* option. In this mode, for each submitted sun direction, *solstice*(1)
+converts the geometry of the submitted *solstice-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 *solstice*(1) is the Alias Wavefront OBJ [3] format. With no more
+sub-option, *solstice*(1) will thus generate an OBJ file containing the whole
+ solar plant mesh. 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 *solstice-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
+description boundaries.
+
+Independently of the *split* strategy, each *solstice-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.
+
+[verse]
+_______
+OBJ-FILE ::= g <entity-identifier>
+ <obj-mesh>
+ [ <obj-mesh> ... ]
+
+<obj-mesh> ::= usemtl <material-type>
+ <obj-vertices>
+ <obj-faces>
+
+<obj-vertices> ::= v <real3>
+ [ v <real3> ... ]
+
+<obj-indices> ::= f <triangle-indices>
+ [ f <triangle-indices> ... ]
+_______
+
+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 trajectory: the path is blue or yellow whether it reaches
+or not a receiver, respectively. A path can be red if its first segment, i.e.
+the ray starting from the sun toward a primary geometry, is occluded by a non
+virtual object. 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.
+
+[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 3
+ <color-occlude>
+ <color-success>
+ <color-missing>
+
+<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 # occlude
+ | 0.5 # success
+ | 1.0 # missing
+
+<color-occlude> ::= 1.0 0.0 0.0 1.0
+<color-success> ::= 0.0 0.0 1.0 1.0
+<color-missing> ::= 1.0 1.0 0.0 1.0
+
+<#paths> ::= INTEGER
+<#path-segments> ::= INTEGER
+<path-vertex-id> ::= INTEGER
+_______
+
+NOTES
+-----
+1. Portable PixMap - <http://netpbm.sourceforge.net/doc/ppm.html>
+2. 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>
+
+SEE ALSO
+--------
+*solstice*(1),
+*solstice-input*(5),
+*solstice-receiver*(5)
