270 lines
12 KiB
Markdown
270 lines
12 KiB
Markdown
# WINDOWS_INSTALL
|
||
|
||
This is an installation guide for Windows, covering all the steps needed to begin developing code for the Urban
|
||
Simulation Platform 'Hub'. At the end of this process you will have installed and configured all the necessary applications,
|
||
set up your own project on CERC's Gitea and created your first python file.
|
||
|
||
## Prepare your environment
|
||
To develop any new code for the Urban Simulation Platform you must have the right software applications installed and configured.
|
||
The Platform is written in python and so the applications you need are:
|
||
* Miniconda
|
||
* SRA Files
|
||
* Python Editor
|
||
|
||
You also need to register a user account with the CERC's code repository on Gitea and have the necessary permissions for
|
||
creating new code. For that purpose, please, contact Guillermo (guillermo.gutierrezmorote@concordia.ca) or
|
||
Koa (kekoa.wells@concordia.ca) as soon as possible.
|
||
|
||
### Get Miniconda
|
||
|
||
1. Download [Miniconda for Windows](https://docs.conda.io/en/latest/miniconda.html) for Python version 3.9.
|
||
2. Run the installer and select in the corresponding window _Register Miniconda3 as my default Python 3.9_.
|
||
|
||
|
||
|
||
If you already installed a Python interpreter, the following message will warn you:
|
||
|
||
|
||
|
||
Click **OK** and then, click **Install**.
|
||
|
||
Once you are done, add Miniconda to the Path by clicking on **New** and writing the path where _conda.exe_ was installed.:
|
||
|
||
|
||
|
||
|
||
|
||
Now, restart the computer to update the Path.
|
||
|
||
Finally, open a terminal and type 'conda init powershell'.
|
||
|
||
|
||
|
||
**NOTE:** This final step could produce the following error:
|
||
_The term '...' is not recognized as the name of a cmdlet, function,..._
|
||
|
||
|
||
|
||
To solve it, type 'Set-ExecutionPolicy Unrestricted' as shown in the image.
|
||
|
||
### Setup SRA
|
||
|
||
1. Get the SRA executable and dll files from Guille or Koa
|
||
2. Create a folder in "C:\Program Files\" called "sra"
|
||
|
||
|
||
|
||
3. Copy shortwave_integer.exe and pthreadGC2.dll into the sra folder.
|
||
|
||
|
||
|
||
4. Add the newly created sra folder to the Path, similar to step 2 from the Miniconda setup above.
|
||
|
||
|
||
|
||
### Install and setup INSEL
|
||
|
||
1. Get the INSEL installer from Guille or Koa
|
||
2. Run the installer to completion using the default installation path
|
||
3. Add the INSEL installation folder to the Path
|
||
|
||
|
||
|
||
### Get a Python editor
|
||
|
||
1. You will need a python editor in order to import the existing Hub source code and to write your own python code.
|
||
Whilst this is a personal choice we would like to recommend [PyCharm Community Edition](https://www.jetbrains.com/pycharm/download/#section=windows),
|
||
an excellent open-source python editor.
|
||
2. Run the installer, and follow the installation instructions for PyCharm, you may change a few options,
|
||
but the default ones should be fine.
|
||
|
||
**NOTE:** If PyCharm asks you to create a Virtual Environment, click **Cancel**. You will do it later using Conda instead.
|
||
|
||
|
||
|
||
## Get the CERC Hub source code
|
||
|
||
1. Run PyCharmCE
|
||
2. Click on the **Get from VCS** button in the top right of the window.
|
||
|
||
|
||
|
||
You can find it also at **Git->Clone...**
|
||
|
||
|
||
|
||
3. Select **Git** as the **Version control**. Open the [hub repository](https://nextgenerations-cities.encs.concordia.ca/gitea/CERC/hub)
|
||
on Gitea and copy the URL from your browser to use as the URL inside PyCharm.
|
||
|
||
|
||
|
||
|
||
|
||
The Directory to store the Hub source code locally is automatically created for you. Edit this if you prefer it to be stored somewhere else.
|
||
|
||
Note: If you see a message saying Git is not installed, click on the **Download and install** and follow instructions.
|
||
|
||
4. Click the **Clone** button to download CERC hub source code. You will then see the project directories and files below,
|
||
with the hub readme document displayed. You have successfully cloned a copy of the CERC hub onto your computer.
|
||
|
||
|
||
|
||
## Configure Python Interpreter
|
||
|
||
1. Click on **File**, and select **Settings...** from the drop-down menu. The Settings window will appear.
|
||
From the panel on the left, select **Project: hub->Python Interpreter** and you will see the following window:
|
||
|
||
|
||
|
||
2. Click on the little gear on the right and click **Add...**. In the new window, click on **Conda Environment**,
|
||
select **New environment** and the Python version 3.9.
|
||
|
||
|
||
|
||
You should end with the following window:
|
||
|
||
|
||
|
||
Click **OK** to close it.
|
||
|
||
**NOTE:** This final step could produce the following error:
|
||
|
||
|
||
|
||
To solve it, add to the Path (as explained in [previous chapter Get Miniconda](WINDOWS_INSTALL.md#Get Miniconda))
|
||
the following paths:
|
||
* C:\Users\User\miniconda3\Library\bin
|
||
* C:\Users\User\miniconda3
|
||
* C:\Users\User\miniconda3\Scripts
|
||
|
||
Restart the computer and come back to step 1 of this section.
|
||
|
||
5. Go to the Terminal (a tab in the bottom) to finish this process. You should see
|
||
_PS C:\Users\Pilar\PycharmProjects\hub>_ preceded either by _(base)_ or _(hub)_. If non of those are there,
|
||
be sure that you have Miniconda installed and included in the path as explained in
|
||
[previous chapter Get Miniconda](WINDOWS_INSTALL.md#Get Miniconda). If not, do it, restart Pycharm, and come back to this point.
|
||
|
||
If the environment you are working in is _(base)_, type 'conda activate ' and the project's name, in this case 'conda activate hub'.
|
||
Click enter, and the environment should change to _(hub)_. If this didn't work, contact Guillermo
|
||
(guillermo.gutierrezmorote@concordia.ca) or Koa (kekoa.wells@concordia.ca) for some help.
|
||
|
||
|
||
|
||
6. Once you are in _(hub)_, type 'pip install -r .\requirements.txt' and wait until all requirements are installed. In the
|
||
bottom-right corner you should be able to see a bar showing the progress.
|
||
|
||
## Create Your Own Branch of the Hub
|
||
|
||
You now need to create a new **Branch** of the Hub source code. This is like your own special version of the Hub,
|
||
where you can safely integrate your model, without affecting the smooth running of the Main Branch Hub and the Platform.
|
||
|
||
To create your working branch you need rights to edit the project. Please, contact Guillermo (guillermo.gutierrezmorote@concordia.ca)
|
||
or Koa (kekoa.wells@concordia.ca) to get those rights and then follow the instructions.
|
||
|
||
1. Create your working branch by right-clicking on the project folder (hub) and then selecting **Git->New Branch...**
|
||
|
||
|
||
|
||
2. Give a name to your branch that has some sense of what will be done with it, _updating_documentation_,
|
||
_lca_classes_,... And, click on the **Create** button.
|
||
|
||
|
||
|
||
3. Click on the **Git** button in the bottom-left corner to pop-up the window showing the Git information.
|
||
See your new branch has been created under _Local_.
|
||
|
||
4. Now we need to let the CERC Gitea repository know about this new branch. You do this by right-clicking on
|
||
your branch and selecting **Push...** from the drop-down menu.
|
||
|
||
5. Then click on the **Push** button at the bottom-right of the **Push Commits** window.
|
||
|
||
|
||
|
||
Check that your branch now appears in the _Remote_ branch hierarchy, in the bottom-left corner. If it does not appear,
|
||
contact Guillermo (guillermo.gutierrezmorote@concordia.ca) or Koa (kekoa.wells@concordia.ca), to find the reason of the error.
|
||
|
||
|
||
|
||
If your branch is there, you are done with this part.
|
||
Now you are all set to contribute to Hub or to use it for your own projects!
|
||
|
||
## Configure Pycharm
|
||
|
||
When integrating your model with the Platform, it is important that you follow [CERC’s coding style guidelines](PYGUIDE.md).
|
||
One of the rules is that we use two spaces as a tab instead of the standard [pep8](https://www.python.org/dev/peps/pep-0008/)
|
||
four spaces indentation. This option can be configured in PyCharm at the settings screen.
|
||
|
||
To access the settings screen, click on **File**, and select **Settings...** from
|
||
the drop-down menu. The Settings window will appear. From the panel on the left, select
|
||
**Editor->Code Style->Python** and you will see where tab size can be changed. Change it to 2.
|
||
See the picture below.
|
||
|
||
|
||
|
||
## Set up a new project on Gitea
|
||
You will need an account before you can access the Gitea. Please contact Guillermo (guillermo.gutierrezmorote@concordia.ca) or
|
||
Koa (kekoa.wells@concordia.ca) to request an account.
|
||
|
||
1. Open a browser and go to the [CERC Gitea](https://nextgenerations-cities.encs.concordia.ca/). Click on the **+** in the top right
|
||
and select "New Repository" or press the **+** below the Organization tab.
|
||
|
||
|
||
|
||
2. Choose the **Create blank project** option from the three options seen below.
|
||
|
||
3. Type in a name that describes your project: _hp_workflow_, _bus_system_optimization_...
|
||
(remember to follow the CERC naming conventions described in the [Coding Style](PYGUIDE.md)).
|
||
Ideally, uncheck the option **Make Repository Private**, and check the **Initialize Repository**
|
||
Then click on the **Create project** button.
|
||
|
||
|
||
|
||
You should then see a confirmation screen with all the information about your new project.
|
||
|
||
## Get your project into Pycharm
|
||
|
||
1. Now you can make a clone of this project, within PyCharm. First, go to the page of your repository on the Gitea and copy the URL.
|
||
|
||
2. Switch back to PyCharm and close the Hub project by choosing **File->Close Project**. You will then see the
|
||
**Welcome To PyCharm** window again.
|
||
|
||
3. Clone a copy of your Project into PyCharm, following the steps 2-6 of the _GET THE CERC HUB SOURCE CODE_
|
||
section above, but using the URL link that you just copied for your Gitea project.
|
||
|
||
4. Select **File->Settings** to open the **Settings** window. From the panel on the left click on
|
||
**Project:<project name> -> Project Structure**.
|
||
|
||
5. Add the Hub project to your own, by clicking on Add Content Root:
|
||
|
||
|
||
|
||
|
||
|
||
6. Still in the **Settings** window, configure your Python interpreter (yes, again, you have to do this step for each new project)
|
||
by following steps 1 to 5 explained in [chapter Configure Python Interpreter](WINDOWS_INSTALL.md#Configure Python Interpreter).
|
||
Then, to install the requirements, type 'cd..' and enter. Then 'pip install -r .\hub\requirements.txt' and wait until all requirements are installed. In the
|
||
bottom-right corner you should be able to see a bar showing the progress. Finally, type 'cd ' and your project's name.
|
||
|
||
7. Now, add your first file to your project and click on install requirements to automatically download all the dependencies (in blue at top-right corner).
|
||
|
||
|
||
|
||
If the blue message doesn't appear, click on the **Terminal** tab (bottom-left), type _pip install -r .\requirements.txt_
|
||
and press enter.
|
||
|
||
8. When all the dependencies are satisfied, you are all set to start importing your first city model.
|
||
|
||
Add the following code to your main.py
|
||
|
||
```python
|
||
|
||
from hub.imports import GeometryFactory
|
||
|
||
city = GeometryFactory('citygml', path='myfile.gml').city
|
||
```
|
||
|
||
9. Always remember to push your own project changes as the last thing you do before ending your working day!
|
||
First, commit your changes by clicking on the green check in the top-right corner of Pycharm. Add a comment that explains briefly your changes.
|
||
Then, pull by clicking on the blue arrow to be sure that there are no conflicts between your version (local) and the remote one (Gitea).
|
||
Once the conflicts are solved and the merge in local is done, push the changes by clicking on the green arrow.
|