Demonstrating solarpilot’s Python Application Programmable Interface Through Heliostat Optimal Aimpoint Strategy Use Case

Power tower concentrating solar power (CSP) systems consist of a solar field, or a field containing hundreds or thousands of heliostats, or devices that track the sun and contain individual mirrored surfaces that reflect incoming solar irradiation onto a receiver. The analysis of power tower CSP systems requires a detailed representation and characterization of the field’s geometric layout and optical performance. One method to generate and evaluate a solar field is to use the National Renewable Energy Laboratory’s (NREL’s) solarpilot^TM software [1]. However, previous releases of solarpilot offer limited user interfaces, which restrict the software’s usability and flexibility to perform detailed solar field analysis conjointly with other CSP researchers’ modeling efforts.

Within the CSP research community, there exists many software programs to analyze optical performance of CSP configurations [2,3]. Tonatiuh [4] is an open-source performance characterization tool that uses Monte Carlo ray tracing (MCRT) and is implemented in c++. SOLSTICE [5] is a standalone executable release that utilizes an integrated formulation Monte Carlo algorithm to obtain the solar flux on the receiver. Heliosim [6] includes a graphical user interface (GUI) and performs MCRT while leveraging the parallel capabilities of GPUs, utilizing NVIDIA’s OptiX Ray Tracing Engine. Similarly, TieSOL [7,8] optimizes both layouts and aiming strategies for CSP tower plants by leveraging GPUs in parallel computing to obtain flux maps. In addition to MCRT, other software packages utilize analytical, convolution-based methods to obtain flux maps efficiently; see, e.g., Refs. [9–13]. Further comparisons between these models are available in Ref. [14]. However, to the authors knowledge, an open-source, python-compatible, computationally efficient software to perform heliostat layout and field optical performances does not exist. sbpray, developed by Schlaich Bergermann Partner, is a parallelized ray-tracing software that is accessible through a bespoke GUI or a python interface [15]. sbpray is a commercially developed software and not open source. Tracer and OTSun are open-source python libraries that perform Monte Carlo ray tracing and have been validated against other optical performance models [16,17]. However, ray tracing can be computationally expensive as the optical system scale increases, e.g., increasing the number of heliostats.

Heliostat field layout and receiver sizing is an important step when designing and optimizing a power tower CSP system. Grigoriev et al. described an approach that uses FluxTracer to optimize a cylindrical receiver sizing by computing an annual ray-tracing simulation and then postprocessing receiver sizing impacts on annual energy collected [18]. The authors conclude that their design space has a global optimum; however, the space is shallow with respect to their design variables, i.e., receiver height and diameter. Ortega et al. used SENSOL evaluate a tower CSP plant profitability for a sensitivity analysis, which included tower height, receiver diameter, and receiver height [19]. The work we present in this article can be applied to similar problems within the CSP industry and research communities.

solarpilot is an open-source, c++ software tool that generates solar field layouts and characterizes the optical performance of CSP tower systems. solarpilot can simulate receiver flux distributions using two methods: (i) a Hermite expansion technique (analytical) and (ii) a ray-tracing technique called SolTrace^TM [20]. The Hermite method enables solarpilot to accurately simulate large solar fields in a quick and computationally efficient manner, while SolTrace provides a robust Monte Carlo-based ray-tracing method that allows cross-comparison of results and analysis of more complex geometries.

solarpilot is a well-known and frequently used software in the CSP research community. Previously, solarpilot users were limited to interacting with software through either the GUI or Language Kit (LK) application programming interface (API), as shown in Fig. 1 on the left-hand side. The GUI provides an interactive visual method for users to update variables and explore results; however, creating multiple cases and performing large parametric analysis can be cumbersome and time consuming. The LK-API overcomes these challenges by providing the ability to create scripts that execute solarpilot’s computational methods. However, LK is a domain-specific language that requires solarpilot’s GUI to operate in the background, has a limited documentation and user support network, and has very limited capabilities for data analysis and visualization; therefore, users typically are required to develop a LK script to perform a specific solarpilot analysis and export those results to a more flexible programming language, e.g., python [21]. In addition, users can utilize solarpilot’s computational methods through system advisor model (SAM), which enables receiver fluid flow path calculations [22]; however, this interface is even more restrictive than the aforementioned two methods. To address this problem, we developed a full-featured, python-based API for solarpilot, which we hereafter refer to as CoPylot.

In this article, we present the architecture and capabilities of CoPylot. We provide a brief description of how users can access CoPylot. Then, we present a working example using CoPylot to generate a solar field, simulate performance, and access solarpilot results. Next, we present an aimpoint optimization use case that utilizes CoPylot to provide solar field layout and characterization of heliostat flux images onto the receiver. Finally, we conclude with a summary and extensions of our work.

