Modifications to address sugestions by JOSS reviewers

docs/sphinx/source/index.rst

@@ -6,6 +6,8 @@ Welcome to bifacial_radiance's documentation!
 
 bifacial_radiance is a NREL supported tool that provides a set of functions and classes for simulating the performance of bifacial PV systems. More information on bifacial_radiance can be found at the Wiki page.
 
+The intended audience ranges from PV performance researchers, Engineering Procurement Construction (EPC) companies, installers, investors, consumers and analysts of the PV industry interested in predicting and evaluating bifacial photovoltaic systems. 
+
 The source code for bifacial_radiance is hosted on `github
 <https://github.com/NREL/bifacial_radiance>`_.
 

docs/sphinx/source/installation.rst

@@ -3,6 +3,12 @@
 Installation
 ============
 
+Compatibility
+~~~~~~~~~~~~~
+
+bifacial_radiance is coded and tested in Windows, but can also work on Linux and Mac OSX, particularly after improvements in the latest release :ref:`whatsnew_0302` which solved some of the binary issues for gencumsky. However, the functionalities in Linux are still being improved, for example the GUI requires special QT installation described in (:issue:`130`:).
+
+
 Video Instructions
 ~~~~~~~~~~~~~~~~~~
 
@@ -19,9 +25,21 @@ If you are on a PC you should also copy the `Jaloxa radwinexe-5.0.a.8-win64.zip
 
 **Note: bifacial_radiance is not endorsed by or officially connected with the Radiance software package or its development team.**
 
+
+Prerequisite: PYTHON:
+~~~~~~~~~~~~~~~~~~~~~~
+You will need python installed to run bifacial_radiance. We suggest using the latest release of `Anaconda with Python 3.7 <https://www.anaconda.com/distribution/>`_ (Python 2.7 is still supported but in the process of being deprecated). Anaconda will install ``Spyder`` to work with the python scripts, and also it will install ``Jupyter``, which is the tool we use for our `tutorial trainings <https://github.com/NREL/bifacial_radiance/tree/master/docs/tutorials>`_
+
+
 STEP 1
 ~~~~~~
-Install and Import bifacial_radiance
+
+The simplest option is to open a command prompt and run::
+
+        pip install bifacial_radiance
+
+
+An alternative which is shown in the Video Instructions, if you want to install bifacial_radiance in a local folder of your choosing and/or be able to modify the internal code to suit your needs, you can do the following:
 
 * clone the bifacial_radiance repo to your local directory or download and unzip the .zip file
 * navigate to the \bifacial_radiance directory using anaconda command line
@@ -38,23 +56,30 @@ For best compatibility, deploy in an `Anaconda 2.7` environment, or run::
 
 STEP 2
 ~~~~~~
-Move gencumulativesky.exe
+Windows:
 
 * Copy gencumulativesky.exe from the repo's ``/bifacial_radiance/data/`` directory and copy into your Radiance install directory.
   This is typically found in ``/program files/radiance/bin/``.  
 
+Linux/Mac OSX:
+
+* Copy the gencumulativesky executable from the repo's ``/bifacial_radiance/data/`` directory and copy into your Radiance install directory.
+  This is typically found in ``/usr/local/radiance/bin/``. 
+* For Linux/Mac OSX, you will need to install QT for the GUI to work properly. Installation and details described in (:issue:`130`:).
+
+
 .. note::
         GenCumulativeSky is detailed in the publication "Robinson, D., Stone, A., Irradiation modeling made simple: the cumulative sky approach and its applications, Proc. PLEA 2004, Eindhoven 2004."   
 
-The source is `available from the authors here <https://documents.epfl.ch/groups/u/ur/urbansimulation/www/GenCumSky/GenCumSky.zip>`_
- 
+        The gencumsky source is included in the repo's ``/bifacial_radiance/data/gencumsky`` directory along with a make_gencumskyexe.py script which builds the multi-platform gencumulativesky executables. More details on the use of this script in readme.txt or on thread (:issue:`1821`).
+
 
 STEP 3
 ~~~~~~
