solstice

README.md (11662B)

---

 # Solstice
 
 The purpose of this program is to compute the total power collected by a
 concentrated solar plant, and to evaluate various efficiencies for each primary
 reflector: it computes losses due to cosine effect, to shadowing and
 masking, to orientation and surface irregularities, to reflectivity, and to
 atmospheric transmission. The efficiency for each one of these effects is
 subsequently computed for each reflector, which provides insightful information
 when looking for the optimal design of a concentrated solar plant. Note that
 Solstice relies on Monte Carlo method, which means that every result is
 provided with its numerical accuracy.
 
 In addition to the computations listed above, Solstice can render an image of
 the solar plant, either with a simple ray-caster or with a path-tracing
 algorithm that correctly handles the materials of the scene.
 
 Solstice is designed to handle complex solar plants: any number of reflectors
 can be specified (planes, conics, cylindro-parabolic, etc.) and positioned in
 3D space, with a possibility for 1-axis and 2-axis auto-orientation with
 respect to the sun direction. CAD geometries can be added to the solar plant
 thanks to the support of the STereo Lithography file format. Multiple materials
 can be used, as long as the relevant physical properties are provided (matte,
 mirror, dielectric, etc.). Spectral effects are also taken into account: it is
 possible to define the spectral distribution of any physical property,
 including the input solar spectrum and the absorption of the atmosphere, at any
 spectral resolution.
 
 Solstice was developed as part of the Solstice project, in collaboration with
 the [Laboratory of Excellence Solstice](http://www.labex-solstice.fr) and the
 [PROMES](http://www.promes.cnrs.fr/) laboratory of the National Center for
 Scientific Research ([CNRS](http://www.cnrs.fr)). Starting in 2026, a new
 development effort funded by [Ademe](https://www.ademe.fr/) is ongoing.
 
 Refer to the solstice(1) man pages for more information on the available
 features.
 
 ## How to build
 
 This program, as part of the Solstice app, can be built on any x86-64 POSIX
 system.
 
 Note that you will most likely want to build the entire Solstice app rather than
 this library alone. If so, a good starting point is the dedicated
 [Solstice web page](https://www.meso-star.com/solstice/install.html).
 
 This program depends on the
 [LibYAML](http://pyyaml.org/wiki/LibYAML),
 [RSys](https://gitlab.com/vaplv/rsys/),
 [Solstice-Anim](https://gitlab.com/meso-star/solstice-anim/),
 [Solstice-Solver](https://gitlab.com/meso-star/solstice-solver/),
 [Star-3DUT](https://gitlab.com/meso-star/star-3dut/),
 [Star-SP](https://gitlab.com/meso-star/star-sp/) and
 [Star-STL](https://gitlab.com/meso-star/star-stm/) libraries.
 
 First ensure that the make utility and a compiler that implements the OpenMP 1.2
 specification are installed on your system. Then install the above
 prerequisites. Finally, edit the config.mk file to meet your needs and build
 the project by running:
 
     make clean install
 
 ## Release notes
 
 ### Version 0.11
 
 - Allow to define sun direction through location + time.
 
 - Add a command line option to set the sun direction algorithm.
   Either meeus or psa (default) at this stage.
 
 - Add a command line option to set the DNI.
   The sun's description in the input data already includes a mandatory dni
   value. The new option allow to supersede this dni value from the command line.
 
 ### Version 0.10
 
 #### Raise the minimum required versions of companion libs
 
 solstice-anim minimum version is now 0.3, while solstice-solver minimum version
 is now 0.10.
 
 #### Replace CMake with a POSIX Makefile
 
 The build procedure is now written in POSIX make and can be configured via
 the config.mk file. A pkg-config file is also provided to link the
 library as an external dependency.
 
 Compared to the CMake alternative, this Makefile adds support for static
 libraries and an uninstall target. It also enables compiler and linker
 flags for various hardening features, improving the security and
 robustness of generated binaries. More broadly, the motivation for this
 rewrite is to rely on a well-established standard with a simple feature
 set, available on all UNIX systems - reducing portability concerns and
 maintenance burden while remaining significantly lighter.
 
 #### Proof-reading and editing manual pages
 
 Write the man pages directly in mdoc's roff macros, instead of using the
 asciidoc markup language as a source for man pages.
 Unlike writing manuals with man's roff macros, and even more so with
 asciidoc, mdoc macros take care of layout, font handling and all the other
 typesetting details which, by construction, guarantee the consistency of
 all manuals without leaving the responsibility to the individual author.
 This also facilitates translation into other formats and documentation
 tools. These are the main reasons for writing manual pages with mdoc
 macros.
 A complete re-reading of the manual pages was carried out during the
 translation into mdoc, with several corrections and rewrites to make the
 manual clearer.
 
 #### Raise the minimum required version of dependencies
 
 Minimum required versions:
 - Rsys = 0.15
 - Star-3DUT = 0.4
 - Star-SP = 0.15
 - Star-STL = 0.7
 - libYAML = 0.2
 
 ### Version 0.9.1
 
 - Raise the minimum required CMake version to 3.1, as version 2.8 has been
   deprecated since CMake 3.20.
 - Raise the minimum required Star-SampPling to 0.12. This version fixes
   compilation errors with gcc 11 but introduces API breaks.
 
 ### Version 0.9
 
 Add the `-G` option that saves and restores the state of the random number
 generator. This option can be used to ensure the statistical independence
 between successive runs.
 
 ### Version 0.8.2
 
 - Fix man pages: the -D option of the solstice CLI was wrongly documented. The
   zenith and elevation angles were sometimes inverted.
 - Bump version of the StarSP dependency to 0.8.
 
 ### Version 0.8.1
 
 Fix the VTK of the receiver map: the receiver map was written as `double` while
 the type notified in the VTK file was `float`. This might produce errors on
 loading of the resulting VTK file. The VTK data type is now set to `double` to
 make it consistent with the type of the written values.
 
 ### Version 0.8
 
 Add the support of per-triangle absorbed flux density. The `per_primitive`
 attribute of the receiver file format controls which flux densities to output
 for each triangle of a receiver. Its value can be:
 
 - `NONE`: no per-triangle flux density is computed, i.e. no receiver map is
   output for the receiver. It was the behaviour of the previous version of
   Solstice when the `per_primitive` flag was undefined or was set to 0.
 - `INCOMING`: output the estimate of the per-triangle incoming flux density.
   It was the behaviour of the previous version of Solstice when the
   `per_primitive` flag was set to 1.
 - `ABSORBED`: output the estimate of the per-triangle absorbed flux density.
 - `INCOMING_AND_ABSORBED`: output both the estimates of incoming and absorbed
   flux density for each triangle of the receiver.
 
 ### Version 0.7.1
 
 - Replace the `roughness` parameter of the mirror material by the
   `slope_error` parameter.
 - Improve the documentation of the sun direction.
 - Ensure that the per-receiver results are sorted according to the order of the
   receivers as listed in the submitted receiver file.
 
 ### Version 0.7
 
 - Add the `gaussian` sun shape.
 - Add the `microfacet` attribute to the mirror material. It controls the normal
   distribution of the microfacets when the mirror roughness is not null. The
   supported distributions are `BECKMANN` and `PILLBOX`.
 
 ### Version 0.6.1
 
 - Fix the solstice-input man page. The `extinction` parameter of the medium and
   the atmosphere was named `absorption`.
 - Rename the pillbox `theta_max` parameter in `half_angle`.
 
 ### Version 0.6
 
 - Rename the `absorption` parameter of the medium and the atmosphere in
   `extinction`.
 - Add several global and per-receiver estimations. The outputs now fully
   describe the incoming and absorbed fluxes: overall flux, flux without
   material loss, flux without atmospheric loss, material losses and atmospheric
   losses.
 - Rename the pillbox `aperture` parameter in `theta_max`.
 - Fix the distribution of the pillbox sun: the pdf was wrong and its angular
   parameter was internally used as an angular diameter while it is an angular
   radius.
 - Fix the solver for non parallel sun: the angle between the principal sun
   direction and the sampled direction was not correctly taken into account
   leading to a wrong initial weight for the optical paths.
 - Fix the solver with shapes having perturbed normals: perturbed normals
   must be taken into account in the bounces of the optical paths only, not in
   the energy computations.
 
 ### Version 0.5
 
 Improve the performances of the solver up to 50% in situations where the
 radiative random walks bounce on many surfaces.
 
 ### Version 0.4.1
 
 - Update the name of the output data in the solstice-output man page.
 - Fix an issue in "dump geometry" mode, i.e. option `-g`. Solstice might fail
   to export the solar plant geometry due to a wrong constraint on the pivots.
 
 ### Version 0.4
 
 - Update the color of the paths output with the `-p` option. A path is blue,
   turquoise or yellow if it reaches a receiver, misses the receivers or is
   occluded before it reaches a primary reflector, respectively.
 - Add a new type of paths tracked with the `-p` option: a path is red if it
   travels unforeseen mediums.
 - Correctly handle the `stacks` parameter of the cylinder.
 
 ### Version 0.3
 
 - Fix several issues in the output results. Refer to the Solstice-Solver 0.3
   release notes for more informations.
 - Add the `--version` option.
 - Update the man pages to fix some issues and improve the output documentation.
 
 ### Version 0.2.3
 
 - Update the solstice-input file format. The anchor and entity name cannot
   contain spaces or tabulations anymore.
 - Fix the reported sun directions in the solstice-output. For each submitted
   sun direction, solstice correctly outputs its Cartesian coordinates but always
   wrote the azimuthal and elevation angles of the first direction.
 - Update the solstice-output map page: add the missing `<efficiency>` grammar
   rule and fix the definition of the `<map-side-data>` grammar rule.
 
 ### Version 0.2.2
 
 - Fix how the AsciiDoc tool suite is searched for on Windows; it was never found
   and consequently the documentation was not generated.
 
 ### Version 0.2.1
 
 - Fix the install target on Windows: copy the solstice runtime libraries in the
   solstice installation path.
 
 ### Version 0.2
 
 - Add the support of an optional normal map to the materials. It defines
   spatially varying normals in the tangent space of the surface. Currently,
   only the quadric surfaces are parameterizable: using a normal mapped material
   on the other shapes will produce unforeseen behaviors.
 - Add the support of spectral data to the materials: a material attribute can be
   either a scalar or follow a spectral distribution.
 - Add an optional atmospheric absorption after the first reflection of the light
   path; the sun description includes the atmospheric effect before the first
   reflector.
 - Write the man pages of the Solstice command line and its associated file
   formats.
 - Add the verbose option `-v`.
 - Update the output format of the simulation.
 
 ## License
 
 Copyright (C) 2018-2026 |Méso|Star> (<contact@meso-star.com>).
 Copyright (C) 2016-2018 CNRS.
 
 Solstice is free software released under the GPL v3+ license: GNU GPL version 3
 or later. You are welcome to redistribute it under certain conditions; refer to
 the COPYING file for details.