Merge remote-tracking branch 'origin/updating_documentation_from_libs_to_hub'

MACOS_INSTALL.md

@@ -1,7 +1,8 @@
 # MACOS_INSTALL
 
-This is an installation guide for macOS, covering all the steps needed to begin developing code for the Urban Simulation Platform ‘Hub’.
+This is an installation guide for macOS, covering all the steps needed to begin developing code for the Urban Simulation 
-At the end of this process you will have installed and configured all the necessary applications, set up your own project on CERC’s Gitlab and created your first python file.
+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 Gitlab and created your first python file.
 
 ## Prepare your environment
 
@@ -9,15 +10,22 @@ To develop any new code for the Urban Simulation Platform you must have the righ
 The Platform is written in python and so the applications you need are:
 * Python Interpreter
 * Python Editor
+* @Chris: Miniconda??
 
-You also need to register a user account with the CERC’s code repository on Gitlab and have the necessary permissions for creating new code.
+You also need to register a user account with the CERC's code repository on Gitlab 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 a Python interpreter
+
 1. Download the latest version of python for macOS: [Python environment](https://www.python.org/downloads/)
 2. Open the downloaded .pkg file and follow the instructions to install.
 
 ### 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=mac), an excellent open-source 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=mac), 
+an excellent open-source python editor.
 2. Open the downloaded .dmg file and then drag the PyCharm CE app into your Applications folder.
 
 ![pycharm ce](docs/img_macos_install/img_0.png)
@@ -33,7 +41,7 @@ You also need to register a user account with the CERC’s code repository on Gi
 
 ![get_vc_2](docs/img_macos_install/img_2.png)
 
-(You can also copy this URL by going to the Hub repository in [Gitlab](https://rs-loy-gitlab.concordia.ca/Guille/hub) 
+(You can also copy this URL by going to the Hub repository in [Gitlab](https://rs-loy-gitlab.concordia.ca/Guille/hub.git) 
 and clicking on the Copy URL button next to **Clone with HTTPS**)
  
 ![git_lab](docs/img_macos_install/img_3.png)
@@ -42,7 +50,7 @@ The Directory to store the Hub source code locally is automatically created for
 
 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.
+4.	Click the **Clone** button to download CERC Hub source code.
 
 (If the macOS security asks if you trust executing this source code, you can click **Trust Project**.)
 
@@ -56,7 +64,11 @@ You have successfully cloned a copy of the CERC hub onto your computer.
 
 ## 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.
+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...**
 
@@ -86,15 +98,15 @@ Note - at this point you may need to login to Gitlab using you Concordia credent
 ![gitlab_credentials](docs/img_macos_install/img_11.png)
 
 Check that your branch now appears in the _Remote_ branch hierarchy, in the bottom-left corner. If it does not appear, 
-contact Guille (guillermo.gutierrezmorote@concordia.ca) or Koa (), to find the reason of the error.
+contact Guille (guillermo.gutierrezmorote@concordia.ca) or Koa (kekoa.wells@concordia.ca), to find the reason of the error.
 
 ![branch_pushed](docs/img_macos_install/img_12.png)
 
 ## 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 four spaces indentation. 
+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/)
-This option can be configured in PyCharm at the settings screen.
+four spaces indentation. This option can be configured in PyCharm at the settings screen.
 
 To access the settings screen, click on the gear icon in the top right corner, and select **Preferences** from 
 the drop-down menu. The Preferences window will appear. From the panel on the left, select 
@@ -113,8 +125,9 @@ See the picture below.
 
 ![blank_project](docs/img_macos_install/img_15.png)
  
-3. Type in a name (remember to follow the CERC naming conventions). Check the option **Initialize repository with a README**, 
+3. Type in a name (remember to follow the CERC naming conventions described in the ![Coding Style](PYGUIDE.md)). 
-and ideally, check the **Visibility Level** to be **Public**. Then click on the **Create project** button.
+Check the option **Initialize repository with a README**, and ideally, check the **Visibility Level** to be **Public**. 
+Then click on the **Create project** button.
 
 ![project_created](docs/img_macos_install/img_16.png)
 

README.md

@@ -1,6 +1,6 @@
 # Hub
 
-Hub is part of Insel4D architecture for urban simulations, created by the CERC group at Concordia University.
+Hub is part of Insel4Cities architecture for urban simulations, created by the CERC group at Concordia University.
 
 Hub repository contains:
 * city_model_structure: a central data model specifically design to model urban environments. An instance of this is called City.

WINDOWS_INSTALL.md

@@ -1,92 +1,235 @@
-# Prepare your environment
+# WINDOWS_INSTALL
 
-Download the latest version of python and Microsoft c++ redistributable
+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 Gitlab and created your first python file.
 
-* [Microsoft C++ redistributable](https://www.microsoft.com/en-ca/download/details.aspx?id=48145)
+## Prepare your environment
-* [Python environment](https://www.python.org/downloads/)
+g
+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
+* Python Editor
 
-# Get the code
+You also need to register a user account with the CERC's code repository on Gitlab 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.
 
-1. First thing you will need is an editor for your source code, that's a personal choice, but we would like to recommend PyCharm community edition, an excellent open-source python editor. [PyCharm Community edition](https://www.jetbrains.com/pycharm/download/download-thanks.html?platform=windows&code=PCC)
+### Get Miniconda
 
-2. Run the installer, and follow the installation instructions for PyCharm, you may change a few options, but the default ones should be fine.
+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_.
 
-3. Open PyCharm and click on **"Get from Version Control"**.
+![conda](docs/img_windows_install/img_20.png)
+
+If you already installed a Python interpreter, the following message will warn you:
+
+![conda_2](docs/img_windows_install/img_21.png)
+
+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.:
+
+![path_1](docs/img_windows_install/img_27.png)
+
+![path_2](docs/img_windows_install/img_28.png)
+
+Now, restart the computer to update the Path.
+
+Finally, open a terminal and type 'conda init powershell'.
+
+![terminal_conda](docs/img_windows_install/img_30.png)
+
+**NOTE:** This final step could produce the following error: 
+_The term '...' is not recognized as the name of a cmdlet, function,..._
+
+![error_conda](docs/img_windows_install/img_32.png)
+
+To solve it, type 'Set-ExecutionPolicy Unrestricted' as shown in the image.
+
+### 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.
+
+![creating_virtual_environment](docs/img_windows_install/img_31.png)
+
+## Get the CERC Hub source code
+
+1. Run PyCharmCE
+2. Click on the **Get from VCS** button in the top right of the window.
 
 ![pycharm welcome screen](docs/img_windows_install/img_0.png)
 
-You can find it also at VCS -> Get from Version Control...
+You can find it also at **Git->Clone...**
 
 ![pycharm get from version control](docs/img_windows_install/img_6.png)
 
-
+3. Select **Git** as the **Version control**. For the URL use the link to the Hub repository, as seen below.
-4. Select Git as the version control, and set the URL to [hub repository](https://rs-loy-gitlab.concordia.ca/Guille/hub.git) as shown in the picture.
-At the website, copy the URL from Clone -> Clone with HTTPS.
 
 ![pycharm get from version control screen](docs/img_windows_install/img_1.png)
 
+(You can also copy this URL by going to the Hub repository in [Gitlab](https://rs-loy-gitlab.concordia.ca/Guille/hub.git) 
+and clicking on the **Copy URL** button, next to **Clone with HTTPS**)
 
-You may need to install Git, by clicking at ***Download and install***. 
+![gitlab get https](docs/img_windows_install/img_17.png)
-If that message does not appear is because you have it already installed in your computer.
 
-5. Click Clone to download CERC hub source code. You will end with a project like this:
+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.
 
-![pycharm project screen](docs/img_windows_install/img_2.png)
+![pycharm_project_screen](docs/img_windows_install/img_2.png)
 
-6. To create your working branch you need rights to edit that project. Please, talk to Guillermo (guillermo.gutierrezmorote@concordia.ca) 
+## Configure Python Interpreter
-or Koa (kekoa.wells@concordia.ca) to get those rights. Once you have them, right-click on the project folder (hub) -> Git -> Repository -> Branches:
+
+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:
+
+![configure_interpreter_1](docs/img_windows_install/img_22.png)
+
+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.
+
+![configure_interpreter_2](docs/img_windows_install/img_25.png)
+
+You should end with the following window:
+
+![configure_interpreter_3](docs/img_windows_install/img_26.png)
+
+Click **OK** to close it.
+
+**NOTE:** This final step could produce the following error:
+
+![conda_environment_error](docs/img_windows_install/img_33.png)
+
+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.
+
+![configure interpreter 4](docs/img_windows_install/img_29.png)
+
+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...**
 
 ![create new branch 1](docs/img_windows_install/img_9.png)
 
-And then + 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.
-![create new branch 2](docs/img_windows_install/img_10.png)
-
-Give a name to your branch and open the tab Git at the down-left corner. Right-click on your branch and push.
 
 ![push new branch 1](docs/img_windows_install/img_11.png)
 
+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 Gitlab 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.
+
 ![push new branch 2](docs/img_windows_install/img_12.png)
 
-Check that your branch appears in the Remote list:
+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.
 
 ![check all set](docs/img_windows_install/img_13.png)
 
-If your branch is there, you are done with this part.
+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
+## Configure Pycharm
 
-We use two spaces as a tab instead of standard [pep8](https://www.python.org/dev/peps/pep-0008/) four spaces indentation.
+When integrating your model with the Platform, it is important that you follow [CERC’s coding style guidelines](PYGUIDE.md). 
-This option can be configured in PyCharm at the settings screen, as shown in the picture.
+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.
 
 ![pycharm configuration screen](docs/img_windows_install/img_5.png)
 
+## Set up a new project on Gitlab 
 
-# Start your project
+1. Open a browser and to the [CERC Git](https://rs-loy-gitlab.concordia.ca/). Click on the blue **New project** button.
-
-1. At our Git (https://rs-loy-gitlab.concordia.ca/), click on New project:
 
 ![git new project screen](docs/img_windows_install/img_14.png)
 
-The create a black project with the desired name (remember to follow our ![Coding Style](PYGUIDE.md)). 
+2. Choose the **Create blank project** option from the three options seen below.
-Be sure that Initialize repository with a README is selected, and ideally, that the Visibility Level is Public. 
+
+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)). 
+Check the option **Initialize repository with a README**, and ideally, check the **Visibility Level** to be **Public**. 
+Then click on the **Create project** button.
 
 ![git give a name](docs/img_windows_install/img_15.png)
 
-And finally, clone it following the same steps as for ![hub](WINDOWS_INSTALL.md#get-the-code) (steps 3 to 5).
+You should then see a confirmation screen with all the information about your new project.
 
-2. Go to project settings and add the hub project to your own, by clicking on Add Content Root:
+## Get your project into Pycharm
+
+1. Now you can make a clone of this project, within PyCharm. First, copy the URL by clicking on the blue **Clone** button 
+and then click on the **Copy URL** button, next to the **Clone with HTTPS** link.
+
+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 gitlab 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:
 
 ![pycharm new project screen](docs/img_windows_install/img_4.png)
 
 ![pycharm add hub](docs/img_windows_install/img_7.png)
 
-3. Add your first file to your project and click on install requirements to automatically download all the dependencies (in blue at top-right corner).
+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).
 
 ![pycharm add dependencies](docs/img_windows_install/img_8.png)
 
-4. When all the dependencies are satisfied, you are all set to start importing your first city model.
+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
 
@@ -97,7 +240,7 @@ from imports.geometry_factory import GeometryFactory
 city = GeometryFactory('citygml', 'myfile.gml').city
 ```
 
-5. Always remember to push your own project changes as the last thing you do before ending your working day! 
+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 at the top-right corner of Pycharm. Add a comment that explains briefly your changes. 
+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 (gitlab). 
 Once the conflicts are solved and the merge in local is done, push the changes by clicking on the green arrow.