Make append=False default behavior in makeScene and makeScene1axis. P…

…ytests passing.

bifacial_radiance/main.py

@@ -2347,6 +2347,7 @@ def printModules(self):
 
 
     def makeScene(self, module=None, sceneDict=None, radname=None,
+                  customtext=None, append=False, 
                   moduletype=None, appendtoScene=None):
         """
         Create a SceneObj which contains details of the PV system configuration including
@@ -2366,19 +2367,29 @@ def makeScene(self, module=None, sceneDict=None, radname=None,
             `hub_height` can also be passed as a possibility.
         radname : str
             Gives a custom name to the scene file. Useful when parallelizing.
-        moduletype: DEPRECATED. use the `module` kwarg instead.
-        appendtoScene : str
+        customtext : str
             Appends to the scene a custom text pointing to a custom object
             created by the user; format of the text should start with the rad 
             file path and name, and then any other geometry transformations 
             native to Radiance necessary.
+        append : bool, default False
+            If multiple scenes exist (makeScene called multiple times), either 
+            overwrite the existing scene (default) or append a new SceneObj to
+            self.scenes
+        moduletype: DEPRECATED. use the `module` kwarg instead.
+        appendtoScene : DEPRECATED.  use the `customtext` kwarg instead.
+
         
         Returns
         -------
         SceneObj 
             'scene' with configuration details
             
         """