CoPylot is a full-featured, python-based API for solarpilot that directly interacts with solarpilot’s dynamic-link library (DLL), as shown in Fig. 1 on the right-hand side. The flow of information when using any function in CoPylot is as follows:

1. A python-based function within CoPylot is called.

2. The analogous c++ function within the solarpilot DLL is executed.

3. The c++ outputs from the DLL are returned in python.

CoPylot enables users access to solarpilot’s computation engines seamlessly through the python scripting interface. This new capability of solarpilot provides a versatile tool to CSP tower researchers to generate heliostat layouts and characterize field performance through python or even embed solarpilot into other research tools. For example, CoPylot could be integrated into a model investigating optimal receiver design or operations, which is outside of the current scope of solarpilot’s capabilities. In addition, CoPylot users have access to the over 100,000 open-source python libraries to develop, analysis, optimize, and visualize CSP tower research.

To develop CoPylot, we create new solarpilotc++ source code to export functions from its DLL. CoPylot accesses the DLL exported functions utilizing ctypes, a foreign function library for python. CoPylot manipulates python user inputs to compatible C data types for interfacing with the c++solarpilot DLL and converts DLL return information to python-specific data structures, thereby increasing CoPylot’s usability. In addition to being accessed by python through the CoPylot interface, solarpilot’s DLL exported functions may be accessed by other scripting languages, e.g., matlab®, by creating an API within the specific language to handle data type conversions, as shown in Fig. 1. While we did not create these links within this work, the development of these APIs would be straightforward with the existing c++ source code and could be developed in future work.

CoPylot enables users to access all of solarpilot’s functionality through a python scripting interface. A brief summary of CoPylot’s functionality includes:

1. Creating and destroying model instances that include callback functionally to propagate messages from solarpilot back to python users

2. Accessing and setting solarpilot’s variables including importing custom land boundaries for field layout

3. Managing receiver and heliostat objects with varied attributes for systems with multiple receiver or heliostat types

4. Generating, assigning, and modifying solar field layouts including the ability to set individual heliostat locations, aimpoints, soiling rates, and reflectivity level

5. Simulating solar field performance

6. Returning detailed results describing performance of individual heliostat performance, the aggregated field, and receiver flux distribution

7. Exporting the python created solarpilot instance to either a .csv file with all variable values or a solarpilot.spt file enabling the instance to be loaded by solarpilot’s GUI

The Appendix presents a complete list of CoPylot’s supported function declarations with brief descriptions. These functions provide users access to solarpilot’s modeling capability through python and enable a flexible interface that can be applied to the user’s specific application of interest. Please refer to the CoPylot python class source code for more detail on function arguments and return values. All interfaces with CoPylot should start with data_create() and end with data_free(), which creates and frees an instance of solarpilot in memory, respectively.

To start using CoPylot, download solarpilot available for Windows or Linux through the NREL website. For the Windows configuration, follow the installer to complete installation of solarpilot. After installation is complete, navigate to the solarpilot 1.4.0 directory (default location:

C:\Program Files\SolarPILOT\1.4.0), where you will see the api folder that contains everything needed to use CoPylot. The minimum set of files required to use CoPylot are copylot.py and solarpilot.dll. Users can copy and paste these files into their specific projects that want to interact with CoPylot. CoPylot assumes that the DLL file exists in the same folder as copylot.py; if not the case, users will need to update CoPylot’s path to the DLL file within the CoPylot class (contained in copylot.py). In addition, there is a CoPylot test script (test_script.py) and a minimum working example (min_example.py) that provides example code using the CoPylot python class. For the Linux version, everything stated earlier holds true except that solarpilot’s download will be a tarball gzip file (i.e., .tar.gz extension) and CoPylot will access solarpilot using a .so dynamic library rather than the Windows .dll.

The following is python code presenting a working example using CoPylot to generate a solar field, simulate performance, and access solarpilot results.

In this example, the solar field is generated and simulated using solarpilot default variable values. The first step when working with CoPylot is to import the class from copylot.py and create a class instance. The CoPylot class contains all of the methods for interacting with solarpilot’s DLL. When data_create() is called, CoPylot creates an api_helper data structure within the DLL to store a solarpilot instance’s variables, solar field, and results. This method returns a pointer that is utilized by other CoPylot methods to access the specific instance of solarpilot. As a result of this methodology, the user can create and manipulate multiple solarpilot instances, simultaneously, using their unique memory pointers. This enables easy implementation of parallel computation in the python interface, e.g., using the multiprocessing package.

