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