cire-thk/bifacialsimu

Simulation of bifacial PV

---

BifacialSimu

BifacialSimu is an open source simulation program designed to simulate and portray the potential benefits of bifacial solar in comparison to standard monofacial solar modules. BifacialSimu allows for the combination of different radiation, albedo and electrical simulation modes, so that multiple scenarios are covered. A defining feature of which is the capability to combine both View Factors and Ray Tracing methods for fast, accurate simulation results.

---

Contents

1. Introduction
2. Prerequisites
3. Installation
4. Quick Start
5. GUI
6. Examples
7. Results
8. Troubleshooting
9. Program Function
10. Contribution
11. Citation
12. License

---

Introduction

This program was developed as part of the doctorate work by Eva-Maria Grommes and developed with the assistance of other students from the TH Köln. It is intended to provide a free, effective tool to simulate the energy yield of bifacial PV technology, thereby proving their advantages and applications. This Readme guide will assist with the installation and operation of the program, providing a quick start to simulating bifacial modules. Basically it is devided into three different simulations, in which each you can choose between different calculation models as displayed below:

The general architechture and functions are displayed in the following figure:

---

Prerequisites

Unfortnatly, BifacialSimu is not supported by Mac OS at the moment. We are working on this issue. If you want to contribute to solving this issue, please contact us.

BifacialSimu is run within a Python environment and dependent on a variety of libraries, most of which are contained within the installation of Anaconda. The program Radiance is necessary in order to run BifacialSimu. Besides that relies BifacialSimu on following libraries:

• bifacial_radiance==0.4.1
• ipython==7.34.0
• matplotlib==3.4.3
• numpy==1.20.3
• pandas==1.3.4
• Pillow==9.1.1
• pvlib==0.9.1
• python_dateutil==2.8.2
• pytz==2021.3
• requests==2.28.1
• seaborn==0.11.2
• Shapely==1.8.2
• tqdm==4.62.3
• pyqt5==5.12.3
• pyqtwebengine==5.12.1
• pvfactors==1.5.2
• daal==2021.4.0
• clyent==1.2.1
• nbformat==5.4.0
• ruamel.yaml==0.17.21

The installation process of which can be found in the following section.

---

Installation

Installation of BifacialSimu is a multi-stage process as it is dependent on a number of other python based tools and programs, combining them to create a comprehensive simulation tool. Make sure to follow these steps closely and before proceeding, read through the entire instructions.

A useful resource for the installation is this video, which covers the following installation steps for bifacial_radiance (necessary for BifacialSimu):

1. Install Anaconda
2. Install Radiance
3. Install Radiance executables (jaloxa)
4. Check Environment Variables
5. Install BifacialSimu

These steps are described below in detail as well, including the intallation of pv_factors, another important tool used by BifacialSimu.

Installation of Anaconda

Anaconda is a Python/R data science distribution, which can be used to run python and related packages. Even if you already have another python environment installed it is still recommended to use Anaconda.
− For Windows: follow the installation instructions here Note: in Step 8 "with Path" should be selected, this is important for the correct installation of bifacial_radiance
− For Mac OS X: follow the installation instructions here
− For other operating systems: follow the installation instructions regarding your system here

Installation of Radiance
for Mac OS X: The installation of XQuartz is required for Radiance to run, this emulates a Windows environment for the program.

An in-depth guide and the installation of Radiance can be found on the Radiance Github Page. Make sure to add the radiance_bin to the system variable path, not the user variable path! Make sure to download the correct package according to your operating system.

Make sure to download and insert the jaloxa Windows Binaries into the Radiance bin folder, these can be downloaded here.

Install BifacialSimu

To install BifacialSimu and Copies of bifacial_radiance and pvfavtors, you can use:

pip install Bifacialsimu --ignore-installed

If that does not work for you, navigate to your local GitHub folder or download BifacialSimu on GitHub. In spyder for example you can navigate using cd:

cd C:\Users\XXX\XXX\GitHub\bifacialSimu

Now use:

pip install . --ignore-installed

Check, if these standard python packages have been installed:
− Pvlib
− Pvfactors

You can find these packages in the Anaconda navigator under “Environments” using the search bar in the upper right corner. The newest version number will be highlighted in blue and you can update the package regarding the manual here

You can check the current version of:
− Pvlib
− Pvfactors

Important! Make sure to update Anaconda regularly to keep your python packages updated!

After a sucessfull installation, you can run the GUI.py in the BifacialSimu\BifacialSimu_src folder.

Run BifacialSimu
− Open Spyder within the Anaconda Navigator
− Open the GUI.py file in spyder
− Run the GUI.py file.

---

Quick Start

This section serves as a Quick Start and also a way of checking that everything has installed correctly, using a base default simulation which can then be adjusted as a way of learning how to operate BifacialSimu and becoming comfortable with the outputs and results.

As a first step, initiate the GUI by running the GUI.py file within your Python operating environment (Spyder or similar) as per the installation instructions. This will then open the Graphical User Interface in a separate window and should look as per below.

By clicking on the button "set default!" all active fields should be filled and ready to simulate. Check that these match the below picture

Before starting the simulation check the Simulation Control and Module Parameter tabs. It may also be advantageous to reduce the simulation time period for this test to one or two days in order to reduce actual simulation time, as per the below example, to one day.

Now check under Module Parameters that all relevant parameters have been filled in, this is also where you can choose a module with the drop down box.

The simulation can now be carried out by clicking on the button "Start Simulation!" under Main Control. This may take a while depending upon your computer's specifications, please have patience.

Once this has completed a variety of graphs will be produced which can be further analysed and exported. Incidentally, the data for these graphs will have been saved in the designated outputs folder produced for this specific simulation which can be found in the same folder as the installation of BifacialSimu:

