NREL · cdeline · Dec 10, 2019 · Nov 19, 2019 · Nov 19, 2019 · Nov 19, 2019
diff --git a/bifacial_radiance/main.py b/bifacial_radiance/main.py
@@ -3665,131 +3665,18 @@ def runJob(daydate):
  modWanted=modWanted,
  rowWanted=rowWanted,
  sensorsy=sensorsy)
-
-def hpcExample(): 
- """ 
- Example of HPC Job call
-
- This allocates the day_dates generated to the different codes in as many nodes are available. 
- Works inside and outside of slurm for testing (but set FullYear to False so it only does two days)
- Full year takes 1 min in 11 Nodes.
-
- Variables stored in input_bf.py. First configure this on top:
-
- .. code-block :: python
-
- if __name__ == "__main__": #in case this is run as a script not a module.
- from readepw import readepw 
- from load import loadTrackerDict
- from input_bf import *
-
- else: # module imported or loaded normally
- from bifacial_radiance.readepw import readepw # epw file reader from pvlib development forums #module load format
- from bifacial_radiance.load import loadTrackerDict
- from bifacial_radiance.input_bf import *
-
- Procedure for a Full Year Run (~1 min in 11 nodes of 36 cores each > 365 days):
-
- .. code-block :: python
-
- Connect to Eagle
- - $ cd bifacial_radiance/bifacial_radiance
- - $ srun -A pvsoiling -t 5 -N 11 --pty bash 
- - $ module load conda
- - $ . activate py3
- - $ srun bifacial_radiance2.py
-
- Procedure for testing before joining SLURM:
 
- .. code-block :: python
-
- change fullYear to False.
- - $ cd bifacial_radiance/bifacial_radiance
- - $ module load conda
- - $ . activate py3
- - $ nano bifacial_radiance.py 
- - $ python bifacial_radiance2.py 
-
- .. warning::
- Do not load conda twice nor activate .py3 twice.
- (following above) Either activate conda or .py3 in the login node
- or on the slurm
-
- """
-
- import multiprocessing as mp
-
- daylist = []
-
- fullYear = True # running faster testing on HPC ~ only 2 days.
-
- if fullYear:
- start = datetime.datetime.strptime("01-01-2014", "%d-%m-%Y")
- end = datetime.datetime.strptime("31-12-2014", "%d-%m-%Y") # 2014 not a leap year.
- daylist.append('12_31') # loop doesn't add last day. Adding it at the beginning because why not.
- daylimit = 365
- else:
- start = datetime.datetime.strptime("14-02-2014", "%d-%m-%Y")
- end = datetime.datetime.strptime("26-02-2014", "%d-%m-%Y") # 2014 not a leap year.
- daylimit = 1
- date_generated = [start + datetime.timedelta(days=x) for x in range(0, (end-start).days)]
- for date in date_generated:
- daylist.append(date.strftime("%m_%d"))
-
- # print("This is daydate %s" % (daydate))
- demo = RadianceObj(simulationname,path=testfolder)
- demo.setGround(albedo)
-# HPC IMPORTANT NOTE:
-# Multiple Nodes get confused when trying to write the JSON at the same time,
-# so make sure moduletype is created before running slurm job for it to work.
-# 2 DO: Fix at some point of course.
-# moduleDict=demo.makeModule(name=moduletype,x=x,y=y,bifi=bifi,
-# torquetube=torqueTube, diameter = diameter, tubetype = tubetype,
-# material = torqueTubeMaterial, zgap = zgap, numpanels = numpanels, ygap = ygap,
-# rewriteModulefile = True, xgap=xgap,
-# axisofrotationTorqueTube=axisofrotationTorqueTube, cellLevelModule=cellLevelModule,
-# numcellsx=numcellsx, numcellsy = numcellsy)
- sceneDict = {'module_type':moduletype, 'pitch': pitch, 'hub_height':hub_height, 'nMods':nMods, 'nRows':nRows}
-
- cores = mp.cpu_count()
- pool = mp.Pool(processes=cores)
- res = None
-
- try:
- nodeID = int(os.environ['SLURM_NODEID'])
- except KeyError:
- nodeID = 0 # in case testing for hpc not on slurm yet.
-
- hpccores = 36 # this is valid for Eagle. Find out how many cores are in each node of your HPC to make this work.
-
- day_index = (hpccores * (nodeID))
-
- for job in range(cores):
- if day_index+job>=len(daylist): # this makes sure no days above 356 are attempted:
- break
- pool.apply_async(runJob, (daylist[day_index+job],))
-
- pool.close()
- pool.join()
- pool.terminate()
-
-def quickExample():
+def quickExample(testfolder=None):
  """
  Example of how to run a Radiance routine for a simple rooftop bifacial system
 
  """
