diff --git a/docs/_static/copybutton.js b/docs/_static/copybutton.js new file mode 100644 index 0000000..01ee2ba --- /dev/null +++ b/docs/_static/copybutton.js @@ -0,0 +1,66 @@ +// Copyright 2014 PSF. Licensed under the PYTHON SOFTWARE FOUNDATION LICENSE VERSION 2 +// File originates from the cpython source found in Doc/tools/sphinxext/static/copybutton.js + +$(document).ready(function() { + /* Add a [>>>] button on the top-right corner of code samples to hide + * the >>> and ... prompts and the output and thus make the code + * copyable. */ + var div = $('.highlight-python .highlight,' + + '.highlight-default .highlight,' + + '.highlight-python3 .highlight') + var pre = div.find('pre'); + + // get the styles from the current theme + pre.parent().parent().css('position', 'relative'); + var hide_text = 'Hide the prompts and output'; + var show_text = 'Show the prompts and output'; + var border_width = pre.css('border-top-width'); + var border_style = pre.css('border-top-style'); + var border_color = pre.css('border-top-color'); + var button_styles = { + 'cursor':'pointer', 'position': 'absolute', 'top': '0', 'right': '0', + 'border-color': border_color, 'border-style': border_style, + 'border-width': border_width, 'color': border_color, 'text-size': '75%', + 'font-family': 'monospace', 'padding-left': '0.2em', 'padding-right': '0.2em', + 'border-radius': '0 3px 0 0' + } + + // create and add the button to all the code blocks that contain >>> + div.each(function(index) { + var jthis = $(this); + if (jthis.find('.gp').length > 0) { + var button = $('>>>'); + button.css(button_styles) + button.attr('title', hide_text); + button.data('hidden', 'false'); + jthis.prepend(button); + } + // tracebacks (.gt) contain bare text elements that need to be + // wrapped in a span to work with .nextUntil() (see later) + jthis.find('pre:has(.gt)').contents().filter(function() { + return ((this.nodeType == 3) && (this.data.trim().length > 0)); + }).wrap(''); + }); + + // define the behavior of the button when it's clicked + $('.copybutton').click(function(e){ + e.preventDefault(); + var button = $(this); + if (button.data('hidden') === 'false') { + // hide the code output + button.parent().find('.go, .gp, .gt').hide(); + button.next('pre').find('.gt').nextUntil('.gp, .go').css('visibility', 'hidden'); + button.css('text-decoration', 'line-through'); + button.attr('title', show_text); + button.data('hidden', 'true'); + } else { + // show the code output + button.parent().find('.go, .gp, .gt').show(); + button.next('pre').find('.gt').nextUntil('.gp, .go').css('visibility', 'visible'); + button.css('text-decoration', 'none'); + button.attr('title', hide_text); + button.data('hidden', 'false'); + } + }); +}); + diff --git a/docs/_static/name_equivalence.csv b/docs/_static/name_equivalence.csv new file mode 100644 index 0000000..69c6db2 --- /dev/null +++ b/docs/_static/name_equivalence.csv @@ -0,0 +1,108 @@ +Old names,New names +Building,b +Site:Location,sl +SizingPeriod:DesignDay,spdd +RunPeriod,rp +RunPeriodControl:SpecialDays,rpcs +ScheduleTypeLimits,stl +Schedule:Constant,sc +Schedule:Day:Hourly,sdh +Schedule:Week:Daily,swd +Schedule:Year,sy +Schedule:Compact,sc +Material,m +Material:NoMass,mnm +Material:AirGap,mag +Construction,c +ZoneList,zl +ZoneGroup,zg +Zone,z +BuildingSurface:Detailed,bsd +Shading:Zone:Detailed,szd +InternalMass,im +People,p +Lights,l +ElectricEquipment,ee +GasEquipment,ge +HotWaterEquipment,hwe +SteamEquipment,se +ZoneBaseboard:OutdoorTemperatureControlled,zbot +ZoneInfiltration:DesignFlowRate,zidf +ZoneVentilation:DesignFlowRate,zvdf +ZoneVentilation:WindandStackOpenArea,zvws +Exterior:Lights,el +Exterior:FuelEquipment,efe +DesignSpecification:OutdoorAir,dsoa +ZoneHVAC:Baseboard:Convective:Electric,zhva +ZoneControl:Thermostat,zct +ThermostatSetpoint:SingleHeating,tssh +ThermostatSetpoint:SingleCooling,tssc +ThermostatSetpoint:DualSetpoint,tsds +AirTerminal:SingleDuct:Uncontrolled,atsd +AirTerminal:SingleDuct:VAV:Reheat,atsd +ZoneHVAC:AirDistributionUnit,zhva +ZoneHVAC:UnitHeater,zhva +ZoneHVAC:HighTemperatureRadiant,zhva +ZoneHVAC:EquipmentList,zhva +Fan:VariableVolume,fvv +Fan:OnOff,foo +Fan:ConstantVolume,fcv +Fan:ZoneExhaust,fze +Coil:Cooling:DX:SingleSpeed,ccdx +Coil:Heating:Electric,che +Coil:Cooling:DX:TwoSpeed,ccdx +Coil:Heating:Fuel,chf +CoilSystem:Cooling:DX,cscd +Controller:MechanicalVentilation,cmv +Controller:OutdoorAir,coa +AirLoopHVAC:Unitary:Furnace:HeatCool,alhv +AirLoopHVAC:ControllerList,alhv +AirLoopHVAC:UnitaryHeatCool,alhv +AirLoopHVAC,alhv +AirLoopHVAC:OutdoorAirSystem:EquipmentList,alhv +AirLoopHVAC:OutdoorAirSystem,alhv +OutdoorAir:Mixer,oam +AirLoopHVAC:ZoneSplitter,alhv +AirLoopHVAC:SupplyPath,alhv +AirLoopHVAC:ReturnPlenum,alhv +AirLoopHVAC:ZoneMixer,alhv +AirLoopHVAC:ReturnPath,alhv +Branch,b +BranchList,bl +NodeList,nl +OutdoorAir:Node,oan +AvailabilityManager:Scheduled,ams +AvailabilityManager:NightCycle,amnc +AvailabilityManagerAssignmentList,amal +SetpointManager:Scheduled,sms +SetpointManager:SingleZone:Reheat,smsz +SetpointManager:MixedAir,smma +WaterHeater:Mixed,whm +WaterUse:Connections,wuc +WaterUse:Equipment,wue +Curve:Quadratic,cq +Curve:Cubic,cc +Curve:Biquadratic,cb +Controller:OutdoorAir,coa +AirLoopHVAC:ZoneMixer,alhv +OutdoorAir:Node,oan +WaterHeater:Mixed,whm +EnergyManagementSystem:Sensor,emss +EnergyManagementSystem:Actuator,emsa +EnergyManagementSystem:ProgramCallingManager,emsp +EnergyManagementSystem:Program,emsp +EnergyManagementSystem:InternalVariable,emsi +PlantEquipmentList,pel +PlantEquipmentOperation:HeatingLoad,peoh +PlantEquipmentOperationSchemes,peos +PlantLoop,pl +Output:Table:Monthly,otm +Connector:Splitter,cs +Connector:Mixer,cm +ConnectorList,cl +Pipe:Adiabatic,pa +Pump:ConstantSpeed,pcs +LifeCycleCost:Parameters,lccp +LifeCycleCost:NonrecurringCost,lccn +UtilityCost:Tariff,uct +UtilityCost:Variable,ucv \ No newline at end of file diff --git a/docs/_templates/autosummary.rst b/docs/_templates/autosummary.rst new file mode 100644 index 0000000..58b1c75 --- /dev/null +++ b/docs/_templates/autosummary.rst @@ -0,0 +1,12 @@ +{{ fullname | escape | underline}} + + +.. currentmodule:: {{ module }} + +.. auto{{ objtype }}:: {{ objname }} {% if objtype in ['class'] %} + :members: + :inherited-members: + {% endif %} + + + diff --git a/docs/caching.rst b/docs/caching.rst new file mode 100644 index 0000000..aabb343 --- /dev/null +++ b/docs/caching.rst @@ -0,0 +1,135 @@ +Caching +======= + +Translater features a caching api aimed at accelerating reproducible workflows using EnergyPlus simulations by reducing +unnecessary calls to the EnergyPlus executable or transitioning programs. Concretely, caching an IDF model means that, +for instance, if an older version model (less than 9.2) is ran, translater will transition a copy of that file to +version 9.2 (making a copy beforehand) and run the simulation with the matching EnergyPlus executable. The next time the +:func:`translater.idfclass.run_eplus` or the :func:`translater.idfclass.load_idf` method is called, the cached +(transitioned) file will be readily available and used; This helps to save time especially with reproducible workflows +since transitioning files can take a while to complete. + +As for simulation results, after :func:`translater.idfclass run_eplus` is called, the EnergyPlus outputs (.csv, sqlite, +mtd, .mdd, etc.) are cached in a folder structure than is identified according to the simulation parameters; those +parameters include the content of the IDF file itself (if the file has changed, a new simulation is required), whether +an annual or design day simulation is executed, etc. This means that if run_eplus is called a second time (let us say +after restarting a Jupyter Notebook kernel), the run_eplus will bypass the EnergyPlus executable and retrieve the cached +simulation results instead. This has two advantages, the first one being a quicker workflow and the second one making +sure that whatever `run_eplus` returns fits the parameters used with the executable. Let us use this in a real world +example. First, caching is enabled using the `config` method: + +Enabling caching +---------------- + +Caching is enabled by passing the `use_cache=True` attribute to the :func:`translater.utils.config` method. The +configuration of translater settings are not persistent and must be called whenever a python session is started. It is +recommended to put the `config` method at the beginning of a script or in the first cells of a Jupyter Notebook +(after the import statements). + +.. code-block:: python + + import translater as tr + tr.config(use_cache=True, log_console=True) + +Example +------- + +In a Jupyter Notebook, one would typically do the following: + +.. code-block:: python + + _, idf, results = tr.run_eplus( + eplus_file=tr.utils.get_eplus_dirs("8-9-0") / "ExampleFiles" / "BasicsFiles/AdultEducationCenter.idf", + weather_file=tr.utils.get_eplus_dirs("8-9-0") / "WeatherData" / "USA_IL_Chicago-OHare.Intl.AP.725300_TMY3.epw", + design_day=True, + return_files=True, + annual=False, + return_idf=True, + expandobjects=True, + prep_outputs=True, + ) + +Since the file is a version 8.0 IDF file, translater is going to transition the file to EnergyPlus 9.2 (or any other +version specified with the ep_version parameter) and execute EnergyPlus for the `design_day` only. + +The command above yields a list of output files thanks to the `return_files=True` parameter. These will be located +inside a cache folder specified by the settings.cache_folder variable (this folder path can be changed using the config +method). + +.. code-block:: python + + [None, , + [Path('cache/e8f4fb7e50ecaaf2cf2c9d4e4d159605/d04795a50b4ff172da72fec54c6991e4/d04795a50b4ff172da72fec54c6991e4tbl.csv'), + Path('cache/e8f4fb7e50ecaaf2cf2c9d4e4d159605/d04795a50b4ff172da72fec54c6991e4/d04795a50b4ff172da72fec54c6991e4out.end'), + Path('cache/e8f4fb7e50ecaaf2cf2c9d4e4d159605/d04795a50b4ff172da72fec54c6991e4/AdultEducationCenter.idf'), + Path('cache/e8f4fb7e50ecaaf2cf2c9d4e4d159605/d04795a50b4ff172da72fec54c6991e4/d04795a50b4ff172da72fec54c6991e4out.dxf'), + Path('cache/e8f4fb7e50ecaaf2cf2c9d4e4d159605/d04795a50b4ff172da72fec54c6991e4/d04795a50b4ff172da72fec54c6991e4out.eso'), + Path('cache/e8f4fb7e50ecaaf2cf2c9d4e4d159605/d04795a50b4ff172da72fec54c6991e4/d04795a50b4ff172da72fec54c6991e4out.mtd'), + Path('cache/e8f4fb7e50ecaaf2cf2c9d4e4d159605/d04795a50b4ff172da72fec54c6991e4/d04795a50b4ff172da72fec54c6991e4out.bnd'), + Path('cache/e8f4fb7e50ecaaf2cf2c9d4e4d159605/d04795a50b4ff172da72fec54c6991e4/d04795a50b4ff172da72fec54c6991e4out.sql'), + Path('cache/e8f4fb7e50ecaaf2cf2c9d4e4d159605/d04795a50b4ff172da72fec54c6991e4/d04795a50b4ff172da72fec54c6991e4out.mdd'), + Path('cache/e8f4fb7e50ecaaf2cf2c9d4e4d159605/d04795a50b4ff172da72fec54c6991e4/d04795a50b4ff172da72fec54c6991e4tbl.htm'), + Path('cache/e8f4fb7e50ecaaf2cf2c9d4e4d159605/d04795a50b4ff172da72fec54c6991e4/d04795a50b4ff172da72fec54c6991e4out.shd'), + Path('cache/e8f4fb7e50ecaaf2cf2c9d4e4d159605/d04795a50b4ff172da72fec54c6991e4/d04795a50b4ff172da72fec54c6991e4out.expidf'), + Path('cache/e8f4fb7e50ecaaf2cf2c9d4e4d159605/d04795a50b4ff172da72fec54c6991e4/d04795a50b4ff172da72fec54c6991e4out.err'), + Path('cache/e8f4fb7e50ecaaf2cf2c9d4e4d159605/d04795a50b4ff172da72fec54c6991e4/eplus_run_AdultEducationCenter.idf_2020_02_27.log'), + Path('cache/e8f4fb7e50ecaaf2cf2c9d4e4d159605/d04795a50b4ff172da72fec54c6991e4/d04795a50b4ff172da72fec54c6991e4out.mtr'), + Path('cache/e8f4fb7e50ecaaf2cf2c9d4e4d159605/d04795a50b4ff172da72fec54c6991e4/sqlite.err'), + Path('cache/e8f4fb7e50ecaaf2cf2c9d4e4d159605/d04795a50b4ff172da72fec54c6991e4/d04795a50b4ff172da72fec54c6991e4out.audit'), + Path('cache/e8f4fb7e50ecaaf2cf2c9d4e4d159605/d04795a50b4ff172da72fec54c6991e4/USA_IL_Chicago-OHare.Intl.AP.725300_TMY3.epw'), + Path('cache/e8f4fb7e50ecaaf2cf2c9d4e4d159605/d04795a50b4ff172da72fec54c6991e4/d04795a50b4ff172da72fec54c6991e4out.eio'), + Path('cache/e8f4fb7e50ecaaf2cf2c9d4e4d159605/d04795a50b4ff172da72fec54c6991e4/d04795a50b4ff172da72fec54c6991e4out.rdd')]] + +Now, if the command above is modified with `annual=True` and set `design_day=False`, then run_eplus should return the +annual simulation results (which do not exist yet). + +.. code-block:: python + + _, idf, results = tr.run_eplus( + eplus_file=tr.utils.get_eplus_dirs("8-9-0") / "ExampleFiles" / "BasicsFiles/AdultEducationCenter.idf", + weather_file=tr.utils.get_eplus_dirs("8-9-0") / "WeatherData" / "USA_IL_Chicago-OHare.Intl.AP.725300_TMY3.epw", + design_day=False, + return_files=True, + annual=True, + return_idf=True, + expandobjects=True, + prep_outputs=True, + ) + +Now, since the original IDF file (the version 8.9 one) has not changed, translater is going to look for the transitioned +file that resides in the cache folder and use that one instead of retransitioning the original file a second time. On +the other hand, since the parameters of run_eplus have changed (annual instead of design_day), it is going to execute +EnergyPlus using the annual method and return the annual results (see that the second-level folder id has changed from +d04795a50b4ff172da72fec54c6991e4 to 9efc05f6e6cde990685b8ef61e326d94; *these ids may be different on your computer*): + +.. code-block:: python + + [None, , + [Path('cache/e8f4fb7e50ecaaf2cf2c9d4e4d159605/9efc05f6e6cde990685b8ef61e326d94/AdultEducationCenter.idf'), + Path('cache/e8f4fb7e50ecaaf2cf2c9d4e4d159605/9efc05f6e6cde990685b8ef61e326d94/9efc05f6e6cde990685b8ef61e326d94out.mdd'), + Path('cache/e8f4fb7e50ecaaf2cf2c9d4e4d159605/9efc05f6e6cde990685b8ef61e326d94/9efc05f6e6cde990685b8ef61e326d94out.shd'), + Path('cache/e8f4fb7e50ecaaf2cf2c9d4e4d159605/9efc05f6e6cde990685b8ef61e326d94/9efc05f6e6cde990685b8ef61e326d94tbl.htm'), + Path('cache/e8f4fb7e50ecaaf2cf2c9d4e4d159605/9efc05f6e6cde990685b8ef61e326d94/9efc05f6e6cde990685b8ef61e326d94out.audit'), + Path('cache/e8f4fb7e50ecaaf2cf2c9d4e4d159605/9efc05f6e6cde990685b8ef61e326d94/9efc05f6e6cde990685b8ef61e326d94out.mtr'), + Path('cache/e8f4fb7e50ecaaf2cf2c9d4e4d159605/9efc05f6e6cde990685b8ef61e326d94/9efc05f6e6cde990685b8ef61e326d94out.err'), + Path('cache/e8f4fb7e50ecaaf2cf2c9d4e4d159605/9efc05f6e6cde990685b8ef61e326d94/9efc05f6e6cde990685b8ef61e326d94out.rdd'), + Path('cache/e8f4fb7e50ecaaf2cf2c9d4e4d159605/9efc05f6e6cde990685b8ef61e326d94/9efc05f6e6cde990685b8ef61e326d94out.expidf'), + Path('cache/e8f4fb7e50ecaaf2cf2c9d4e4d159605/9efc05f6e6cde990685b8ef61e326d94/9efc05f6e6cde990685b8ef61e326d94out.eio'), + Path('cache/e8f4fb7e50ecaaf2cf2c9d4e4d159605/9efc05f6e6cde990685b8ef61e326d94/9efc05f6e6cde990685b8ef61e326d94out.dxf'), + Path('cache/e8f4fb7e50ecaaf2cf2c9d4e4d159605/9efc05f6e6cde990685b8ef61e326d94/9efc05f6e6cde990685b8ef61e326d94out.end'), + Path('cache/e8f4fb7e50ecaaf2cf2c9d4e4d159605/9efc05f6e6cde990685b8ef61e326d94/9efc05f6e6cde990685b8ef61e326d94tbl.csv'), + Path('cache/e8f4fb7e50ecaaf2cf2c9d4e4d159605/9efc05f6e6cde990685b8ef61e326d94/9efc05f6e6cde990685b8ef61e326d94out.eso'), + Path('cache/e8f4fb7e50ecaaf2cf2c9d4e4d159605/9efc05f6e6cde990685b8ef61e326d94/9efc05f6e6cde990685b8ef61e326d94out.bnd'), + Path('cache/e8f4fb7e50ecaaf2cf2c9d4e4d159605/9efc05f6e6cde990685b8ef61e326d94/9efc05f6e6cde990685b8ef61e326d94out.mtd'), + Path('cache/e8f4fb7e50ecaaf2cf2c9d4e4d159605/9efc05f6e6cde990685b8ef61e326d94/sqlite.err'), + Path('cache/e8f4fb7e50ecaaf2cf2c9d4e4d159605/9efc05f6e6cde990685b8ef61e326d94/9efc05f6e6cde990685b8ef61e326d94out.sql'), + Path('cache/e8f4fb7e50ecaaf2cf2c9d4e4d159605/9efc05f6e6cde990685b8ef61e326d94/USA_IL_Chicago-OHare.Intl.AP.725300_TMY3.epw')]] + +If we were to rerun the first code block (annual simulation) then it would return the cached results instantly from +the cache: + +.. code-block:: shell + + Successfully parsed cached idf run in 0.00 seconds + +Profiling this simple script shows an 8x speedup. \ No newline at end of file diff --git a/docs/commands.rst b/docs/commands.rst new file mode 100644 index 0000000..98488c1 --- /dev/null +++ b/docs/commands.rst @@ -0,0 +1,17 @@ +================= +Command reference +================= + +Translater provides many commands for managing packages and environments. +The links on this page provide help for each command. +You can also access help from the command line with the +``--help`` flag: + +.. code-block:: bash + + translater --help + +.. include:: commands/convert.rst + + +.. include:: commands/transition.rst diff --git a/docs/commands/convert.rst b/docs/commands/convert.rst new file mode 100644 index 0000000..05b94e0 --- /dev/null +++ b/docs/commands/convert.rst @@ -0,0 +1,5 @@ + + +.. click:: translater:convert + :prog: translater convert + :show-nested: diff --git a/docs/commands/transition.rst b/docs/commands/transition.rst new file mode 100644 index 0000000..cccee77 --- /dev/null +++ b/docs/commands/transition.rst @@ -0,0 +1,5 @@ + + +.. click:: translater:transition + :prog: translater transition + :show-nested: diff --git a/docs/conf.py b/docs/conf.py new file mode 100644 index 0000000..470cdc2 --- /dev/null +++ b/docs/conf.py @@ -0,0 +1,223 @@ +# -*- coding: utf-8 -*- +# +# Configuration file for the Sphinx documentation builder. +# +# This file does only contain a selection of the most common options. For a +# full list see the documentation: +# http://www.sphinx-doc.org/en/stable/config + +# -- Path setup -------------------------------------------------------------- + +# If extensions (or modules to document with autodoc) are in another directory, +# add these directories to sys.path here. If the directory is relative to the +# documentation root, use os.path.abspath to make it absolute, like shown here. +# +import os +import sys +import datetime + +sys.path.insert(0, os.path.abspath(".")) +sys.path.insert(0, os.path.abspath("archetypal")) + +# -- Project information ----------------------------------------------------- + +project = "translater" +copyright = "{}, Samuel Letellier-Duchesne & Louis Leroy".format(datetime.datetime.now().year) +author = "Samuel Letellier-Duchesne & Louis Leroy" + +# The full version, including alpha/beta/rc tags +import translater + +version = release = translater.__version__ + +# -- General configuration --------------------------------------------------- + +# If your documentation needs a minimal Sphinx version, state it here. +# +# needs_sphinx = '1.0' + +# Add any Sphinx extension module names here, as strings. They can be +# extensions coming with Sphinx (named 'sphinx.ext.*') or your custom +# ones. +extensions = [ + "sphinx.ext.autodoc", + "sphinx.ext.autosummary", + "sphinx.ext.doctest", + "sphinx.ext.intersphinx", + "sphinx.ext.todo", + "sphinx.ext.coverage", + "sphinx.ext.mathjax", + "sphinx.ext.ifconfig", + "sphinx.ext.viewcode", + "sphinx.ext.githubpages", + "sphinx.ext.napoleon", + "sphinx_click.ext", + "recommonmark", + "sphinx.ext.autosummary", + "sphinx.ext.autosectionlabel", +] + +# Add any paths that contain templates here, relative to this directory. +templates_path = ["_templates"] + +# The suffix(es) of source filenames. +# You can specify multiple suffix as a list of string: +# + +source_suffix = [".rst", ".md"] + +# The master toctree document. +master_doc = "index" +numfig = True + +autosummary_generate = True +autoclass_content = "both" +autodoc_member_order = "bysource" + +# The language for content autogenerated by Sphinx. Refer to documentation +# for a list of supported languages. +# +# This is also used if you do content translation via gettext catalogs. +# Usually you set "language" from the command line for these cases. +language = None + +# List of patterns, relative to source directory, that match files and +# directories to ignore when looking for source files. +# This pattern also affects html_static_path and html_extra_path. +exclude_patterns = ["_build", "Thumbs.db", ".DS_Store"] + +# -- Options for HTML output ------------------------------------------------- + +# The theme to use for HTML and HTML Help pages. See the documentation for +# a list of builtin themes. +# +html_theme = "sphinx_rtd_theme" + +# Theme options are theme-specific and customize the look and feel of a theme +# further. For a list of options available for each theme, see the +# documentation. +# +# html_theme_options = {} + +# Add any paths that contain custom static files (such as style sheets) here, +# relative to this directory. They are copied after the builtin static files, +# so a file named "default.css" will overwrite the builtin "default.css". +html_static_path = ["_static"] + + +def setup(app): + app.add_stylesheet("theme_overrides.css") + app.add_javascript("copybutton.js") + # Add the 'copybutton' javascript, to hide/show the prompt in code examples + + +# Custom sidebar templates, must be a dictionary that maps document names +# to template names. +# +# The default sidebars (for documents that don't match any pattern) are +# defined by theme itself. Builtin themes are using these templates by +# default: ``['localtoc.html', 'relations.html', 'sourcelink.html', +# 'searchbox.html']``. +# +# html_sidebars = {} + + +# -- Options for HTMLHelp output --------------------------------------------- + +# Output file base name for HTML help builder. +htmlhelp_basename = "archetypaldoc" + +# -- Options for LaTeX output ------------------------------------------------ + +latex_elements = { + # The paper size ('letterpaper' or 'a4paper'). + # + # 'papersize': 'letterpaper', + # The font size ('10pt', '11pt' or '12pt'). + # + # 'pointsize': '10pt', + # Additional stuff for the LaTeX preamble. + # + # 'preamble': '', + # Latex figure (float) alignment + # + # 'figure_align': 'htbp', +} + +# Grouping the document tree into LaTeX files. List of tuples +# (source start file, target name, title, +# author, documentclass [howto, manual, or own class]). +latex_documents = [ + ( + master_doc, + "archetypal.tex", + "archetypal Documentation", + "Samuel Letellier-Duchesne", + "manual", + ) +] + +# -- Options for manual page output ------------------------------------------ + +# One entry per manual page. List of tuples +# (source start file, name, description, authors, manual section). +man_pages = [(master_doc, "archetypal", "archetypal Documentation", [author], 1)] + +# -- Options for Texinfo output ---------------------------------------------- + +# Grouping the document tree into Texinfo files. List of tuples +# (source start file, target name, title, author, +# dir menu entry, description, category) +texinfo_documents = [ + ( + master_doc, + "archetypal", + "archetypal Documentation", + author, + "archetypal", + "One line description of project.", + "Miscellaneous", + ) +] + +# -- Options for Epub output ------------------------------------------------- + +# Bibliographic Dublin Core info. +epub_title = project +epub_author = author +epub_publisher = author +epub_copyright = copyright + +# The unique identifier of the text. This can be a ISBN number +# or the project homepage. +# +# epub_identifier = '' + +# A unique identification for the text. +# +# epub_uid = '' + +# A list of files that should not be packed into the epub file. +epub_exclude_files = ["search.html"] + +# -- Extension configuration ------------------------------------------------- + +# -- Options for intersphinx extension --------------------------------------- + +# Example configuration for intersphinx: refer to the Python standard library. +intersphinx_mapping = { + "python": ("https://docs.python.org/3", None), + "pandas": ("http://pandas.pydata.org/pandas-docs/stable/", None), + "eppy": ("https://eppy.readthedocs.io/en/latest/", None), + "numpy": ("https://docs.scipy.org/doc/numpy/", None), + "networkx": ( + "https://networkx.github.io/documentation/stable/index.html", + "https://networkx.github.io/documentation/stable/objects.inv", + ), + "umidocs": ("https://umidocs.readthedocs.io/en/latest/", None), +} + +# -- Options for _todo extension ---------------------------------------------- + +# If true, `_todo` and `todoList` produce output, else they produce nothing. +todo_include_todos = True diff --git a/docs/converter_bui.rst b/docs/converter_bui.rst new file mode 100644 index 0000000..8d2b00f --- /dev/null +++ b/docs/converter_bui.rst @@ -0,0 +1,181 @@ +Converting IDF to BUI +--------------------- + +.. figure:: images/converter@2x.png + :alt: converter logo + :width: 100% + :align: center + +The necessity of translating IDF files (EnergyPlus_ input files) to BUI files (TRNBuild_ input files) emerged from the +need of modeling building archetypes [#]_. Knowing that a lot of different models from different sources (NECB_ and US-DOE_) +have already been developed under EnergyPlus, and it can be a tedious task to create a multizone building in a model +editor (e.g. TRNBuild), we assume the development of a file translator could be useful for simulationists. + +Objectives +.......... + +The principal objectives of this module was to translate (from IDF to BUI) the geometry of the building, the different schedules used in +the model, and the thermal gains. + +1. Geometry + +The building geometry is kept with all the zoning, the different surfaces (construction and windows) and the thermal +properties of the walls. The thermal properties of windows are not from the IDF, but chosen by the user. The user gives +a U-value, a SHGC value and Tvis value. Then a window is chosen in the Berkeley Lab library (library used in TRNBuild). +For more information, see the methodology_ section please. + +2. Schedules + +All schedules from the IDF file are translated. The translator is able to process all schedule types defined by +EnergyPlus (see the different schedule_ types for more information). Only day and week schedules are written in the output +BUI file + +3. Gains + +Internal thermal gains such as “people”, “lights” and “equipment” are translated from the IDF file to the BUI file. + +4. Conditioning + +Heating and cooling demands are translated from the IDF file to the BUI file such as power per floor area (W/m²) and a temperature setpoint. +The temperature set-point is the set-point at the peak time for heating (or cooling). + +Methodology +........... + +The module is divided in 2 major operations. The first one consist in translating the IDF file from EnergyPlus, to an +IDF file proper to an input file for TRNBuild (T3D file), usually created by the TRNSYS plugin "Trnsys3D_" in SketchUp. +The second operation is the conversion of the IDF file for TRNBuild to a BUI file done with the executable trnsidf.exe +(installed by default in the TRNSYS installation folder: `C:TRNSYS18\\Building\\trnsIDF\\`) + +1. IDF to T3D + +The conversion from the IDF EnergyPlus file to the IDF TRNBuild file (called here T3D file) is the important part of +the module, which uses the Eppy_ python package, allowing, with object classes, to find the IDF objects, modify them if +necessary and re-transcribe them in the T3D file + +2. T3D to BUI + +The operation to convert the T3D file to the BUI file is done by running the trnsidf.exe executable with a command +line. After this operation, the infiltration rate, internal gains and conditioning systems are written in the "REGIME" +section of each zone in the BUI file. + +How to convert an IDF file +.......................... + +Converting an IDF file to a BUI file is done using the terminal with a command line. First, open the Command Prompt on Windows +or the Terminal on Mac. Note that if you used Anaconda to install python on your machine, you will most likely avoid some issues +by using the Anaconda Prompt instead. + +Then simply run the following command: + +.. code-block:: python + + translater convert [OPTIONS] IDF_FILE WEATHER_FILE OUTPUT_FOLDER + +1. ``IDF_FILE`` is the file path of the IDF file to convert. If there are space characters in the path, it should be +enclosed in quotation marks. + +2. ``WEATHER_FILE`` is the file path of the weather file to use to run the EnergyPlus simulation. If there are space characters in the path, it should be +enclosed in quotation marks. + +3. ``OUTPUT_FOLDER`` is the folder where we want the output folders to be written. If there are space characters in +the path, it should enclosed in quotation marks. If output folder path is passed, it must exist. +If nothing is passed, the output folder will be the current working directory. + +Here is an example. Make sure to replace the last two arguments with the idf file path and the output folder path +respectively. + +.. code-block:: python + + translater convert "/Users/Documents/NECB 2011 - Warehouse.idf" "/Users/Documents/CAN_PQ_Montreal.Intl.AP.716270_CWEC.epw" "/Users/Documents/WIP" + +4. `OPTIONS`: There are different options to the `convert` command. The first 3 manage the requested output files. +Users can chose to return a combination of flags + + - if ``-i`` is added, the path to the modified IDF file is returned in the console, and the modified IDF file is + returned in the output folder. If ``-t`` is added, the path to the T3D file (converted from the IDF file) is + returned. If ``-d`` is added, the DCK file (TRNSYS input file) is returned in the output folder, and the path to + this DCK file is returned in the console. + + .. code-block:: python + + translater convert -i -t -d "/Users/Documents/NECB 2011 - Warehouse.idf" "/Users/Documents/CAN_PQ_Montreal.Intl.AP.716270_CWEC.epw" "/Users/Documents/WIP" + + - ``--window_lib`` is the path of the window library (W74-lib.dat). This library must be in the same format as the + Berkeley Lab library used by default in TRNBuild. If nothing is passed, the "W74-lib.dat" file available in the + package "ressources" folder will be used. + + .. code-block:: python + + translater convert --window_lib "/Users/Documents/W74-lib.dat" "/Users/Documents/NECB 2011 - Warehouse.idf" "/Users/Documents/CAN_PQ_Montreal.Intl.AP.716270_CWEC.epw" "/Users/Documents/WIP" + + - ``--trnsidf_exe`` is the path of the trnsidf.exe executable. Usually located in the TRNSYS18 folder under + "Building/trnsIDF/trnsidf.exe". + If nothing is passed, the following path will be used : "C:TRNSYS18\\Building\\trnsIDF\\trnsidf.exe". + + .. code-block:: python + + translater convert --trnsidf_exe "C:TRNSYS18\\Building\\trnsIDF\\trnsidf.exe" "/Users/Documents/NECB 2011 - Warehouse.idf" "/Users/Documents/CAN_PQ_Montreal.Intl.AP.716270_CWEC.epw" "/Users/Documents/WIP" + + - ``--template`` is the path of the .d18 template file (usually in the same directory as the `trnsidf.exe` executable). + If nothing is passed, the following path will be used : "C:TRNSYS18\\Building\\trnsIDF\\NewFileTemplate.d18". + + .. code-block:: python + + translater convert --template "C:TRNSYS18\\Building\\trnsIDF\\NewFileTemplate.d18" "/Users/Documents/NECB 2011 - Warehouse.idf" "/Users/Documents/CAN_PQ_Montreal.Intl.AP.716270_CWEC.epw" "/Users/Documents/WIP" + + - ``--log_clear_names`` if added, do not print log of "clear_names" (equivalence between old and new names) in + the console. + + .. code-block:: python + + translater convert --log_clear_names "/Users/Documents/NECB 2011 - Warehouse.idf" "/Users/Documents/CAN_PQ_Montreal.Intl.AP.716270_CWEC.epw" "/Users/Documents/WIP" + + - ``--window`` specifies the window properties . + If nothing is passed, the following values will be used : 2.2 0.65 0.8 0.05 0.15 8.17 + + .. code-block:: python + + translater convert --window 2.2 0.65 0.8 0.05 0.15 8.17 "/Users/Documents/NECB 2011 - Warehouse.idf" "/Users/Documents/CAN_PQ_Montreal.Intl.AP.716270_CWEC.epw" "/Users/Documents/WIP" + + - ``--ordered`` sorts the idf object names + + .. code-block:: python + + translater convert --ordered "/Users/Documents/NECB 2011 - Warehouse.idf" "/Users/Documents/CAN_PQ_Montreal.Intl.AP.716270_CWEC.epw" "/Users/Documents/WIP" + + - If ``--nonum`` is added, do not renumber surfaces in BUI. If ``--batchjob`` or ``-N`` is added, does BatchJob Modus when running trnsidf.exe. + ``--geofloor`` must be followed by a float between 0 and 1, and generates GEOSURF values for distributing direct solar radiation where `geo_floor` % is directed to the floor, + the rest to walls/windows. If ``--refarea`` is added, updates floor reference area of airnodes. If ``--volume`` is added, updates volume of airnodes. + If ``--capacitance`` is added, updates capacitance of airnodes. All those options are used when running trnsidf.exe (converting T3D file to BUI file). + + .. code-block:: python + + translater convert --nonum -N --geofloor 0.6 --refarea --volume --capacitance "/Users/Documents/NECB 2011 - Warehouse.idf" "/Users/Documents/CAN_PQ_Montreal.Intl.AP.716270_CWEC.epw" "/Users/Documents/WIP" + + - ``-h`` Shows the "help" message + + .. code-block:: python + + translater convert -h + +.. [#] Archetype: building model representing a type of building based on its geometry, thermal properties and its + usage. Usually used to create urban building model by assigning different archetypes to represent at best the + building stock we want to model. + +Equivalence between idf object names when converting a file +........................................................... + +.. csv-table:: Equivalences + :file: ./_static/name_equivalence.csv + :header-rows: 1 + + +.. _EnergyPlus: https://energyplus.net +.. _TRNBuild: http://www.trnsys.com/features/suite-of-tools.php +.. _NECB: https://github.com/canmet-energy/necb_2011_reference_buildings/tree/master/osm_files +.. _US-DOE: https://www.energycodes.gov/development/commercial/prototype_models +.. _schedule: https://bigladdersoftware.com/epx/docs/8-9/input-output-reference/group-schedules.html#group-schedules +.. _Trnsys3D: https://www.trnsys.de/docs/trnsys3d/trnsys3d_uebersicht_en.htm +.. _Eppy: https://pythonhosted.org/eppy/Main_Tutorial.html + diff --git a/docs/converting.rst b/docs/converting.rst new file mode 100644 index 0000000..dd365fc --- /dev/null +++ b/docs/converting.rst @@ -0,0 +1,7 @@ +Converting IDF models +===================== + +EnergyPlus models can be converted to two different other formats using `translater`. TRNSYS users can convert IDF +files to TRNBuild/Type56 files. + +.. include:: converter_bui.rst diff --git a/docs/examples/parallel_process.py b/docs/examples/parallel_process.py new file mode 100644 index 0000000..f00f340 --- /dev/null +++ b/docs/examples/parallel_process.py @@ -0,0 +1,39 @@ +import pandas as pd +from path import Path + +from translater import config, run_eplus, parallel_process + +config(cache_folder="../../tests/.temp/cache", use_cache=True, log_console=True) + + +def main(): + + # setup directories and input files + necb_basedir = Path("../../tests/input_data/trnsys") + files = necb_basedir.glob("Ref*.idf") + epw = Path("../../tests/input_data/CAN_PQ_Montreal.Intl.AP.716270_CWEC.epw") + + idfs = pd.DataFrame({"file": files, "name": [file.basename() for file in files]}) + + # setup the runner. We'll use the DataFrame index as keys (k). + rundict = { + k: dict( + eplus_file=str(file), + prep_outputs=True, + weather_file=str(epw), + expandobjects=True, + verbose="v", + design_day=True, + output_report="sql_file", + ) + for k, file in idfs.file.to_dict().items() + } + + sql_files = parallel_process(rundict, run_eplus, use_kwargs=True, processors=-1) + return sql_files + + +if __name__ == "__main__": + config(use_cache=True, log_console=True) + sql_files = main() + print(sql_files) diff --git a/docs/examples/zoneuncontrolled.idf b/docs/examples/zoneuncontrolled.idf new file mode 100644 index 0000000..430df24 --- /dev/null +++ b/docs/examples/zoneuncontrolled.idf @@ -0,0 +1,515 @@ +!1ZoneUncontrolled.idf +! Basic file description: Basic test for EnergyPlus. Resistive Walls. Regular (no ground contact) floor. +! Regular roof. No Windows. +! +! Highlights: Very basic test to see that EnergyPlus "works". +! +! +! Simulation Location/Run: DENVER_STAPLETON_CO_USA_WMO_724690, 2 design days, 1 run period, +! Run Control executes two design days (see RUN PERIOD object) +! +! Location: Denver, CO +! +! Design Days: DENVER_STAPLETON_CO_USA Annual Heating 99%, MaxDB=-16°C +! DENVER_STAPLETON_CO_USA Annual Cooling (DB=>MWB) 1%, MaxDB=32.6°C MWB=15.5°C +! +! Run Period (Weather File): Full Annual Simulation, DENVER_STAPLETON_CO_USA_WMO_724690 +! +! Run Control: No zone or system sizing, design day run control (no weather file simulation) +! +! Building: Fictional 1 zone building with resistive walls. +! +! The building is oriented due north. +! +! Floor Area: 232.25 m2 +! Number of Stories: 1 +! +! Zone Description Details: +! +! (0,15.24,0) (15.24,15.24,0) +! _____________________________ +! | | +! | | +! | | +! | | +! | | +! | | +! | | +! | | +! | | +! | | +! | | +! | | +! | | +! | | +! | | +! |_____________________________| +! +! (0,0,0) (15.24,0,0) +! +! Internal gains description: NA +! +! Interzone Surfaces: None +! Internal Mass: None +! People: None +! Lights: None +! Equipment: None +! Windows: 0 +! Detached Shading: None +! Daylight: None +! Natural Ventilation: None +! Compact Schedules: NA (Example of non-Compact Schedules) +! Solar Distribution: MinimalShadowing +! +! HVAC: NA +! +! Zonal Equipment: NA +! Central Air Handling Equipment: No +! System Equipment Autosize: No +! Purchased Cooling: No +! Purchased Heating: No +! Purchased Chilled Water: No +! Purchased Hot Water: No +! Coils: None +! Pumps: None +! Boilers: None +! Chillers: None +! Towers: None +! +! Results: +! Standard Reports: Variable Dictionary, Surfaces (dxf-wireframe), Meter File +! Timestep or Hourly Variables: Hourly and Daily +! Time bins Report: None +! HTML Report: None +! Environmental Emissions: None +! Utility Tariffs: None + + Output:PreprocessorMessage, + No Preprocessor Used, !- Preprocessor Name + Information, !- Error Severity + Illustrative Message, !- Message Line 1 + No problems for processing; !- Message Line 2 + + Version, + 3.0; !- Version Identifier + + Timestep, + 4; !- Number of Timesteps per Hour + + Building, + Simple One Zone (Wireframe DXF), !- Name + 0.0000000E+00, !- North Axis {deg} + Suburbs, !- Terrain + .04, !- Loads Convergence Tolerance Value + .004, !- Temperature Convergence Tolerance Value {deltaC} + MinimalShadowing, !- Solar Distribution + 30; !- Maximum Number of Warmup Days + + HeatBalanceAlgorithm, + ConductionTransferFunction; !- Algorithm + + SurfaceConvectionAlgorithm:Inside, + Detailed; !- Algorithm + + SurfaceConvectionAlgorithm:Outside, + Detailed; !- Algorithm + + SimulationControl, + No, !- Do Zone Sizing Calculation + No, !- Do System Sizing Calculation + No, !- Do Plant Sizing Calculation + Yes, !- Run Simulation for Sizing Periods + Yes; !- Run Simulation for Weather File Run Periods + + RunPeriod, + 1, !- Begin Month + 1, !- Begin Day of Month + 12, !- End Month + 31, !- End Day of Month + Tuesday, !- Day of Week for Start Day + Yes, !- Use Weather File Holidays and Special Days + Yes, !- Use Weather File Daylight Saving Period + No, !- Apply Weekend Holiday Rule + Yes, !- Use Weather File Rain Indicators + Yes; !- Use Weather File Snow Indicators + + Site:Location, + DENVER_STAPLETON_CO_USA_WMO_724690, !- Name + 39.77, !- Latitude {deg} + -104.87, !- Longitude {deg} + -7.00, !- Time Zone {hr} + 1611.00; !- Elevation {m} + + ! WMO=724690 Time Zone=NAM (GMT-07:00) Mountain Time (US & Canada) + ! Data Source=ASHRAE 2005 Annual Design Conditions + ! Using Design Conditions from "Climate Design Data 2005 ASHRAE Handbook" + ! DENVER_STAPLETON_CO_USA Extreme Annual Wind Speeds, 1%=10.9m/s, 2.5%=8.8m/s, 5%=7.7m/s + ! DENVER_STAPLETON_CO_USA Extreme Annual Temperatures, Max Drybulb=37.2°C Min Drybulb=-24.6°C + ! DENVER_STAPLETON_CO_USA Annual Heating Design Conditions Wind Speed=2.3m/s Wind Dir=180 + ! Coldest Month=December + ! DENVER_STAPLETON_CO_USA Annual Heating 99%, MaxDB=-16°C + + SizingPeriod:DesignDay, + DENVER_STAPLETON Ann Htg 99% Condns DB, !- Name + -16, !- Maximum Dry-Bulb Temperature {C} + 0.0, !- Daily Temperature Range {deltaC} + -16, !- Humidity Indicating Conditions at Maximum Dry-Bulb + 83411., !- Barometric Pressure {Pa} + 2.3, !- Wind Speed {m/s} + 180, !- Wind Direction {deg} + 0.00, !- Sky Clearness + 0, !- Rain Indicator + 0, !- Snow Indicator + 21, !- Day of Month + 12, !- Month + WinterDesignDay, !- Day Type + 0, !- Daylight Saving Time Indicator + WetBulb; !- Humidity Indicating Type + + ! DENVER_STAPLETON Annual Cooling Design Conditions Wind Speed=4m/s Wind Dir=120 + ! Hottest Month=July + ! DENVER_STAPLETON_CO_USA Annual Cooling (DB=>MWB) 1%, MaxDB=32.6°C MWB=15.5°C + + SizingPeriod:DesignDay, + DENVER_STAPLETON Ann Clg 1% Condns DB=>MWB, !- Name + 32.6, !- Maximum Dry-Bulb Temperature {C} + 15.2, !- Daily Temperature Range {deltaC} + 15.5, !- Humidity Indicating Conditions at Maximum Dry-Bulb + 83411., !- Barometric Pressure {Pa} + 4, !- Wind Speed {m/s} + 120, !- Wind Direction {deg} + 1.00, !- Sky Clearness + 0, !- Rain Indicator + 0, !- Snow Indicator + 21, !- Day of Month + 7, !- Month + SummerDesignDay, !- Day Type + 0, !- Daylight Saving Time Indicator + WetBulb; !- Humidity Indicating Type + + Material:NoMass, + R13LAYER, !- Name + Rough, !- Roughness + 2.290965, !- Thermal Resistance {m2-K/W} + 0.9000000, !- Thermal Absorptance + 0.7500000, !- Solar Absorptance + 0.7500000; !- Visible Absorptance + + Material:NoMass, + R31LAYER, !- Name + Rough, !- Roughness + 5.456, !- Thermal Resistance {m2-K/W} + 0.9000000, !- Thermal Absorptance + 0.7500000, !- Solar Absorptance + 0.7500000; !- Visible Absorptance + + Material, + C5 - 4 IN HW CONCRETE, !- Name + MediumRough, !- Roughness + 0.1014984, !- Thickness {m} + 1.729577, !- Conductivity {W/m-K} + 2242.585, !- Density {kg/m3} + 836.8000, !- Specific Heat {J/kg-K} + 0.9000000, !- Thermal Absorptance + 0.6500000, !- Solar Absorptance + 0.6500000; !- Visible Absorptance + + Construction, + R13WALL, !- Name + R13LAYER; !- Outside Layer + + Construction, + FLOOR, !- Name + C5 - 4 IN HW CONCRETE; !- Outside Layer + + Construction, + ROOF31, !- Name + R31LAYER; !- Outside Layer + + Site:GroundTemperature:BuildingSurface, + 18.89, !- January Ground Temperature {C} + 18.92, !- February Ground Temperature {C} + 19.02, !- March Ground Temperature {C} + 19.12, !- April Ground Temperature {C} + 19.21, !- May Ground Temperature {C} + 19.23, !- June Ground Temperature {C} + 19.07, !- July Ground Temperature {C} + 19.32, !- August Ground Temperature {C} + 19.09, !- September Ground Temperature {C} + 19.21, !- October Ground Temperature {C} + 19.13, !- November Ground Temperature {C} + 18.96; !- December Ground Temperature {C} + + Zone, + ZONE ONE, !- Name + 0.0000000E+00, !- Direction of Relative North {deg} + 0.0000000E+00, !- X Origin {m} + 0.0000000E+00, !- Y Origin {m} + 0.0000000E+00, !- Z Origin {m} + 1, !- Type + 1, !- Multiplier + autocalculate, !- Ceiling Height {m} + autocalculate; !- Volume {m3} + + ScheduleTypeLimits, + Fraction, !- Name + 0.0 : 1.0, !- Range + CONTINUOUS; !- Numeric Type + + GlobalGeometryRules, + UpperLeftCorner, !- Starting Vertex Position + CounterClockWise, !- Vertex Entry Direction + WorldCoordinateSystem; !- Coordinate System + + BuildingSurface:Detailed, + Zn001:Wall001, !- Name + Wall, !- Surface Type + R13WALL, !- Construction Name + ZONE ONE, !- Zone Name + Outdoors, !- Outside Boundary Condition + , !- Outside Boundary Condition Object + SunExposed, !- Sun Exposure + WindExposed, !- Wind Exposure + 0.5000000, !- View Factor to Ground + 4, !- Number of Vertices + 0.0000000E+00,0.0000000E+00,4.572000, !- X,Y,Z ==> Vertex 1 + 0.0000000E+00,0.0000000E+00,0.0000000E+00, !- X,Y,Z ==> Vertex 2 + 15.24000,0.0000000E+00,0.0000000E+00, !- X,Y,Z ==> Vertex 3 + 15.24000,0.0000000E+00,4.572000; !- X,Y,Z ==> Vertex 4 + + BuildingSurface:Detailed, + Zn001:Wall002, !- Name + Wall, !- Surface Type + R13WALL, !- Construction Name + ZONE ONE, !- Zone Name + Outdoors, !- Outside Boundary Condition + , !- Outside Boundary Condition Object + SunExposed, !- Sun Exposure + WindExposed, !- Wind Exposure + 0.5000000, !- View Factor to Ground + 4, !- Number of Vertices + 15.24000,0.0000000E+00,4.572000, !- X,Y,Z ==> Vertex 1 + 15.24000,0.0000000E+00,0.0000000E+00, !- X,Y,Z ==> Vertex 2 + 15.24000,15.24000,0.0000000E+00, !- X,Y,Z ==> Vertex 3 + 15.24000,15.24000,4.572000; !- X,Y,Z ==> Vertex 4 + + BuildingSurface:Detailed, + Zn001:Wall003, !- Name + Wall, !- Surface Type + R13WALL, !- Construction Name + ZONE ONE, !- Zone Name + Outdoors, !- Outside Boundary Condition + , !- Outside Boundary Condition Object + SunExposed, !- Sun Exposure + WindExposed, !- Wind Exposure + 0.5000000, !- View Factor to Ground + 4, !- Number of Vertices + 15.24000,15.24000,4.572000, !- X,Y,Z ==> Vertex 1 + 15.24000,15.24000,0.0000000E+00, !- X,Y,Z ==> Vertex 2 + 0.0000000E+00,15.24000,0.0000000E+00, !- X,Y,Z ==> Vertex 3 + 0.0000000E+00,15.24000,4.572000; !- X,Y,Z ==> Vertex 4 + + BuildingSurface:Detailed, + Zn001:Wall004, !- Name + Wall, !- Surface Type + R13WALL, !- Construction Name + ZONE ONE, !- Zone Name + Outdoors, !- Outside Boundary Condition + , !- Outside Boundary Condition Object + SunExposed, !- Sun Exposure + WindExposed, !- Wind Exposure + 0.5000000, !- View Factor to Ground + 4, !- Number of Vertices + 0.0000000E+00,15.24000,4.572000, !- X,Y,Z ==> Vertex 1 + 0.0000000E+00,15.24000,0.0000000E+00, !- X,Y,Z ==> Vertex 2 + 0.0000000E+00,0.0000000E+00,0.0000000E+00, !- X,Y,Z ==> Vertex 3 + 0.0000000E+00,0.0000000E+00,4.572000; !- X,Y,Z ==> Vertex 4 + + BuildingSurface:Detailed, + Zn001:Flr001, !- Name + Floor, !- Surface Type + FLOOR, !- Construction Name + ZONE ONE, !- Zone Name + Surface, !- Outside Boundary Condition + Zn001:Flr001, !- Outside Boundary Condition Object + NoSun, !- Sun Exposure + NoWind, !- Wind Exposure + 1.000000, !- View Factor to Ground + 4, !- Number of Vertices + 15.24000,0.000000,0.0, !- X,Y,Z ==> Vertex 1 + 0.000000,0.000000,0.0, !- X,Y,Z ==> Vertex 2 + 0.000000,15.24000,0.0, !- X,Y,Z ==> Vertex 3 + 15.24000,15.24000,0.0; !- X,Y,Z ==> Vertex 4 + + BuildingSurface:Detailed, + Zn001:Roof001, !- Name + Roof, !- Surface Type + ROOF31, !- Construction Name + ZONE ONE, !- Zone Name + Outdoors, !- Outside Boundary Condition + , !- Outside Boundary Condition Object + SunExposed, !- Sun Exposure + WindExposed, !- Wind Exposure + 0.0000000E+00, !- View Factor to Ground + 4, !- Number of Vertices + 0.000000,15.24000,4.572, !- X,Y,Z ==> Vertex 1 + 0.000000,0.000000,4.572, !- X,Y,Z ==> Vertex 2 + 15.24000,0.000000,4.572, !- X,Y,Z ==> Vertex 3 + 15.24000,15.24000,4.572; !- X,Y,Z ==> Vertex 4 + + Output:Variable, + *, !- Key Value + outdoor dry bulb, !- Variable Name + hourly; !- Reporting Frequency + + Output:Variable, + *, !- Key Value + Daylight Saving Time Indicator, !- Variable Name + daily; !- Reporting Frequency + + Output:Variable, + *, !- Key Value + DayType Index, !- Variable Name + daily; !- Reporting Frequency + + Output:Variable, + *, !- Key Value + Zone Mean Air Temperature, !- Variable Name + hourly; !- Reporting Frequency + + Output:Variable, + *, !- Key Value + Zone Total Internal Latent Gain, !- Variable Name + hourly; !- Reporting Frequency + + Output:Variable, + *, !- Key Value + Zone Mean Radiant Temperature, !- Variable Name + hourly; !- Reporting Frequency + + Output:Variable, + *, !- Key Value + Zone Air Balance Surface Convection Rate, !- Variable Name + hourly; !- Reporting Frequency + + Output:Variable, + *, !- Key Value + Zone Air Balance Air Energy Storage Rate, !- Variable Name + hourly; !- Reporting Frequency + + Output:Variable, + *, !- Key Value + Surface Inside Temperature, !- Variable Name + daily; !- Reporting Frequency + + Output:Variable, + *, !- Key Value + Surface Outside Temperature, !- Variable Name + daily; !- Reporting Frequency + + Output:Variable, + *, !- Key Value + Surface Int Convection Coeff, !- Variable Name + daily; !- Reporting Frequency + + Output:Variable, + *, !- Key Value + Surface Ext Convection Coeff, !- Variable Name + daily; !- Reporting Frequency + + Output:Reports, + VariableDictionary, !- Type of Report + IDF; !- Report Name + + Output:Reports, + surfaces, !- Type of Report + dxf:wireframe; !- Report Name + + Output:Reports, + construction; !- Type of Report + + Output:Meter:MeterFileOnly, + ExteriorLights:Electricity, !- Name + hourly; !- Reporting Frequency + + Output:Meter:MeterFileOnly, + Carbon Equivalent:Facility, !- Name + hourly; !- Reporting Frequency + + Output:Meter:MeterFileOnly, + EnergyTransfer:Building, !- Name + hourly; !- Reporting Frequency + + Output:Meter:MeterFileOnly, + EnergyTransfer:Facility, !- Name + hourly; !- Reporting Frequency + + OutputControl:Table:Style, + HTML; !- Column Separator + + Output:Table:SummaryReports, + AllSummary; !- Report 1 Name + + Exterior:Lights, + ExtLights, !- Name + AlwaysOn, !- Schedule Name + 5250, !- Design Level {W} + AstronomicalClock, !- Control Option + Grounds Lights; !- End-Use Subcategory + + ScheduleTypeLimits, + On/Off, !- Name + 0:1, !- Range + DISCRETE; !- Numeric Type + + Schedule:Day:Hourly, + On, !- Name + On/Off, !- Schedule Type Limits Name + 1., !- Hour 1 + 1., !- Hour 2 + 1., !- Hour 3 + 1., !- Hour 4 + 1., !- Hour 5 + 1., !- Hour 6 + 1., !- Hour 7 + 1., !- Hour 8 + 1., !- Hour 9 + 1., !- Hour 10 + 1., !- Hour 11 + 1., !- Hour 12 + 1., !- Hour 13 + 1., !- Hour 14 + 1., !- Hour 15 + 1., !- Hour 16 + 1., !- Hour 17 + 1., !- Hour 18 + 1., !- Hour 19 + 1., !- Hour 20 + 1., !- Hour 21 + 1., !- Hour 22 + 1., !- Hour 23 + 1.; !- Hour 24 + + Schedule:Week:Daily, + On Weeks, !- Name + On, !- Sunday Schedule:Day Name + On, !- Monday Schedule:Day Name + On, !- Tuesday Schedule:Day Name + On, !- Wednesday Schedule:Day Name + On, !- Thursday Schedule:Day Name + On, !- Friday Schedule:Day Name + On, !- Saturday Schedule:Day Name + On, !- Holiday Schedule:Day Name + On, !- SummerDesignDay Schedule:Day Name + On, !- WinterDesignDay Schedule:Day Name + On, !- CustomDay1 Schedule:Day Name + On; !- CustomDay2 Schedule:Day Name + + Schedule:Year, + AlwaysOn, !- Name + On/Off, !- Schedule Type Limits Name + On Weeks, !- Schedule:Week Name 1 + 1, !- Start Month 1 + 1, !- Start Day 1 + 12, !- End Month 1 + 31; !- End Day 1 diff --git a/docs/images/20181211121922.png b/docs/images/20181211121922.png new file mode 100644 index 0000000..ac70d17 Binary files /dev/null and b/docs/images/20181211121922.png differ diff --git a/docs/images/converter@2x.png b/docs/images/converter@2x.png new file mode 100644 index 0000000..b80b2cf Binary files /dev/null and b/docs/images/converter@2x.png differ diff --git a/docs/images/extract_transition_EP_files.gif b/docs/images/extract_transition_EP_files.gif new file mode 100644 index 0000000..eb2e764 Binary files /dev/null and b/docs/images/extract_transition_EP_files.gif differ diff --git a/docs/images/model_complexity_reduction@3x.png b/docs/images/model_complexity_reduction@3x.png new file mode 100644 index 0000000..73225a4 Binary files /dev/null and b/docs/images/model_complexity_reduction@3x.png differ diff --git a/docs/images/template/buildingtemplate.png b/docs/images/template/buildingtemplate.png new file mode 100644 index 0000000..4e75077 Binary files /dev/null and b/docs/images/template/buildingtemplate.png differ diff --git a/docs/images/template/constructions-opaque.png b/docs/images/template/constructions-opaque.png new file mode 100644 index 0000000..5e39cb7 Binary files /dev/null and b/docs/images/template/constructions-opaque.png differ diff --git a/docs/images/template/constructions-structure.png b/docs/images/template/constructions-structure.png new file mode 100644 index 0000000..0002a9f Binary files /dev/null and b/docs/images/template/constructions-structure.png differ diff --git a/docs/images/template/constructions-window.png b/docs/images/template/constructions-window.png new file mode 100644 index 0000000..900c942 Binary files /dev/null and b/docs/images/template/constructions-window.png differ diff --git a/docs/images/template/materials-gas.png b/docs/images/template/materials-gas.png new file mode 100644 index 0000000..fecb7be Binary files /dev/null and b/docs/images/template/materials-gas.png differ diff --git a/docs/images/template/materials-glazing.png b/docs/images/template/materials-glazing.png new file mode 100644 index 0000000..ac03d43 Binary files /dev/null and b/docs/images/template/materials-glazing.png differ diff --git a/docs/images/template/materials-opaque.png b/docs/images/template/materials-opaque.png new file mode 100644 index 0000000..e79712d Binary files /dev/null and b/docs/images/template/materials-opaque.png differ diff --git a/docs/images/template/schedules-day.png b/docs/images/template/schedules-day.png new file mode 100644 index 0000000..8369fe8 Binary files /dev/null and b/docs/images/template/schedules-day.png differ diff --git a/docs/images/template/schedules-week.png b/docs/images/template/schedules-week.png new file mode 100644 index 0000000..7cd9d56 Binary files /dev/null and b/docs/images/template/schedules-week.png differ diff --git a/docs/images/template/schedules-year.png b/docs/images/template/schedules-year.png new file mode 100644 index 0000000..e370f67 Binary files /dev/null and b/docs/images/template/schedules-year.png differ diff --git a/docs/images/template/zoneinfo-constructions.png b/docs/images/template/zoneinfo-constructions.png new file mode 100644 index 0000000..b741b8c Binary files /dev/null and b/docs/images/template/zoneinfo-constructions.png differ diff --git a/docs/images/template/zoneinfo-dhw.png b/docs/images/template/zoneinfo-dhw.png new file mode 100644 index 0000000..85ea590 Binary files /dev/null and b/docs/images/template/zoneinfo-dhw.png differ diff --git a/docs/images/template/zoneinfo-loads.png b/docs/images/template/zoneinfo-loads.png new file mode 100644 index 0000000..eb92ce6 Binary files /dev/null and b/docs/images/template/zoneinfo-loads.png differ diff --git a/docs/images/template/zoneinfo-ventilation.png b/docs/images/template/zoneinfo-ventilation.png new file mode 100644 index 0000000..e3b0de0 Binary files /dev/null and b/docs/images/template/zoneinfo-ventilation.png differ diff --git a/docs/images/template/zoneinfo-windows.png b/docs/images/template/zoneinfo-windows.png new file mode 100644 index 0000000..b2f5149 Binary files /dev/null and b/docs/images/template/zoneinfo-windows.png differ diff --git a/docs/images/template/zoneinfo-zone.png b/docs/images/template/zoneinfo-zone.png new file mode 100644 index 0000000..d5b2a42 Binary files /dev/null and b/docs/images/template/zoneinfo-zone.png differ diff --git a/docs/images/template/zoninfo-conditioning.png b/docs/images/template/zoninfo-conditioning.png new file mode 100644 index 0000000..ec35e39 Binary files /dev/null and b/docs/images/template/zoninfo-conditioning.png differ diff --git a/docs/images/unsigned_app_error.png b/docs/images/unsigned_app_error.png new file mode 100644 index 0000000..b27bc55 Binary files /dev/null and b/docs/images/unsigned_app_error.png differ diff --git a/docs/index.rst b/docs/index.rst new file mode 100644 index 0000000..24d5390 --- /dev/null +++ b/docs/index.rst @@ -0,0 +1,61 @@ +.. archetypal documentation master file, created by + sphinx-quickstart on Thu Nov 8 13:38:32 2018. + You can adapt this file completely to your liking, but it should at least + contain the root `toctree` directive. + +archetypal |version| +==================== + +`translater` is a Python package designed with the objective of helping building energy modelers and researchers +maintain collections of building archetypes. `translater` depends on `eppy`_ for EnergyPlus models and makes use of +great packages such as `pandas`_ for data structure processing and `tsam`_ for time series aggregation. + +.. _eppy: https://eppy.readthedocs.io/ +.. _pandas: http://pandas.pydata.org +.. _tsam: https://github.com/FZJ-IEK3-VSA/tsam + +Description +=========== + +As building energy modelers ourselves, we found it was sometimes difficult to use scripting language to retrieve, +modify, simulate and analyze Building Energy Models (BEM). This is why `translater` was created. We built a package +able to an EnergyPlus file to `TRNBuild `_ models (shout out to TRNSYS users!) + +`translater` also features a :ref:`Command Line Interface (CLI)` which means that users can execute +commands in the terminal instead of writing a python script. In addition, we believe reproducible research through +Jupyter Notebooks, for instance, is the way foreword. Therefore, all the modules are discoverable and can be imported +independently. + +.. toctree:: + :maxdepth: 1 + :caption: Getting Started + + Installation + For MacOS/Linux users + Caching + + +.. toctree:: + :maxdepth: 2 + :caption: User Guide + + Converting IDF models + Reading and Running IDF files + Parallel Processing + Managing Schedules + Troubleshooting + +.. toctree:: + :maxdepth: 1 + :caption: Reference Guide + + commands + package_modules + + +Indices and tables +================== + +* :ref:`genindex` +* :ref:`modindex` +* :ref:`search` diff --git a/docs/install.rst b/docs/install.rst new file mode 100644 index 0000000..a342fb3 --- /dev/null +++ b/docs/install.rst @@ -0,0 +1,185 @@ +Installation +============ + + +Requirements +------------ + +.. warning:: + + Prior to installing this package, you must have EnergyPlus version 9.2.0 (download_ here at the bottom of + the page). + +`EnergyPlus`_ should be installed in it's default location. On Windows that would be in `C:\\EnergyPlusV9-2-0` and on +MacOS that would be in `/Applications/EnergyPlus-9-2-0`. + +It is also recommended that the older transition programs be installed as well. These programs allow older IDF files +(versions 7.2 and below) to be upgraded to version 9-2-0. Since these, don't come by default with EnergyPlus, they +need to be installed by hand. A script has been created for windows (see `Installation from scratch`_). For +macOS, refer to the `supplementary conversion programs`_. + +Installation from scratch +------------------------- + +This first step should be helpful for users that are not familiar with python environments. If you already have python +installed and think that you can manage the installation a new package using `pip`, then you can skip to the next +section. + +Download & Install MiniConda (or the full Anaconda) +................................................... + +found at the following URL: https://docs.conda.io/en/latest/miniconda.html + +Launch the executable and select the following settings: + +- InstallationType=JustMe +- AddToPath=Yes (there might be a warning, but ignore it) +- RegisterPython=Yes +- Installation path=%UserProfile%\Miniconda3 + +Check if everything is ok by running `conda list` in the command line (make sure to open a new command line window just +in case). You should see something like this: + +.. code-block:: doscon + + C:\Users\translater>conda list + # packages in environment at C:\ProgramData\Miniconda3: + # + # Name Version Build Channel + asn1crypto 1.2.0 py37_0 + ca-certificates 2019.10.16 0 + certifi 2019.9.11 py37_0 + ... + win_inet_pton 1.1.0 py37_0 + wincertstore 0.2 py37_0 + yaml 0.1.7 hc54c509_2 + +Install EnergyPlus & Conversion Programs +........................................ + +EnergyPlus is a prerequisite of translater. It must be installed beforehand. Moreover, translater contains routines that +may download IDF components that are coded in earlier versions of EnergyPlus (e.g., 7.1). For this reason, users should +also download the `supplementary conversion programs`_, and install the content in the EnergyPlus installation folder: + +- On Windows: `C:\\EnergyPlusV9-2-0\\PreProcess\\IDFVersionUpdater` (For Windows, see automated procedure below). +- On MacOS: `/Applications/EnergyPlus-9-2-0/PreProcess/IDFVersionUpdater` + +On Windows, this installation procedure can be automated with the following `script`_ which will download and installEnergyPlus as +well as the supplementary conversion programs. + +To use the script, follow the next steps. First git must be installed beforehand with default installation parameters. +See https://git-scm.com/downloads to download git. Then the following commands will change the current directory to the +user's Downloads folder. Then the script will be downloaded using the `git clone` command. Finally the script will be executed. +Copy the whole code block below in Command Prompt and Hit :guilabel:`&Enter:⏎`. + +.. code-block:: doscon + + cd %USERPROFILE%\Downloads + git clone https://gist.github.com/aef233396167e0f961df3d62a193573e.git + cd aef233396167e0f961df3d62a193573e + install_eplus_script.cmd + +To install *translater*, follow the steps detailed below in `Installing using pip`_ + +Installing using ``pip`` +------------------------ + +If you have Python 3 already installed on your machine and don't bother to create a virtual environment (which is +highly recommended), then simply install using the following command in the terminal: + +.. code-block:: shell + + pip install translater + +.. hint:: + + If you encounter an issue during the installation of translater using ``pip``, you can try + out `Installing using conda (Anaconda)`_ instead. + + +Installation within a Virtual Environment +----------------------------------------- + +It is highly recommended to use/install *translater* on a fresh python virtual environment. If you have any trouble +with the installation above, try installing translater in a new, clean `virtual environment`_ using venv or conda. Note +that this pacakge was tested with python 3.6: + +.. code-block:: shell + + python3 -m venv translater + source translater/bin/activate + +Activating the virtual environment will change your shell’s prompt to show what virtual environment you’re using, and +modify the environment so that running python will get you that particular version and installation of Python. For +example: + +.. code-block:: shell + + $ source translater/bin/activate + (translater) $ python + Python 3.5.1 (default, May 6 2016, 10:59:36) + ... + >>> import sys + >>> sys.path + ['', '/usr/local/lib/python35.zip', ..., + '~/envs/translater/lib/python3.5/site-packages'] + >>> + +Then you can install translater in this freshly created environment: + +.. code-block:: shell + + pip install translater + +To use the new environment inside a `jupyter notebook`_, we recommend using the steps described by `Angelo +Basile`_: + +.. code-block:: shell + + source translater/bin/activate + pip install ipykernel + ipython kernel install --user --name=translater + +Next time you `start a jupyter notebook`_, you will have the option to choose the *kernel* corresponding to your +project, *translater* in this case. + +.. figure:: images/20181211121922.png + :alt: choosing the correct kernel in a jupyter notebook + :width: 100% + :align: center + + choosing the correct kernel in a jupyter notebook. + In the *kernel* menu, select *Change Kernel* + and select the appropriate virtual env created earlier (*translater* in this case). + + +Installing using ``conda`` (Anaconda) +------------------------------------- + +.. hint:: + + If you encounter package dependency errors while installing `translater` using pip, you can use conda instead. + +Installing with conda is similar to pip. The following workflow creates a new virtual environment (named translater) +which contains the required dependencies. It then installs the package using pip. You will need to download the +`environment.yml`_ file from the github repository. For the following code to work, first change the working +directory to the location of the downloaded `environment.yml` file. Here we use the `conda env update` method which +will work well to create a new environment using a specific dependency file in one line of code: + +.. code-block:: shell + + conda update -n base conda + conda env update -n translater -f environment.yml + conda activate translater + pip install translater + +.. _start a jupyter notebook: https://jupyter.readthedocs.io/en/latest/running.html#starting-the-notebook-server +.. _jupyter notebook: https://jupyter-notebook.readthedocs.io/en/stable/# +.. _Angelo Basile: https://anbasile.github.io/programming/2017/06/25/jupyter-venv/ +.. _virtual environment: https://docs.conda.io/projects/conda/en/latest/user-guide/tasks/manage-environments.html#managing-environments +.. _EnergyPlus: https://energyplus.net +.. _umi: https://umidocs.readthedocs.io/en/latest/ +.. _download: https://github.com/NREL/EnergyPlus/releases/tag/v9.2.0 +.. _supplementary conversion programs: http://energyplus.helpserve.com/Knowledgebase/List/Index/46/converting-older-version-files +.. _script: https://gist.github.com/samuelduchesne/aef233396167e0f961df3d62a193573e +.. _environment.yml: https://github.com/louisleroy5/translater/blob/master/environment.yml \ No newline at end of file diff --git a/docs/package_modules.rst b/docs/package_modules.rst new file mode 100644 index 0000000..5418280 --- /dev/null +++ b/docs/package_modules.rst @@ -0,0 +1,157 @@ +Modules +======= + +IDF Class +--------- + +.. currentmodule:: archetypal.idfclass + +.. autosummary:: + :template: autosummary.rst + :nosignatures: + :toctree: reference/ + + load_idf + IDF + run_eplus + OutputPrep + +.. _templates_label: + + +Schedule Module +--------------- + +.. currentmodule:: translater.schedule + +.. autosummary:: + :template: autosummary.rst + :nosignatures: + :toctree: reference/ + + Schedule + + +EnergyDataFrame +--------------- + +.. currentmodule:: translater.energydataframe + +.. autosummary:: + :template: autosummary.rst + :nosignatures: + :toctree: reference/ + + EnergyDataFrame.set_unit + EnergyDataFrame.discretize_tsam + plot_energydataframe_map + + +EnergySeries +------------ + +.. currentmodule:: translater.energyseries + +.. autosummary:: + :template: autosummary.rst + :nosignatures: + :toctree: reference/ + + EnergySeries.from_sqlite + EnergySeries.unit_conversion + EnergySeries.concurrent_sort + EnergySeries.normalize + EnergySeries.ldc_source + EnergySeries.source_side + EnergySeries.discretize_tsam + EnergySeries.discretize + EnergySeries.plot3d + EnergySeries.plot2d + EnergySeries.p_max + EnergySeries.p_max + EnergySeries.monthly + EnergySeries.capacity_factor + EnergySeries.bin_edges + EnergySeries.time_at_min + EnergySeries.bin_scaling_factors + EnergySeries.duration_scaling_factor + EnergySeries.ldc + EnergySeries.nseries + save_and_show + plot_energyseries + plot_energyseries_map + + +Report Data +----------- + +.. currentmodule:: translater.reportdata + +.. autosummary:: + :template: autosummary.rst + :nosignatures: + :toctree: reference/ + + ReportData.from_sql_dict + ReportData.from_sqlite + ReportData.heating_load + ReportData.filter_report_data + ReportData.sorted_values + + + +IDF to BUI module +----------------- + +.. currentmodule:: translater.trnsys + +.. autosummary:: + :template: autosummary.rst + :nosignatures: + :toctree: reference/ + + convert_idf_to_trnbuild + get_idf_objects + clear_name_idf_objects + zone_origin + closest_coords + parse_window_lib + choose_window + trnbuild_idf + + + +Utils +----- + +.. currentmodule:: translater.utils + +.. autosummary:: + :template: autosummary.rst + :nosignatures: + :toctree: reference/ + + config + validate_trnsys_folder + log + load_umi_template_objects + umi_template_object_to_dataframe + get_list_of_common_umi_objects + newrange + date_transform + weighted_mean + top + copy_file + piecewise + rmse + checkStr + write_lines + load_umi_template + check_unique_name + angle + float_round + timeit + lcm + recursive_len + rotate + parallel_process \ No newline at end of file diff --git a/docs/reading_idf.rst b/docs/reading_idf.rst new file mode 100644 index 0000000..2ade5c9 --- /dev/null +++ b/docs/reading_idf.rst @@ -0,0 +1,85 @@ +Reading and running IDF files +============================= + +`translater` is packed up with some built-in workflows to read, edit and run EnergyPlus files. + +Reading +------- + +To read an IDF file, simply call :meth:`~translater.idfclass.load_idf` with the path name. For example: + +.. code-block:: python + + >>> from translater import get_eplus_dirs, load_idf + >>> eplus_dir = get_eplus_dirs("9-2-0") # Getting EnergyPlus install path + >>> eplus_file = eplus_dir / "ExampleFiles" / "BasicsFiles" / "AdultEducationCenter.idf" # Model path + >>> idf = load_idf(eplus_file) # IDF load + +You can optionally pass the weather file path as well: + +.. code-block:: python + + >>> weather = eplus_dir / "WeatherData" / "USA_IL_Chicago-OHare.Intl.AP.725300_TMY3.epw" # Weather file path + >>> idf = load_idf(eplus_file, weather_file=weather) # IDF load + +Editing +------- + +Editing IDF files is based on the :ref:`eppy` package. The :class:`~translater.idfclass.IDF` object returned by +:meth:`~translater.idfclass.load_idf` exposes the EnergyPlus objects that make up the IDF file. These objects can be +edited and new objects can be created. See the `eppy documentation `_ for +more information on how to edit IDF files. + +.. hint:: Pre-sets + + EnergyPlus outputs can be quickly defined using the :class:`translater.idfclass.OutputPrep` class. This class + and its methods handle adding predefined or custom outputs to an IDF object. For example, the + idf object created above can be modified by adding a basic set of outputs: + + .. code-block:: python + + >>> from translater import OutputPrep + >>> OutputPrep(idf=idf, save=True).add_basics() + + See :class:`~translater.idfclass.OutputPrep` for more details on all possible methods. + + +Running +------- + +Running an EnerguPlus file can be done in two ways. The first way is to call the :meth:`translater.idfclass.run_eplus` +function with the path of the IDF file and the path of the weather file. The second method is to call the +:meth:`~translater.idfclass.IDF.run_eplus` method on an :class:`~translater.idfclass.IDF` object that has been +previously read. In both cases, users can also specify run options as well as output options. For example, instead of +creating an OutputPrep object, one can specify custom outputs in the +:py:attr:`translater.idfclass.run_eplus.prep_outputs` attribute. These outputs will be appended to the IDF file before +the simulation is run. See :meth:`~translater.idfclass.run_eplus` for other parameters to pass to `run_eplus`. + +For the same IDF object above, the following: + +.. code-block:: python + + >>> idf.run_eplus(weather_file=weather) + +is equivalent to: + +.. code-block:: python + + >>> from translater import run_eplus + >>> run_eplus(eplus_file, weather) + +.. hint:: Caching system. + + When running EnergyPlus simulations, a caching system can be activated to reduce the number of calls to the + EnergyPlus executable. This can be helpful when `translater` is called many times. This caching system will save + simulation results in a folder identified by a unique identifier. This identifier is based on the content of the IDF + file, as well as the various :meth:`~translater.idfclass.run_eplus` options. If caching is activated, then + subsequent calls to the :meth:`~translater.idfclass.run_eplus` method will return the cached results. + + The caching system is activated by calling the :meth:`translater.utils.config` method, which can also be used to + set a series of package-wide options. ``config`` would typically be put at the top of a python script: + + .. code-block:: python + + >>> from translater import config + >>> config(use_cache=True) \ No newline at end of file diff --git a/docs/troubleshooting.rst b/docs/troubleshooting.rst new file mode 100644 index 0000000..8aae56b --- /dev/null +++ b/docs/troubleshooting.rst @@ -0,0 +1,38 @@ +Troubleshooting +=============== + +MacOs Catalina Compatibility +---------------------------- + +With the release of MacOs Catalina, Apple requires apps to be signed and/or notarized. This helps users make sure they +open apps from trusted developers. It appears that the transition files that are needed to upgrade older IDF files to +the latest version of EnergyPlus are not signed. Thus, users using translater on the MacOs platform might encounter an +error of this type: "Transition cannot be opened because the developer cannot be verified". (see `Missing transition +programs`_ for more details on downloading and installing older transition programs). + +.. image:: images/unsigned_app_error.png + :scale: 50 % + :align: center + +It seems that clicking "cancel" will still work, although the prompt will appear for all older transition files +repetitively. An issue has been submitted `here `_ on the EnergyPlus +github repository. Hopefully, the developers of EnergyPlus will be able to address this issue soon. + +Missing transition programs +--------------------------- + +For older EnergyPlus file versions (< 7-1-0), the necessary transition files are not included with the EnergyPlus +installer. Users must download and install missing transition programs manually. This can be acheived in two simple +steps: + +1. Navigate to the EnergyPlus Knowledgebase_ and download the appropriate transition programs depending on the platform + you are using (MacOs, Linux or Windows). These programs come in the form of a zipped folder. +2. Extract all the files from the zipped folder to your EnergyPlus installation folder at + ./PreProcess/IDFVersionUpdater/. For example, on MacOs with EnergyPlus version 8-9-0, this path is + ``/Applications/EnergyPlus-8-9-0/PreProcess/IDFVersionUpdater/``. + +.. image:: images/extract_transition_EP_files.gif + :scale: 150 % + :align: center + +.. _Knowledgebase: http://energyplus.helpserve.com/Knowledgebase/List/Index/46/converting-older-version-files \ No newline at end of file diff --git a/docs/tutorials/parallel_process.rst b/docs/tutorials/parallel_process.rst new file mode 100644 index 0000000..4b74c6e --- /dev/null +++ b/docs/tutorials/parallel_process.rst @@ -0,0 +1,86 @@ +Running multiple files +====================== + +Running multiple IDF files is easily achieved by using the :meth:`~translater.utils.parallel_process` method. + +.. hint:: + + The :meth:`~translater.utils.parallel_process` method works with any method. You can use it to parallelize + other functions in your script. + +To create a parallel run, first import the usual pacakge methods and configure `translater` to use caching and to +show logs in the console. + +.. code-block:: python + + >>> from path import Path + >>> from translater import load_idf, config, run_eplus, settings, parallel_process + >>> import pandas as pd + >>> config(use_cache=True, log_console=True) + +Then, use + +.. code-block:: python + + >>> from translater import load_idf, config, run_eplus, settings + >>> from translater import parallel_process + >>> import pandas as pd + >>> config(use_cache=True, log_console=True) + +Then, use `glob` to make a list of NECB idf files in the input_data directory (relative to this package). The weather +file path is also created: + +.. code-block:: python + + >>> necb_basedir = Path("tests/input_data/necb") + >>> files = necb_basedir.glob("*.idf") + >>> epw = Path("data/CAN_PQ_Montreal.Intl.AP.716270_CWEC.epw") + +For good measure, load the files in a DataFrame, which we will use to create the rundict in the next step. + +.. code-block:: python + + >>> idfs = pd.DataFrame({"file": files, "name": [file.basename() for file in files]}) + +The rundict, is the list of tasks we wish to do in parallel. This dictionary is passed to :meth:`~translater.idfclass +.parallel_process`. Here, we want to execute :meth:`~translater.idfclass.run_eplus` with the following parameters: + +.. code-block:: python + + >>> rundict = { + k: dict( + eplus_file=str(file), + prep_outputs=True, + weather_file=str(epw), + expandobjects=True, + verbose="v", + design_day=True, + output_report="sql_file", + ) + for k, file in idfs.file.to_dict().items() + } + +Finally, execute :meth:`~translater.utils.parallel_process`. The resulting sql_file paths, which we defined as the +type of output_report attribute for :meth:`~translater.idfclass.run_eplus` is returned as a dictionary with the same +keys as the index of the DataFrame. + +.. code-block:: python + + >>> sql_files = parallel_process(rundict, run_eplus, use_kwargs=True, processors=-1) + >>> sql_files + {0: Path('cache/06e92da0247c71762d64aed4bcf3cdb2/output_data/06e92da0247c71762d64aed4bcf3cdb2out.sql'), + 1: Path('cache/aee8caf562b3519942ef88f533800dd0/output_data/aee8caf562b3519942ef88f533800dd0out.sql'), + 2: Path('cache/9d14a6aa6fda03a77ed5c5c48d28a73b/output_data/9d14a6aa6fda03a77ed5c5c48d28a73bout.sql'), + 3: Path('cache/5ddfa8827d2a577aabb02d60195bf53a/output_data/5ddfa8827d2a577aabb02d60195bf53aout.sql'), + 4: Path('cache/225c3428099e2abcc4051750db12731b/output_data/225c3428099e2abcc4051750db12731bout.sql'), + 5: Path('cache/0991d42c5af387833b68adffc0d7b523/output_data/0991d42c5af387833b68adffc0d7b523out.sql'), + 6: Path('cache/e10a4bf8bae93b0b0d2ad2638c807b61/output_data/e10a4bf8bae93b0b0d2ad2638c807b61out.sql'), + 7: Path('cache/86439047af9e8ff4650d6bab460d5e70/output_data/86439047af9e8ff4650d6bab460d5e70out.sql'), + 8: Path('cache/68da0886afa316f75bc63d7e576d0228/output_data/68da0886afa316f75bc63d7e576d0228out.sql'), + 9: Path('cache/68a8be47fe4573a61d388a0101798958/output_data/68a8be47fe4573a61d388a0101798958out.sql'), + 10: Path('cache/f6f8abae5272bf607a9f53d18c10a50d/output_data/f6f8abae5272bf607a9f53d18c10a50dout.sql'), + 11: Path('cache/4cf8589df098bb0c3f2b9f8589ec6ed6/output_data/4cf8589df098bb0c3f2b9f8589ec6ed6out.sql'), + 12: Path('cache/5dd643faf859ed1aed5adffcecd0d47c/output_data/5dd643faf859ed1aed5adffcecd0d47cout.sql'), + 13: Path('cache/e7cf6ae2be8917a409c9a1acad3bc349/output_data/e7cf6ae2be8917a409c9a1acad3bc349out.sql'), + 14: Path('cache/3f122e04f7d8d19195cb8818a0be390f/output_data/3f122e04f7d8d19195cb8818a0be390fout.sql'), + 15: Path('cache/d263b5b5d3bc56f2fb3795c61ac89cfe/output_data/d263b5b5d3bc56f2fb3795c61ac89cfeout.sql')} \ No newline at end of file diff --git a/docs/tutorials/schedules.rst b/docs/tutorials/schedules.rst new file mode 100644 index 0000000..ce76393 --- /dev/null +++ b/docs/tutorials/schedules.rst @@ -0,0 +1,42 @@ +Schedules +========= + +`translater` can parse EnergyPlus schedules. In EnergyPlus, there are many ways to define schedules in an IDF file. The +Schedule module defines a class that handles parsing, plotting converting schedules. + +Reading Schedules +----------------- + +*translater* can read almost any schedules defined in an IDF file using a few commands. First, + +.. code-block:: python + + >>> import translater as tr + >>> idf = tr.load_idf() + >>> this_schedule = Schedule(Name='name', idf=idf) + + +Converting Schedules +-------------------- + +Some tools typically rely on a group of 3 schedules; defined as a Yearly, Weekly, Daily schedule object. This is the +case for the :ref:`IDF to TRNSYS ` converter. The Schedule module of *translater* can handle this conversion. + +The `year-week-day` representation for any schedule object is invoked with +the :py:meth:`~translater.schedule.Schedule.to_year_week_day` method: + +.. code-block:: python + + >>> this_schedule.to_year_week_day() + +Plotting Schedules +------------------ + +Schedules can be parsed as :class:`pandas.Series` objects (call the `series` property on a Schedule object) which then +exposes useful methods from the pandas package. For convenience, a wrapper for the plotting method is built-in the +Schedule class. To plot the full annual schedule (or a specific range), simply call the :meth:`translater.schedule.Schedule.plot` +method. For example, + +.. code-block:: python + + >>> this_schedule.plot(slice=("2018/01/02", "2018/01/03"), drawstyle="steps-post") \ No newline at end of file diff --git a/docs/unix_users.rst b/docs/unix_users.rst new file mode 100644 index 0000000..79d2f04 --- /dev/null +++ b/docs/unix_users.rst @@ -0,0 +1,60 @@ +For MacOS/Linux users +===================== + +MacOS or Linux users must install Wine_ before running translater. This software +will allow MacOS/Linux users to run Windows application (e.g. `trnsidf.exe`). + +Wine installation +----------------- + +1. In the Terminal, you have to install Homebrew with the following command line: + +.. code-block:: python + + ruby -e "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/master/install)" + +You will have to confirm this action by pressing enter. The Terminal might ask your password, +then you have to enter the Admin password (followed by :guilabel:`&Enter: ⏎`). The installation of Homebrew +should take few seconds or minutes. + +2. After installing Homebrew, you have to run 'brew doctor' (the Terminal might ask you) +with the following command line: + +.. code-block:: python + + brew doctor + +This action will make Homebrew inspected your system to make sure the installation is correctly set up + +3. Then you will need to install Xquartz using Homebrew by typing the following command line: + +.. code-block:: python + + brew cask install xquartz + +4. Finally you can install Wine by copying the following command line: + +.. code-block:: python + + brew install wine + +For more information about Wine installation, you can visit the following website: https://www.davidbaumgold.com/tutorials/wine-mac/ + +Using WINE with ``translater convert`` command +---------------------------------------------- + +The IDF to BUI converter uses an executable installed with TRNSYS (which is Windows only). Users that have bought +TRNSYS can copy the trnsidf.exe executable to their UNIX machine (MacOs or Linux) and invoke the `translater convert` +command with the :option:`--trnsidf_exe` option. + +Example: + +.. code-block:: python + + translater convert --trnsidf-exe "" "" + +You can find the executable trnsidf.exe in the TRNSYS default installation folder: +`C:\\TRNSYS18\\Building\\trnsIDF` + + +.. _Wine: https://www.winehq.org/ \ No newline at end of file