commit 8f428968636acf0647f9f13d293b86169924ada5
parent d437d65a72875ba1a1db182ddd39a5c5acdda5b8
Author: Vincent Forest <vincent.forest@meso-star.com>
Date: Mon, 15 May 2017 17:01:19 +0200
First the redaction of the solstice-output man
First draft of the solstice-ouput description and provide its raw
grammar rules.
Diffstat:
1 file changed, 148 insertions(+), 0 deletions(-)
diff --git a/doc/solstice-output.5.ronn b/doc/solstice-output.5.ronn
@@ -0,0 +1,148 @@
+solstice-output(5) -- output format of `solstice`(1) results
+============================================================
+
+## DESCRIPTION
+
+The `solstice-output` describes the output format of the `solstice`(1) program.
+The data generated by a `solstice`(1) invocation are all written in a single
+file or on the standard output whether an _output_ file is defined by 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, and thus how they are formatted,
+depends on the mode in which `solstice`(1) is invoked. By default,
+`solstice`(1) evaluates the power collected by the submitted solar plant and
+its efficiency. 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
+
+ <output> ::= <simulation-output>
+ | <dump-geometry-output>
+ | <dump-radiative-paths-output>
+ | <rendering-output>
+
+ <simulation-output> ::= <sun-direction>
+ <counts>
+ <global>
+ [ <receivers-list> ]
+ [ <primaries-list> ]
+ [ <rcvXprims-list> ]
+ [ <receiver-maps> ]
+ [ <simulation-output> ... ]
+
+ <dump-geometry-output>
+ ::= <sun-direction>
+ <geometry-data>
+ [ <geometry-output> ... ]
+
+ <dump-radiative-paths-output>
+ ::= <sun-direction>
+ VTK-FILE
+ [ <dump-radiative-paths-output> ... ]
+
+ <rendering-output> ::= <sun-direction>
+ PPM-FILE
+ [ <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> ::= <irradiance>
+ <absorbed-irradiance>
+ <cos-factor>
+ <shadow-loss>
+ <missing-loss>
+ <absorptivity-loss>
+ <reflectivity-loss>
+
+ ----------------------------------------
+
+ <receivers-list> ::= <receiver>
+ [ <receiver> ... ]
+
+ <receiver> ::= <receiver-name> <receiver-id> <area> <front> <back>
+
+ <receiver-name> ::= <entity-identifier> # Defined in `solstice-input`(5)
+
+ <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> # Defined in `solstice-input`(5)
+
+ <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-FILE
+ [ <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]
+
+ <absorbed-irradiance> ::= <estimation>
+ <absorptivity-loss> ::= <estimation>
+ <cos-factor> ::= <estimation>
+ <irradiance> ::= <estimation>
+ <missing-loss> ::= <estimation>
+ <reflectivity-loss> ::= <estimation>
+ <shadow-loss> ::= <estimation>
+
+ <estimation> ::= <expected-value> <standard-error>
+ <expected-value> ::= REAL
+ <standar-error> ::= REAL # in [0, INF)
+
+## SEE ALSO
+`solstice`(1),
+`solstice-input`(5)
