solstice-solver

Solver library of the solstice app
git clone git://git.meso-star.com/solstice-solver.git
Log | Files | Refs | README | LICENSE

README.md (6614B)

      1 # Solstice Solver
      2 
      3 The purpose of this library is to integrate the solar flux in complex solar
      4 facilities. It was developed as part of the
      5 [Solstice](https://gitlab.com/meso-star/solstice) project, in collaboration with
      6 the [Laboratory of Excellence Solstice](http://www.labex-solstice.fr) and the
      7 [PROMES](http://www.promes.cnrs.fr/) laboratory of the National Center for
      8 Scientific Research ([CNRS](http://www.cnrs.fr)). Starting in 2026, a new
      9 development effort funded by [Ademe](https://www.ademe.fr/) is ongoing.
     10 
     11 ## How to build
     12 
     13 This library, as part of the Solstice app, can be built on any POSIX system.
     14 
     15 Note that you will most likely want to build the entire Solstice app rather than
     16 this library alone. If so, a good starting point is the
     17 [start-build](https://gitlab.com/meso-star/star-build) build system.
     18 
     19 The Solstice-Solver library depends on the
     20 [RSys](https://gitlab.com/vaplv/rsys/),
     21 [Star-3D](https://gitlab.com/meso-star/star-3d/),
     22 [Star-3DUT](https://gitlab.com/meso-star/star-3dut),
     23 [Star-CPR](https://gitlab.com/meso-star/star-cpr),
     24 [Star-SF](https://gitlab.com/meso-star/star-sf) and
     25 [Star-SP](https://gitlab.com/meso-star/star-sp/) libraries as well as on the
     26 [OpenMP](http://www.openmp.org) 1.2 specification to parallelize its
     27 computations.
     28 
     29 First ensure that the make utility and a compiler that implements the OpenMP 1.2
     30 specification are installed on your system. Then install the above
     31 prerequisites. Finally, edit the config.mk file to meet your needs and build
     32 the project by running:
     33 
     34     make clean install
     35 
     36 ## Release notes
     37 
     38 ### Version 0.10
     39 
     40 Replace CMake with a POSIX Makefile
     41 
     42 The build procedure is now written in POSIX make and can be configured via
     43 the config.mk file. A pkg-config file is also provided to link the
     44 library as an external dependency.
     45 
     46 Compared to the CMake alternative, this Makefile adds support for static
     47 libraries and an uninstall target. It also enables compiler and linker
     48 flags for various hardening features, improving the security and
     49 robustness of generated binaries. More broadly, the motivation for this
     50 rewrite is to rely on a well-established standard with a simple feature
     51 set, available on all UNIX systems - reducing portability concerns and
     52 maintenance burden while remaining significantly lighter.
     53 
     54 Also raise the minimum required version of dependencies.
     55 
     56 ### Version 0.9
     57 
     58 - Fix self-intersection on meshed mirrors.
     59 - Raise the minimum required Star-SampPling to 0.12. This version fixes
     60   compilation errors with gcc 11 but introduces API breaks.
     61 - Raise the minimum required Star-3D to 0.8.
     62 - Fix compilation warnings detected by gcc 11.
     63 
     64 ### Version 0.8
     65 
     66 Register into the estimator the final state of the RNG used during the
     67 simulation. Add the `ssol_estimator_get_rng_state` function that returns this
     68 state.
     69 
     70 ### Version 0.7.3
     71 
     72 - Update the version of the RSys and StarSP dependencies.
     73 - Fix a compilation warning with GCC7 and above.
     74 
     75 ### Version 0.7.2
     76 
     77 Fix the gaussian sunshape.
     78 
     79 ### Version 0.7.1
     80 
     81 Fix the creation of a glossy BSDF that uses a pillbox microfacet distribution.
     82 
     83 ### Version 0.7
     84 
     85 - Add the Gaussian sun shape.
     86 - Add the microfacet distribution parameter to the mirror material: one can
     87   choose either the Beckmann or the pillbox distribution.
     88 
     89 ### Version 0.6.1
     90 
     91 - Rename the `ssol_sun_pillbox_set_theta_max` function in
     92   `ssol_sun_pillbox_set_half_angle`.
     93 
     94 ### Version 0.6
     95 
     96 - Fix the integration for non parallel sun: the angle between the principal sun
     97   direction and the sampled direction was not correctly taken into account
     98   leading to a wrong initial weight for the optical paths.
     99 - Fix the integration with shapes having perturbed normals: perturbed normals
    100   must be taken into account in the bounces of the optical paths only, not in
    101   the energy computations.
    102 - Fix the distribution of the pillbox sun: the pdf was wrong.
    103 - Fix the `ssol_sun_pillbox_aperture` function and rename it to
    104   `ssol_sun_pillbox_set_theta_max`. The submitted parameter, i.e. `theta_max`,
    105   is the angular radius but was treated as the angular diameter.
    106 - Update the `ssol_solve` API: add a parameter that controls the number of
    107   realisations than can fail before an error occurs.
    108 
    109 ### Version 0.5
    110 
    111 - Improve performance by up to 50% by optimizing the allocation of the BSDF
    112   along the optical paths. Performance gains are mainly observed in situations
    113   where the optical paths are deep, i.e. when they bounce on many surfaces.
    114 
    115 ### Version 0.4.2
    116 
    117 - Energy conservation property might not be ensured when the optical paths were
    118   fully absorbed.
    119 - Handle infinite optical paths, i.e. paths that bounce infinitely due to the
    120   material properties and/or numerical inaccuracies. Use a Russian roulette to
    121   stop the optical random walk without bias.
    122 
    123 ### Version 0.4.1
    124 
    125 - Fix a wrong "path inconsistency" check. The paths going from a dielectric to
    126   infinity were wrongly detected as inconsistent.
    127 
    128 ### Version 0.4
    129 
    130 - Add the `SSOL_PATH_ERROR` type used for the paths that travel unforeseen
    131   mediums.
    132 - Fix the cosine factor estimation that did not take into account the
    133   shadowed realisations.
    134 - Ensure the energy conservation property for dielectric materials. Previously,
    135   some energy was lost even for dielectric materials with no absorption.
    136 
    137 ### Version 0.3
    138 
    139 - Full rewrite of the estimated values. The global results report the cosine
    140   factor, and the overall flux that is: absorbed by the receivers, atmosphere,
    141   or other entities; occluded before it reaches a primary entity; missed
    142   because it does not reaches any surface. The per receiver results include the
    143   incoming/absorbed flux in 3 situations: all phenomenons are taken into
    144   account; the atmosphere is disabled; the material propagate the whole
    145   incoming flux, i.e. they absorbed nothing.
    146 - Update the `ssol_solve` API. Streamed binary outputs are removed.
    147 
    148 ### Version 0.2.2
    149 
    150 - Fix the estimation of the cosine factor for the  sampled instances: it was
    151   not correctly reported and was thus always equal to 0.
    152 
    153 ### Version 0.2
    154 
    155 - Add normal maps to describe spatially varying normals in the tangent space of
    156   the surface.
    157 - Add support of spectral data to the atmosphere and the materials.
    158 - Fix the per primitive irradiance estimate by dividing the result by the area
    159   of the primitive in order to have watts per square meter.
    160 
    161 ## License
    162 
    163 Copyright (C) 2018-2026 |Meso|Star> (<contact@meso-star.com>).
    164 Copyright (C) 2016, 2018 CNRS.
    165 
    166 Solstice-Solver is free software released under the GPL v3+ license: GNU GPL
    167 version 3 or later. You are welcome to redistribute it under certain
    168 conditions; refer to the COPYING file for details.
    169