For a more in-depth explanation of these graphs and what each of them mean please refer to the section Results

Providing that everything has been installed correctly and is functioning properly you can move onto the detailed explanation of the GUI found in the next section.

If, however, any error messages have occured or the simulation doesn't complete please refer to the Troubleshooting section found later in this document.

---

Standard Tests

You can find standard test in the following folder:

BifacialSimu_src\Tests

Running those tests, you are able to test the most important functions of BifacialSimu.

GUI

The GUI provides access to all necessary boundary conditions for simulation within the following sections:

Simulation Parameter

The overarching simulation parameters can be set within this section. These are related to the physical attributes of the entire system such as angle and orientation of the modules. This is where the structure of the PV Array is built, and features such as tracking and which type of surface they are installed on are integrated.

Main Control

This is where the Simulation can be renamed as well as choosing whether to use a local weather file or download an external file depending upon the location

Simulation Control

Within this section various simulation modes can be selected accordingly, depending upon the parameters of the array and desired outcome.

As a rule of thumb, ViewFactors offers a quicker result while Raytracing is more accurate. There are other factors that feed into this however, such as whether there is tracking in the system or if the modules are simply monofacial. The default setting simulates the front side with ViewFactors and the rear with Raytracing, this has the advantage of providing a balance between accuracy and a reduced simulation time. It is especially recommended to use Raytracing for the rear side when simulating a system with tracking as this can be very complex for ViewFactors to handle.

The Time Period of the simulation is set within this section as well as the Time Zone in which the simulation should take place. It's important to note that the Time Zone needs to be manually updated to match the specified Location.

Module Parameter

A number of preset modules can be selected here for evaluation or the specific parameters can be entered manually, allowing a large degree of control and customisation. These should be values obtained under Standard Test Conditions (STC) and as such the correct input values will greatly affect simulation results.

A glossary of the adjustable parameters can be found below:

bi_factor - bifaciality factor
n_front - module efficiency
I_sc_f - short circuit current front side
I_sc_r - short circuit current rear side
V_oc_f - open circuit voltage front side
V_oc_r - open circuit voltage rear side
V_mpp_f - maximum power point voltage front side
V_mpp_r - maximum power point voltage rear side
I_mpp_f - maximum power point current front side
I_mpp_r - maximum power point current rear side
_mpp - maximum power point power
T_koeff_P - temperature coefficient
T_amb - ambient temperature
T_koeff_I - temperature coefficient for short circuit current
T_koeff_V - temperature coefficient for open circuit voltage
zeta - open circuit voltage irradiation coefficient

Important to note is that when no rear side irradiance values are present (e.g. V_oc_r) then you must select "without rear values". More info to this can be found in Electrical Simulation and within the next section.

---

Examples

This section provides a number of examples to help with learning what each part of BifacialSimu does and how to operate it.

Main Control - Weather Data + Location

The first step should be to enter the title of your simulation in the field "Insert Simulation Name".

To use a weather file which has been produced from the location that you are simulating you need to select "Local weather File!" within the Main Control tab.

Using the "Insert Weatherfile!" button you can point to the file on your computer. This will need to be in TMY format, further tips on this can be found in the section Troubleshooting.

If you don't have the data for the area, you can choose the option "Download weather File!" which will require filling out the fields "Enter Longitude" and "Enter Latitude" to locate a weather file for this region.

The time period of your simulation will then need to match that of the weather data. This should be set within the Simulation Control tab as per the below image.

Another important point is to update the Time Zone to match the location in which the simulation is taking place. This is done within the field "UTC offset" as a + or - value e.g. "+1" for Paris or "-5" for New York.

---

Simulation Parameter - Tracking

There are two options for solar tracking within the system which can be chosen for the simulation:

The first is Single Axis Tracking which will amend the angle of the panels in the horizontal plane to acheive higher efficiencies. Once this is activated the "Limit Angle of Tracking System" should be set; this is the maximum angle that the modules can rotate to.

The second option is Backtracking, which aims to reduce the shadowing on modules during extreme sun angles in the morning and evening. For this a clearance height has to be entered which should represent distance between the module and the ground.

---

Simulation Parameter - Albedo

Essentially, the choice of albedo simulation mode will depend upon the data available for your simulation. You can select from the above four options. A detailed explanation for each of these options can be found in the section Program Function under the heading Albedo Simulation.

The simplest option is to choose "Average measured Albedo" and then choose an option from the drop-down menu. This will then take a constant value and implement it in the simulation calculations. It is also possible to manually enter a value here based upon literature sources or otherwise, however this will not be saved and therefore should be taken note of.

If you choose to use the option "Hourly Spectral Albedo" you will need a separate "Reflectivity File" which should be inserted under the section Main Control as per the below picture.

---

Simulation Control - Simulation Options

This example runs through how to set the simulation mode for various use cases and important things that should be taken into consideration. The default setting for simulation is currently to simulate with View Factors on the front side and Ray Tracing on the rear.

This has the advantage of balancing quick simulation results with an improved accuracy, more can be found on this in the section Program Function under the heading Electrical Simulation. Currently it is not possible to utilise Ray Tracing for simulations with a fixed tilt, this is however not disadvantageous, due to how View Factors works with static calculations.
Each Simulation mode can be selected by clicking on it, with the possibility to simulate the surfaces individually if so desired.

Be aware that when selecting View Factors the simulation will be much quicker than Ray Tracing however with a higher degree of inaccuracy.

---

Module Parameter - Module Choice and Electrical Simulation

This example will show you how to choose and customise the solar module to be simulated.

The first step is to go onto the tab Module Parameter. There will be a drop-down menu in the top right corner as per the picture below, with a number of pre-programmed modules available to select from.