-Create a local Radiance directory for storing the scene files created
+Create a local directory for storing your simulations and runs results. 
+If run in the default directory, simulation results will be saved in the TEMP folder, but will also be overwritten with every run. We recommend to keep the simulation files (scene geometry, skies, results, etc) separate from the bifacial_radiance directory by creating a local directory somewhere to be used for storing those files.
+
 
-Keep scene geometry files separate from the bifacial_radiance directory.  Create a local directory somewhere to be used for storing scene files.
-
 STEP 4
 ~~~~~~
 Reboot the computer

paper/paper.md

@@ -31,11 +31,11 @@ bifacial_radiance is hosted on Github and PyPi, and it was developed by contribu
     <figcaption> Visualization of a bifacial photovoltaic array generated through bifacial_radiance. Courtesy of J. Alderman. </figcaption>
 </figure>
 
-The bifacial_radiance API and graphical user interface (GUI) were designed to serve the various needs of the many subfields of bifacial solar panel power research and engineering. It is implemented in three layers: core RADIANCE-interface functions; ``Bifacial-Radiance``, ``Meteorological``, ``Scene``, and ``Analysis`` classes; and the ``GUI`` and ``model-chain`` classes. The core API consists of a collection of functions that implement commands directly to the RADIANCE software. These commands are typical implementations of algorithms and models described in peer-reviewed publications. The functions provide maximum user flexibility; however, some of the function arguments require an unwieldy number of parameters. The next API level contains the ``Bifacial-Radiance``, ``Meteorological``, ``Scene``, and ``Analysis`` classes. These abstractions provide simple methods that wrap the core function API layer and communicate with the RADIANCE software, which provides ray-trace processing capabilities. The method API simplification is achieved by separating the data that represent the object (object attributes) from the data that the object methods operate on (method arguments). For example, a ``Bifacial-Radiance`` object is represented by a ``module`` object, meteorological data, and ``scene`` objects. The ``gendaylit`` method operates on the meteorological data to calculate solar position and generate corresponding sky files, linking them to the ``Bifacial-Radiance`` object. Then the ``makeOct`` method combines the sky files, ``module`` and ``scene`` objects when calling the function layer, returning the results from an ``Analysis`` object to the user. The final level of API is the ``ModelChain`` class, designed to simplify and standardize the process of stitching together the many modeling steps necessary to convert a time series of weather data to AC solar power generation, given a PV system and a location. The ``ModelChain`` also powers the ``GUI``, which provides a cohesive visualization of all the input parameters and options for most common modeling needs.
+The bifacial_radiance API and graphical user interface (GUI) were designed to serve the various needs of the many subfields of bifacial solar panel power research and engineering. The intended audience ranges from PV performance researchers, Engineering Procurement Construction (EPC) companies, installers, investors, consumers and analysts of the PV industry interested in predicting and evaluating bifacial photovoltaic systems. It is implemented in three layers: core RADIANCE-interface functions; ``Bifacial-Radiance``, ``Meteorological``, ``Scene``, and ``Analysis`` classes; and the ``GUI`` and ``model-chain`` classes. The core API consists of a collection of functions that implement commands directly to the RADIANCE software. These commands are typical implementations of algorithms and models described in peer-reviewed publications. The functions provide maximum user flexibility; however, some of the function arguments require an unwieldy number of parameters. The next API level contains the ``Bifacial-Radiance``, ``Meteorological``, ``Scene``, and ``Analysis`` classes. These abstractions provide simple methods that wrap the core function API layer and communicate with the RADIANCE software, which provides ray-trace processing capabilities. The method API simplification is achieved by separating the data that represent the object (object attributes) from the data that the object methods operate on (method arguments). For example, a ``Bifacial-Radiance`` object is represented by a ``module`` object, meteorological data, and ``scene`` objects. The ``gendaylit`` method operates on the meteorological data to calculate solar position and generate corresponding sky files, linking them to the ``Bifacial-Radiance`` object. Then the ``makeOct`` method combines the sky files, ``module`` and ``scene`` objects when calling the function layer, returning the results from an ``Analysis`` object to the user. The final level of API is the ``ModelChain`` class, designed to simplify and standardize the process of stitching together the many modeling steps necessary to convert a time series of weather data to AC solar power generation, given a PV system and a location. The ``ModelChain`` also powers the ``GUI``, which provides a cohesive visualization of all the input parameters and options for most common modeling needs.
 
 bifacial_radiance was first coded in Python and released as a stable version in Github in 2017 [@MacAlpine2017], and it was submitted as a U.S. Department of Energy Code project on December of the same year [@Deline2017]. Efforts to make the project more pythonic were undertaken in 2018 [@Ayala2018]. Additional features continue to be added as described in [@Ayala2019; @Stein2019] and the documentation’s “What’s New” section.
 
