nrel / soltrace

SolTrace

SolTrace

The SolTrace Open Source Project repository contains the source code, tools, and instructions to build a desktop version of the National Renewable Energy Laboratory's SolTrace. SolTrace is a software tool developed at NREL to model concentrating solar power (CSP) systems and analyze their optical performance. Although ideally suited for solar applications, the code can also be used to model and characterize many general optical systems. The creation of the code evolved out of a need to model more complex solar optical systems than could be modeled with existing tools. For more details about SolTrace's capabilities, see the SolTrace website. For details on integration with SAM, see the SAM website.

The desktop version of SolTrace for Windows or Linux builds from the following open source projects:

• LK is a scripting language that is integrated into SAM and allows users to add functionality to the program.

• wxWidgets is a cross-platform graphical user interface platform used for SAM's user interface, and for the development tools included with SSC (SDKtool) and LK (LKscript). The current version of SAM uses wxWidgets 3.1.0.

• WEX is a set of extensions to wxWidgets for custom user-interface elements used by SAM, and by LKscript and DView, which are integrated into SAM.

• This repository, SolTrace, provides the user interface to assign values to inputs of the computational modules, run the modules in the correct order, and display calculation results. It also includes tools for editing LK scripts and viewing ray intersection and flux map data.

SolTrace Python API

Users can also run simulations via the pysoltrace SolTrace Python API found in the folder app/deploy/api. Example files for running the API are found in the app/deploy/api/examples subfolder. Documentation is available in HTML or PDF format in the corresponding API subfolder.

The pysoltrace API is capable of running multi-threaded simulations, generating flux maps, creating 3D interactive trace plots, and provides other capabilities that are found in the SolTrace graphical interface. The functionality and flexibility of the API generally exceeds that of the graphical interface.

The API requires the compiled coretrace library. Project files for building this library are generated using CMake as outlined in the steps below. It is possible to build only coretrace and not build the graphical interface by following the steps 1-7, but only building the coretrace_api project in step 7.vii.

Steps for Building SolTrace

These are the general steps you need to follow to set up your computer for developing SolTrace:

1. Set up your development tools:

   • Windows: Visual Studio 2022 Community or other editions available at https://www.visualstudio.com/.
   • Linux: g++ compiler available at http://www.cprogramming.com/g++.html or as part of the Linux distribution.

2. Download and install CMake 3.28 or higher from https://cmake.org/download/ with the Add CMake to the System Path for ... option selected.

3. Download the wxWidgets 3.2.4 source code for your operating system from https://www.wxwidgets.org/downloads/.

4. Build wxWidgets.

5. In Windows, create the WXMSW3 environment variable on your computer to point to the wxWidgets installation folder, or Linux, create the dynamic link /usr/<USERNAME>/local/bin/wx-config-3 to point to /path/to/wxWidgets/bin/wx-config.

6. As you did for wxWidgets, clone (download) the LK and WEX repositories and then (Windows only) create an environment variable pointing to the project folder.

   Project	Repository URL	Windows Environment Variable	Environment Variable Path
   LK	https://github.com/NREL/lk	LKDIR	/path/to/lk
   WEX	https://github.com/NREL/wex	WEXDIR	/path/to/wex

   Open a Git Bash window and navigate to the WEX directory. Check out the following tag:

   cd wex
   git checkout tags/2021.12.02.r2.ssc.274
   

7. Run CMake to create the project build files

   1. Copy the file parent-dir-CMakeLists.txt into the parent directory also containing soltrace/ lk/ wex/ and wxwidgets-3.x.x/ folders.

   2. Rename this file to CMakeLists.txt before running cmake. You may need to temporarily rename any other file in this directory with the same name.

      E.g., the file should be at C:/stdev/CMakeLists.txt

   3. Create a directory in the main parent folder to store the build files. E.g., C:/stdev/build-soltrace/

   4. Open a shell or command window, and navigate to the build folder you just created.

   5. Copy the following cmake command to the shell and run. Replace the cmake target with a supported generator

      cmake -G "Visual Studio 17 2022" -DCMAKE_CONFIGURATION_TYPES="Debug;Release" -DCMAKE_SYSTEM_VERSION=10.0 -DSAM_SKIP_TOOLS=1 .. 
      

   6. Confirm the project files built. If running visual studio, you should see a soltrace_ui.sln file in the build-soltrace/ directory.

   7. Build all files. The output is stored in the soltrace repository folder, e.g., C:/stdev/soltrace/app/deploy/soltrace.exe.

      Note that output is NOT stored in the build-soltrace/ directory!