By default, CoPylot callback functionality is disabled to suppress console messages when CoPylot is embedded into other research modeling tools. However, users may enable the callback by using api_callback_create(). This method provides a link between CoPylot and the DLL, which allows the latter to return messages to the python console. This callback can be very useful when working with CoPylot for the first time as it provides users with detailed error messages for common mistakes, e.g., trying to set a variable with the wrong name or data type. To disable the callback, users can call the api_disable_callback() method.

When CoPylot creates a solarpilot instance, it sets all the variables to their default values except for the weather file path. We designed CoPylot to exist independent of solarpilot’s GUI and its installed directory that includes climate_files containing a collection of location-specific weather files. As a result, the user is required to set "ambient.0.weather_file" to a weather file path using the appropriate variable setter method, data_set_string(), before field generation. This weather file must conform with the formats described in the solarpilot’s documentation. A complete list of solarpilot variable names can be found through the LK scripting tool accessed through solarpilot’s GUI (File → New Script → Help). We plan to improve the variable naming documentation in the future work.

Once the user has updated variable values as desired, they can run generate_layout() to generate a solar field layout. This method returns a Boolean to specify if the process was successful. This method is equivalent to pressing the “Generate New Layout” on the Field Layout page in the solarpilot’s GUI. get_layout_info() returns the solar field layout as a Pandas DataFrame [23], which contains each heliostat’s x-, y-, and z-coordinates as well as a unique ID number, heliostat template ID, and layout metric. This method has additional keyword functionality, which can (i) change the return format to either dictionary (restype = "dict") or a matrix and header lists (restype = "mat") and/or (ii) provide the corner coordinates for each heliostat reflective surface (get_corners = True).

CoPylot’s simulate() simulates performance using the stored solar field, specified sun position, and simulation parameters (equivalent to pressing the “simulate performance” button on the Performance Simulation page in the solarpilot’s GUI). Similar to generate_layout(), simulate() returns a Boolean to specify if the method was successful. After simulation, users can access the receiver flux distribution using get_fluxmap(), which returns a matrix (i.e., list of lists).

CoPylot’s detail_results() provides the detailed simulations results for each heliostat in a Pandas DataFrame (by default) [23]. This DataFrame contains all of the information typically found on the Layout Results page in the solarpilot GUI. This method contains all of the keyword arguments described for get_layout_info(), as well as a way to select specific heliostats using a list of heliostat ID numbers (selhel= []). With the output of detail_results(), users can analyze and visualize the solar field performance metrics using any of the available open-source python libraries. For example, we created an interactive Bokeh heliostat field plotting tool that allows users to (i) change the field performance metric being displayed, (ii) zoom in to and highlight specific heliostats within the field, and (iii) view overall heliostat field statistics and distribution of performance for the specific metric of interest, as shown in Fig. 2 [24]. Currently, this Bokeh application has not been released to the public; however, a version of this application may be released during the future development.

CoPylot’s summary_results() returns a dictionary of system summary results from each simulation, which is equivalent to table presented on System Summary page of the solarpilot’s GUI. This table can be printed to console using the keyword argument save_dict=False. Finally, when the desired computation is completed, it is important to free the solarpilot instance allocated memory using data_free(). This will prevent a potential memory leak during multi-threading processes.

The purpose of presenting this working example of CoPylot is to provide a basic understanding of using CoPylot to create solarpilot instances, generate solar fields, and simulate field performance. This example is by no means comprehensive and does not present all of CoPylot’s functionality. For further documentation, CoPylot’s methods use docstrings to provide users with details about each method’s purpose, parameters, and returns.

We demonstrate the usefulness of the CoPylot library to the CSP community by describing a use case in which the solarpilotpython API is used to support an aimpoint optimization tool that is implemented in python. The tool, Heliostat and Layout Optimization Software (halos) [25], generates layouts using solarpilot and obtains optimized aimpoint strategies by solving a mixed-integer linear program. This implementation differs from other aimpoint strategy optimization methods using integer programming methods [26,27] by separating a solar field into sections whose flux images and aimpoint strategies are optimized in parallel and then aggregated into a final solution.

halos² is an open-source aimpoint optimization software tool that is developed in python [25]. Using a field layout and receiver characteristics as input, halos generates flux images assuming a centrally located aimpoint on the receiver and then translates the flux images directly across a discretized surface for a collection of aimpoints to obtain candidate aimpoints and flux maps. These then serve as input to a mixed-integer linear program that is implemented in pyomo, an open-source algebraic modeling language developed at Sandia National Laboratories [28]. The formulation within halos enforces receiver flux limits and allows for a discrete collection of aimpoints and measurement points on the receiver, similar to other mixed-integer programming models developed by Ashley et al. [26] and Kuhnke et al. [27]. However, although the other models utilize a single instance to obtain all aimpoints, halos subdivides the solar field into sections that may be solved in parallel to reduce computing time for large-scale systems. More information on halos and the mathematical formulation are available in Ref. [29].