+        if appendtoScene is not None:
+            customtext = appendtoScene
+            print("Warning:  input `appendtoScene` is deprecated. Use kwarg "
+                  "`customtext` instead")
         if moduletype is not None:
             module = moduletype
             print("Warning:  input `moduletype` is deprecated. Use kwarg "
@@ -2446,13 +2457,15 @@ def makeScene(self, module=None, sceneDict=None, radname=None,
                     print( "Radfile APPENDAGE created!")
         else:
             scene.radfiles = [sceneRAD]
-        #TODO: change appendtoScene kwarg to customObject kwarg.  keep appendtoScene as deprecated input
-        if appendtoScene is not None:
-            self.appendtoScene(scene.radfiles[0], customObject = appendtoScene)
+        #
+        if customtext is not None:
+            self.appendtoScene(scene.radfiles[0], customObject = customtext)
 
-        # TODO: what's the desired default behavior here?
-        #       Do we append a new scene by default, or overwrite?  
-        self.scenes.append(scene)
+        # default behavior: overwrite. (backwards compatible behavior.)
+        if append:
+            self.scenes.append(scene)
+        else:
+            self.scenes = [scene]
         return scene
 
     def appendtoScene(self, radfile=None, customObject=None):
@@ -2494,7 +2507,8 @@ def appendtoScene(self, radfile=None, customObject=None):
 
 
     def makeScene1axis(self, trackerdict=None, module=None, sceneDict=None,
-                       cumulativesky=None, moduletype=None, appendtoScene=None):
+                       cumulativesky=None, customtext=None, append=False, 
+                       moduletype=None, appendtoScene=None):
         """
         Creates a SceneObj for each tracking angle which contains details of the PV
         system configuration including row pitch, hub_height, nMods per row, nRows in the system...
@@ -2509,12 +2523,17 @@ def makeScene1axis(self, trackerdict=None, module=None, sceneDict=None,
             Dictionary with keys:`tilt`, `hub_height`, `pitch`, `azimuth`
         cumulativesky : bool
             Defines if sky will be generated with cumulativesky or gendaylit.
-        moduletype: DEPRECATED. use the `module` kwarg instead.
-        appendtoScene : str
+        customtext : str
             Appends to each scene a custom text pointing to a custom object
             created by the user; format of the text should start with the rad 
             file path and name, and then any other geometry transformations 
             native to Radiance necessary.
+        append : bool, default False
+            If multiple scenes exist (makeScene called multiple times), either 
+            overwrite the existing scene (default) or append a new SceneObj to
+            self.scenes
+        moduletype: DEPRECATED. use the `module` kwarg instead.
+        appendtoScene : DEPRECATED. use the `customtext` kwarg instead
             
         Returns
         --------
@@ -2535,7 +2554,11 @@ def makeScene1axis(self, trackerdict=None, module=None, sceneDict=None,
                   'sceneDict inputs: .hub_height .azimuth .nMods .nRows'+
                   'and .pitch or .gcr')
             return
-
+
+        if appendtoScene is not None: #kwarg is deprecated.
+            customtext = appendtoScene
+            print("Warning:  input `appendtoScene` is deprecated. Use kwarg "
+                  "`customtext` instead")
         # If no nRows or nMods assigned on deprecated variable or dictionary,
         # assign default.
         if 'nRows' not in sceneDict:
@@ -2637,7 +2660,10 @@ def makeScene1axis(self, trackerdict=None, module=None, sceneDict=None,
                 try:
                     name=f"Scene{trackerdict[theta]['scenes'].__len__()}"
                     scene.name = name
-                    trackerdict[theta]['scenes'].append(scene)
+                    if append:
+                        trackerdict[theta]['scenes'].append(scene)
+                    else:
+                        trackerdict[theta]['scenes'] = [scene]
                 except KeyError: #either KeyError or maybe IndexError?  
                     trackerdict[theta]['scenes'] = [scene]
 
@@ -2688,17 +2714,20 @@ def makeScene1axis(self, trackerdict=None, module=None, sceneDict=None,
                     try:
                         name=f"Scene{trackerdict[time]['scenes'].__len__()}"
                         scene.name = name
-                        trackerdict[time]['scenes'].append(scene)
+                        if append:
+                            trackerdict[time]['scenes'].append(scene)
+                        else:
+                            trackerdict[time]['scenes'] = [scene]
                     except KeyError: #either KeyError or maybe IndexError?  
                         trackerdict[time]['scenes'] = [scene]
                     count+=1
             print('{} Radfiles created in /objects/'.format(count))
 
 
-        if appendtoScene is not None:
+        if customtext is not None:
             for key in trackerdict:
                 #TODO: test if this actually works
-                self.appendtoScene(trackerdict[key]['scenes'][0].radfiles, customObject = appendtoScene)
+                self.appendtoScene(trackerdict[key]['scenes'][0].radfiles, customObject = customtext)
 
         self.trackerdict = trackerdict
         #self.nMods = sceneDict['nMods']  #assign nMods and nRows to RadianceObj

docs/sphinx/source/whatsnew/pending.rst

@@ -1,9 +1,13 @@
-.. _whatsnew_0430:
+.. _whatsnew_050:
 
-v0.4.3 (XX / XX / 2023)
+v0.5.0 (4 / XX / 2024)
 ------------------------
 Release of new version including ...
 
+Deprecations
+~~~~~~~~~~~~
+* :py:class:`~bifacial_radiance.makeScene`.`appendtoScene` is deprecated in favor of :py:class:`~bifacial_radiance.makeScene`.`customtext` 
+
 
 API Changes
 ~~~~~~~~~~~~
@@ -13,7 +17,7 @@ API Changes
 * To support multiple modules and row scans for 1axis simulations, outputs like Wm2Front are now stored in ``trackerdict``.``Results``  (:issue:`405`)(:pull:`408`)
 * ``mismatch.mad_fn`` has new functionality and input parameter `axis`. If a 2D matrix or dataframe is passed in as data, MAD is calculated along the row (default) or along the columns by passing 'axis=1' (:issue:`449`)(:pull:`485`)
 * NSRDB weather data can now be loaded using :py:class:`~bifacial_radiance.RadianceObj.NSRDBWeatherData`.
-* ``scene.appendtoscene`` functionality added (add more detail here, fix hyperlinks)
+* :py:class:`~bifacial_radiance.makeScene`.`append` added to allow multiple scenes to be attached to a single RadianceObj.  Default: False (over-write the scene)
 * ``scene.appendtoscene`` functionality added (add more detail here, fix hyperlinks)
 
 

tests/test_bifacial_radiance.py

@@ -222,29 +222,31 @@ def test_1axis_gencumSky():
     assert trackerdict[-5.0]['scenes'][0].radfiles[0:7] == 'objects' # 'objects\\1axis-5.0_1.825_11.42_5.0_10x3_origin0,0.rad'
 
     sceneDict = {'pitch': pitch,'clearance_height':hub_height, 'nMods':10, 'nRows':3}  # testing height filter too
-    trackerdict = demo.makeScene1axis(sceneDict=sceneDict, module = 'test-module')
+    trackerdict = demo.makeScene1axis(sceneDict=sceneDict, module = 'test-module', append=True)
 #    assert trackerdict[-5.0]['radfile'] == 'objects\\1axis-5.0_1.825_11.42_5.0_10x3_origin0,0.rad'
     sceneDict = {'pitch': pitch,'height':hub_height, 'nMods':10, 'nRows':3}  # testing height filter too
-    trackerdict = demo.makeScene1axis(sceneDict=sceneDict, module = 'test-module')
+    trackerdict = demo.makeScene1axis(sceneDict=sceneDict, module = 'test-module', append=True)
 #    assert trackerdict[-5.0]['radfile'] == 'objects\\1axis-5.0_1.825_11.42_5.0_10x3_origin0,0.rad'
     sceneDict = {'pitch': pitch,'height':hub_height, 'clearance_height':hub_height, 'nMods':10, 'nRows':3}  # testing height filter too
-    trackerdict = demo.makeScene1axis(sceneDict=sceneDict, module = 'test-module')
+    trackerdict = demo.makeScene1axis(sceneDict=sceneDict, module = 'test-module', append=True)
 #    assert trackerdict[-5.0]['radfile'] == 'objects\\1axis-5.0_1.825_11.42_5.0_10x3_origin0,0.rad'
     sceneDict = {'pitch': pitch,'height':hub_height, 'hub_height':hub_height, 'nMods':10, 'nRows':3}  # testing height filter too
-    trackerdict = demo.makeScene1axis(sceneDict=sceneDict, module = 'test-module')
+    trackerdict = demo.makeScene1axis(sceneDict=sceneDict, module = 'test-module', append=True)
     assert trackerdict[-5.0]['scenes'].__len__() == 5
 
     demo.exportTrackerDict(trackerdict, savefile = 'results\exportedTrackerDict2.csv')
     assert trackerdict[-5.0]['scenes'][4].radfiles[0:7] == 'objects' 
     #assert trackerdict[-5.0]['radfile'] == 'objects\\1axis-5.0_1.825_11.42_5.0_10x3_origin0,0.rad'
     minitrackerdict = {}
     minitrackerdict[list(trackerdict)[0]] = trackerdict[list(trackerdict.keys())[0]]
+    minitrackerdict[list(trackerdict)[0]]['scenes'] = [trackerdict[list(trackerdict)[0]]['scenes'][4]]
+
     trackerdict = demo.makeOct1axis(trackerdict=minitrackerdict) # just run this for one timestep: Jan 1 11am
-    trackerdict = demo.analysis1axis(trackerdict=trackerdict, modWanted=7, rowWanted=3, sensorsy=2, sceneNum=4) 
+    trackerdict = demo.analysis1axis(trackerdict=trackerdict, modWanted=7, rowWanted=3, sensorsy=2, sceneNum=0) 
     assert trackerdict[-5.0]['Results'][0]['AnalysisObj'].x[0] == -10.76304
     modscanfront = {}
     modscanfront = {'xstart': -5}
-    trackerdict = demo.analysis1axis(trackerdict=trackerdict, modWanted=7, rowWanted=3, sensorsy=2, modscanfront=modscanfront, sceneNum=4) 
+    trackerdict = demo.analysis1axis(trackerdict=trackerdict, modWanted=7, rowWanted=3, sensorsy=2, modscanfront=modscanfront, sceneNum=0) 
     assert trackerdict[-5.0]['Results'][1]['AnalysisObj'].x[0] == -5