- def _interactive_directory(title=None):
- # Tkinter directory picker. Now Py3.6 compliant!
- import tkinter
- from tkinter import filedialog
- root = tkinter.Tk()
- root.withdraw() #Start interactive file input
- root.attributes("-topmost", True) #Bring to front
- return filedialog.askdirectory(parent=root, title=title)
 
  import bifacial_radiance
- testfolder = _interactive_directory(title = 'Select or create an empty directory for the Radiance tree')
- # testfolder = r'C:\Users\sayala\Documents\RadianceScenes\Demo3'
+
+ if testfolder == None:
+ testfolder = bifacial_radiance.main._interactive_directory(title = 'Select or create an empty directory for the Radiance tree')
+
  demo = bifacial_radiance.RadianceObj('simple_panel',path = testfolder) # Create a RadianceObj 'object'
 
  # A=load_inputvariablesfile()
@@ -3830,4 +3717,4 @@ def _interactive_directory(title=None):
  print('Annual bifacial ratio average: %0.3f' %(
  sum(analysis.Wm2Back) / sum(analysis.Wm2Front) ) )
 
-
+ return analysis
diff --git a/docs/images_wiki/Webinar/mainsteps.PNG b/docs/images_wiki/Webinar/mainsteps.PNG
diff --git a/docs/images_wiki/Webinar/wrapper.PNG b/docs/images_wiki/Webinar/wrapper.PNG
diff --git a/docs/sphinx/source/conf.py b/docs/sphinx/source/conf.py
@@ -192,10 +192,9 @@ def setup(app):
 #latex_domain_indices = True
 """
 # extlinks alias
-extlinks = {'issue': ('https:/NREL/bifacial_radiance/issues/%s',
- 'GH'),
- 'wiki': ('https:/NREL/bifacial_radiance/wiki/%s',
- 'wiki '),
+extlinks = {'issue': ('https:/NREL/bifacial_radiance/issues/%s', 'GH'),
+ 'pull': ('https:/NREL/bifacial_radiance/pull/%s', 'GH'),
+ 'wiki': ('https:/NREL/bifacial_radiance/wiki/%s', 'wiki '),
  'doi': ('http://dx.doi.org/%s', 'DOI: '),
  'ghuser': ('https:/%s', '@')}
 """

diff --git a/docs/sphinx/source/contributing.rst b/docs/sphinx/source/contributing.rst
@@ -199,9 +199,9 @@ style.
 
 Remove any ``logging`` calls and ``print`` statements that you added
 during development. ``warning`` is ok.
-
+
 We typically use GitHub's
