SOLSTICE-OUTPUT(5) File Formats Manual SOLSTICE-OUTPUT(5)

solstice-output — output format of solstice

The solstice-output format describes the output produced by the solstice(1) program. All data generated by a solstice(1) invocation are written to a single file or to standard output, depending on whether an output file is specified through the -o option or not. Submitting several sun directions to solstice(1) through the -D option produces as many outputs as sun directions: invoking solstice(1) with N sun directions is equivalent to calling it N times and concatenating the associated outputs.

The type of data 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, it converts the solar plant geometries into a list of CAO files. The -p option tracks the sampled radiative paths, and the -r option renders an image of the solar facility.

Output values are mainly ASCII data formatted line by line. By convention, line data in the following grammar are listed between quote marks. The grammar may span multiple lines for formatting purposes, but data are on a single line until a closing quote mark.

<o>              ::= <simulation-output>
                   | <dump-geometry-output>        # -g option
                   | <dump-radiative-paths-output> # -p option
                   | <rendering-output>            # -r option

<simulation-output>
                 ::= <sun-specification>
                     <counts>
                     <global>
                   [ <receivers-list> ]
                   [ <primaries-list> ]
                   [ <rcvXprims-list> ]
                   [ <receiver-maps> ]
                   [ <simulation-output> ... ]

<dump-geometry-output>
                 ::= <sun-specification>
                     <geometry-data>
                   [ <dump-geometry-output> ... ]

<dump-radiative-paths-output>
                 ::= <sun-specification>
                     VTK-RADIATIVE-PATHS
                   [ <dump-radiative-paths-output> ... ]

<rendering-output>
                 ::= <sun-specification>
                     PPM-FILE # ASCII PPM with 8-bits per component [1]
                   [ <rendering-output> ... ]

<sun-specification>
                 ::= <sun-direction>
                   | <sun-time>

<sun-direction>  ::= "#--- Sun direction: <azimuth> <elevation> (<sun-vector>)"

<sun-time>       ::= "#--- Sun location and time: <lat> <long> <time> (<sun-vector>)"

<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-flux>
                     <absorbed-flux>
                     <cos-factor>
                     <shadow-loss>
                     <missing-loss>
                     <materials-loss>
                     <atmospheric-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>           ::= "<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>"
<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>  ::= "<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>"
<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]
<sun-vector>     ::= <real3>
<lat>            ::= REAL # Degrees in [-90, +90]
<long>           ::= REAL # Degrees in [-180, +180]
<time>           ::= STRING # Same YYYY-MM-DDThh:mm:ss format as on the CLI

<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 solstice-input(5)

A begins with two header lines. The first reports the sun direction used in the simulation (two angles in degrees, plus the corresponding sun vector). The second lists the numbers of global, per-receiver and per-primary results, as well as the overall number of Monte-Carlo experiments and the number of experiments that failed due to unforeseen errors such 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 an "Error in integrating the solar flux" message, and the validity of subsequent results is questionable: estimates are produced using the number of successful experiments, which is necessarily smaller than the required number.

After the two header lines, the output includes various result lines; the exact number is given in the header (currently 7). Each global result is a pair of real numbers: the expected value and its standard error. The global results are, in order:

Maximum flux that all primary geometries could intercept if properly oriented and flat-shaped.
Absorbed part of the flux reaching any receiver geometry. At most equal to the potential flux.
Cosine of the angle between the sun direction and the normal of the primary surfaces (average over all primary geometries).
Potential flux intercepted by another geometry before reaching a primary geometry.
Part of the flux that reaches a primary geometry and follows a radiative path but is not absorbed; this flux may have bounced on geometries, including receivers, without being absorbed.
Total flux absorbed by non-receivers along radiative paths; includes both surface and volume absorption.
Total flux extinction by the atmosphere along radiative paths.

These 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.

Following the global results, the output includes one line per receiver, sorted according to the order of the receivers as defined in the submitted solstice-receiver(5) file. Each line contains:

Name of the receiver, i.e. the entity-identifier of the entity in which the receiving geometry is defined (see solstice-input(5)).
Unique integer identifying the receiver.
Area of the receiver.
Estimated results for the front side of the receiver.
Estimated results for the back side of the receiver.

The estimates for the front and back sides are as follows (each is a pair: expected value and standard error):

Flux that reaches the receiver side.
Incoming flux if absorption on non-receivers is not taken into account.
Incoming flux if atmospheric extinction is not taken into account.
- incoming-flux.
- incoming-flux.
Flux absorbed by the receiver side.
Absorbed flux if absorption by non-receivers is not taken into account.
Absorbed flux if atmospheric extinction is not taken into account.
- absorbed-flux.
- absorbed-flux.
Fraction of the potential flux absorbed by this receiver side.

