Add doc

2024-12-22 23:55:56 -05:00 · 2020-06-23 12:12:49 -04:00 · 2020-06-23 12:12:49 -04:00 · 3cdfa2fca7
commit 3cdfa2fca7
parent ed41a6b6e8
42 changed files with 2027 additions and 0 deletions
--- a/docs/_static/copybutton.js
+++ 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 = $('<span class="copybutton">&gt;&gt;&gt;</span>');
+            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('<span>');
+    });
+
+    // 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');
+        }
+    });
+});
+
--- a/docs/_static/name_equivalence.csv
+++ 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
--- a/docs/_templates/autosummary.rst
+++ 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 %}
+
+
+
--- a/docs/caching.rst
+++ 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, <translater.idfclass.IDF at 0x10fb9f4a8>,
+    [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, <translater.idfclass.IDF at 0x1a2c7e0128>,
+    [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.
--- a/docs/commands.rst
+++ 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
--- a/docs/commands/convert.rst
+++ b/docs/commands/convert.rst
@ -0,0 +1,5 @@
+
+
+.. click:: translater:convert
+   :prog: translater convert
+   :show-nested:
--- a/docs/commands/transition.rst
+++ b/docs/commands/transition.rst
@ -0,0 +1,5 @@
+
+
+.. click:: translater:transition
+   :prog: translater transition
+   :show-nested:
--- a/docs/conf.py
+++ 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
--- a/docs/converter_bui.rst
+++ 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 <u_value (W/m²-K)> <shgc (-)> <t_vis (-)> <tolerance (-)> <fframe (-)> <uframe (kJ/m²-K-h)>.
+      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
+
--- a/docs/converting.rst
+++ 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
--- a/docs/examples/parallel_process.py
+++ 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)
--- a/docs/examples/zoneuncontrolled.idf
+++ 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
--- a/docs/images/20181211121922.png
+++ b/docs/images/20181211121922.png
--- a/docs/images/converter@2x.png
+++ b/docs/images/converter@2x.png
--- a/docs/images/extract_transition_EP_files.gif
+++ b/docs/images/extract_transition_EP_files.gif
--- a/docs/images/model_complexity_reduction@3x.png
+++ b/docs/images/model_complexity_reduction@3x.png
--- a/docs/images/template/buildingtemplate.png
+++ b/docs/images/template/buildingtemplate.png
--- a/docs/images/template/constructions-opaque.png
+++ b/docs/images/template/constructions-opaque.png
--- a/docs/images/template/constructions-structure.png
+++ b/docs/images/template/constructions-structure.png
--- a/docs/images/template/constructions-window.png
+++ b/docs/images/template/constructions-window.png
--- a/docs/images/template/materials-gas.png
+++ b/docs/images/template/materials-gas.png
--- a/docs/images/template/materials-glazing.png
+++ b/docs/images/template/materials-glazing.png
--- a/docs/images/template/materials-opaque.png
+++ b/docs/images/template/materials-opaque.png
--- a/docs/images/template/schedules-day.png
+++ b/docs/images/template/schedules-day.png
--- a/docs/images/template/schedules-week.png
+++ b/docs/images/template/schedules-week.png
--- a/docs/images/template/schedules-year.png
+++ b/docs/images/template/schedules-year.png
--- a/docs/images/template/zoneinfo-constructions.png
+++ b/docs/images/template/zoneinfo-constructions.png
--- a/docs/images/template/zoneinfo-dhw.png
+++ b/docs/images/template/zoneinfo-dhw.png
--- a/docs/images/template/zoneinfo-loads.png
+++ b/docs/images/template/zoneinfo-loads.png
--- a/docs/images/template/zoneinfo-ventilation.png
+++ b/docs/images/template/zoneinfo-ventilation.png
--- a/docs/images/template/zoneinfo-windows.png
+++ b/docs/images/template/zoneinfo-windows.png
--- a/docs/images/template/zoneinfo-zone.png
+++ b/docs/images/template/zoneinfo-zone.png
--- a/docs/images/template/zoninfo-conditioning.png
+++ b/docs/images/template/zoninfo-conditioning.png
--- a/docs/images/unsigned_app_error.png
+++ b/docs/images/unsigned_app_error.png
--- a/docs/index.rst
+++ 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 <http://sel.me.wisc.edu/trnsys/index.html>`_ models (shout out to TRNSYS users!)
+
+`translater` also features a :ref:`Command Line Interface (CLI)<Command reference>` 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 <install.rst>
+   For MacOS/Linux users <unix_users.rst>
+   Caching <caching.rst>
+
+
+.. toctree::
+   :maxdepth: 2
+   :caption: User Guide
+
+   Converting IDF models <converting.rst>
+   Reading and Running IDF files <reading_idf.rst>
+   Parallel Processing <tutorials/parallel_process.rst>
+   Managing Schedules <tutorials/schedules.rst>
+   Troubleshooting <troubleshooting.rst>
+
+.. toctree::
+   :maxdepth: 1
+   :caption: Reference Guide
+
+   commands
+   package_modules
+
+
+Indices and tables
+==================
+
+* :ref:`genindex`
+* :ref:`modindex`
+* :ref:`search`
--- a/docs/install.rst
+++ 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
--- a/docs/package_modules.rst
+++ 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
--- a/docs/reading_idf.rst
+++ 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 <https://eppy.readthedocs.io/en/latest/>`_ 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)
--- a/docs/troubleshooting.rst
+++ 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 <https://github.com/NREL/EnergyPlus/issues/7631>`_ 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
--- a/docs/tutorials/parallel_process.rst
+++ 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')}
--- a/docs/tutorials/schedules.rst
+++ 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(<idf-file-path>)
+    >>> 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 <Converting IDF to BUI>` 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")
--- a/docs/unix_users.rst
+++ 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 "<path to executable on UNIX machine>" "<path to IDF file>"
+
+You can find the executable trnsidf.exe in the TRNSYS default installation folder:
+`C:\\TRNSYS18\\Building\\trnsIDF`
+
+
+.. _Wine: https://www.winehq.org/