commit 32db8269a3fdf90b9f29062e18fb5711ffd2f208
parent 5f9bd6a74bc84391c20c2ec303037a349e194567
Author: Vincent Forest <vincent.forest@meso-star.com>
Date: Thu, 18 May 2017 12:14:40 +0200
Write the solstice-receiver man
Diffstat:
1 file changed, 80 insertions(+), 0 deletions(-)
diff --git a/doc/solstice-receiver.5.ronn b/doc/solstice-receiver.5.ronn
@@ -0,0 +1,80 @@
+solstice-receiver(5) -- declare the solar-plant receivers for `solstice`(1)
+===========================================================================
+
+## DESCRIPTION
+
+The `solstice-receiver` format is used by `solstice`(1) to declare which
+geometric entities defined in a `solstice-input`(5) file are receivers. For
+each receiver, `solstice`(1) computes its overall intercepted power, its
+associated losses as well as its efficiency. Refer to the `solstice-output`(5)
+format for informations on the per receiver data generated by `solstice`(1).
+Declaring the receivers separately of the solar plant, allows to use the same
+`solstice-input`(5) file for several simulations using different receivers. For
+instance, one can define a specific `solstice-receiver` file that declares some
+primary reflectors as receivers in order to track an unforeseen comportment
+observed during a previous simulation.
+
+The `solstice-receiver` format uses the YAML 1.1 data serialization standard
+[1]; assuming that the file is compatible with the `solstice-receiver`
+semantic, the YAML compact notation can thus be used.
+
+A receiver is identified by its `name` that must be a valid `entity-identifier`
+as defined in the `solstice-input`(5) format. This identifier must reference a
+geometric entity and not a pivot or an empty entity. The side of the geometry
+that is tracked is defined by the `side` attribute of the receiver. Note that
+the front and the back side of a geometry can be both considered if the `side`
+attribute is set to `FRONT_AND_BACK`. Refer to the `solstice-input`(5)
+specification for informations on which side of the geometry is front facing or
+back facing. Finally, if the optional `per_primitive` flag is set to `1`,
+`solstice`(1) will estimate the irradiance for each triangle of the receiver
+and use these data to generate a receiver map as described in
+`solstice-output`(5).
+
+## GRAMMAR
+
+ <receivers-list> ::= - <receiver>
+ [ - <receiver> ... ]
+
+ <receiver> ::= name: <entity-identifier>
+ side: <side-identifier>
+ [ per_primitive: INTEGER ] # in [0, 1]
+
+ <side-identifier> ::= FRONT
+ | BACK
+ | FRONT_AND_BACK
+
+ <entity-identifier> # Defined in solstice-input(1)
+
+## EXAMPLES
+
+Define that the entity `small_square` is a receiver for both its front and back
+side. Enable the estimation of its per triangle front and back irradiance.
+
+ - name: small_square
+ side: FRONT_AND_BACK
+ per_primitive: 1
+
+Declare 3 reflectors as receivers for their front side. Use the YAML compact
+notation to reduce the number of lines:
+
+ - {name: H1.heliostat.reflector, side: FRONT}
+ - {name: H4.heliostat.reflector, side: FRONT}
+ - {name: H7.heliostat.reflector, side: FRONT}
+
+Declare that the back side of `receiver` is effectively a receiver and enable
+the estimation of its associated irradiance map. Make a receiver from the front
+side of the reflector named `LFR0.pivot.reflector`:
+
+ - {name: receiver, side: BACK, per_primitive: 1}
+ - {name: LFR0.pivot.reflector, side: FRONT}
+
+## NOTES
+
+* [1]:
+ YAML Ain't Markup Language - <http://yaml.org>
+
+## SEE ALSO
+`solstice`(1),
+`solstice-input`(5),
+`solstice-output`(5)
+
