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