By selecting a module, the module parameter section will be filled out, depending upon values provided by the manufacturer. It's important to note here that if no values are provided for any of the rear side, then the electrical simulation will have to be changed to "without rear values" which uses a different simulation mode. More on this can be found in the section Program Function under the heading Electrical Simulation.

Once a module has been selected it is also possible to amend the values in each individual field, this can be useful when comparing similar modules that aren't already in BifacialSimu's database. These settings however will not be saved so make a note of them for future reference.

---

Results

Once a simulation has successfully completed, various graphs will be automatically generated with matplotlib which can then be exported. The data for all of these graphs can be found in the simulation results located in the Output folder. These graphs will vary depending upon the simulation mode chosen and as such below is a representation of what these could be.

This graph represents the relationship between the Diffuse Horizontal Irradiance (dhi) and the Direct Normal Irradiance (dni) over the course of one day. This is shown with the timescale on the x-axis and Watts per square metre on the y-axis.

---

The graph above portrays the Back and Front Side Irradiance with both the total incident irradiance (qinc) and the total absorbed irradiance (qabs) on the respective graphs. This can be a useful comparison tool however make sure to inspect the y-axis for the scale of the results as this could be misleading.

---

Here is a representation of the PV Array in a ViewFactors simulation. Effectively a graphical drawing of the angles of the modules produced by the integrated pv_factors tool. More informatino on this can be found later in Program Functions.

---

This particular graph shows the Bifacial Power Output in a time series with days on the x-axis and power output on the y-axis. The Bifacial Gain is then also protrayed as a percentage, giving a clear indication of how much extra power is being produced by the bifacial modules.

---

The absolute irradiance on the modules is shown in this graph over the entire simulation period, being displayed in terms of days.

---

This graph also displays the total irradiance of the system, this time broken down into the Global Horizontal Irradiance (ghi), Diffuse Horizontal Irradiance (dhi) and Direct Normal Irradiance (dni).

---

Troubleshooting

Here you can find some general troubleshooting measures which may help when running into problems with the simulation.

name 'rootPath' is not defined - If you get this error, the rootPath was not set beforehand. If you run the GUI.py again, it won't show the error.

Program unresponsive - If the simulation is itself unresponsive and no longer operating correctly it is possible to stop the program within the environment and reload.

temp_air Error - If the simulation produces this error it may be a sign that the "load" and "main" files from BifacialSimu haven't been copied into the installation of bifacial_radiance correctly. These files should overwrite the files in the bifacial_radiance Lib folder. It is also important that they are installed in the correct location, check within the anaconda installation of bifacial_radiance. An example path would be:

C:\Users\[USER]\anaconda3\Lib\site-packages\bifacial_radiance

Invalid Input - Most errors are a case of incorrectly defined parameters, these generally display error messages either as separate windows from the GUI or within the terminal in the Python Environment which BifacialSimu is running in.

Weather File Data Format - It is important to ensure that the imported weather data is included in the correct format and file type. This should be a .csv file and an example of how the data should be formatted can be seen in the included data file for the default simulation, the path of which can be found by clicking on "set default" within the GUI. There is also a script to convert weather files into TMY formate which can be found within the folder:

WeatherData/weatherFilesToTMY.py

Incorrect Timescale on Graphs - This is a result of not changing the time zone under the Simulation Control settings. It is also possible to manually amend the axis titles within the matlibplot graphs by using the edit button.

Cannot load backend 'Qt5Agg' - If this error appears, you have to change the IPython Console from 'tk' to 'Qt5', f.e. in spyder.

"ImportError: Cannot load backend 'Qt5Agg' which requires the 'qt' interactive framework, as 'tk' is currently running."

Cannot uninstall 'TBB' - If this error appears, you have to change the IPython Console from 'tk' to 'Qt5', f.e. in spyder. "TBB is a system package and anaconda does not allow users to uninstall it. The reinstallation of the package should thus be avoided."

pip install TBB --ignore-installed

rtrace cannot be found - if you are doing a Raytracing simulation and this error occurs, it means incorrectly installed bifacial_radiance. To handle this error make sure the radiance_bin is added to the system variables. You can test weather your installation is correct by opening the cmd console and type in ratrace as a command. When your installation is correct the outcome is as follows: "rtrace: fatal - missing octree argument".

---

Program Function

BifacialSimu uses various simulation methods in order to acheive it's results which can be split into three distinct groups; Irradiance Simulation, Albedo Calculation & Electrical Simulation. Through varying methods in each of these Simulations a comprehensive and accurate simulation can be constructed with varying degrees of accuracy according to the application.

In comparison to some other simulation tools, BifacialSimu is purely focused on the comparison of bifacial solar modules in comparison to their monofacial counterparts. As such, various aspects are not taken into consideration such as losses due to DC-AC inverters, cabling, battery management or other similar components commonly found in PV systems. This simplified aspect means that the simulation is easier to set up and provides enough information as to whether the implementation of a bifacial PV system over a standard one will be worth it.

Irradiance Simulation

The irradiance has essentially three main simulation modes that can be implemented, these are a combination of two different simulation methods and how they are applied to the solar modules. These methods are explained in simple terms below with the view of how to use them in a simulation environment and what is important to consider for which method. These use scripts from pv_factors and bifacial_radiance, the use of which is determined by the simulation mode. For instance simulations with View Factors will utilise pv_factors, whereas Ray Tracing simulations use bifacial_radiance. These can then, as previously described, be combined or used separately accordingly.