Contributing

If you would like to report an issue with SolTrace or make a feature request, please let us know by adding a new issue on the issues page.

If you would like to submit code to fix an issue or add a feature, you can use GitHub to do so. Please see Contributing for instructions.

License

SolTrace's open source code is copyrighted by the Alliance for Sustainable Energy and licensed under a mixed MIT and GPLv3 license. It allows for-profit and not-for-profit organizations to develop and redistribute software based on SolTrace under terms of an MIT license and requires that research entities including national laboratories, colleges and universities, and non-profit organizations make the source code of any redistribution publicly available under terms of a GPLv3 license.

Citing SolTrace

We appreciate your use of SolTrace, and ask that you appropriately cite the software in exchange for its open-source publication. Please use one of the following references in documentation that you provide on your work. For general usage citations, the preferred option is:

Wendelin, T. (2003). "SolTRACE: A New Optical Modeling Tool for Concentrating Solar Optics." Proceedings of the ISEC 2003: International Solar Energy Conference, 15-18 March 2003, Kohala Coast, Hawaii. New York: American Society of Mechanical Engineers, pp. 253-260; NREL Report No. CP-550-32866.

For citations in work that involves substantial development or extension of the existing code, the preferred option is:

Wendelin, T., Wagner, M.J. (2018). "SolTrace Open-Source Software Project: github.com/NREL/SolTrace". National Renewable Energy Laboratory. Golden, Colorado.

soltrace's Issues

format of binary data for writerayfile

Hi,
Is there any documentation for how to read the binary file created from writerayfile()? What is the encoding method?
Thanks,
Tamir

SolTRACE unable to export heat flux CSV file

In my latest download of solTRACE, I am able to get the heat flux map; however when trying to export to csv file, only the x and y axis markers are exported, instead of the flux data

How to define the height of the secondary concentrator in Soltrace

Dear managers:
I would like to add a secondary reflector to the upper part of the heat absorber based on the Trough system, but I find no way to define the length of the secondary reflector. Even the secondary mirror intersects with the trough concentrator. Other than that I wonder how I can run the LK script with cmd calling SOLTRACE, I follow the prompt on GITHUB and Fail to open file '-s' appears.
Hope to be able to get some advice!!!!
Best wishes!

Randomness and Seed Value

Is there any documentation about how the SolTrace implements the monte carlo randomness for ray distribution? I was under the impression that if you used the same seed you would get the same ray distribution.

Specifically the problem I am having is that for a single flat surface element in a singe stage I get different ray distributions depending on the optical properties of the that element. Depending on if the transmission is 0 or 1 I get different distributions. I would expect that all else being equal - a single element should get the same distribution regardless of the transmission value (assuming reflectivity is 0 for both). I can see how it would change if you add and remove elements from a stage or otherwise change the geometry of the stage but not for a stage with a single element and nothing else.

I've attached two stinput files which I expect to give the same distribution when using the same seed value.

Seed.zip

Add project files for VSCode in coretrace

Needs cpp and tasks file for build. Does not need launch file for debug, as coretrace is just a library.

csoltrace error

When I run csoltrace I always get a critical error when trying to specify the seed

I kick off csoltrace from within an lk script using something like this

system("start /b csoltrace.exe -f " + '"' + "myinputfile.stinput" + '"' + " -s 123");

Any idea what might be wrong? It seems like it doesn't like the format of whatever I'm using to specify the seed value

Why don't using bidirectional ray tracing algorithm?

