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