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\trnslator>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 trnslator. It must be installed beforehand. Moreover, trnslator 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 *trnslator*, 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 trnslator .. hint:: If you encounter an issue during the installation of trnslator using ``pip``, you can try out `Installing using conda (Anaconda)`_ instead. Installation within a Virtual Environment ----------------------------------------- It is highly recommended to use/install *trnslator* on a fresh python virtual environment. If you have any trouble with the installation above, try installing trnslator 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 trnslator source trnslator/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 trnslator/bin/activate (trnslator) $ python Python 3.5.1 (default, May 6 2016, 10:59:36) ... >>> import sys >>> sys.path ['', '/usr/local/lib/python35.zip', ..., '~/envs/trnslator/lib/python3.5/site-packages'] >>> Then you can install trnslator in this freshly created environment: .. code-block:: shell pip install trnslator To use the new environment inside a `jupyter notebook`_, we recommend using the steps described by `Angelo Basile`_: .. code-block:: shell source trnslator/bin/activate pip install ipykernel ipython kernel install --user --name=trnslator Next time you `start a jupyter notebook`_, you will have the option to choose the *kernel* corresponding to your project, *trnslator* 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 (*trnslator* in this case). Installing using ``conda`` (Anaconda) ------------------------------------- .. hint:: If you encounter package dependency errors while installing `trnslator` using pip, you can use conda instead. Installing with conda is similar to pip. The following workflow creates a new virtual environment (named trnslator) 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 trnslator -f environment.yml conda activate trnslator pip install trnslator .. _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/trnslator/blob/master/environment.yml