As mentioned in Visual HFLCAL - A Software Tool for Layout and Optimisation of Heliostat Fields, the bidirectional ray tracing algorithms ,that generate ray on the surface of heliostats, will get better performance by getting rid of calculating the intersection of ray with heliostat and the rays casting to ground.
Why SolTrace don't using bidirectional ray tracing algorithms to accelerate ?
Look forward to your reply.

Importing Topography and contour details in

I intend to use topography details to evaluate shading factors on individual strings;
Is there a method to import topography ?

Can't seem to find soltrace.exe

The final step is to open soltrace.exe in the deploy folder, but I can't seem to find it. I have even typed in soltrace.exe in the search bar, but still found nothing. Could I have made a mistake during the setup and builds?

Inconsistency between element numbering in GUI and code

Element numbering in scripting language starts at 0 but in GUI it starts at 1 which can be sometimes confusing

linux installation problem

when I run command make in app folder(the last step)
It said cannot find -lcoretrace and exit
how can i solve this problem
i use ubuntu 18.04 server

Looking for example projects

Are there any example projects to get started with? I'm looking to model a Fresnel lens, but can't find much documentation on importing complex surfaces. I have found some documentation on the surface types, but do not recognize any of the supported files. Any advice/best practices for generating and importing complex geometries would be greatly appreciated. Even better if anyone has advice for importing surfaces from SolidWorks. Thanks!

Trace through setting on SolTrace

I would like more information on the "trace through" function on SolTrace. I would need to evaluate the intercept factor on a beam down system without considering shadowing and blocking of the heliostats.
Thanks

Using SolTrace CLI without UI

Hi @mjwagner2,
First of all, thanks for offering the community an excellent tool like SolTrace. I am currently using it for some ray tracing + electrical model applications and would like to learn how to use it to run scenes without the UI on command line for massive parallelization of simulations in a cluster.
Would you be able to advice?
Thanks,
Chetan.

sundata() contents - help

Could you please provide some info about the sundata table?
Which code file should I search in order to find its contents and related calculations?

Thanks in advance
Alex

Gaussian error distribution algorithm

A model intercomparison between SolTrace and other tools revealed some slight differences in the shape of modeled Gaussian distributions, particularly near the low-probability tails. It was determined that the cause of the discrepancies was the Gaussian-normal probability distribution sampling technique used in SolTrace.

The hard-coded routines for calculating distribution samples were replaced by C++ standard library routines, and the discrepancy was resolved.

This bug potentially affects systems relying on Gauss-normal distribution sampling. Errors are typically small and appear in circumstances where single reflectors with perfect or near-perfect focal properties are under consideration.

Updates to interface documentation

The current help functionality in SolTrace consists of LK a function reference listing and a link to the PDF of the Wendelin et al. NREL report on SolTrace. In the older version of SolTrace (pre-wxWidgets...), an interactive help structure existed that provided reference and guidance for each input page.

Moving forward, SolTrace should be updated to restore interactive help menu functionality. Files associated with the old help menu are attached.

old-soltrace-help.zip

The documentation needs to be updated to be accurate for the current model, and it requires expansion to cover new features as needed.

Unsupported features in UI

The user interface currently provides "inputs" for several optical properties and interactions that are not supported by coretrace. Specifically, on the optics page, the following are not supported:

• Optical surface number
• Aperture stop..
• Diffraction order
• Refraction indices > Imag
• Grating spacing coefs (all)

The values specified for these may need to be hard-coded in the interface, as I believe they are all still passed to coretrace as function arguments.

The help menu will be updated to remove reference to these per #12.

Refraction related issue

Hello everybody,

I am trying to model a fresnel lens. Since, rays are perpendicular to the front face of the lens, I am using a single element for refraction. Optical properties are shown below:

addoptic('Refractive Sample');
opticopt('Refractive Sample', 1, {'refl'=0.0, 'refractr'=1.49, 'trans'=1.0, 'errslope'=0.001, 'errspec'=0.001 } );
opticopt('Refractive Sample', 2, {'refl'=0.0, 'refractr'=1.0, 'trans'=1.0, 'errslope'=0.001, 'errspec'=0.001 } );

