solstice.1.in (14323B)
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 1 18 .Os 19 .Sh NAME 20 .Nm solstice 21 .Nd compute the power collected by a concentrated solar plant 22 .Sh SYNOPSIS 23 .Nm 24 .Op Ar option ... 25 .Op Ar file 26 .Nm 27 .Fl g Ar sub-option Ns Op : Ns Ar ... 28 .Op Ar option ... 29 .Op Ar file 30 .Nm 31 .Fl p Ar sub-option Ns Op : Ns Ar ... 32 .Op Ar option ... 33 .Op Ar file 34 .Nm 35 .Fl r Ar sub-option Ns Op : Ns Ar ... 36 .Op Ar option ... 37 .Op Ar file 38 .Sh DESCRIPTION 39 .Nm 40 computes the total power collected by a concentrated solar plant, as 41 described in the 42 .Xr solstice-input 5 43 .Ar file . 44 If the 45 .Ar file 46 argument is not provided, the solar plant is read from standard input. 47 To evaluate various efficiencies for each primary reflector, it computes 48 losses due to cosine effect, shadowing and masking, orientation and surface 49 irregularities, materials properties and atmospheric extinction. 50 The efficiency for each one of these effects is subsequently computed for 51 each reflector. 52 .Pp 53 The entities on which computations must be performed are listed in the 54 .Xr solstice-receiver 5 55 file submitted through the 56 .Fl R 57 option. 58 The estimated results follow the 59 .Xr solstice-output 5 60 format and are written to the 61 .Ar output 62 file or to the standard output whether the 63 .Fl o Ar output 64 option is defined or not, respectively. 65 Note that the 66 .Nm 67 algorithm is based on the Monte-Carlo method, which means that every 68 result is provided with its numerical accuracy. 69 .Pp 70 .Nm 71 is designed to efficiently handle complex solar facilities: several 72 reflectors can be specified (planes, conics, cylindro-parabolic, etc.\&) 73 and positioned in 3D space, with a possibility for 1-axis and 2-axis 74 auto-orientation. 75 Multiple materials can be used, as long as the relevant physical properties 76 are provided. 77 Spectral effects are also taken into account: it is possible to define the 78 spectral distribution of any physical property, including the input solar 79 spectrum and the transmissivity of the atmosphere, at any spectral 80 resolution. 81 Refer to 82 .Xr solstice-input 5 83 for more information. 84 .Pp 85 In addition to the aforementioned computations, 86 .Nm 87 provides three other functionalities. 88 The 89 .Fl g 90 option can be used to convert the 91 .Xr solstice-input 5 92 geometries into CAD files. 93 The 94 .Fl p 95 option saves the sampled radiative paths used by the estimates, allowing 96 the user to visualise them externally, which may be a great help to identify a 97 design issue. 98 Finally, the 99 .Fl r 100 option is used to render an image of the submitted solar facility. 101 Note that these three options are mutually exclusive, and once defined, 102 they replace the default 103 .Nm 104 behaviour. 105 .Pp 106 All coordinates in 107 .Nm 108 follow the right-handed convention. 109 .Sh OPTIONS 110 .Bl -tag -width Ds 111 .It Fl A Ar algorithm Ns 112 The algorithm used to compute sun directions. 113 Only meaningful if a direction needs to be computed from a location. 114 Available algorithms are: 115 .Bl -tag -width Ds 116 .It Ar psa 117 The algorithm published by Manuel Blanco et al. in Solar Energy 118 .Pq see Sy Blanco et al. in the SEE ALSO section . 119 .It Ar meeus 120 The algorithm published by J. Meeus in Astronomical Algorithms 121 .Pq see Sy Meeus in the SEE ALSO section . 122 .El 123 .Pp 124 By default 125 .Ar algorithm 126 is set to 127 .Sy @SOLSTICE_ARGS_DEFAULT_SUN_DIRECTION_ALGORITHM@ . 128 .It Fl D Ar azimuth,elevation Ns 129 A sun direction, defined by two angles in degrees. 130 The first one is the azimuthal angle in [0,\ 360[, and the second one 131 is the elevation in [0,\ 90]. 132 Each provided sun direction triggers a new computation whose results are 133 concatenated to the 134 .Ar output . 135 .Pp 136 Following the right-handed convention, azimuthal rotation is 137 counter-clockwise, with 0\(de on the +X axis. 138 Elevation starts from 0\(de for directions in the XY plane, up to 90\(de 139 at zenith. 140 Thus 141 .Fl D Ns Ar 0,0 , 142 .Fl D Ns Ar 90,0 , 143 .Fl D Ns Ar 180,0 144 and 145 .Fl D Ns Ar 270,0 146 produce solar vectors {-1,0,0}, {0,-1,0}, {+1,0,0} and {0,+1,0} 147 respectively, while 148 .Fl D Ns Ar azimuth , Ns 90 149 produces {0,0,-1} regardless of the value of 150 .Ar azimuth . 151 .It Fl f 152 Force overwrite of the output files, i.e.\& the 153 .Ar output 154 file and the file where the state of the random number generator is saved 155 (see the 156 .Fl G 157 option). 158 .It Fl G Ar sub-option Ns Op : Ns Ar ... 159 Save and restore the state of the random number generator. 160 This option can be used to ensure statistical independence between 161 successive simulations on the same system. 162 Available sub-options are: 163 .Bl -tag -width Ds 164 .It Cm istate= Ns Ar input_rng_state 165 Define the file from which the initial state of the random number 166 generator is read. 167 If not defined, the random number generator is initialised with its 168 default seed. 169 .It Cm ostate= Ns Ar output_rng_state 170 Define the file where the final state of the random number generator is 171 written. 172 If not defined, this state is simply discarded. 173 .El 174 .It Fl g Ar sub-option Ns Op : Ns Ar ... 175 Generate the shape of the geometry defined in the submitted 176 .Ar file 177 and store it in 178 .Ar output . 179 Available sub-options are: 180 .Bl -tag -width Ds 181 .It Cm format=obj 182 Define the file format in which the meshes are stored. 183 Currently, only the Alias Wavefront OBJ file format is supported. 184 .It Cm split= Ns Aq Cm geometry Ns | Ns Cm object Ns | Ns Cm none 185 Define how the output mesh is split into sub-meshes. 186 A sub-mesh can be generated for each 187 .Cm geometry 188 or for each 189 .Cm object 190 as defined in the 191 .Xr solstice-input 5 192 file format. 193 The 194 .Cm none 195 option means that only one mesh is generated for the whole solar 196 facility. 197 By default, 198 .Cm split 199 is set to 200 .Cm none . 201 .El 202 .It Fl h 203 List short help and exit. 204 .It Fl I Ar dni 205 Set the Direct Normal Irradiance value, in in W/m\u2\s0\d, used for the 206 computation. 207 Must be in ]0 INF). 208 If unset, use the mandatory 209 .Ar dni 210 value describing the sun in the input data. 211 .It Fl L Ar latitude,longitude 212 Define the location of the solar plant. 213 The 214 .Ar latitude 215 must be in [-90, 90] degrees relative to the equator, counting 216 positive towards the north. 217 The 218 .Ar longitude 219 must be in [-180, 180] degrees relative to Greenwich, counting 220 positive towards the east. 221 A location must be defined before any time is defined. 222 It is then applied to any following time until a new location is defined. 223 .It Fl n Ar samples-count 224 Number of Monte-Carlo samples used to estimate the solar flux. 225 By default 226 .Ar samples-count 227 is set to 228 .Sy @SOLSTICE_ARGS_DEFAULT_NREALISATIONS@ . 229 .It Fl o Ar output 230 Write results to 231 .Ar output 232 in the 233 .Xr solstice-output 5 234 format. 235 If not defined, write results to standard output. 236 .It Fl p Ar sub-option Ns Op : Ns Ar ... 237 Register the sampled radiative paths for each sun direction and write 238 them to 239 .Ar output . 240 Available sub-options are: 241 .Bl -tag -width Ds 242 .It Cm default 243 Use default sub-options. 244 .It Cm irlen= Ns Ar length 245 Length of the radiative path segments going to infinity. 246 By default, it is computed relative to the scene size. 247 .It Cm srlen= Ns Ar length 248 Length of the radiative path segments coming from the sun. 249 By default, it is computed relative to the scene size. 250 .El 251 .It Fl q 252 Do not print the helper message when no 253 .Ar file 254 is submitted. 255 .It Fl R Ar receivers 256 .Xr solstice-receiver 5 257 file defining the scene receivers, i.e.\& the solar plant entities for 258 which 259 .Nm 260 computes Monte-Carlo estimates. 261 .It Fl r Ar sub-option Ns Op : Ns Ar ... 262 Render an image of the scene through a pinhole camera for each submitted 263 sun direction. 264 Write the resulting images to 265 .Ar output . 266 Available sub-options are: 267 .Bl -tag -width Ds 268 .It Cm fov= Ns Ar angle 269 Horizontal field of view of the camera in [30,\ 120] degrees. 270 By default 271 .Ar angle 272 is 273 .Sy @SOLSTICE_ARGS_DEFAULT_CAMERA_FOV@ 274 degrees. 275 .It Cm img= Ns Ar width Ns x Ns Ar height 276 Definition of the rendered image in pixels. 277 By default the image definition is 278 .Sy @SOLSTICE_ARGS_DEFAULT_IMG_WIDTH@ Ns x Ns Sy @SOLSTICE_ARGS_DEFAULT_IMG_HEIGHT@ . 279 .It Cm pos= Ns Ar x , Ns Ar y , Ns Ar z 280 Position of the camera. 281 By default it is set to 282 .Sy { Ns @SOLSTICE_ARGS_DEFAULT_CAMERA_POS@ Ns } 283 or it is automatically computed to ensure that the whole scene is 284 visible, whether 285 .Cm tgt 286 is set or not, respectively. 287 .It Cm rmode= Ns Aq Cm draft Ns | Ns Cm pt 288 Rendering mode. 289 In 290 .Cm draft 291 mode, images are computed by ray-casting; all materials are lambertian, 292 the sun is ignored and the only light source is positioned at the camera 293 position. 294 In 295 .Cm pt 296 mode, the scene is rendered with the unbiased path-tracing Monte-Carlo 297 algorithm; the materials described in the committed 298 .Ar file 299 as well as the submitted sun directions are correctly handled and a 300 uniform skydome is added to simulate the diffuse infinite lighting. 301 By default 302 .Cm rmode 303 is set to 304 .Cm draft . 305 .It Cm spp= Ns Ar samples-count 306 Number of samples per pixel. 307 If 308 .Cm rmode 309 is 310 .Cm draft , 311 the sample positions within a pixel are the same for all pixels. 312 With 313 .Cm rmode=pt 314 the pixel samples are generated independently for each pixel. 315 By default, @SOLSTICE_ARGS_DEFAULT_IMG_SPP@ sample per pixel is used. 316 .It Cm tgt= Ns Ar x , Ns Ar y , Ns Ar z 317 Position targeted by the camera. 318 By default it is set to 319 .Sy { Ns @SOLSTICE_ARGS_DEFAULT_CAMERA_TGT@ Ns } 320 or it is automatically computed to ensure that the whole scene is 321 visible, whether 322 .Cm pos 323 is set or not, respectively. 324 .It Cm up= Ns Ar x , Ns Ar y , Ns Ar z 325 Up vector of the camera. 326 If 327 .Cm rmode 328 is 329 .Cm pt , 330 this vector also defines the direction toward the top of the skydome. 331 By default, 332 .Cm up 333 is set to 334 .Sy { Ns @SOLSTICE_ARGS_DEFAULT_CAMERA_UP@ Ns } . 335 .El 336 .It Fl T Ar utc_time Ns 337 A time, defined by a string in Coordinated Universal Time 338 .Pq UTC+00:00 . 339 .Pp 340 The date must be in the format 341 .Dq YYYY-MM-DDThh:mm:ss , 342 i.e., as printed for the current date by the following date command: 343 .Bd -literal -offset indent 344 date -u +"%Y-%m-%dT%H:%M:%S" 345 .Ed 346 .Pp 347 Each provided 348 .Ar time 349 is used in conjunction with the last provided location to compute a 350 sun direction using the selected algorithm 351 and triggers a new computation whose results are 352 concatenated to the 353 .Ar output . 354 .It Fl t Ar threads-count 355 Hint at the number of threads to use. 356 By default, as many threads as CPU cores are used. 357 .It Fl v 358 Make 359 .Nm 360 more verbose. 361 .It Fl -version 362 Output version information and exit. 363 .El 364 .Sh EXAMPLES 365 Launch two simulations for sun directions whose azimuthal and elevation 366 angles are {45,70} and {50,75}. 367 The solar facility is described in 368 .Pa input.yaml 369 and the receivers on which the integrations must be performed are declared 370 in 371 .Pa rcvs.yaml . 372 10000 samples are used by the Monte-Carlo estimates and the results 373 are written to 374 .Pa output 375 even though this file already exists: 376 .Bd -literal -offset indent 377 solstice -D45,70 -D50,75 -R rcvs.yaml -n 10000 -f -o output input.yaml 378 .Ed 379 .Pp 380 Launch one simulation at Toulouse, France, at 2 PM on May 1 2022 381 .Pq UTC+2 . 382 The solar facility is described in 383 .Pa input.yaml 384 and the receivers on which the integrations must be performed are declared 385 in 386 .Pa rcvs.yaml . 387 The sun direction is computed using the psa algorithm. 388 The results are written to standard output: 389 .Bd -literal -offset indent 390 solstice -L43.605,1.445 -A psa -T"2022-05-01T12:00:00" -R rcvs.yaml input.yaml 391 .Ed 392 .Pp 393 Generate a mesh for each geometry described in 394 .Pa input.yaml 395 and save them in 396 .Pa output 397 in the Alias Wavefront OBJ format. 398 The meshes are positioned according to their orientation constraints, 399 for the sun direction whose azimuthal and elevation angles 400 are {30,60}. 401 Use 402 .Xr csplit 1 403 to generate one Alias Wavefront OBJ file per geometry stored in 404 .Pa output . 405 The generated files are named 406 .Pa geom Ns Ar NUM Ns .obj 407 with 408 .Ar NUM 409 in [0,\ N-1] where N is the number of geometries described in 410 .Pa input.yaml . 411 Refer to 412 .Xr solstice-output 5 413 for information on the regular expression 414 .Qq ^---$ 415 used to split the output file: 416 .Bd -literal -offset indent 417 solstice -D30,60 -g format=obj:split=geometry -f -o output input.yaml 418 csplit -f geom -b %02d.obj -z --suppress-matched output /^---$/ {*} 419 .Ed 420 .Pp 421 Trace 100 radiative paths into the solar plant described in 422 .Pa input.yaml , 423 for the sun direction whose azimuthal and elevation angles 424 are 0 and 90 degrees, respectively. 425 Write the 426 .Xr solstice-output 5 427 result to standard output and postprocess it with 428 .Xr sed 1 429 to remove the first line that stores the sun direction. 430 The remaining data listing the radiative path geometry are redirected 431 into 432 .Pa paths.vtk : 433 .Bd -literal -offset indent 434 solstice -n 100 -D0,90 -R rcvs.yaml -p default input.yaml | sed '1d' > paths.vtk 435 .Ed 436 .Pp 437 Use the path-tracing rendering algorithm to draw the solar plant 438 .Pa solplant.yaml 439 for the sun direction whose azimuthal and elevation angles 440 are 180 and 45 degrees, respectively. 441 Use 64 samples per pixel to estimate the per-pixel radiance and fix the 442 camera up vector to {0,0,1}. 443 Write the 444 .Xr solstice-output 5 445 result to standard output, use 446 .Xr sed 1 447 to remove the first line which stores the sun direction, and visualise 448 the rendered picture by redirecting the remaining data to the 449 .Xr feh 1 450 image viewer: 451 .Bd -literal -offset indent 452 solstice -D180,45 -r up=0,0,1:rmode=pt:spp=64 solplant.yaml | sed '1d' | feh - 453 .Ed 454 .Sh SEE ALSO 455 .Xr csplit 1 , 456 .Xr feh 1 , 457 .Xr sed 1 , 458 .Xr solstice-input 5 , 459 .Xr solstice-output 5 , 460 .Xr solstice-receiver 5 461 .Rs 462 .%A Manuel Blanco-Muriel 463 .%A Diego C. Alarcón-Padilla 464 .%A Teodoro López-Moratalla 465 .%A Martín Lara-Coira 466 .%T Computing the solar vector 467 .%J Solar Energy 468 .%V 70 469 .%N 5 470 .%D 2001 471 .%P 431-441 472 .Re 473 .Rs 474 .%A Jean Meeus 475 .%B Astronomical Algorithms 476 .%D 1991 477 .Re 478 .Sh HISTORY 479 .Nm 480 was initially developed with funding from the 481 .Em SOLSTICE LabEx 482 .Pq Laboratory of Excellence , 483 in collaboration with the PROMES Laboratory of the 484 French National Centre for Scientific Research 485 .Pq CNRS . 486 Starting in 2026, a new development effort funded by Ademe is ongoing.