{ "cells": [ { "cell_type": "markdown", "metadata": {}, "source": [ "# Running EnergyPlus from Eppy" ] }, { "cell_type": "markdown", "metadata": {}, "source": [ "## Using idf.run" ] }, { "cell_type": "markdown", "metadata": {}, "source": [ "Running an E+ simulation from eppy is as simple as doing ``idf.run()``\n", "\n", "Here is a n example of how to do it." ] }, { "cell_type": "code", "execution_count": 1, "metadata": {}, "outputs": [], "source": [ "# you would normaly install eppy by doing\n", "# python setup.py install\n", "# or\n", "# pip install eppy\n", "# or\n", "# easy_install eppy\n", "\n", "# if you have not done so, uncomment the following three lines\n", "import sys\n", "# pathnameto_eppy = 'c:/eppy'\n", "pathnameto_eppy = '../'\n", "sys.path.append(pathnameto_eppy)" ] }, { "cell_type": "code", "execution_count": 2, "metadata": {}, "outputs": [], "source": [ "from eppy.modeleditor import IDF\n", "\n", "iddfile = \"/Applications/EnergyPlus-8-3-0/Energy+.idd\"\n", "IDF.setiddname(iddfile)\n" ] }, { "cell_type": "code", "execution_count": 3, "metadata": {}, "outputs": [ { "name": "stdout", "output_type": "stream", "text": [ "\r\n", "/Applications/EnergyPlus-8-3-0/energyplus --weather /Applications/EnergyPlus-8-3-0/WeatherData/USA_IL_Chicago-OHare.Intl.AP.725300_TMY3.epw --output-directory /Users/santoshphilip/Documents/coolshadow/github/eppy/docs --idd /Applications/EnergyPlus-8-3-0/Energy+.idd /Users/santoshphilip/Documents/coolshadow/github/eppy/docs/in.idf\r\n", "\n" ] } ], "source": [ "idfname = \"/Applications/EnergyPlus-8-3-0/ExampleFiles/BasicsFiles/Exercise1A.idf\"\n", "epwfile = \"/Applications/EnergyPlus-8-3-0/WeatherData/USA_IL_Chicago-OHare.Intl.AP.725300_TMY3.epw\"\n", "\n", "idf = IDF(idfname, epwfile)\n", "idf.run()" ] }, { "cell_type": "markdown", "metadata": {}, "source": [ "\n", "if you are in a terminal, you will see something like this::\n" ] }, { "cell_type": "markdown", "metadata": {}, "source": [ " \n", " Processing Data Dictionary\n", " Processing Input File\n", " Initializing Simulation\n", " Reporting Surfaces\n", " Beginning Primary Simulation\n", " Initializing New Environment Parameters\n", " Warming up {1}\n", " Warming up {2}\n", " Warming up {3}\n", " Warming up {4}\n", " Warming up {5}\n", " Warming up {6}\n", " Starting Simulation at 07/21 for CHICAGO_IL_USA COOLING .4% CONDITIONS DB=>MWB\n", " Initializing New Environment Parameters\n", " Warming up {1}\n", " Warming up {2}\n", " Warming up {3}\n", " Warming up {4}\n", " Warming up {5}\n", " Warming up {6}\n", " Starting Simulation at 01/21 for CHICAGO_IL_USA HEATING 99.6% CONDITIONS\n", " Writing final SQL reports\n", " EnergyPlus Run Time=00hr 00min 0.24sec\n" ] }, { "cell_type": "markdown", "metadata": {}, "source": [ "It’s as simple as that to run using the EnergyPlus defaults, but all the EnergyPlus command line interface options are also supported.\n", "\n", "To get a description of the options available, as well as the defaults you can call the Python built-in help function on the IDF.run method and it will print a full description of the options to the console." ] }, { "cell_type": "code", "execution_count": 4, "metadata": {}, "outputs": [ { "name": "stdout", "output_type": "stream", "text": [ "Help on method run in module eppy.modeleditor:\n", "\n", "run(**kwargs) method of eppy.modeleditor.IDF instance\n", " This method wraps the following method:\n", " \n", " run(idf=None, weather=None, output_directory='', annual=False, design_day=False, idd=None, epmacro=False, expandobjects=False, readvars=False, output_prefix=None, output_suffix=None, version=False, verbose='v', ep_version=None)\n", " Wrapper around the EnergyPlus command line interface.\n", " \n", " Parameters\n", " ----------\n", " idf : str\n", " Full or relative path to the IDF file to be run, or an IDF object.\n", " \n", " weather : str\n", " Full or relative path to the weather file.\n", " \n", " output_directory : str, optional\n", " Full or relative path to an output directory (default: 'run_outputs)\n", " \n", " annual : bool, optional\n", " If True then force annual simulation (default: False)\n", " \n", " design_day : bool, optional\n", " Force design-day-only simulation (default: False)\n", " \n", " idd : str, optional\n", " Input data dictionary (default: Energy+.idd in EnergyPlus directory)\n", " \n", " epmacro : str, optional\n", " Run EPMacro prior to simulation (default: False).\n", " \n", " expandobjects : bool, optional\n", " Run ExpandObjects prior to simulation (default: False)\n", " \n", " readvars : bool, optional\n", " Run ReadVarsESO after simulation (default: False)\n", " \n", " output_prefix : str, optional\n", " Prefix for output file names (default: eplus)\n", " \n", " output_suffix : str, optional\n", " Suffix style for output file names (default: L)\n", " L: Legacy (e.g., eplustbl.csv)\n", " C: Capital (e.g., eplusTable.csv)\n", " D: Dash (e.g., eplus-table.csv)\n", " \n", " version : bool, optional\n", " Display version information (default: False)\n", " \n", " verbose: str\n", " Set verbosity of runtime messages (default: v)\n", " v: verbose\n", " q: quiet\n", " \n", " ep_version: str\n", " EnergyPlus version, used to find install directory. Required if run() is\n", " called with an IDF file path rather than an IDF object.\n", " \n", " Returns\n", " -------\n", " str : status\n", " \n", " Raises\n", " ------\n", " CalledProcessError\n", " \n", " AttributeError\n", " If no ep_version parameter is passed when calling with an IDF file path\n", " rather than an IDF object.\n", "\n" ] } ], "source": [ "help(idf.run)" ] }, { "cell_type": "markdown", "metadata": {}, "source": [ "*Note:* idf.run() works for E+ version >= 8.3" ] }, { "cell_type": "markdown", "metadata": {}, "source": [ "## Make idf.run() work like EPLaunch" ] }, { "cell_type": "markdown", "metadata": {}, "source": [ "**An Explanation:** EPLaunch is an application that comes with EnergyPlus on the Windows Platform. It has a default functionality that people become familiar with and come to expect. ``make_eplaunch_options`` set up the idf.run() arguments so that it behaves in the same way as EPLaunch.\n", "\n", "Here is the Sample code below. Modify and use it for your needs" ] }, { "cell_type": "code", "execution_count": null, "metadata": {}, "outputs": [], "source": [ "\"\"\"single run EPLaunch style\"\"\"\n", "\n", "\n", "import os \n", "from eppy.modeleditor import IDF\n", "from eppy.runner.run_functions import runIDFs\n", "\n", "def make_eplaunch_options(idf):\n", " \"\"\"Make options for run, so that it runs like EPLaunch on Windows\"\"\"\n", " idfversion = idf.idfobjects['version'][0].Version_Identifier.split('.')\n", " idfversion.extend([0] * (3 - len(idfversion)))\n", " idfversionstr = '-'.join([str(item) for item in idfversion])\n", " fname = idf.idfname\n", " options = {\n", " # 'ep_version':idfversionstr, # runIDFs needs the version number\n", " # idf.run does not need the above arg\n", " # you can leave it there and it will be fine :-)\n", " 'output_prefix':os.path.basename(fname).split('.')[0],\n", " 'output_suffix':'C',\n", " 'output_directory':os.path.dirname(fname),\n", " 'readvars':True,\n", " 'expandobjects':True\n", " }\n", " return options\n", "\n", "\n", "def main():\n", " iddfile = \"/Applications/EnergyPlus-9-3-0/Energy+.idd\" # change this for your operating system and E+ version\n", " IDF.setiddname(iddfile)\n", " epwfile = \"USA_CA_San.Francisco.Intl.AP.724940_TMY3.epw\"\n", "\n", "\n", "\n", " # File is from the Examples Folder\n", " idfname = \"HVACTemplate-5ZoneBaseboardHeat.idf\"\n", " idf = IDF(idfname, epwfile)\n", " theoptions = make_eplaunch_options(idf)\n", " idf.run(**theoptions)\n", "\n", "\n", "if __name__ == '__main__':\n", " main()" ] }, { "cell_type": "markdown", "metadata": {}, "source": [ "## Running in parallel processes" ] }, { "cell_type": "markdown", "metadata": {}, "source": [ "If you have acomputer with multiple cores, you may want to use all the cores. EnergyPlus allows you to run simulations on multiple cores. \n", "\n", "Here is an example script of how use ``eppy`` to run on multiple cores" ] }, { "cell_type": "code", "execution_count": null, "metadata": {}, "outputs": [], "source": [ "\"\"\"multiprocessing runs\"\"\"\n", "\n", "\n", "import os \n", "from eppy.modeleditor import IDF\n", "from eppy.runner.run_functions import runIDFs\n", "\n", "def make_eplaunch_options(idf):\n", " \"\"\"Make options for run, so that it runs like EPLaunch on Windows\"\"\"\n", " idfversion = idf.idfobjects['version'][0].Version_Identifier.split('.')\n", " idfversion.extend([0] * (3 - len(idfversion)))\n", " idfversionstr = '-'.join([str(item) for item in idfversion])\n", " fname = idf.idfname\n", " options = {\n", " 'ep_version':idfversionstr, # runIDFs needs the version number\n", " 'output_prefix':os.path.basename(fname).split('.')[0],\n", " 'output_suffix':'C',\n", " 'output_directory':os.path.dirname(fname),\n", " 'readvars':True,\n", " 'expandobjects':True\n", " }\n", " return options\n", "\n", "\n", "\n", "\n", "def main():\n", " iddfile = \"/Applications/EnergyPlus-9-3-0/Energy+.idd\" # change this for your operating system\n", " IDF.setiddname(iddfile)\n", " epwfile = \"USA_CA_San.Francisco.Intl.AP.724940_TMY3.epw\"\n", "\n", "\n", " runs = []\n", "\n", " # File is from the Examples Folder\n", " idfname = \"HVACTemplate-5ZoneBaseboardHeat.idf\"\n", " idf = IDF(idfname, epwfile)\n", " theoptions = make_eplaunch_options(idf) \n", " runs.append([idf, theoptions])\n", "\n", " # copy of previous file\n", " idfname = \"HVACTemplate-5ZoneBaseboardHeat1.idf\"\n", " idf = IDF(idfname, epwfile)\n", " theoptions = make_eplaunch_options(idf)\n", " runs.append([idf, theoptions])\n", "\n", " num_CPUs = 2\n", " runIDFs(runs, num_CPUs)\n", "\n", "if __name__ == '__main__':\n", " main()" ] }, { "cell_type": "markdown", "metadata": {}, "source": [ "## Running in parallel processes using Generators" ] }, { "cell_type": "markdown", "metadata": {}, "source": [ "Maybe you want to run a 100 or a 1000 simulations. The code above will not let you do that, since it will try to load 1000 files into memory. \n", "\n", "Now you need to use generators (python's secret sauce. if you don't know this, you need to look into it). \n", "\n", "Here is a code using generators. Now you can simulate a 1000 files" ] }, { "cell_type": "markdown", "metadata": {}, "source": [ "### gmulti.py" ] }, { "cell_type": "code", "execution_count": null, "metadata": {}, "outputs": [], "source": [ "\"\"\"multiprocessing runs\n", "\n", "using generators instead of a list\n", "when you are running a 100 files you have to use generators\"\"\"\n", "\n", "import os \n", "from eppy.modeleditor import IDF\n", "from eppy.runner.run_functions import runIDFs\n", "\n", "def make_eplaunch_options(idf):\n", " \"\"\"Make options for run, so that it runs like EPLaunch on Windows\"\"\"\n", " idfversion = idf.idfobjects['version'][0].Version_Identifier.split('.')\n", " idfversion.extend([0] * (3 - len(idfversion)))\n", " idfversionstr = '-'.join([str(item) for item in idfversion])\n", " fname = idf.idfname\n", " options = {\n", " 'ep_version':idfversionstr, # runIDFs needs the version number\n", " 'output_prefix':os.path.basename(fname).split('.')[0],\n", " 'output_suffix':'C',\n", " 'output_directory':os.path.dirname(fname),\n", " 'readvars':True,\n", " 'expandobjects':True\n", " }\n", " return options\n", "\n", "\n", "\n", "\n", "def main():\n", " iddfile = \"/Applications/EnergyPlus-9-3-0/Energy+.idd\"\n", " IDF.setiddname(iddfile)\n", " epwfile = \"USA_CA_San.Francisco.Intl.AP.724940_TMY3.epw\"\n", "\n", "\n", "\n", " # File is from the Examples Folder\n", " idfname1 = \"HVACTemplate-5ZoneBaseboardHeat.idf\"\n", " # copy of previous file\n", " idfname2 = \"HVACTemplate-5ZoneBaseboardHeat1.idf\"\n", "\n", "\n", " fnames = [idfname1, idfname1]\n", " idfs = (IDF(fname, epwfile) for fname in fnames)\n", " runs = ((idf, make_eplaunch_options(idf) ) for idf in idfs)\n", "\n", "\n", " num_CPUs = 2\n", " runIDFs(runs, num_CPUs)\n", "\n", "if __name__ == '__main__':\n", " main()" ] }, { "cell_type": "markdown", "metadata": {}, "source": [ "## True Multi-processing" ] }, { "cell_type": "markdown", "metadata": {}, "source": [ "What if you want to run your simulations on multiple computers. What if those computers are on other networks (some at home and the other in your office and others in your server room) and some on the cloud.\n", "\n", "There is an experimental repository where you can do this. Keep an eye on this:\n", "\n", "https://github.com/pyenergyplus/zeppy" ] }, { "cell_type": "markdown", "metadata": {}, "source": [ "## Debugging and reporting problems" ] }, { "cell_type": "markdown", "metadata": {}, "source": [ "Debugging issues with IDF.run() used to be difficult, since you needed to go and hunt for the eplusout.err file, and the error message returned was not at all helpful.\n", "\n", "Now the output from EnergyPlus is returned in the error message, as well as the location and contents of eplusout.err.\n", "\n", "For example, this is the error message produced when running an IDF which contains an “HVACTemplate:Thermostat” object without passing expand_objects=True to idf.run():" ] }, { "cell_type": "code", "execution_count": null, "metadata": {}, "outputs": [], "source": [ "E eppy.runner.run_functions.EnergyPlusRunError:\n", "E Program terminated: EnergyPlus Terminated--Error(s) Detected.\n", "E\n", "E Contents of EnergyPlus error file at C:\\Users\\jamiebull1\\git\\eppy\\eppy\\tests\\test_dir\\eplusout.err\n", "E Program Version,EnergyPlus, Version 8.9.0-40101eaafd, YMD=2018.10.14 20:49,\n", "E ** Severe ** Line: 107 You must run the ExpandObjects program for \"HVACTemplate:Thermostat\"\n", "E ** Fatal ** Errors occurred on processing input file. Preceding condition(s) cause termination.\n", "E ...Summary of Errors that led to program termination:\n", "E ..... Reference severe error count=1\n", "E ..... Last severe error=Line: 107 You must run the ExpandObjects program for \"HVACTemplate:Thermostat\"\n", "E ************* Warning: Node connection errors not checked - most system input has not been read (see previous warning).\n", "E ************* Fatal error -- final processing. Program exited before simulations began. See previous error messages.\n", "E ************* EnergyPlus Warmup Error Summary. During Warmup: 0 Warning; 0 Severe Errors.\n", "E ************* EnergyPlus Sizing Error Summary. During Sizing: 0 Warning; 0 Severe Errors.\n", "E ************* EnergyPlus Terminated--Fatal Error Detected. 0 Warning; 1 Severe Errors; Elapsed Time=00hr 00min 0.16sec" ] }, { "cell_type": "markdown", "metadata": {}, "source": [ "When reporting any issues related to IDF.run(), please include the error message as well as the code used to call the function. Also, it may help to include an IDF and EPW which display the problem so that we can try to reproduce it." ] } ], "metadata": { "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.10.8" } }, "nbformat": 4, "nbformat_minor": 1 }