View Factors
View Factors is a commonly used method for calculating irradiance and is based upon basic geometric calculations and the relationships between the angles of which. This consists in simulation terms of 2D Geometries, in which the PV Arrays are plotted as rows and the ground plotted according to shaded and illuminated areas. A graphical depiction of which can be seen in the Results section with Figure 3. The illuminated and shaded sections naturally change according to the angle of the Sun and at points there may be overlapping which will also be taken into account by the software. The fixed parameters of hub height, module size, number of rows and width of rows remain constant during the simulation and define the previously mentioned geometry. This 2D model means that back surface irradiation can only be calculated vertically and not laterally.

Ray Tracing
BifacialSimu builds upon the work previously done by NREL with the tool bifacial_radiance which itself uses the rendering program Radiance to produce accurate Ray Tracing models for PV Simulation.
Ray Tracing is a relatively new technique in terms of PV simulation and is a method of rendering light sources either from the source (Forward Ray Tracing) or alternatively from the geometry back to the light source (Reverse Ray Tracing). The latter of which is used within BifacialSimu as this is much more efficient and much simpler to compute.
This technique has the advantage of being able to accurately calculate the irradiation in a 3D environment as well as involving the use of complex geometries and how the light rays then interact with them. This is naturally an lot more calculation-intensive and results in longer simulation times however this accuracy is much more important when using systems with tracking where the angles result in extrememly complex mathematical calculations.

Another aspect of Ray Tracing and where it differs from View Factors is the way in which the irradiation and sky are depicted. For this either a Cumulative Sky model is produced whereby an entire Sky model is produced on an annual basis. As such this simulation mode takes a lot longer than View Factors, with the building of the sky being quite an intense task. This should be taken into consideration when setting up your simulation and especially considering how long the simulation time period should be.

Reverse Ray Tracing lends itself well to applications where complex geometries are used i.e. the framing and mounting should be considered, and also if tracking is being implemented. By default BifacialSimu uses Ray Tracing for the rear side as this provides the most accurate results, an important factor when calculating bifacial gain.

Albedo Calculation

The albedo plays a large role when calculating bifacial PV systems, as this is responsible not only for calculating the reflected diffuse irradiation on the front side of the modules but also almost the entire irradiance received by the rear side of the modules. As such the model and values used will influence the accuracy of the simulation greatly.
Albedo is affected not only by the surface but also the weather and time of year in which the simulation should take place. As such, it is best to use measured data from the area in which the simulation should take place and during a similar time period when possible.

Spectral Albedo Model
This model calculates the spectral albedo of the surface selected and is dependent on not only the spectral reflectance of the material (measured and stored in a separate reflectivity file as a matrix of values) but also the atmospheric irradiance and how they interact with each other. This is an effective way of modelling the albedo for simulations, however it is quite computationally intensive and dependent on accurate weather data and comprehensive albedo values.

Simplified Variable Albedo Model
The simplified variable albedo model uses the basic albedo value of a surface and implements a calculation based upon the position of the sun and how this varies the albedo. This is a slightly more accurate solution to the constant albedo value however it is still heavily dependent on the constant value.

Hourly Albedo Measurement Data
It is also possible to use previously measured hourly albedo values for further simulations, this can be useful for validation of the bifacial gain of a new module within BifacialSimu or alternatively then a way to find out how other modules would function in this particular scenario.

Please note that the use of hourly measured albedo values is not possible with fixed tilt simulations at this point in time.

Constant Albedo Value
This is the simplest and therefore least accurate implementation of albedo in the simulation. It relies on a simple, average value of the ground's albedo and inputs this into the irradiance calculation for the front and rear sides. These can be selected with the drop-down menu according to what the surface is made of, or alternatively a custom numerical value can be entered. Please note that the name of the Surface will not be amended after entering a custom value.

Electrical Simulation

There are two main electrical simulation methods that are used in BifacialSimu, both of which are variations on the One Diode Model for calculating the power produced by PV modules. The use of either is dependent on whether the rear side irradiance values for the modules are present, these being determined by the manufacturer.

One Diode Model for bifacial PV
This standard model for photovoltaic simulation uses separate calculations for the front and rear side of the module with these then being added together to calculate the total energy yield of the system. This calculation requires the use of rear side irradiance values, as such if the selected module doesn't have these it will not be possible to use this mode.

Simplified One Diode Model
The Simplified One Diode Model should be used when there aren't any values for the rear side of the modules which can be the case depending upon the manufacturers specification. This model then calculates the energy yield of a bifacial module purely using the front side of the module and the bifaciality factor to calculate the rear side yield.

---

Contribution

The development of this program was assisted by the following people:

Sarah Glaubitz (Spectral Albedo)
Frederik Klag (Ray Tracing)
Sebastian Nows (Ray Tracing)
Felix Schemann (Variable Albedo, Ray Tracing)
Jan Schmitt (Graphical User Interface)
Fares Aoun (Installation Procedure) Jan Steinke (Threading)

Thank you to all who have contributed so far to this project, it wouldn't have been as successful without their input.

---

The Contribution guide is still a work in progress. If you have ideas how to improve it, please share them with us.

We are always happy if you would like to contribute to BifacialSimu. For example you could:

• Create GitHub issues and contribute to the discussions about how to solve them
• Read issues and pull requests that other poeple created and contribute on how to solve them
• Write unit tests for functions in BifacialSimu
• Improve the documentation
• If you would like to contribute a new function to BifacialSimu, it is manditory that you provide a unit test with it

If you wish to assist in further developing this program please contact Eva-Maria Grommes.

---

Citation and License of pvfactors and bifacial_radiance

BifacialSimu applies parts from pvfavtors. Copyright (c) 2017, SunPower Corp:

Anoma, M., Jacob, D., Bourne, B. C., Scholl, J. A., Riley, D. M., & Hansen, C. W. (2017). View Factor Model and Validation for Bifacial PV and Diffuse Shade on Single-Axis Trackers. In 44th IEEE Photovoltaic Specialist Conference.

