docs/tutorials/2 - Single Axis Tracking Yearly Simulation.ipynb

{
 "cells": [
  {
   "cell_type": "code",
   "execution_count": 1,
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "Working on a  Windows 10\n",
      "Python version  3.11.7 | packaged by Anaconda, Inc. | (main, Dec 15 2023, 18:05:47) [MSC v.1916 64 bit (AMD64)]\n",
      "Pandas version  2.1.4\n",
      "bifacial_radiance version  0+untagged.1553.g23d2640.dirty\n"
     ]
    }
   ],
   "source": [
    "# This information helps with debugging and getting support :)\n",
    "import sys, platform\n",
    "import pandas as pd\n",
    "import bifacial_radiance as br\n",
    "print(\"Working on a \", platform.system(), platform.release())\n",
    "print(\"Python version \", sys.version)\n",
    "print(\"Pandas version \", pd.__version__)\n",
    "print(\"bifacial_radiance version \", br.__version__)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "# 2 - Single Axis Tracking Yearly Simulation\n",
    "\n",
    "Method <b> Gencumsky </b> has been modified to divide the yearly-cumulative sky into various skies, each one representing the cumulative irradiance for the hours at which the tracker is at a certain angle. For faster running, for a tracker that moves between 45 and -45 degrees limit angle, if only positions every 5 degrees are considered (45, 40, 35 .... -4-, -45), then only 18 skies (and 18 simulations) will be run for the whole year.\n",
    "\n",
    "![Example of the hemisphere cumulative sky](../images_wiki/Journal2Pics/tracking_cumulativesky.PNG)\n",
    "\n",
    "\n",
    "This procedure was presented in:\n",
    "\n",
    "Ayala Pelaez S, Deline C, Greenberg P, Stein JS, Kostuk RK. Model and validation of single-axis tracking with bifacial PV. IEEE J Photovoltaics. 2019;9(3):715–21. https://ieeexplore.ieee.org/document/8644027 and https://www.nrel.gov/docs/fy19osti/72039.pdf (pre-print, conference version)\n",
    "\n",
    "\n",
    "***Steps:***\n",
    "1. <a href='#step1'> Create a folder for your simulation, and load bifacial_radiance </a> \n",
    "2. <a href='#step2'> Create a Radiance Object, set Albedo and Download Weather Files </a>  \n",
    "4. <a href='#step3'> Set Tracking Angles </a>\n",
    "5. <a href='#step4'> Generate the Sky </a> \n",
    "6. <a href='#step5'> Define a Module type </a>\n",
    "7. <a href='#step6'> Create the scene </a>\n",
    "8. <a href='#step7'> Combine Ground, Sky and Scene Objects </a>\n",
    "9. <a href='#step8'> Analyze and get results </a>\n",
    "10. <a href='#step9'> Clean Results </a>   \n",
    "   \n",
    "\n",
    "And finally: <a href='#condensed'> Condensed instructions </a>"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "<a id='step1'></a>"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "\n",
    "## 1. Create a folder for your simulation, and load bifacial_radiance \n",
    "\n",
    "First let's set the folder where the simulation will be saved. By default, this is the TEMP folder in the bifacial_radiance distribution.\n",
    "\n",
    "The lines below find the location of the folder relative to this Jupyter Journal. You can alternatively point to an empty directory (it will open a load GUI Visual Interface) or specify any other directory in your computer, for example:\n",
    "\n",
    "***testfolder = r'C:\\Users\\sayala\\Documents\\RadianceScenes\\Tutorials\\Journal2'***\n",
    "\n"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 1,
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "Your simulation will be stored in C:\\Users\\mprillim\\sam_dev\\bifacial_radiance\\bifacial_radiance\\TEMP\\Tutorial_02\n"
     ]
    }
   ],
   "source": [
    "import os\n",
    "from pathlib import Path\n",
    "\n",
    "testfolder = Path().resolve().parent.parent / 'bifacial_radiance' / 'TEMP' / 'Tutorial_02'\n",
    "\n",
    "# Another option using relative address; for some operative systems you might need '/' instead of '\\'\n",
    "# testfolder = os.path.abspath(r'..\\..\\bifacial_radiance\\TEMP')  \n",
    "\n",
    "print (\"Your simulation will be stored in %s\" % testfolder)\n",
    "\n",
    "if not os.path.exists(testfolder):\n",
    "    os.makedirs(testfolder)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "This will load bifacial_radiance and other libraries from python that will be useful for this Jupyter Journal:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 2,
   "metadata": {},
   "outputs": [],
   "source": [
    "from bifacial_radiance import *\n",
    "import numpy as np"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "<a id='step2'></a>"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## 2. Create a Radiance Object, Set Albedo, and Download and Load Weather File\n",
    "\n",
    "These are all repeated steps from Tutorial 1, so condensing:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 3,
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "path = C:\\Users\\mprillim\\sam_dev\\bifacial_radiance\\bifacial_radiance\\TEMP\\Tutorial_02\n",
      "Loading albedo, 1 value(s), 0.250 avg\n",
      "1 nonzero albedo values.\n",
      "Getting weather file: USA_VA_Richmond.724010_TMY2.epw\n",
      " ... OK!\n",
      "8760 line in WeatherFile. Assuming this is a standard hourly WeatherFile for the year for purposes of saving Gencumulativesky temporary weather files in EPW folder.\n",
      "Coercing year to 2021\n",
      "Saving file EPWs\\metdata_temp.csv, # points: 8760\n",
      "Calculating Sun position for Metdata that is right-labeled  with a delta of -30 mins. i.e. 12 is 11:30 sunpos\n"
     ]
    }
   ],
   "source": [
    "# Create a RadianceObj 'object' named bifacial_example. no whitespace allowed\n",
    "demo = RadianceObj('tutorial_2', path = str(testfolder))  \n",
    "\n",
    "albedo = 0.25\n",
    "demo.setGround(albedo)\n",
    "\n",
    "# Pull in meteorological data using pyEPW for any global lat/lon\n",
    "epwfile = demo.getEPW(lat = 37.5, lon = -77.6)  # This location corresponds to Richmond, VA.\n",
    "# Read in the weather data pulled in above. \n",
    "metdata = demo.readWeatherFile(weatherFile = epwfile) "
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "<a id='step3'></a>"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "# TRACKING Workflow"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Until now, all the steps looked the same from Tutorial 1. The following section follows similar steps, but the functions are specific for working with single axis tracking.\n",
    "\n",
    "## 3. Set Tracking Angles\n",
    "\n",
    "This function will read the weather file, and based on the sun position it will calculate the angle the tracker should be at for each hour. It will create metdata files for each of the tracker angles considered."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 4,
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "Saving file EPWs\\1axis_-5.0.csv, # points: 2214\n",
      "Saving file EPWs\\1axis_0.0.csv, # points: 57\n",
      "Saving file EPWs\\1axis_5.0.csv, # points: 2096\n"
     ]
    }
   ],
   "source": [
    "limit_angle = 5 # tracker rotation limit angle. Setting it ridiculously small so this runs faster.\n",
    "angledelta = 5 # sampling between the limit angles. \n",
    "backtrack = True\n",
    "gcr = 0.33\n",
    "cumulativesky = True # This is important for this example!\n",
    "trackerdict = demo.set1axis(metdata = metdata, limit_angle = limit_angle, backtrack = backtrack, \n",
    "                            gcr = gcr, cumulativesky = cumulativesky)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Setting backtrack to True is important in this step, so the trackers correct for self-shading when following the sun at high zenith angles. "
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "<a id='step4'></a>"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## 4. Generate the Sky\n",
    "\n",
    "This will create the skies for each sub-metdata file created by set1axis.\n"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 5,
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "message: There were 2174 sun up hours in this climate file\n",
      "Total Ibh/Lbh: 0.000000\n",
      "Created skyfile skies\\1axis_-5.0.rad\n",
      "message: There were 50 sun up hours in this climate file\n",
      "Total Ibh/Lbh: 0.000000\n",
      "Created skyfile skies\\1axis_0.0.rad\n",
      "message: There were 2065 sun up hours in this climate file\n",
      "Total Ibh/Lbh: 0.000000\n",
      "Created skyfile skies\\1axis_5.0.rad\n"
     ]
    }
   ],
   "source": [
    "trackerdict = demo.genCumSky1axis()"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "This is how one of the cumulative sky .cal files associated with each .rad file generated look like: \n",
    "\n",
    "![Example of the gencumsky1axis](../images_wiki/Journal2Pics/gencumsky1axis_example_file_structure_and_contents.PNG)\n",
    "\n",
    "\n",
    "Each of the values corresponds to the cumulative rradiance of one of those patches, for when the tracker is at that specific angle through the year."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "<a id='step5'></a>"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## 5. Define the Module type\n",
    "\n",
    "Let's make a more interesting module in this example. Let's do 2-up configuration in portrait, with the modules rotating around a 10 centimeter round torque tube. Let's add a gap between the two modules in 2-UP of 10 centimeters, as well as gap between the torque tube and the modules of 5 centimeters. Along the row, the modules are separated only 2 centimeters for this example. The torquetube is painted Metal_Grey in this example (it's one of the materials available in Ground.rad, and it is 40% reflective).\n",
    "\n",
    "Note that starting with bifacial_radiance version 0.4.0, the module object has a new geometry generation function `addTorquetube`.  The old way of passing a properly formatted dictionary as a keyword argument will still work too.\n"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 6,
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "\n",
      "Module Name: test-module\n",
      "Module test-module updated in module.json\n",
      "Pre-existing .rad file objects\\test-module.rad will be overwritten\n",
      "\n",
      "Module test-module updated in module.json\n",
      "Pre-existing .rad file objects\\test-module.rad will be overwritten\n",
      "\n",
      "\n",
      "{'x': 0.984, 'y': 1.7, 'z': 0.02, 'modulematerial': 'black', 'scenex': 1.004, 'sceney': 3.5, 'scenez': 0.1, 'numpanels': 2, 'bifi': 1, 'text': '! genbox black test-module 0.984 1.7 0.02 | xform -t -0.492 -1.75 0.1 -a 2 -t 0 1.8 0\\r\\n! genrev Metal_Grey tube1 t*1.004 0.05 32 | xform -ry 90 -t -0.502 0 0', 'modulefile': 'objects\\\\test-module.rad', 'glass': False, 'offsetfromaxis': 0.1, 'xgap': 0.02, 'ygap': 0.1, 'zgap': 0.05}\n",
      "\n",
      "{'diameter': 0.1, 'tubetype': 'round', 'material': 'Metal_Grey', 'visible': True}\n"
     ]
    }
   ],
   "source": [
    "x = 0.984  # meters\n",
    "y = 1.7    # meters\n",
    "moduletype = 'test-module'\n",
    "numpanels = 2\n",
    "zgap = 0.05\n",
    "ygap = 0.10\n",
    "xgap = 0.02\n",
    "\n",
    "module = demo.makeModule(name=moduletype, x=x, y=y,xgap=xgap, ygap=ygap, zgap=zgap, \n",
    "                numpanels=numpanels)\n",
    "\n",
    "module.addTorquetube(diameter=0.1, material='Metal_Grey', tubetype='round') # New torquetube generation function\n",
    "print()\n",
    "print(module)\n",
    "print()\n",
    "print(module.torquetube)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "<a id='step6'></a>"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## 6. Make the Scene\n",
    "\n",
    "The scene Dictionary specifies the information of the scene. For tracking, different input parameters are expected in the dictionary, such as number of rows, number of modules per row, row azimuth, hub_height (distance between the axis of rotation of the modules and the ground). "
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 7,
   "metadata": {
    "scrolled": true
   },
   "outputs": [],
   "source": [
    "hub_height = 2.3\n",
    "sceneDict = {'gcr': gcr,'hub_height':hub_height, 'nMods': 20, 'nRows': 7}  \n"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "To make the scene we have to create a Scene Object through the method makeScene1axis. This method will create a .rad file in the objects folder, with the parameters specified in sceneDict and the module created above."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 8,
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "\n",
      "Making .rad files for cumulativesky 1-axis workflow\n",
      "3 Radfiles created in /objects/\n"
     ]
    }
   ],
   "source": [
    "trackerdict = demo.makeScene1axis(trackerdict = trackerdict, module = module, sceneDict = sceneDict) "
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "<a id='step7'></a>"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## 7. Combine Ground, Sky and Scene Objects\n",
    "\n",
    "makeOct1axis joins the sky.rad file, ground.rad file, and the geometry.rad files created in makeScene."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "\n",
      "Making 3 octfiles in root directory.\n"
     ]
    }
   ],
   "source": [
    "trackerdict = demo.makeOct1axis(trackerdict = trackerdict)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "<a id='step8'></a>"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## 8. Analyze and get results\n",
    "\n",
    "We can choose to analyze any module in the Scene we have created. The default, if no modWanted or rowWanted is passed, is to sample the center module of the center row. \n",
    "\n",
    "For this example we will sample row 2, module 9."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "modWanted = 9\n",
    "rowWanted = 2\n",
    "customname = '_Row_2_Module_09' # This is useful if we want to do various analysis.\n",
    "trackerdict = demo.analysis1axis(trackerdict, modWanted=9, rowWanted = 2, customname=customname)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Let's look at the results with more detail. The analysis1axis routine created individual result .csv files for each angle, as well as one cumulative result .csv where the irradiance is added by sensor.\n"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "results = load.read1Result('cumulative_results__Row_2_Module_09.csv')\n",
    "results"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "There are various things to notice:\n",
    "\n",
    "I. The materials column has a specific format that will tell you if you are sampling the correct module:\n",
    "\n",
    "                                a{ModWanted}.{rowWanted}.a{numPanel}.{moduletype}.material_key\n",
    "\n",
    "* Since for this journal numPanels = 2, numPanel can either be 0 or 1, for the East-most and West-most module in the collector width.\n",
    "* numPanel, ModWanted and RowWanted are indexed starting at 0 in the results.\n",
    "* material_key is from the surface generated inside radiance. Usually it is 6457 for top surface of hte module and .2310 for the bottom one. \n",
    "\n",
    "II. Sensors sample always in the same direction. For this N-S aligned tracker, that is East-most to West. For this 2-up portrait tracker which is 3.5 meters, 20x7 rows and we are sampling module 9 on row 2, the East to West sampling goes from 22.6 m to 19.81 m = 2.79m. It is not exatly 3.5 because the sensors are spaced evenly through the collector width (CW): \n",
    "\n",
    "\n",
    "![Sensors spaced along collector width](../images_wiki/Journal2Pics/spaced_sensors.PNG)\n",
    "\n",
    "III. When there is a ygap in the collector width (2-UP or more configuration), some of the sensors might end up sampling the torque tube, or the sky. You can ses that in the materials columns. This also happens if the number of sensors is quite high, the edges of the module might be sampled instead of the sensors. For this reason, before calculating bifacial gain these results must be cleaned. For more advanced simulations, make sure you clean each result csv file individually.  We provide some options on load.py but some are very use-specific, so you might have to develop your own cleaning tool (or let us know on issues!)\n",
    "\n",
    "<div class=\"alert alert-warning\">\n",
    "Important: If you have torquetubes and y-gap values, make sure you clean your results.\n",
    "</div>\n"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "<a id='step9'></a>"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## 9. Clean Results\n",
    "\n",
    "We have two options for cleaning results. The simples on is <b>load.cleanResults</b>, but there is also a deepClean for specific purposes.\n",
    "\n",
    "cleanResults will find materials that should not have values and set them to NaN."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "results_clean = load.cleanResult(results)\n",
    "results_clean\n"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "These are the total irradiance values over all the hours of the year that the module at each sampling point will receive. Dividing the back irradiance average by the front irradiance average will give us the bifacial gain for the year:\n",
    "\n",
    "![Bifacial Gain in Irradiance Formula](../images_wiki/Journal1Pics/BGG_Formula.PNG)\n",
    "\n",
    "Assuming that our module from Prism Solar has a bifaciality factor (rear to front performance) of 90%, our <u> bifacial gain </u> is of:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "bifacialityfactor = 0.9\n",
    "print('Annual bifacial ratio: %0.3f ' %( np.nanmean(results_clean.Wm2Back) * bifacialityfactor / np.nanmean(results_clean.Wm2Front)) )"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "<a id='condensed'></a>"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## CONDENSED VERSION\n",
    "Everything we've done so far in super short condensed version:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {
    "scrolled": true
   },
   "outputs": [],
   "source": [
    "albedo = 0.25\n",
    "lat = 37.5\n",
    "lon = -77.6\n",
    "nMods = 20\n",
    "nRows = 7\n",
    "hub_height = 2.3\n",
    "gcr = 0.33\n",
    "moduletype = 'test-module'  # this must already exist since we are not calling makeModule in this CONDENSED example.\n",
    "#testfolder = r'C:\\Users\\sayala\\Documents\\RadianceScenes\\Tutorials\\Journal2'\n",
    "limit_angle = 5\n",
    "angeldelta = 5\n",
    "backtrack = True\n",
    "gcr = gcr\n",
    "modWanted = 9\n",
    "rowWanted = 2\n",
    "cumulativesky = True\n",
    "\n",
    "import bifacial_radiance\n",
    "demo = RadianceObj('test') \n",
    "demo.setGround(albedo)\n",
    "epwfile = demo.getEPW(lat, lon) \n",
    "metdata = demo.readWeatherFile(epwfile)\n",
    "demo.set1axis(limit_angle=limit_angle, backtrack=backtrack, gcr=gcr, cumulativesky=cumulativesky)\n",
    "demo.genCumSky1axis()\n",
    "sceneDict = {'gcr': gcr,'hub_height':hub_height, 'nMods': nMods, 'nRows': nRows}  # orientation deprecated on v.0.2.4.\n",
    "demo.makeScene1axis(module=moduletype, sceneDict=sceneDict)\n",
    "demo.makeOct1axis()\n",
    "demo.analysis1axis(modWanted=modWanted, rowWanted=rowWanted);\n"
   ]
  }
 ],
 "metadata": {
  "anaconda-cloud": {},
  "kernelspec": {
   "display_name": "Python 3 (ipykernel)",
   "language": "python",
   "name": "python3"
  },
  "language_info": {
   "codemirror_mode": {
    "name": "ipython",
    "version": 3
   },
   "file_extension": ".py",
   "mimetype": "text/x-python",
   "name": "python",
   "nbconvert_exporter": "python",
   "pygments_lexer": "ipython3",
   "version": "3.11.7"
  }
 },
 "nbformat": 4,
 "nbformat_minor": 4
}