With these settings, I do not expect reflected rays and also, the maximum number of rays used for the first stage to strike the receiver. (The receiver is a very large horizontal surface located below the lens). However, there exist a small number of rays that appear to be reflected.

Is there a known issue of bug related to the above problem or am I missing something here?

Hope to hear from you,
Alex

Treemesh data structure permanence

The LayoutData structure is a pointer member of the st_hash_tree. In practice, it is instantiated in a method, then passed as an argument to the create_mesh method. If the object is not preserved in the memory of the calling method, important settings used to create the tree mesh are lost. LayoutData should be moved to be an object that is a member of st_hash_tree.

Small field point focus algorithm

The point-focus algorithm seems to be causing a ~3% error in average receiver flux for small heliostat fields. Attached is field containing 33 heliostats at two different solar positions.

small_field.zip

I think we could resolve this using a warning message to users with "small" heliostat fields or adding "large" in front of the point-focus option. I have not checked how many heliostats are required to reduce the observed error.

reftoloc use

Are there any examples of how to use reftoloc? I ended up writing my own code but would be nice to use built in functions

Sun Position

The LK script language should support changing sun position types. Just setting the latitude, day and hour doesn't do anything if the radio button in the GUI is set to global coordinates (which is selected by default when launching the program).

Issues compiling the library to use the Python API

Hi,

I've come across a seemingly unsurmountable barrier when trying to compile soltrace to use the python API. I've compiled and built wxwidgets and set all env variables accordingly, but when I try to compile the library I get the following error:

CMake Error at C:/Program Files/CMake/share/cmake-3.28/Modules/FindPackageHandleStandardArgs.cmake:230 (message): Could NOT find wxWidgets (missing: wxWidgets_LIBRARIES wxWidgets_INCLUDE_DIRS qa webview aui richtext html propgrid adv net stc core base scintilla) Call Stack (most recent call first): C:/Program Files/CMake/share/cmake-3.28/Modules/FindPackageHandleStandardArgs.cmake:600 (_FPHSA_FAILURE_MESSAGE) C:/Program Files/CMake/share/cmake-3.28/Modules/FindwxWidgets.cmake:988 (find_package_handle_standard_args) lk/CMakeLists.txt:92 (find_package)

I don't have a lot of experience building C++ libraries and the whole process was pretty confusing, especially with regards to having everything in the same folder, the role of visual studio, "only building the coretrace_api project" etc. I can only hope that someday we will be able to install this in a more straightforward manner, but I regardless thank the developers for their incredible work with this program and also in advance to anyone who can lend me a hand!

Angle of Incidence Dependence for Transmissivity

Would it be possible to add in the same feature that currently exists for reflectance based on angle of incidence to transmittance as well?

File save/open missing variables

Most inputs on the Trace page are not captured in the save/open process. A file that was saved with modified values will open with default values.

pysoltrace not plotting heat flux data for virtual stage

Hi,

I'm trying to plot the heat flux data for a virtual stage between my heliostats and collector. In the 3d plot it works as expected:

However in the 2d heat flux plot everything seems at zero:

Here's my stage declaration:

sensors = PT.add_stage()
sensors.is_virtual = True
sensors.is_multihit = True

ela = sensors.add_element()
ela.position = Point(0,0,5)
ela.aim.z = 0.
ela.aim.x = 0.
ela.aim.y = 0.
ela.optic = opt_abs
ela.surface_flat()
ela.aperture_rectangle(10,10)

I tried with and without multihit and nothing changes. The reason I've added an optic even if it's a virtual stage is that it crashes without it.

On the plot_flux function I've tried with absorbed_only True and False and nothing changes either.

Any tips? Thanks in advance

Unable to form path of reflection

Hi Just wondering can anyone please provide a guide from using the SolTrace? I have no background of programming and I am currently using it for light stimulation since this earlier year.

I am unable to observe the reflection path when the light strikes on the plate.

And I also aim to create two semicylindrical reflection side-by-side but it wouldnt let me to do it. (or I dont know how to create it)

Can anyone please help? It is really urgent as I used 3 months and get nothing on the stimulation,