-"`squash and merge` <https://help.github.com/articles/about-pull-request-merges/#squash-and-merge-your-pull-request-commits>_"
+"`squash and merge <https://help.github.com/articles/about-pull-request-merges/#squash-and-merge-your-pull-request-commits>`_"
 feature to merge your pull request into bifacial_radiance. GitHub will condense the
 commit history of your branch into a single commit when merging into
 bifacial_radiance/master (the commit history on your branch remains
@@ -231,17 +231,30 @@ specific types may be used:
 
 Parameters that specify a specific type require that specific input type.
 
-A relatively easy way to test your documentation is to build it on
-`readthedocs.org <https://readthedocs.org>` by following their
-`Import Your Docs <http://docs.readthedocs.io/en/stable/getting_started.html#import-your-docs>`_
-instructions and enabling your branch on the readthedocs
-`versions admin page <http://docs.readthedocs.io/en/stable/features.html#versions>`_.
+Read the Docs will automatically build the documentation for each pull
+request. Please confirm the documentation renders correctly by following
+the ``continuous-documentation/read-the-docs`` link within the checks
+status box at the bottom of the pull request.
+
+To build the docs locally, install the ``doc`` dependencies specified in the
+`setup.py <https:/NREL/bifacial_radiance/blob/master/setup.py>`_
+file. See :ref:`installation` instructions for more information.
 
 .. _testing:
 
 Testing
 ~~~~~~~
 
+Developers **must** include comprehensive tests for any additions or
+modifications to bifacial_radiance. New unit test code should be placed in the corresponding test module in the bifacial_radiance/test directory.
+
+A pull request will automatically run the tests for you on Linux platform and python versions 2.7 and 3.6. However, it is typically more efficient to run and debug the tests in your own local
+environment.
+
+To run the tests locally, install the ``test`` dependencies specified in the
+`setup.py <https:/NREL/bifacial_radiance/blob/master/setup.py>`_
+file. See :ref:`installation` instructions for more information.i
+
 bifacial_radiance's unit tests can easily be run by executing ``pytest`` on the
 bifacial_radiance directory:
 
@@ -257,7 +270,7 @@ or, for a single test:
 
 We suggest using pytest's ``--pdb`` flag to debug test failures rather
 than using ``print`` or ``logging`` calls. For example:
-
+
 ``pytest bifacial_radiance/test/modelchain.py --pdb``
 
 will drop you into the
@@ -266,12 +279,6 @@ location of a test failure. As described in :ref:`code-style`, bifacial_radiance
 code does not use ``print`` or ``logging`` calls, and this also applies
 to the test suite (with rare exceptions).
 
-New unit test code should be placed in the corresponding test module in
-the bifacial_radiance/test directory.
-
-Developers **must** include comprehensive tests for any additions or
-modifications to bifacial_radiance.
-
 This documentation
 ~~~~~~~~~~~~~~~~~~
 

diff --git a/docs/sphinx/source/index.rst b/docs/sphinx/source/index.rst
@@ -6,12 +6,14 @@ 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:/NREL/bifacial_radiance>`_.
 
 Please see the :ref:`installation` page for installation help.
 
-For examples on how to use bifacial_radiance, please see :ref:`package_overview` and our `Jupyter Notebook tutorials
+For examples on how to use bifacial_radiance, please see our `Webinar tutorial video <https://www.youtube.com/watch?v=1X9L-R-RVGA>`_. Also find more information on :ref:`package_overview` and our `Jupyter Notebook tutorials
 <http:/Nrel/bifacial_radiance/docs/tutorials/>`_. The documentation assumes general familiarity with Python, NumPy, and Pandas. Google searches will yield many excellent tutorials for these packages.
 
 The bifacial_radiance GitHub wiki has a `Projects and publications that use bifacial_radiance <https:/NREL/bifacial_radiance/wiki/>`_ page for inspiration and listing of your application.

diff --git a/docs/sphinx/source/installation.rst b/docs/sphinx/source/installation.rst
@@ -3,10 +3,16 @@
 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
 ~~~~~~~~~~~~~~~~~~
 
-`https://youtu.be/4A9GocfHKyM <https://youtu.be/4A9GocfHKyM>`_ This video shows how to install the bifacial_radiance software and all associated softwares needed. More info on the Wiki. Instructions are also shown below.
+`https://youtu.be/4A9GocfHKyM <https://youtu.be/4A9GocfHKyM>`_ This video shows how to install the bifacial_radiance software and all associated softwares needed for Windows. More info on the Wiki. Instructions for Windows and Linux-based OS are also shown below.
 
 
 PREREQUISITES (Step 0)
@@ -15,13 +21,38 @@ This software requires the previous installation of ``RADIANCE`` from https://gi
 
 Make sure you add radiance to the system PATH so Python can interact with the radiance program
 
-If you are on a PC you should also copy the `Jaloxa radwinexe-5.0.a.8-win64.zip <http://www.jaloxa.eu/resources/radiance/radwinexe.shtml>`_ executables into ``program files/radiance/bin`` 
+Windows:
+
+If you are on a Windows computer you should also copy the `Jaloxa radwinexe-5.0.a.8-win64.zip <http://www.jaloxa.eu/resources/radiance/radwinexe.shtml>`_ executables into ``program files/radiance/bin``. This executables allow for some nifty visualization options of your generated scene inside of bifacial_radiance, like falsecolor images.
+
+Linux/Mac OSX:
+
+* For Linux/Mac OSX, you will need to install QT for the GUI to work properly. Installation and details described in (:issue:`131`:):
+1. Install ``qt5-default`` from Ubuntu using ``apt``,
+2. get the official Radiance 5.2 source tarball with auxiliary libraries ``rad5R2all.tar.gz`` from either `RADIANCE <https://www.radiance-online.org/download-install/radiance-source-code/latest-release>`_ online or `LBL <https://floyd.lbl.gov/radiance/framed.html>`_ - do _not_clone the GitHub repo as it doesn't have the auxiliary libraries which you may also need. Finally extract the tarball.
+3. you may also need to install ``csh`` and ``cmake`` 
+4. make directories where you want to install radiance, for example ``~/.local/opt/radiance``
+5. read the README and run ``./makeall install clean`` and choose where you want ``bin`` and ``lib``
+You can test it by rendering the daffodil.
+
 
 **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:/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
@@ -31,30 +62,36 @@ Install and Import bifacial_radiance
 
 The period ``.`` is required, the ``-e`` flag is optional and installs in development mode where changes to the `bifacial_radiance.py` files are immediately incorporated into the module if you re-start the python kernel)
 
