commit ab1841b45be0a828e9f8cc618d804bf7d20b1548
parent 610545a24321674bbff4dcc1400f378801291ead
Author: Vincent Forest <vincent.forest@meso-star.com>
Date: Tue, 23 May 2017 11:47:26 +0200
Rewrite some parts of the solstice-output man page
Diffstat:
1 file changed, 81 insertions(+), 82 deletions(-)
diff --git a/doc/solstice-output.5.txt b/doc/solstice-output.5.txt
@@ -28,9 +28,9 @@ 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.
+directions. In other words, invoking *solstice*(1) with _N_ 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
@@ -41,7 +41,6 @@ collected by the submitted solar plant. When invoked with the *-g* option,
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
@@ -192,56 +191,55 @@ 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:
+Each global result is a pair of real numbers: the expected value and its
+standard error. The global results are, in this order:
-- *potential-irradiance*: the maximum irradiance that all the primary
+- *potential-irradiance*: maximum irradiance that all the primary
geometries could intercept if properly oriented;
-- *absorbed-irradiance*: the absorbed part of the irradiance hitting any
+- *absorbed-irradiance*: absorbed part of the irradiance reaching any
receiver geometry. At most equal to potential irradiance;
-- *cos-factor*: the fraction of incoming irradiance not intercepted by the
+- *cos-factor*: 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
+- *shadow-loss*: irradiance lost before reaching primary geometries due to the
+ shadow of another geometry;
+- *missing-loss*: irradiance that reaches a primary geometry, 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
+ path, can have missed the receivers, or can have reach a receiver but
+ without being absorbed;
+- *reflectivity-loss*: additional irradiance that could have been absorbed
+ by receivers if reflections had occurred on materials with reflectivity 1.0;
+- *absorptivity-loss*: 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:
+After the global results, the output includes various per-receiver lines, one
+line per receiver, the exact number of lines being part of the headers. Each
+line contains the following data:
-- *receiver-name*: the name of the receiver, from the input file;
-- *receiver-id*: an unique integer identifying the receiver;
+- *receiver-name*: name of the receiver, i.e. *entity-identifier* of the
+ entity in which the receiving geometry is defined (see the
+ *solstice-input*(5) format);
+- *receiver-id*: 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
+- *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.
+
+- *absorbed-irradiance*: irradiance absorbed by the receiver side;
+- *irradiance*: irradiance that reaches the receiver side;
+- *reflectivity-loss*: irradiance that could have been absorbed by the
+ receiver side if reflections had occurred on materials with reflectivity 1.0;
+- *absorptivity-loss*: irradiance that could have been absorbed by the
+ receiver side if atmospheric absorption had not been taken into account;
+- *efficiency*: fraction of incoming irradiance absorbed by the 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
@@ -251,16 +249,17 @@ 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;
+- *primary-name*: name of the primary geometry, i.e. *entity-identifier* of
+ the entity in in which the primary geometry is defined (see the
+ *solstice-input*(5) format);
+- *primary-id*: unique integer identifying the primary geometry;
- *area*: area of the primary geometry;
-- *#sample*: the number of Monte-Carlo experiments sampled on the primary
+- *#sample*: 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).
+- *cos-factor*: expected value and standard error of the fraction of incoming
+ irradiance not intercepted by the primary geometry due to its orientation;
+- *shadow-loss*: expected value and standard error of the irradiance lost
+ before reaching the primary geometry due to the shadow of another geometry.
Per receiver and per primary results
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
@@ -270,29 +269,29 @@ 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-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.
+
+- *absorbed-irradiance*: irradiance absorbed by the receiver side coming
+ from the primary geometry;
+- *irradiance*: irradiance reaching the receiver side coming from the primary
+ geometry;
+- *reflectivity-loss*: irradiance that could have been absorbed by the
+ receiver side coming from the primary geometry if reflections had occurred
+ on materials with reflectivity 1.0;
+- *absorptivity-loss*: irradiance that could have been absorbed by
+ the receiver side coming from the primary geometry if atmospheric
+ absorption had not been taken into account.
+
+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
~~~~~~~~~~~~
@@ -367,13 +366,13 @@ 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.
+sub-option, *solstice*(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 *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 the end of the current OBJ.
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
@@ -408,8 +407,8 @@ 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
+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]
