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 (6789B)

      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 x86-64 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 dedicated
     17 [Solstice web page](https://www.meso-star.com/solstice/install.html).
     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.11
     39 
     40 - Add location + date as a way to define sun direction.
     41 
     42 - Add 2 algorithm to compute sun direction from locatio + date (Meeus and PSA).
     43 
     44 ### Version 0.10
     45 
     46 Replace CMake with a POSIX Makefile
     47 
     48 The build procedure is now written in POSIX make and can be configured via
     49 the config.mk file. A pkg-config file is also provided to link the
     50 library as an external dependency.
     51 
     52 Compared to the CMake alternative, this Makefile adds support for static
     53 libraries and an uninstall target. It also enables compiler and linker
     54 flags for various hardening features, improving the security and
     55 robustness of generated binaries. More broadly, the motivation for this
     56 rewrite is to rely on a well-established standard with a simple feature
     57 set, available on all UNIX systems - reducing portability concerns and
     58 maintenance burden while remaining significantly lighter.
     59 
     60 Also raise the minimum required version of dependencies.
     61 
     62 ### Version 0.9
     63 
     64 - Fix self-intersection on meshed mirrors.
     65 - Raise the minimum required Star-SampPling to 0.12. This version fixes
     66   compilation errors with gcc 11 but introduces API breaks.
     67 - Raise the minimum required Star-3D to 0.8.
     68 - Fix compilation warnings detected by gcc 11.
     69 
     70 ### Version 0.8
     71 
     72 Register into the estimator the final state of the RNG used during the
     73 simulation. Add the `ssol_estimator_get_rng_state` function that returns this
     74 state.
     75 
     76 ### Version 0.7.3
     77 
     78 - Update the version of the RSys and StarSP dependencies.
     79 - Fix a compilation warning with GCC7 and above.
     80 
     81 ### Version 0.7.2
     82 
     83 Fix the gaussian sunshape.
     84 
     85 ### Version 0.7.1
     86 
     87 Fix the creation of a glossy BSDF that uses a pillbox microfacet distribution.
     88 
     89 ### Version 0.7
     90 
     91 - Add the Gaussian sun shape.
     92 - Add the microfacet distribution parameter to the mirror material: one can
     93   choose either the Beckmann or the pillbox distribution.
     94 
     95 ### Version 0.6.1
     96 
     97 - Rename the `ssol_sun_pillbox_set_theta_max` function in
     98   `ssol_sun_pillbox_set_half_angle`.
     99 
    100 ### Version 0.6
    101 
    102 - Fix the integration for non parallel sun: the angle between the principal sun
    103   direction and the sampled direction was not correctly taken into account
    104   leading to a wrong initial weight for the optical paths.
    105 - Fix the integration with shapes having perturbed normals: perturbed normals
    106   must be taken into account in the bounces of the optical paths only, not in
    107   the energy computations.
    108 - Fix the distribution of the pillbox sun: the pdf was wrong.
    109 - Fix the `ssol_sun_pillbox_aperture` function and rename it to
    110   `ssol_sun_pillbox_set_theta_max`. The submitted parameter, i.e. `theta_max`,
    111   is the angular radius but was treated as the angular diameter.
    112 - Update the `ssol_solve` API: add a parameter that controls the number of
    113   realisations than can fail before an error occurs.
    114 
    115 ### Version 0.5
    116 
    117 - Improve performance by up to 50% by optimizing the allocation of the BSDF
    118   along the optical paths. Performance gains are mainly observed in situations
    119   where the optical paths are deep, i.e. when they bounce on many surfaces.
    120 
    121 ### Version 0.4.2
    122 
    123 - Energy conservation property might not be ensured when the optical paths were
    124   fully absorbed.
    125 - Handle infinite optical paths, i.e. paths that bounce infinitely due to the
    126   material properties and/or numerical inaccuracies. Use a Russian roulette to
    127   stop the optical random walk without bias.
    128 
    129 ### Version 0.4.1
    130 
    131 - Fix a wrong "path inconsistency" check. The paths going from a dielectric to
    132   infinity were wrongly detected as inconsistent.
    133 
    134 ### Version 0.4
    135 
    136 - Add the `SSOL_PATH_ERROR` type used for the paths that travel unforeseen
    137   mediums.
    138 - Fix the cosine factor estimation that did not take into account the
    139   shadowed realisations.
    140 - Ensure the energy conservation property for dielectric materials. Previously,
    141   some energy was lost even for dielectric materials with no absorption.
    142 
    143 ### Version 0.3
    144 
    145 - Full rewrite of the estimated values. The global results report the cosine
    146   factor, and the overall flux that is: absorbed by the receivers, atmosphere,
    147   or other entities; occluded before it reaches a primary entity; missed
    148   because it does not reaches any surface. The per receiver results include the
    149   incoming/absorbed flux in 3 situations: all phenomenons are taken into
    150   account; the atmosphere is disabled; the material propagate the whole
    151   incoming flux, i.e. they absorbed nothing.
    152 - Update the `ssol_solve` API. Streamed binary outputs are removed.
    153 
    154 ### Version 0.2.2
    155 
    156 - Fix the estimation of the cosine factor for the  sampled instances: it was
    157   not correctly reported and was thus always equal to 0.
    158 
    159 ### Version 0.2
    160 
    161 - Add normal maps to describe spatially varying normals in the tangent space of
    162   the surface.
    163 - Add support of spectral data to the atmosphere and the materials.
    164 - Fix the per primitive irradiance estimate by dividing the result by the area
    165   of the primitive in order to have watts per square meter.
    166 
    167 ## License
    168 
    169 Copyright (C) 2018-2026 |Méso|Star> (<contact@meso-star.com>).
    170 Copyright (C) 2016, 2018 CNRS.
    171 
    172 Solstice-Solver is free software released under the GPL v3+ license: GNU GPL
    173 version 3 or later. You are welcome to redistribute it under certain
    174 conditions; refer to the COPYING file for details.
    175