BifacialSimu applies parts from bifacial_radiance. Copyright (c) 2017-2021, Alliance for Sustainable Energy, LLC:

Ayala Pelaez and Deline, (2020). bifacial_radiance: a python package for modeling bifacial solar photovoltaic systems. Journal of Open Source Software, 5(50), 1865, https://doi.org/10.21105/joss.01865

---

Citation of BifacialSimu

If you use BifacialSimu in a published work, please cite:

Grommes et al., (2022). BifacialSimu: Holistic Simulation of large-scale Bifacial Photovoltaic Systems. Journal of Open Source Software, 7(78), 4443, https://doi.org/10.21105/joss.04443

---

License

BifacialSimu open source code is copyrighted by Eva-Maria Grommes and licensed with BSD-3-Clause terms, found here.

bifacialsimu's Issues

[JOSS] pvlib and pvfactors not included in Anaconda by default

pvlib and pvfactors are not installed by default in Anaconda, at least in the version I downloaded from the official website.
Therefore I had to install these libs manually using the Anaconda Poweshell prompt:
pip install pvlib
pip install pvfactors

Idem for radiance:
pip install bifacial_radiance

Please update the install procedure accordingly

[openjournals/joss-reviews#4443 (comment)](openjournals/joss-reviews#4443 (comment))

[JOSS] GUI issues on linux

I ran into two issues with BifacialSimu_src/GUI.py on linux. The first is that the filepaths for logos, help text, configuration files, etc use hardcoded backslashes, but linux (and Mac OS) use forward slashes, and so I get errors like this:

TclError: couldn't open "/home/kevin/projects/BifacialSimu/BifacialSimu_src\Lib\Button_Images\Button-Info-icon.png": no such file or directory

and

FileNotFoundError: [Errno 2] No such file or directory: '/home/kevin/projects/BifacialSimu/BifacialSimu_src\\Lib\\input_albedo\\Albedo.json'

Editing GUI.py to use forward slashes gets it working for me, but of course that might break on Windows. To be cross platform you can use os.path.join or the pathlib standard library (new in python 3.4).

---

The second issue is that tkinter doesn't like the .ico files even after fixing the filepath. For example I get this:

_tkinter.TclError: bitmap "/home/kevin/projects/BifacialSimu/BifacialSimu_src/Lib/Button_Images/info_logo.ico" not defined

But os.path.exists confirms the file is there, so it must be some incompatibility that I don't understand. Anyway this prevents some things from working, for example the button_SP() window is empty until I comment out the pop_SP.iconbitmap(...) line. I did not try to find a better fix since I assume omitting the icons will not break any functionality.

Cross-reference: openjournals/joss-reviews#4443

Shapely issue on Mac

When running BifacialSimu on Mac I get the following error:

/Users/evagrommes/Documents/GitHub/BifacialSimu/BifacialSimu_src/Vendor/pvfactors/geometry/base.py:349: ShapelyDeprecationWarning: Setting custom attributes on geometry objects is deprecated, and will raise an AttributeError in Shapely 2.0
self.list_surfaces = list_surfaces
/Users/evagrommes/Documents/GitHub/BifacialSimu/BifacialSimu_src/Vendor/pvfactors/geometry/base.py:350: ShapelyDeprecationWarning: Setting custom attributes on geometry objects is deprecated, and will raise an AttributeError in Shapely 2.0
self.shaded = self._get_shading(shaded)
/Users/evagrommes/Documents/GitHub/BifacialSimu/BifacialSimu_src/Vendor/pvfactors/geometry/base.py:351: ShapelyDeprecationWarning: Setting custom attributes on geometry objects is deprecated, and will raise an AttributeError in Shapely 2.0
self.is_collinear = is_collinear(list_surfaces)
/Users/evagrommes/Documents/GitHub/BifacialSimu/BifacialSimu_src/Vendor/pvfactors/geometry/base.py:352: ShapelyDeprecationWarning: Setting custom attributes on geometry objects is deprecated, and will raise an AttributeError in Shapely 2.0
self.param_names = param_names
/Users/evagrommes/Documents/GitHub/BifacialSimu/BifacialSimu_src/Vendor/pvfactors/geometry/base.py:937: ShapelyDeprecationWarning: Setting custom attributes on geometry objects is deprecated, and will raise an AttributeError in Shapely 2.0
self.list_segments = tuple(list_segments)
/Users/evagrommes/Documents/GitHub/BifacialSimu/BifacialSimu_src/Vendor/pvfactors/geometry/base.py:938: ShapelyDeprecationWarning: Setting custom attributes on geometry objects is deprecated, and will raise an AttributeError in Shapely 2.0
self._all_surfaces = None

[JOSS] Using modified versions of pvfactors and bifacial_radiance seems unsustainable

The installation instructions in the README say to install pvfactors and bifacial_radiance, then edit those installations to use modified files in this repository. This approach seems problematic to me for a few reasons:

• It makes installation more manual and error-prone.
• It is brittle: the original projects will continue to evolve and diverge from the old code in this repository. Maybe someday they will diverge enough that your modified code becomes incompatible with the latest version of pvfactors or bifacial_radiance and the code breaks.
• By replacing their code with yours, it means any improvements they make to those packages might not apply to your code. For example maybe someday someone finds a bug in pvfactors's pvground.py and fixes it. BifacialSimu won't get the bugfix because it is overwriting that file with an old version from before the bugfix.
• It isn't aligned with the open-source ethos of sharing improvements with the wider community. Ideally, any improvements you make to a dependency would be contributed to the dependency itself so that everyone can benefit from it.

If you compare the bifacial_radiance main.py in this repository with the latest version in their repository (here), there are already many differences. I am worried that using modified files will not be sustainable in the long term, and maybe not even in the short term.

Would it be possible to either get rid of those changes, or to contribute those changes back to the original projects? Maybe there is some other solution to this problem?

Cross-reference: openjournals/joss-reviews#4443

FileNotFoundError

FileNotFoundError: [Errno 2] No such file or directory: 'C:\Users\lizhen\anaconda3\envs\bifacialsimu\Lib\Outputs\2022 11 30_17_24_results//radiation_qabs_results.csv'

This error occurs when running both modes 3 and 5.

[JOSS] No community guidelines

One of the JOSS review checklist items is about instructions for users and contributors:

Community guidelines: Are there clear guidelines for third parties wishing to 1) Contribute to the software 2) Report issues or problems with the software 3) Seek support

