solstice-output.5 (21436B)
1 .\" SPDX-License-Identifier: GPL-3.0-or-later 2 .\" Copyright (C) 2016-2018 CNRS, 2018-2019 |Méso|Star> 3 .\" 4 .\" This is free documentation: you can redistribute it and/or modify 5 .\" it under the terms of the GNU General Public License as published by 6 .\" the Free Software Foundation, either version 3 of the License, or 7 .\" (at your option) any later version. 8 .\" 9 .\" This manual is distributed in the hope that it will be useful, 10 .\" but WITHOUT ANY WARRANTY; without even the implied warranty of 11 .\" MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the 12 .\" GNU General Public License for more details. 13 .\" 14 .\" You should have received a copy of the GNU General Public License 15 .\" along with this program. If not, see <http://www.gnu.org/licenses/>. 16 .Dd $Mdocdate$ 17 .Dt SOLSTICE-OUTPUT 5 18 .Os 19 .Sh NAME 20 .Nm solstice-output 21 .Nd output format of solstice 22 .Sh DESCRIPTION 23 The 24 .Nm 25 format describes the output produced by the 26 .Xr solstice 1 27 program. 28 All data generated by a 29 .Xr solstice 1 30 invocation are written to a single file or to standard output, depending 31 on whether an 32 .Ar output 33 file is specified through the 34 .Fl o 35 option or not. 36 Submitting several sun directions to 37 .Xr solstice 1 38 through the 39 .Fl D 40 option produces as many outputs as sun directions: invoking 41 .Xr solstice 1 42 with N sun directions is equivalent to calling it N times and 43 concatenating the associated outputs. 44 .Pp 45 The type of data generated depends on the mode in which 46 .Xr solstice 1 47 is invoked. 48 By default, 49 .Xr solstice 1 50 evaluates the power collected by the submitted solar plant. 51 When invoked with the 52 .Fl g 53 option, it converts the solar plant geometries into a list of CAO files. 54 The 55 .Fl p 56 option tracks the sampled radiative paths, and the 57 .Fl r 58 option renders an image of the solar facility. 59 .Sh GRAMMAR 60 Output values are mainly ASCII data formatted line by line. 61 By convention, line data in the following grammar are listed between 62 quote marks. 63 The grammar may span multiple lines for formatting purposes, but data 64 are on a single line until a closing quote mark. 65 .Bd -literal 66 <o> ::= <simulation-output> 67 | <dump-geometry-output> # -g option 68 | <dump-radiative-paths-output> # -p option 69 | <rendering-output> # -r option 70 71 <simulation-output> 72 ::= <sun-direction> 73 <counts> 74 <global> 75 [ <receivers-list> ] 76 [ <primaries-list> ] 77 [ <rcvXprims-list> ] 78 [ <receiver-maps> ] 79 [ <simulation-output> ... ] 80 81 <dump-geometry-output> 82 ::= <sun-direction> 83 <geometry-data> 84 [ <dump-geometry-output> ... ] 85 86 <dump-radiative-paths-output> 87 ::= <sun-direction> 88 VTK-RADIATIVE-PATHS 89 [ <dump-radiative-paths-output> ... ] 90 91 <rendering-output> 92 ::= <sun-direction> 93 PPM-FILE # ASCII PPM with 8-bits per component [1] 94 [ <rendering-output> ... ] 95 .Ed 96 .Bd -literal 97 <sun-direction> ::= "#--- Sun direction: <alpha> <beta> (<sun-vector>)" 98 99 <counts> ::= "<#globals> <#receivers> <#primaries> 100 <#samples> <#failed>" 101 102 <#globals> ::= 7 103 <#receivers> ::= INTEGER # in [0, INF) 104 <#primaries> ::= INTEGER # in [0, INF) 105 <#samples> ::= INTEGER # in [0, INF) 106 <#failed> ::= INTEGER # in [0, INF) 107 108 <global> ::= <potential-flux> 109 <absorbed-flux> 110 <cos-factor> 111 <shadow-loss> 112 <missing-loss> 113 <materials-loss> 114 <atmospheric-loss> 115 .Ed 116 .Bd -literal 117 <receivers-list> ::= <receiver> 118 [ <receiver> ... ] 119 120 <receiver> ::= "<receiver-name> <receiver-id> <area> 121 <front> <back>" 122 123 <receiver-name> ::= <entity-identifier> 124 <receiver-id> ::= INTEGER 125 126 <front> ::= <side> 127 <back> ::= <side> 128 129 <side> ::= "<incoming-flux> <in-if-no-mat-loss> 130 <in-if-no-atm-loss> <in-mat-loss> <in-atm-loss> 131 <absorbed-flux> <abs-if-no-mat-loss> 132 <abs-if-no-atm-loss> <abs-mat-loss> <abs-atm-loss> 133 <efficiency>" 134 .Ed 135 .Bd -literal 136 <primaries-list> ::= <primary> 137 [ <primary> ... ] 138 139 <primary> ::= "<primary-name> <primary-id> <area> <#samples> 140 <cos-factor> <shadow-loss>" 141 142 <primary-name> ::= <entity-identifier> 143 <primary-id> ::= INTEGER 144 .Ed 145 .Bd -literal 146 <rcvXprims-list> ::= <rcvXprim> 147 [ <rcvXprim> ... ] 148 149 <rcvXprim> ::= "<receiver-id> <primary-id> 150 <rcvXprim-front> <rcvXprim-back>" 151 152 <rcvXprim-front> ::= <rcvXprim-side> 153 <rcvXprim-back> ::= <rcvXprim-side> 154 155 <rcvXprim-side> ::= "<incoming-flux> <in-if-no-mat-loss> 156 <in-if-no-atm-loss> <in-mat-loss> <in-atm-loss> 157 <absorbed-flux> <abs-if-no-mat-loss> 158 <abs-if-no-atm-loss> <abs-mat-loss> <abs-atm-loss>" 159 .Ed 160 .Bd -literal 161 <receiver-maps> ::= VTK-RECEIVER-MAP 162 [ <receiver-maps> ... ] 163 164 <geometry-data> ::= OBJ-FILE 165 [ --- 166 <geometry-data> ... ] 167 .Ed 168 .Bd -literal 169 <area> ::= REAL # in ]0, INF) 170 <real3> ::= REAL REAL REAL 171 172 <alpha> ::= REAL # Degrees in [0, 360[ 173 <beta> ::= REAL # Degrees in [0, 90] 174 <sun-vector> ::= <real3> 175 176 <incoming-flux> ::= <estimate> 177 <in-if-no-mat-loss> ::= <estimate> 178 <in-if-no-atm-loss> ::= <estimate> 179 <in-mat-loss> ::= <estimate> 180 <in-atm-loss> ::= <estimate> 181 <absorbed-flux> ::= <estimate> 182 <abs-if-no-mat-loss> ::= <estimate> 183 <abs-if-no-atm-loss> ::= <estimate> 184 <abs-mat-loss> ::= <estimate> 185 <abs-atm-loss> ::= <estimate> 186 <cos-factor> ::= <estimate> 187 <missing-loss> ::= <estimate> 188 <materials-loss> ::= <estimate> 189 <atmospheric-loss> ::= <estimate> 190 <shadow-loss> ::= <estimate> 191 <efficiency> ::= <estimate> 192 193 <estimate> ::= <expected-value> <standard-error> 194 <expected-value> ::= REAL 195 <standard-error> ::= REAL # in [0, INF) 196 197 <entity-identifier> # Defined in solstice-input(5) 198 .Ed 199 .Sh SIMULATION 200 A 201 .Em simulation-output 202 begins with two header lines. 203 The first reports the sun direction used in the simulation (two angles 204 in degrees, plus the corresponding sun vector). 205 The second lists the numbers of global, per-receiver and per-primary 206 results, as well as the overall number of Monte-Carlo experiments and 207 the number of experiments that failed due to unforeseen errors such as 208 numerical imprecisions. 209 As soon as the number of failed experiments reaches 1% of the required 210 number of Monte-Carlo experiments, the code exits with an 211 .Qq Error in integrating the solar flux 212 message, and the validity of subsequent results is questionable: 213 estimates are produced using the number of successful experiments, which 214 is necessarily smaller than the required number. 215 .Ss Global results 216 After the two header lines, the output includes various 217 .Em global 218 result lines; the exact number is given in the header (currently 7). 219 Each global result is a pair of real numbers: the expected value and its 220 standard error. 221 The global results are, in order: 222 .Bl -tag -width Ds 223 .It Em potential-flux 224 Maximum flux that all primary geometries could intercept if properly 225 oriented and flat-shaped. 226 .It Em absorbed-flux 227 Absorbed part of the flux reaching any receiver geometry. 228 At most equal to the potential flux. 229 .It Em cos-factor 230 Cosine of the angle between the sun direction and the normal of the 231 primary surfaces (average over all primary geometries). 232 .It Em shadow-loss 233 Potential flux intercepted by another geometry before reaching a primary 234 geometry. 235 .It Em missing-loss 236 Part of the flux that reaches a primary geometry and follows a radiative 237 path but is not absorbed; this flux may have bounced on geometries, 238 including receivers, without being absorbed. 239 .It Em materials-loss 240 Total flux absorbed by non-receivers along radiative paths; includes 241 both surface and volume absorption. 242 .It Em atmospheric-loss 243 Total flux extinction by the atmosphere along radiative paths. 244 .El 245 .Pp 246 These results can be used to check conservation of energy: 247 .Em potential-flux No * Em cos-factor 248 and 249 .Pq Em absorbed-flux No + Em shadow-loss No + Em missing-loss No + Em materials-loss No + Em atmospheric-loss 250 should be equal within their respective uncertainty ranges. 251 .Ss Per receiver results 252 Following the global results, the output includes one line per receiver, 253 sorted according to the order of the receivers as defined in the 254 submitted 255 .Xr solstice-receiver 5 256 file. 257 Each line contains: 258 .Bl -tag -width Ds 259 .It Em receiver-name 260 Name of the receiver, i.e.\& the 261 .Em entity-identifier 262 of the entity in which the receiving geometry is defined (see 263 .Xr solstice-input 5 ) . 264 .It Em receiver-id 265 Unique integer identifying the receiver. 266 .It Em area 267 Area of the receiver. 268 .It Em front 269 Estimated results for the front side of the receiver. 270 .It Em back 271 Estimated results for the back side of the receiver. 272 .El 273 .Pp 274 The estimates for the 275 .Em front 276 and 277 .Em back 278 sides are as follows (each is a pair: expected value and standard 279 error): 280 .Bl -tag -width Ds 281 .It Em incoming-flux 282 Flux that reaches the receiver side. 283 .It Em in-if-no-mat-loss 284 Incoming flux if absorption on non-receivers is not taken into account. 285 .It Em in-if-no-atm-loss 286 Incoming flux if atmospheric extinction is not taken into account. 287 .It Em in-mat-loss 288 .Em in-if-no-mat-loss No \- Em incoming-flux . 289 .It Em in-atm-loss 290 .Em in-if-no-atm-loss No \- Em incoming-flux . 291 .It Em absorbed-flux 292 Flux absorbed by the receiver side. 293 .It Em abs-if-no-mat-loss 294 Absorbed flux if absorption by non-receivers is not taken into account. 295 .It Em abs-if-no-atm-loss 296 Absorbed flux if atmospheric extinction is not taken into account. 297 .It Em abs-mat-loss 298 .Em abs-if-no-mat-loss No \- Em absorbed-flux . 299 .It Em abs-atm-loss 300 .Em abs-if-no-atm-loss No \- Em absorbed-flux . 301 .It Em efficiency 302 Fraction of the potential flux absorbed by this receiver side. 303 .El 304 .Pp 305 Both 306 .Em front 307 and 308 .Em back 309 side estimates are always output, even if the receiver has only a single 310 receiving side. 311 In that case, the results of the non-receiving side are meaningless 312 (invalid \-1 value). 313 .Ss Per primary results 314 Following the per-receiver results, the output includes one line per 315 primary geometry. 316 Each line contains: 317 .Bl -tag -width Ds 318 .It Em primary-name 319 Name of the primary geometry, i.e.\& the 320 .Em entity-identifier 321 of the entity in which the primary geometry is defined (see 322 .Xr solstice-input 5 ) . 323 .It Em primary-id 324 Unique integer identifying the primary geometry. 325 .It Em area 326 Area of the primary geometry. 327 .It Em #samples 328 Number of Monte-Carlo experiments sampled on the primary geometry. 329 .It Em cos-factor 330 Cosine of the angle between the sun direction and the normal of the 331 primary surface (average over the primary geometry). 332 .It Em shadow-loss 333 Potential flux intercepted by another geometry before reaching this 334 primary geometry. 335 .El 336 .Ss Per receiver and per primary results 337 Following the per-primary results, the output includes result lines 338 describing the contribution of each primary geometry to each receiver. 339 The total number of such lines is the number of receivers times the 340 number of primary geometries. 341 Each line contains: 342 .Bl -tag -width Ds 343 .It Em receiver-id 344 Identifier of the involved receiver. 345 .It Em primary-id 346 Identifier of the involved primary geometry. 347 .It Em rcvXprim-front 348 Estimated results for the receiver front side. 349 .It Em rcvXprim-back 350 Estimated results for the receiver back side. 351 .El 352 .Pp 353 The estimated values of 354 .Em rcvXprim-front 355 and 356 .Em rcvXprim-back 357 are as follows (each is a pair: expected value and standard error): 358 .Bl -tag -width Ds 359 .It Em incoming-flux 360 Flux that reaches the receiver side. 361 .It Em in-if-no-mat-loss 362 Incoming flux if absorption on non-receivers is not taken into account. 363 .It Em in-if-no-atm-loss 364 Incoming flux if atmospheric extinction is not taken into account. 365 .It Em in-mat-loss 366 .Em in-if-no-mat-loss No \- Em incoming-flux . 367 .It Em in-atm-loss 368 .Em in-if-no-atm-loss No \- Em incoming-flux . 369 .It Em absorbed-flux 370 Flux absorbed by the receiver side. 371 .It Em abs-if-no-mat-loss 372 Absorbed flux if absorption by non-receivers is not taken into account. 373 .It Em abs-if-no-atm-loss 374 Absorbed flux if atmospheric extinction is not taken into account. 375 .It Em abs-mat-loss 376 .Em abs-if-no-mat-loss No \- Em absorbed-flux . 377 .It Em abs-atm-loss 378 .Em abs-if-no-atm-loss No \- Em absorbed-flux . 379 .El 380 .Pp 381 Both front and back side estimates are always output, even if the 382 receiver has only a single receiving side. 383 In that case, the results of the non-receiving side are meaningless 384 (invalid \-1 value). 385 .Ss Receiver map 386 A receiver defined in the submitted 387 .Xr solstice-receiver 5 388 file can have a per-primitive estimate of its incoming flux density 389 and/or absorbed flux density if its 390 .Em per_primitive 391 flag is active. 392 In this case, 393 .Xr solstice 1 394 generates a 395 .Em receiver-map : 396 an ASCII VTK file 397 .Po 398 see 399 .Sx NOTES , 400 reference 2 401 .Pc 402 that stores the triangular mesh of the receiver and, for each triangle, 403 the estimate of its associated incoming and/or absorbed flux density. 404 The resolution of the receiver map is thus controlled by the 405 discretization of the receiver's shape as described in the 406 .Xr solstice-input 5 407 file. 408 To obtain a good estimate of the per-triangle flux densities, the 409 number of per-triangle experiments must be sufficient; since only a 410 small fraction of the overall sampled radiative paths reach a given 411 triangle, the total number of experiments specified through the 412 .Fl n 413 option of 414 .Xr solstice 1 415 should be increased significantly, by 1 or 2 orders of magnitude. 416 .Pp 417 The number of written per-triangle flux density estimates depends on 418 the receiver's parameters: both front and back sides can be active, and 419 each side can produce an estimate for both incoming and absorbed flux 420 density. 421 As a consequence, the output can include up to 4 different estimates, 422 written in the order: incoming front, absorbed front, incoming back, 423 absorbed back. 424 The following grammar describes the formatting of a 425 .Em VTK-RECEIVER-MAP . 426 Refer to the VTK format specification 427 .Po 428 reference 2 429 .Pc 430 for more information on the VTK file format. 431 .Bd -literal 432 VTK-RECEIVER-MAP ::= # vtk DataFile Version 2.0 433 <receiver-name> 434 ASCII 435 DATASET POLYDATA 436 POINTS <#vertices> float 437 <map-vertices> 438 POLYGONS <#triangles> <#triangles*4> 439 <map-triangles> 440 CELL_DATA <#triangles> 441 <map-triangle-data> 442 443 <map-vertices> ::= <real3> 444 [ <real3> ... ] # up to <#vertices> 445 446 <map-triangles> ::= 3 <triangle-indices> 447 [ 3 <triangle-indices> ... ] # up to <#triangles> 448 449 <map-triangle-data> ::= <map-front-data> 450 | <map-back-data> 451 | <map-front-data> <map-back-data> 452 453 <map-front-data> ::= <map-side-data> 454 <map-back-data> ::= <map-side-data> 455 456 <map-side-data> ::= <incoming-flux> 457 | <absorbed-flux> 458 | <incoming-flux> <absorbed-flux> 459 460 <incoming-flux> ::= <flux-density-data> 461 <absorbed-flux> ::= <flux-density-data> 462 463 <flux-density-data> ::= SCALARS <side-and-flux-names> float 2 464 LOOKUP_TABLE default 465 <estimate> 466 [ <estimate> ... ] 467 468 <side-and-flux-names> ::= Front_faces_Incoming_flux 469 | Front_faces_Absorbed_flux 470 | Back_faces_Incoming_flux 471 | Back_faces_Absorbed_flux 472 473 <#triangles> ::= INTEGER 474 <#vertices> ::= INTEGER 475 <triangle-indices> ::= INTEGER INTEGER INTEGER 476 .Ed 477 .Sh DUMP GEOMETRY 478 A 479 .Em dump-geometry-output 480 is generated when 481 .Xr solstice 1 482 is invoked with the 483 .Fl g 484 option. 485 For each submitted sun direction, 486 .Xr solstice 1 487 converts the geometry of the submitted 488 .Xr solstice-input 5 489 file into triangular meshes written to the output in the format 490 specified by the 491 .Cm format 492 sub-option of 493 .Fl g . 494 The only currently supported format is Alias Wavefront OBJ 495 .Po 496 reference 3 497 .Pc . 498 With no further sub-option, a single OBJ file containing the whole mesh 499 of the solar plant is generated. 500 The 501 .Cm split 502 sub-option of 503 .Fl g 504 allows generating several OBJ descriptions, one per 505 .Cm geometry 506 or per 507 .Cm object 508 as defined in the 509 .Xr solstice-input 5 510 format; each description is then followed by a line containing 511 .Qq --- 512 to mark the end of the current OBJ. 513 .Pp 514 Regardless of the 515 .Cm split 516 strategy, each geometry is an OBJ group whose name is the 517 .Em entity-identifier 518 of the entity in which it is encapsulated. 519 The 520 .Em usemtl 521 OBJ directive associates to each mesh the name of its material type. 522 The following grammar describes the formatting of an 523 .Em OBJ-FILE . 524 Refer to the OBJ format specification 525 .Po 526 reference 3 527 .Pc 528 for more information. 529 .Bd -literal 530 OBJ-FILE ::= g <entity-identifier> 531 <obj-mesh> 532 [ <obj-mesh> ... ] 533 534 <obj-mesh> ::= usemtl <material-type> 535 <obj-vertices> 536 <obj-faces> 537 538 <obj-vertices> ::= v <real3> 539 [ v <real3> ... ] 540 541 <obj-indices> ::= f <triangle-indices> 542 [ f <triangle-indices> ... ] 543 544 <material-type> ::= dielectric 545 | matte 546 | mirror 547 | thin_dielectric 548 | virtual 549 .Ed 550 .Sh DUMP RADIATIVE PATHS 551 For each sun direction, the 552 .Em dump-radiative-paths-output 553 lists the geometric data of the radiative paths sampled during a 554 simulation. 555 Each path is coloured according to its type: 556 .Bl -tag -width Ds 557 .It Yellow 558 The first segment (the ray from the sun toward a primary geometry) is 559 occluded by a non-virtual object. 560 .It Blue 561 The path is not occluded and reaches a receiver. 562 .It Turquoise 563 The path is not occluded and does not reach a receiver. 564 .It Red 565 The path was cancelled due to a topologically incoherent impact (an 566 impact on a surface not at the boundary of the medium in which the ray 567 was propagating). 568 .El 569 .Pp 570 The following grammar describes the formatting of a 571 .Em VTK-RADIATIVE-PATHS 572 file. 573 Refer to the VTK format specification 574 .Po 575 reference 2 576 .Pc 577 for more information. 578 .Bd -literal 579 VTK-RADIATIVE-PATHS ::= # vtk DataFile Version 2.0 580 Radiative paths 581 ASCII 582 DATASET POLYDATA 583 POINTS <#vertices> float 584 <paths-vertices> 585 LINES <#paths> <#paths+#vertices> 586 <paths-lists> 587 CELL_DATA <#paths> 588 SCALAR Radiative_path_type float 1 589 LOOKUP_TABLE path_type 590 <paths-type> 591 LOOKUP_TABLE path_type 5 592 <color-error> 593 <color-unused> 594 <color-success> 595 <color-missing> 596 <color-occluded> 597 598 <paths-vertices> ::= <real3> 599 [ <real3> ... ] # up to <#vertices> 600 601 <paths-lists> ::= <radiative-path> 602 [ <radiative-path> ... ] # up to <#paths> 603 604 <radiative-path> ::= <#path-segments> <path-vertex-id> ... 605 606 <paths-type> ::= <color-id> 607 [ <color-id> ... ] # up to <#paths> 608 609 <color-id> ::= 0.0 # Red: for error paths 610 | 0.25 # Green: unused 611 | 0.5 # Blue: for success paths 612 | 0.75 # Turquoise: for missing paths 613 | 1.0 # Yellow: for occluded paths 614 615 <color-error> ::= 1.0 0.0 0.0 1.0 616 <color-unused> ::= 0.0 1.0 0.0 1.0 617 <color-success> ::= 0.0 0.0 1.0 1.0 618 <color-missing> ::= 0.0 1.0 1.0 1.0 619 <color-occluded> ::= 1.0 1.0 0.0 1.0 620 621 <#paths> ::= INTEGER 622 <#path-segments> ::= INTEGER 623 <path-vertex-id> ::= INTEGER 624 .Ed 625 .Sh RENDERING 626 When invoked with the 627 .Fl r 628 option, 629 .Xr solstice 1 630 generates one image of the solar facility per submitted sun direction. 631 Each image is preceded by its associated sun direction and saved in the 632 ASCII PPM file format 633 .Po 634 reference 1 635 .Pc . 636 The output images are greyscale images whose pixels store the average 637 normalized radiance that reaches them. 638 .Sh NOTES 639 .Bl -enum 640 .It 641 Portable PixMap \(em 642 .Lk http://netpbm.sourceforge.net/doc/ppm.html 643 .It 644 VTK file format \(em 645 .Lk http://www.vtk.org/wp-content/uploads/2015/04/file-formats.pdf 646 .It 647 OBJ file format \(em 648 .Lk http://www.martinreddy.net/gfx/3d/OBJ.spec 649 .El 650 .Sh SEE ALSO 651 .Xr solstice 1 , 652 .Xr solstice-input 5 , 653 .Xr solstice-receiver 5 654 .Sh HISTORY 655 .Nm 656 was initially developed with funding from the 657 .Em SOLSTICE LabEx 658 .Pq Laboratory of Excellence , 659 in collaboration with the PROMES Laboratory of the 660 French National Centre for Scientific Research 661 .Pq CNRS . 662 Starting in 2026, a new development effort funded by Ademe is ongoing. 663 .Sh AUTHORS 664 .Nm 665 was written and is maintained by 666 .An |M\['e]so|Star> Aq Mt contact@meso-star.com .