-bifacial_radiance has been used in numerous studies, for example, for modeling and validation of rear irradiance for fixed-tilt systems [@Ayala2019b], estimation of energy gain and performance ratio for single-axis-tracked bifacial systems [@Berrian2019; @Ayala2019c], as well as the study of edge effects [@Ayala2019c] and smart tracking algorithms [@Ayala2018b]; benchmarking with other rear-irradiance calculation softwares [@Ayala2018b; @DiOrio2018; @Capelle2019], estimation of shading factor from racking structures [@Ayala2019d], and parameterization of electrical mismatch power losses due to irradiance nonuniformity in bifacial systems [@Deline2019; @Deline2019b; @Ayala2019e]. Sensitivity studies of installation and simulation parameters [@Asgharzadeh2018] and optimization for bifacial fields with the aid of high-performance computing [@Stein2019; @Stein2019b] have also been performed with bifacial_radiance.
+bifacial_radiance has been used in numerous studies, for example, for modeling and validation of rear irradiance for fixed-tilt systems [@Ayala2019b], estimation of energy gain and performance ratio for single-axis-tracked bifacial systems [@Berrian2019; @Ayala2019c], as well as the study of edge effects [@Ayala2019c] and smart tracking algorithms [@Ayala2018b]; estimation of shading factor from racking structures [@Ayala2019d], and parameterization of electrical mismatch power losses due to irradiance nonuniformity in bifacial systems [@Deline2019; @Deline2019b; @Ayala2019e]. Sensitivity studies of installation and simulation parameters [@Asgharzadeh2018] and optimization for bifacial fields with the aid of high-performance computing [@Stein2019; @Stein2019b] have also been performed with bifacial_radiance. Furthermore, benchmarking with other rear-irradiance calculation software has been performed on several occasions [@Ayala2018b; @DiOrio2018; @Capelle2019]. Rear-irradiance calculation software fall into two categories: view-factor and ray-tracing models. View factor models assume isotropic scattering of reflected rays, allowing for calculation of irradiance by integration. Due-diligence software such as PVSyst or SAM use the view-factor model. Ray-tracing models simulate multipath reflection and absorption of individual rays entering a scene. Raytracing software such as bifacial_radiance, which is the only available open-source toolkit, offers the possibility of reproducing complex scenes, including shading or finite-system edge effects. Model agreement for view factor and bifacial_radiance software is better than 2% (absolute) when compared with measured results. [@Ayala2018b]. 
 
 Plans for bifacial_radiance development include the implementation of new and existing models, addition of functionality to assist with input/output, and improvements to API consistency.
 
@@ -49,4 +49,4 @@ S.A.P. and C.D. acknowledge support from the U.S. Department of Energy’s Solar
 
 The National Renewable Energy Laboratory is a national laboratory of the U.S. Department of Energy, Office of Energy Efficiency and Renewable Energy, operated by the Alliance for Sustainable Energy, LLC.
 
-# References
+# References

setup.py

@@ -110,6 +110,7 @@
     # $ pip install -e .[dev,test]
 
     extras_require={
+        'examples': ['jupyter'],
         #'dev': ['check-manifest'],
         #'test': ['coverage'],
     },