I think these points are not really addressed in the README or anywhere else. Here are some examples from other packages if you'd like some inspiration:

• pvlib: https://github.com/pvlib/pvlib-python#getting-support and https://pvlib-python.readthedocs.io/en/stable/contributing.html
• rdtools: https://rdtools.readthedocs.io/en/stable/developer_notes.html
• astropy: https://www.astropy.org/contribute.html

Cross-reference: openjournals/joss-reviews#4443

[JOSS] git repository contains unnecessary files

There are a handful of __pycache__ folders and .DS_Store files scattered around the repository. Since these are unnecessary and essentially just clutter, I suggest removing them and creating a .gitignore file to prevent them from coming back.

Cross-reference: openjournals/joss-reviews#4443

[JOSS] egg-info should be removed

The repository currently has a BifacialSimu.egg-info directory. I suggest deleting it (and potentially adding it to the .gitignore) since it is an artifact of the build and not actually part of the repository's source code.

Cross-reference: openjournals/joss-reviews#4443

[JOSS] package version in setup.py is out of date

I see that the latest version on PyPI is 1.0.2, but setup.py still lists 1.0.0:

BifacialSimu/setup.py

Line 29 in 158ca37

version='1.0.0',

Something to consider: rather than manually updating a hardcoded version string in setup.py, what many projects do is to determine the version automatically from the git repository information, in particular git tags. setuptools_scm or versioneer are two ways to do this. Using git tags as the basis for versioning is also nice because it makes it easy to go back to the version of the code for older releases. For example here is the code for pvlib version 0.7.1: https://github.com/pvlib/pvlib-python/tree/v0.7.1, which is easy to find because of the git tag.

Cross-reference: openjournals/joss-reviews#4443

[JOSS] paper.md feedback

Here are some notes I took while reading the paper.md manuscript file. Hopefully this feedback is helpful!

Statement of need

PV is the third largest power generation technology and will play a significant role in future global electricity generation (International Renewable Energy Agengy, 2019).

I read this as claiming that solar is currently the third largest power generation technology, which I don't think is what the sentence was intended to convey. Maybe something like "Current forecasts expect PV to be the third largest power generation technology by 2050..." would be better?

---

There is a need for an open source software tool to simulate bifacial PV, which combines existing radiation and electrical models and provides a graphical user interface (GUI).

I think this deserves more explanation. Why is the combination of viewfactor and raytracing desirable? Why not just use one or the other? I would also argue that albedo should be discussed here. Why are advanced albedo models necessary? I'm not saying they aren't necessary, but that it would strengthen the paper to discuss it.

---

This comment is a little more vague, but I as the reader am not sure what the main "selling point" of BifacialSimu is, or why I might want to use it instead of some other tool. Here are the questions I'm asking myself as prospective user:

• Is it for more accurate system performance modeling? No, since it doesn't include all the auxiliary things needed to model system performance (soiling, inverters, etc).
• Is it to make bifacial irradiance modeling easier for non-programmers? No, since other bifacial tools (bifacial_radiance, SAM) also have GUIs.
• Is it because it's open-source? No, because the underlying irradiance models are also open-source.

Tied in with this is the question "why create a new tool instead of improving an existing tool?". For example someone could say that it would have been better to add fancy albedo models to bifacial_radiance, and improve its existing gui, instead of making a new wrapper around it. If you can, it would be good to clarify what exactly the need is and why these other existing tools don't address it.

State of the field

BifacialSimu offers the advantage of an integrated energy yield calculation, whereas bifacial_radiance need a third software, the open-source software PVMismatch [@Mikofski.2018].

I think this is no longer true; my understanding is that bifacial_radiance now includes its own PV I-V calculations using pvlib. See for example their Tutorial 21.

---

The commonly known open-source software using the viewfactor model, pvfactors [@Anoma.2017] and bifacialVF [@Marion.2017], have both no energy yield calculation and no GUI, which limits the target audience and the application possibilities. The commonly used software PVsyst offers an energy yield calculation and a GUI, but the used physical models are only documented to a limited extent and the software must be paid [@PVsystSA].

NREL's System Advisor Model has a viewfactor-based rear-side irradiance model, does energy yield calculation, has a GUI, is well-documented, and is open source, so if those are the relevant criteria then it's probably worth mentioning SAM here.

---

I also think BifacialSimu's advanced albedo modeling should be highlighted in this State of the field section, since that's a clear technical advantage compared to other packages.

---

Cross-reference: openjournals/joss-reviews#4443

[JOSS] ImportError: cannot import name '_missingKeyWarning' from 'bifacial_radiance.main'

When starting GUI.py in Spyder, I have:
ImportError: cannot import name '_missingKeyWarning' from 'bifacial_radiance.main' (C:\Users\Sidi\anaconda3\lib\site-packages\bifacial_radiance\main.py)
Removing it from Lib\site-packages\bifacial_radiance\module.py solves this issue but why? Is _missingKeyWarning really used?