Both front and back side estimates are always output, even if the receiver has only a single receiving side. In that case, the results of the non-receiving side are meaningless (invalid -1 value).

Following the per-receiver results, the output includes one line per primary geometry. Each line contains:

Name of the primary geometry, i.e. the entity-identifier of the entity in which the primary geometry is defined (see solstice-input(5)).
Unique integer identifying the primary geometry.
Area of the primary geometry.
Number of Monte-Carlo experiments sampled on the primary geometry.
Cosine of the angle between the sun direction and the normal of the primary surface (average over the primary geometry).
Potential flux intercepted by another geometry before reaching this primary geometry.

Following the per-primary results, the output includes result lines describing the contribution of each primary geometry to each receiver. The total number of such lines is the number of receivers times the number of primary geometries. Each line contains:

Identifier of the involved receiver.
Identifier of the involved primary geometry.
Estimated results for the receiver front side.
Estimated results for the receiver back side.

The estimated values of rcvXprim-front and rcvXprim-back are as follows (each is a pair: expected value and standard error):

Flux that reaches the receiver side.
Incoming flux if absorption on non-receivers is not taken into account.
Incoming flux if atmospheric extinction is not taken into account.
- incoming-flux.
- incoming-flux.
Flux absorbed by the receiver side.
Absorbed flux if absorption by non-receivers is not taken into account.
Absorbed flux if atmospheric extinction is not taken into account.
- absorbed-flux.
- absorbed-flux.

Both front and back side estimates are always output, even if the receiver has only a single receiving side. In that case, the results of the non-receiving side are meaningless (invalid -1 value).

A receiver defined in the submitted solstice-receiver(5) file can have a per-primitive estimate of its incoming flux density and/or absorbed flux density if its flag is active. In this case, solstice(1) generates a : an ASCII VTK file (see NOTES, reference 2) that stores the triangular mesh of the receiver and, for each triangle, the estimate of its associated incoming and/or absorbed flux density. The resolution of the receiver map is thus controlled by the discretization of the receiver's shape as described in the solstice-input(5) file. To obtain a good estimate of the per-triangle flux densities, the number of per-triangle experiments must be sufficient; since only a small fraction of the overall sampled radiative paths reach a given triangle, the total number of experiments specified through the -n option of solstice(1) should be increased significantly, by 1 or 2 orders of magnitude.

The number of written per-triangle flux density estimates depends on the receiver's parameters: both front and back sides can be active, and each side can produce an estimate for both incoming and absorbed flux density. As a consequence, the output can include up to 4 different estimates, written in the order: incoming front, absorbed front, incoming back, absorbed back. The following grammar describes the formatting of a . Refer to the VTK format specification (reference 2) for more information 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>       ::= <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

A is generated when solstice(1) is invoked with the -g option. For each submitted sun direction, solstice(1) converts the geometry of the submitted solstice-input(5) file into triangular meshes written to the output in the format specified by the format sub-option of -g. The only currently supported format is Alias Wavefront OBJ (reference 3). With no further sub-option, a single OBJ file containing the whole mesh of the solar plant is generated. The split sub-option of -g allows generating several OBJ descriptions, one per geometry or per object as defined in the solstice-input(5) format; each description is then followed by a line containing "---" to mark the end of the current OBJ.

Regardless of the split strategy, each geometry is an OBJ group whose name is the entity-identifier of the entity in which it is encapsulated. The OBJ directive associates to each mesh the name of its material type. The following grammar describes the formatting of an . Refer to the OBJ format specification (reference 3) for more information.

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> ... ]

<material-type>  ::= dielectric
                   | matte
                   | mirror
                   | thin_dielectric
                   | virtual

For each sun direction, the lists the geometric data of the radiative paths sampled during a simulation. Each path is coloured according to its type:

Yellow
The first segment (the ray from the sun toward a primary geometry) is occluded by a non-virtual object.
Blue
The path is not occluded and reaches a receiver.
Turquoise
The path is not occluded and does not reach a receiver.
Red
The path was cancelled due to a topologically incoherent impact (an impact on a surface not at the boundary of the medium in which the ray was propagating).

The following grammar describes the formatting of a file. Refer to the VTK format specification (reference 2) for more information.

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 <#paths>

<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

When invoked with the -r option, solstice(1) generates one image of the solar facility per submitted sun direction. Each image is preceded by its associated sun direction and saved in the ASCII PPM file format (reference 1). The output images are greyscale images whose pixels store the average normalized radiance that reaches them.

  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

solstice(1), solstice-input(5), solstice-receiver(5)

solstice-output was initially developed with funding from the (Laboratory of Excellence), in collaboration with the PROMES Laboratory of the French National Centre for Scientific Research (CNRS). Starting in 2026, a new development effort funded by Ademe is ongoing.

solstice-output was written and is maintained by |Méso|Star> <contact@meso-star.com>.

August 17, 2026 UNIX