-For best compatibility, deploy in an `Anaconda 2.7` environment, or run::
+For best compatibility, deploy in an `Anaconda 2019.10` environment, or run::
 
- pip install -r requirements.txt
+ pip install -r requirements.txt
 
 
 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/``. 
+
+
 .. 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:`182`).
+
 
 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

diff --git a/docs/sphinx/source/package_overview.rst b/docs/sphinx/source/package_overview.rst
@@ -3,4 +3,42 @@
 Package Overview
 ================
 
-This is also still under construction. ! :D
+The following section describes some of the functionalities of bifacial_radiance, and how the software is structured. For a SUPER complete explanation and package overview, we highly recommend you watch our `Webinar tutorial video <https://www.youtube.com/watch?v=1X9L-R-RVGA>`_. (`Slides here <https://www.nrel.gov/docs/fy20osti/75218.pdf>`_.
+
+bifacial_radiance is a python wrapper for calling and using Radiance, with specific functions to generate geometry (text files) related to bifacial photovoltaic systems
+
+.. image:: ../../images_wiki/Webinar/wrapper.png
+ :width: 600
+
+A full example might look like:
+
+.. code-block :: python
+
+ from bifacial_radiance import *
+ demo = RadianceObj()
+ demo.setGround()
+ epwfile = demo.getEPW(37.5, -77.6)
+ metdata = demo.readWeatherFile(epwfile)
+ demo.gendaylit(metdata, 4020)
+ demo.makeModule ("My_panel", x=1,y=2)
+ sceneDict = {'tilt':30, 'pitch':3, 'clearance_height':0.5, 'azimuth':180, 'nMods':10, 'nRows':4}
+ scene = demo.makeScene("My_panel", sceneDict)
+ octfile = demo.makeOct()
+ analysis = AnalysisObj(octfile, demo.name)
+ frontscan, backscan = analysis.moduleAnalysis(scene)
+ analysis.analysis(octfile, demo.name, frontscan, backscan)
+
+What this example is showing are the main/minimum instructions or steps needed to run a simulation, which are:
+
+1. Make a Radiance Object
+2. Make Sky - generates a hourly or cumulative sky based on the given weather file irradiance data. Saves files in skies folder and in main folder.
+3. Make Module - creates a module of your desire. Cell-level module, and 1-up or more configurations. Saves the module info as a .rad in objects folder.
+4. Make Scene - replicates your module at the desired pitch/tilt for desired number of rows / modules per row. Saves the scene info as a .rad in objects folder.
+5. Make Oct - creates a .oct file that ties Sky, Module, and Scene.
+6. Analysis Obj - calculates the coordinates that will be sampled for irradiance. You can specify any module and row desired or custom coordinates.
+7. Analysis - runs the Radiance rtrace command and saves the measured irradiance values for the surface specified in the results folder.
+
+.. image:: ../../images_wiki/Webinar/mainsteps.png
+ :width: 600
+
+Each of this steps has more options than described here, so we really recommend looking at the `Webinar tutorial <https://www.youtube.com/watch?v=1X9L-R-RVGA>`_ And our `Jupyter Notebook tutorials <http:/Nrel/bifacial_radiance/docs/tutorials/>`_, as well as the :ref:`manualapi` as each function has description of input parameters.