openjournals/joss-reviews#4443 (comment)

[JOSS] ViewFactors error: "dateutil.parser._parser.ParserError: Unknown string format: 11-01 00:00%"

To reproduce:

1. Start GUI
2. Hit "set default!"
3. In "Simulation Control", select "front and back simulation with Viewfactors"
4. Hit "start simulation"

Full traceback:

Click to expand!

Exception in thread Thread-11:
Traceback (most recent call last):
  File "/home/kevin/miniconda3/envs/bifacialsimu-review/lib/python3.8/site-packages/pandas/core/arrays/datetimes.py", line 2187, in objects_to_datetime64ns
    values, tz_parsed = conversion.datetime_to_datetime64(data.ravel("K"))
  File "pandas/_libs/tslibs/conversion.pyx", line 359, in pandas._libs.tslibs.conversion.datetime_to_datetime64
TypeError: Unrecognized value type: <class 'str'>

During handling of the above exception, another exception occurred:

Traceback (most recent call last):
  File "/home/kevin/miniconda3/envs/bifacialsimu-review/lib/python3.8/threading.py", line 932, in _bootstrap_inner
    self.run()
  File "/home/kevin/miniconda3/envs/bifacialsimu-review/lib/python3.8/threading.py", line 870, in run
    self._target(*self._args, **self._kwargs)
  File "/home/kevin/projects/BifacialSimu/BifacialSimu_src/GUI.py", line 562, in StartSimulation
    Controller.startSimulation(SimulationDict, ModuleDict, resultsPath)
  File "/home/kevin/projects/BifacialSimu/BifacialSimu_src/BifacialSimu/Controller/BifacialSimu_simulationController.py", line 91, in startSimulation
    df_reportVF, df = BifacialSimu_radiationHandler.ViewFactors.simulateViewFactors(simulationDict, demo, metdata,  df, resultsPath, onlyFrontscan = False)
  File "/home/kevin/projects/BifacialSimu/BifacialSimu_src/BifacialSimu/Handler/BifacialSimu_radiationHandler.py", line 580, in simulateViewFactors
    df['timestamp'] = pd.to_datetime(df['timestamp'])  
  File "/home/kevin/miniconda3/envs/bifacialsimu-review/lib/python3.8/site-packages/pandas/core/tools/datetimes.py", line 887, in to_datetime
    values = convert_listlike(arg._values, format)
  File "/home/kevin/miniconda3/envs/bifacialsimu-review/lib/python3.8/site-packages/pandas/core/tools/datetimes.py", line 401, in _convert_listlike_datetimes
    result, tz_parsed = objects_to_datetime64ns(
  File "/home/kevin/miniconda3/envs/bifacialsimu-review/lib/python3.8/site-packages/pandas/core/arrays/datetimes.py", line 2193, in objects_to_datetime64ns
    raise err
  File "/home/kevin/miniconda3/envs/bifacialsimu-review/lib/python3.8/site-packages/pandas/core/arrays/datetimes.py", line 2175, in objects_to_datetime64ns
    result, tz_parsed = tslib.array_to_datetime(
  File "pandas/_libs/tslib.pyx", line 379, in pandas._libs.tslib.array_to_datetime
  File "pandas/_libs/tslib.pyx", line 611, in pandas._libs.tslib.array_to_datetime
  File "pandas/_libs/tslib.pyx", line 749, in pandas._libs.tslib._array_to_datetime_object
  File "pandas/_libs/tslib.pyx", line 740, in pandas._libs.tslib._array_to_datetime_object
  File "pandas/_libs/tslibs/parsing.pyx", line 257, in pandas._libs.tslibs.parsing.parse_datetime_string
  File "/home/kevin/miniconda3/envs/bifacialsimu-review/lib/python3.8/site-packages/dateutil/parser/_parser.py", line 1368, in parse
    return DEFAULTPARSER.parse(timestr, **kwargs)
  File "/home/kevin/miniconda3/envs/bifacialsimu-review/lib/python3.8/site-packages/dateutil/parser/_parser.py", line 643, in parse
    raise ParserError("Unknown string format: %s", timestr)
dateutil.parser._parser.ParserError: Unknown string format: 11-01 00:00%

I think this line (and a similar one several lines farther down) has an extra % character:

BifacialSimu/BifacialSimu_src/BifacialSimu/Handler/BifacialSimu_radiationHandler.py

Line 562 in 158ca37

df['timestamp'] = df['corrected_timestamp'].dt.strftime('%m-%d %H:%M%')

But even removing that extra %, the datetime is still not parsed correctly:

Click to expand!

Exception in thread Thread-11:
Traceback (most recent call last):
  File "/home/kevin/miniconda3/envs/bifacialsimu-review/lib/python3.8/site-packages/pandas/core/arrays/datetimes.py", line 2187, in objects_to_datetime64ns
    values, tz_parsed = conversion.datetime_to_datetime64(data.ravel("K"))
  File "pandas/_libs/tslibs/conversion.pyx", line 359, in pandas._libs.tslibs.conversion.datetime_to_datetime64
TypeError: Unrecognized value type: <class 'str'>

During handling of the above exception, another exception occurred:

Traceback (most recent call last):
  File "/home/kevin/miniconda3/envs/bifacialsimu-review/lib/python3.8/threading.py", line 932, in _bootstrap_inner
    self.run()
  File "/home/kevin/miniconda3/envs/bifacialsimu-review/lib/python3.8/threading.py", line 870, in run
    self._target(*self._args, **self._kwargs)
  File "/home/kevin/projects/BifacialSimu/BifacialSimu_src/GUI.py", line 562, in StartSimulation
    Controller.startSimulation(SimulationDict, ModuleDict, resultsPath)
  File "/home/kevin/projects/BifacialSimu/BifacialSimu_src/BifacialSimu/Controller/BifacialSimu_simulationController.py", line 91, in startSimulation
    df_reportVF, df = BifacialSimu_radiationHandler.ViewFactors.simulateViewFactors(simulationDict, demo, metdata,  df, resultsPath, onlyFrontscan = False)
  File "/home/kevin/projects/BifacialSimu/BifacialSimu_src/BifacialSimu/Handler/BifacialSimu_radiationHandler.py", line 580, in simulateViewFactors
    df['timestamp'] = pd.to_datetime(df['timestamp'])  
  File "/home/kevin/miniconda3/envs/bifacialsimu-review/lib/python3.8/site-packages/pandas/core/tools/datetimes.py", line 887, in to_datetime
    values = convert_listlike(arg._values, format)
  File "/home/kevin/miniconda3/envs/bifacialsimu-review/lib/python3.8/site-packages/pandas/core/tools/datetimes.py", line 401, in _convert_listlike_datetimes
    result, tz_parsed = objects_to_datetime64ns(
  File "/home/kevin/miniconda3/envs/bifacialsimu-review/lib/python3.8/site-packages/pandas/core/arrays/datetimes.py", line 2193, in objects_to_datetime64ns
    raise err
  File "/home/kevin/miniconda3/envs/bifacialsimu-review/lib/python3.8/site-packages/pandas/core/arrays/datetimes.py", line 2175, in objects_to_datetime64ns
    result, tz_parsed = tslib.array_to_datetime(
  File "pandas/_libs/tslib.pyx", line 379, in pandas._libs.tslib.array_to_datetime
  File "pandas/_libs/tslib.pyx", line 606, in pandas._libs.tslib.array_to_datetime
  File "pandas/_libs/tslib.pyx", line 602, in pandas._libs.tslib.array_to_datetime
  File "pandas/_libs/tslib.pyx", line 557, in pandas._libs.tslib.array_to_datetime
  File "pandas/_libs/tslibs/conversion.pyx", line 516, in pandas._libs.tslibs.conversion.convert_datetime_to_tsobject
  File "pandas/_libs/tslibs/np_datetime.pyx", line 120, in pandas._libs.tslibs.np_datetime.check_dts_bounds
pandas._libs.tslibs.np_datetime.OutOfBoundsDatetime: Out of bounds nanosecond timestamp: 1-11-01 00:00:00

It seems to me like the year should be included with %Y, otherwise how can pd.to_datetime know what year it is?

Cross-reference: openjournals/joss-reviews#4443

[JOSS] AUTHORS file

Please add an AUTHORS file to the repo, with the list you gave in Readme.md, with their contribution.
They can also be added in the acknowledgements section.

openjournals/joss-reviews#4443 (comment)

[JOSS] Does the package have standard tests?

One of the JOSS review checklist items is about software testing:

Automated tests: Are there automated tests or manual steps described so that the functionality of the software can be verified?

Having some kind of standard suite of tests has a lot of benefits for scientific software packages, including but not limited to:

• preventing unintentional changes to simulation results by checking that the software output doesn't change over time
• detecting incompatibilities with dependencies (e.g. perhaps tomorrow pvlib releases a new version that breaks your code)
• making it easier for new users to ensure they have installed the software correctly on their computer

What many other packages do, including pvlib, pvfactors, and bifacial_radiance, is have a suite of tests covering most or nearly all of the primary package code. We also run these tests automatically for each commit to give us confidence that we are not accidentally breaking something. Using pvlib as an example:

• test definitions: https://github.com/pvlib/pvlib-python/tree/master/pvlib/tests
• example automated test run: https://github.com/pvlib/pvlib-python/actions/runs/2503197724

In my opinion, testing is essentially a requirement for robust and reliable scientific software. For pvlib we take it so seriously that nearly 100% of the package code is covered by tests (see https://app.codecov.io/gh/pvlib/pvlib-python) and we don't accept new code unless it has tests (see pvlib's contributing docs).

Does BifacialSimu have anything along these lines? I didn't see any tests, but maybe I missed it. If not, do you have any plans to implement tests?

Cross-reference: openjournals/joss-reviews#4443

[JOSS] Simulations run in the GUI thread ==> freezing GUI

An issue that I mentioned in the Preview stage: the simulations run in the main GUI thread, which make it unresponsive during long time (even if the spyder console output is seen). Simulations should be run in a working thread using the 'threading' library, and a communication between the two threads can be done, e.g. to show the progress of calculations (like a progessbar in tkinter or a simple label). Using threading will make the GUI part remaining responsive and the simulations can be monitored and even stopped when needed. This makes the user experience much more easier.

openjournals/joss-reviews#4443 (comment)

[JOSS] document all dependencies

One of the JOSS review checklist items is about dependencies:

Is there a clearly-stated list of dependencies? Ideally these should be handled with an automated package management solution.

I think right now the answer to that question is "no". Looking through the package files, I see that, in addition to the dependencies explicitly mentioned in the README, BifacialSimu requires these external packages:

• pandas
• IPython
• matplotlib
• numpy
• tqdm
• webbrowser
• dateutil
• seaborn (optional)

I think at least some of these are not provided by the default Anaconda distribution, so they should be at least mentioned in the README installation instructions.

However, I agree with the checklist item that it would be better to use an automated package manager to track dependencies. In the python world you can use setup.py or setup.cfg for this, which would make your package compatible with tools like pip. You could also list it on pypi.org if you wanted.

Cross-reference: openjournals/joss-reviews#4443