halos connects to solarpilot via the CoPylot library, which allows for a large collection of flux models and plant characteristics to be evaluated using optimized aiming strategies rather than the heuristic employed within solarpilot. In what follows, we describe a collection of case studies that test the computational advantage of using CoPylot to obtain flux images to populate instances of the model in halos instead of either using python or interacting with solarpilot through the filesystem.

Figure 3 describes the procedure halos uses to generate and then solve instances of its optimization model, which is implemented in pyomo [28,30]. If a solar field is provided, halos can call solarpilot to obtain the individual heliostat flux images by simulating with only one heliostat enabled in the field via modify_heliostats(), simulate(), and get_fluxmap() methods; these individual images serve as input to the halos aimpoint strategy optimization model. Alternatively, if no solar field is provided but the required information to generate a solar field is provided to halos, it uses CoPylot to generate a solar field layout via generate_layout() and then to produce the flux images.

The default method of flux characterization in halos is Gaussian when solarpilot is not used, and so we compare the computing times when using solarpilot to calculate the flux images versus using halos directly, in which the former uses the Hermite method to develop a single image after aggregating different sources of optical error. By utilizing the flux image processing library in solarpilot via the CoPylot library, halos has direct access to high-fidelity flux characterization methods without re-implementation of those methods. In addition, using CoPylot to generate model instances was about 2–4× faster than the analogous flux model in halos for a collection of four separate cases, as presented in Table 1. Because halos does not calculate non-Gaussian images within its own library, we develop a second collection of case studies for the pillbox flux method by comparing the direct use of CoPylot against using solarpilot to generate individual flux maps, saving each one to the filesystem, and then running halos to read in the images from the filesystem to populate the aimpoint optimization model. All cases were generated using a Dell Laptop with an Intel Core i7-8650 CPU and 16GB RAM. The results of the first four cases demonstrate the computational benefit associated with using solarpilot’s more complex but faster c++ implementation versus performing inverse-Gaussian calculations in python, while the results of the second four cases demonstrate the benefit of directly passing the flux images to the optimization model in memory rather than using the filesystem. We note that in the latter four cases, we utilize CoPylot to generate the individual flux maps because doing so through the solarpilot GUI would require a run for each individual heliostat, which would increase the improvement factor by orders of magnitude.

In addition to the aforementioned case studies, we generated a collection of 30 different individual flux images using both the solarpilot GUI and CoPylot. In each case, the flux maps generated were identical; as a result, the accuracy of CoPylot as a flux method is identical to that of solarpilot.

CoPylot is an open-source, computationally efficient python API for solarpilot, which enables users to generate and simulate power tower solar field optical performance. In this article, we presented the architecture and capabilities of CoPylot, provided users the location to access CoPylot, presented a basic CoPylot working example, and described an aimpoint optimization use case that utilizes CoPylot.

CoPylot provides CSP researchers access to solarpilot’s computational methods within the python framework. We believe CoPylot will increase solarpilot usability and enables researchers to quickly perform CSP power tower modeling with minimum overhead using solarpilot. In addition, CoPylot users have access to the over 100,000 open-source python libraries to develop, analyze, optimize, and visualize CSP tower research.

With the release of CoPylot, we hope CSP researchers find the API useful and encourage them to provide feedback about their user experience. In the future work, we will provide CoPylot users access to additional functionality developed within solarpilot. In addition, researchers can develop other language API’s using the exported DLL functions developed in this work, thereby increasing solarpilot accessibility.

This material is based upon work supported by the U.S. Department of Energy’s Office of Energy Efficiency and Renewable Energy (EERE) under the Solar Energy Technologies Office Award Number 35930. This paper was prepared as an account of work sponsored by an agency of the United States Government. Neither the United States Government nor any agency thereof, nor any of their employees, makes any warranty, express or implied, or assumes any legal liability or responsibility for the accuracy, completeness, or usefulness of any information, apparatus, product, or process disclosed, or represents that its use would not infringe privately owned rights. Reference herein to any specific commercial product, process, or service by trade name, trademark, manufacturer, or otherwise does not necessarily constitute or imply its endorsement, recommendation, or favoring by the United States Government or any agency thereof. The views and opinions of authors expressed herein do not necessarily state or reflect those of the United States Government or any agency thereof.

There are no conflicts of interest.

Table 2 presents the list of CoPylot’s supported function declarations.