################################ Getting Started ################################ We recommend using PyCharm and Miniconda when working with the CITYhub Python package with Windows 11. This guide will walkthrough a recommend set of steps to start using the CITYhub: 1. :ref:`installing-pycharm` 2. :ref:`installing-miniconda` 3. :ref:`installing-energyplus` 4. :ref:`creating-project-in-pycharm` .. _installing-pycharm: ******************************** Installing PyCharm ******************************** 1. `Download PyCharm `_ .. note:: If you have a university email address, you may be eligible to use PyCharm Professional through the `JETBRAINS Student Pack `_ 2. Run the installer 3. Click **Next** .. image:: ../../../images/installing-pycharm-1.png :width: 400 4. Click **Next** .. image:: ../../../images/installing-pycharm-2.png :width: 400 5. Click **Next** .. image:: ../../../images/installing-pycharm-3.png :width: 400 6. Click **Install** .. image:: ../../../images/installing-pycharm-4.png :width: 400 7. Click **Finish** .. image:: ../../../images/installing-pycharm-5.png :width: 400 .. _installing-miniconda: ******************************** Installing MiniConda ******************************** 1. `Download MiniConda `_ 2. Run the installer 3. Click **Next** .. image:: ../../../images/installing-miniconda-1.png :width: 400 4. Click **I Agree** .. image:: ../../../images/installing-miniconda-2.png :width: 400 5. Click **Next** .. image:: ../../../images/installing-miniconda-3.png :width: 400 6. Click **Next** .. image:: ../../../images/installing-miniconda-4.png :width: 400 7. Click **Install** .. image:: ../../../images/installing-miniconda-5.png :width: 400 8. Click **Next** .. image:: ../../../images/installing-miniconda-6.png :width: 400 9. Uncheck the two options and click **Finish** .. image:: ../../../images/installing-miniconda-7.png :width: 400 .. _installing-energyplus: ******************************** Installing EnergyPlus v24.1.0 ******************************** 1. `Download EnergyPlus v24.1.0 `_ .. note:: For Windows 11, you should select the EnergyPlus-24.1.0-XXXXXXXXXX-Windows-x86_64.exe installer 2. Run the installer 3. Click **Next** to start the installation process .. image:: ../../../images/installing-energyplus-1.png :width: 600 4. Click **Next** to accept the default installation path .. image:: ../../../images/installing-energyplus-2.png :width: 600 5. Click **Next** to install all default components .. image:: ../../../images/installing-energyplus-3.png :width: 600 6. Check the box to accept the license agreement and click **Next** .. image:: ../../../images/installing-energyplus-4.png :width: 600 7. Click **Next** to accept the default location for the EnergyPlus shortcut .. image:: ../../../images/installing-energyplus-5.png :width: 600 8. Click **Install** to install EnergyPlus .. image:: ../../../images/installing-energyplus-6.png :width: 600 9. Click **Yes** to give the installer permission to run .. image:: ../../../images/installing-energyplus-7.png :width: 400 10. Click **Finish** to close the installer .. image:: ../../../images/installing-energyplus-8.png :width: 600 .. _creating-project-in-pycharm: ******************************** Creating Project in PyCharm ******************************** 1. Open PyCharm 2. Check the box and click **Continue** .. image:: ../../../images/create-pycharm-project-1.png :width: 400 3. Click **Don't Send** .. image:: ../../../images/create-pycharm-project-2.png :width: 400 4. Click **Allow** to give PyCharm access to the network .. image:: ../../../images/create-pycharm-project-3.png :width: 400 5. Click the **New Project** button .. image:: ../../../images/create-pycharm-project-4.png :width: 400 6. Select **Custom environment**. Choose the following options to create a virtual environment with MiniConda - It is generally recommended that the virtual environment matches the name of the project. In this example, the project and the virtual environment are called **PythonProject** - For **Type** select Conda - Select Python 3.12 Click **Create** to create the project. .. note:: The CITYhub has been tested for Python versions 3.9 - 3.12. If you are unsure which version to select, we recommend Python 3.12. .. image:: ../../../images/create-pycharm-project-5.png :width: 800 .. note:: If you receive a warning about Microsoft Defender, you can press **Exclude folders** to prevent Windows Defender from causing performance issues or false virus detections. .. image:: ../../../images/create-pycharm-project-6.png :width: 400 7. Now that your project has been created, here are a few useful things to note about PyCharm - In the top left you can find the name and the folder structure of the project .. image:: ../../../images/create-pycharm-project-7.png :width: 400 - In the bottom right you can find the name of the Miniconda virtual environment for the project .. image:: ../../../images/create-pycharm-project-8.png :width: 400 - In the bottom left you can find a handy toolbar full of tools .. image:: ../../../images/create-pycharm-project-14.png :width: 200 - Python Console can be used to see the output of your code. Print statements and errors while running code will show up here .. image:: ../../../images/create-pycharm-project-9.png :width: 900 - Python Packages can be used to manage the packages installed inside the Miniconda virtual environment .. image:: ../../../images/create-pycharm-project-10.png :width: 900 - Terminal, which uses PowerShell by default, can be used to run git commands if you are working with a Github/Gitea repository. It can also be used to manage packages inside of the Miniconda virtual environment. The terminal is recommended for more advanced users. .. image:: ../../../images/create-pycharm-project-11.png :width: 900 - Version Control is used to work with git repositories from GitHub or Gitea. For a quick understanding on how git and version control work, checkout [this short video by ByteByteGo](https://www.youtube.com/watch?v=e9lnsKot_SQ) .. image:: ../../../images/create-pycharm-project-12.png :width: 900 8. To install the CITYhub Python package, open Python Packages and search **cerc-hub**. Select the first cerc-hub in the list and press **Install** .. image:: ../../../images/create-pycharm-project-13.png :width: 900 You have now created the project and installed the cerc-hub Python package.