Merge branch 'helmet-5' into feat/workplace_share_check

README.md

@@ -6,7 +6,7 @@ This repository contains python files for Helmet 4.1 Model System. Source codes
 
 ## Usage
 
-You can run HELMET 4.1 from the command line or by using [helmet-ui](https://github.com/HSLdevcom/helmet-ui).
+You can run HELMET 5 from the command line or by using [helmet-ui](https://github.com/HSLdevcom/helmet-ui).
 In this chapter, we will guide you how to install HELMET 4.1 to work with Inro EMME software from the command line.
 The user is not expected to install any new software apart from [helmet-model-system](https://github.com/HSLdevcom/helmet-model-system) and EMME.
 
@@ -16,6 +16,8 @@ If you do not have an Emme license or you wish to develop HELMET 4.1 further, pl
 
 From this repository, copy the contents of the [Scripts](Scripts) folder to your computer.
 
+From this repository, copy the contents of the [Scripts](Scripts) folder to your computer.
+
 In production, we are using Python 3.7 which is supported by and installed together with INRO Emme software.
 We are using those Python dependencies that come with Inro EMME installation.
 To get access to these dependencies, you need to add them to your local PATH variable:
@@ -32,7 +34,7 @@ Emme assignment can be tested without further configuration.
 Open command line to your local Scripts folder and write:
 
 ```
-python test_assignment.py
+python -m tests.emme_only.test_assignment
 ```
 
 This will create a small EMME test network and run test assignments on it.
@@ -67,8 +69,10 @@ Although not covered here, installing [Git](https://git-scm.com/downloads) is hi
 We are using Python 3.7 because it is supported by INRO Emme 4.5 software.
 
 1. Install Python 3.7.
-2. Add `C:\Python37` and `C:\Python37\Scripts` to your local PATH variable in "Environment Variables".
-3. Open a new Command Prompt and type `python --version`. You should get `Python 3.7.9` or some other Python 3.7 version.
+2. Add the path were you installed python (e.g., `C:\Python37`) and `C:\Python37\Scripts`
+   to your local PATH variable in "Environment Variables".
+3. Open a new Command Prompt and type `python --version`.
+   You should get `Python 3.7.9` or some other Python 3.7 version.
 
 `pip` is the recommended package installer for Python.
 The normal Python installation routine installs `pip` to `C:\Python37\Scripts`.
@@ -82,19 +86,22 @@ or [Jonathan Cutrer's blog](https://jcutrer.com/python/pipenv-pipfile).
 
 1. Open Command Prompt.
 2. Install `pipenv` by running `python -m pip install --user pipenv`.
-   `pipenv` should now be installed in `%APPDATA%\Python\Scripts` (e.g. `C:\Users\USERNAME\AppData\Roaming\Python\Scripts`).
-3. Add `%APPDATA%\Python\Scripts` to your local PATH variable.
+   `pipenv` should now be installed in `%APPDATA%\Python\Python37\Scripts`
+   (e.g. `C:\Users\USERNAME\AppData\Roaming\Python\Python37\Scripts`).
+3. Add `%APPDATA%\Python\Python37\Scripts` to your local PATH variable.
     1. Open Control Panel.
     2. Go to User Accounts, then click again User Accounts, then select from the left hand menu "Change my environment variables".
     3. From the top box ("User variables for USERNAME"), find and select "Path" variable, and click "Edit...".
-    4. Click "New" and write `%APPDATA%\Python\Scripts`.
+    4. Click "New" and write `%APPDATA%\Python\Python37\Scripts`.
     5. Click OK in the "Edit environment variable" window, and then click OK again in the "Environment Variables" window.
-4. Close and reopen Command Prompt and check that `pipenv` is recognised by typing `pipenv --version`. It should return `pipenv, version 2020.11.15`.
-5. Download [helmet-model-system](https://github.com/HSLdevcom/helmet-model-system) repository and open a Command Prompt to its "Scripts" folder.
+4. Close and reopen Command Prompt and check that `pipenv` is recognised by typing `pipenv --version`.
+   It should return `pipenv, version 2020.11.15` (`pipenv` version may vary).
+5. Download [helmet-model-system](https://github.com/HSLdevcom/helmet-model-system) repository
+   and open a Command Prompt to its "Scripts" folder.
 6. Install dependencies from `Pipfile`:
     - First setup: `pipenv --python 3.7 install --dev`
     - Additional syncing if new packages are added: `pipenv --python 3.7 sync --dev`
-7. Depending on your operating system, rename either `.env-win` (Windows) or `.env-nix` (Linux) to `.env`. 
+7. Depending on your operating system, rename either `.env-win` (Windows) or `.env-nix` (Linux) to `.env`.
    In Windows, you can do this in Command Propmpt by typing `copy .env-win .env`.
 
 Now, you should have a virtual environment in `C:\Users\USERNAME\.virtualenvs\Scripts-xxxxxxxx\Lib\site-packages`.
@@ -106,6 +113,48 @@ cd Scripts
 pipenv run python helmet.py
 ```
 
+
+### Mock assignment run in Helmet UI
+
+Refer to this manual: [https://hsldevcom.github.io/helmet-docs/kaytto-ohje.html#helmet-asennus](https://hsldevcom.github.io/helmet-docs/kaytto-ohje.html#helmet-asennus).
+
+#### Change the config settings
+1. Download latest version of helmet-model-system in `Projektin asetukset` (edit: or set this manually to `helmet-model-system\Scripts` folder which you probably downloaded when installing Python environment!).
+2. Find out where that version is saved by hovering over the text box (for example: `C:\Users\xxx\helmet-model-system-v4.1.3-24-04-1684924655775`)
+3. Open `dev-config.json` inside that previous folder and modify OPTIONAL_FLAGS argument:
+    -     `"OPTIONAL_FLAGS": ["DO_NOT_USE_EMME"]`
+
+#### Set Helmet UI settings
+1. Click "Projektin asetukset" button
+    - Python from previous virtual environment, for example `C:\Users\xxx\.virtualenvs\Scripts-AJXyDTuP\Scripts\python.exe`
+    - helmet-model-system was set previously
+    - Projektin kansiopolku: your choice
+    - Lähtödata: `helmet-model-system\tests\test_data\Base_input_data`
+    - Tulokset: your choice (copy Matrices folder from to the location) or `helmet-model-system\tests\test_data\Results`
+2. "Uusi Helmet-skenaario" button
+    - Skenaarion nimi: your choice
+    - Emme-projekti: create an empty (dummy) text file and save it with file extension `.emp`
+    - Liikenneverkon sisältävä skenaario: default
+    - Syöttötiedot: `helmet-model-system\tests\test_data\Scenario_input_data\2030_test`
+    - Iteraatioiden enimmäismäärä: default (do not cross "loppusijoittelu")
+    - The rest can have default values (edited) 
+
+#### Run your first demo model run
+1. In case your scenario name is not `test`, copy the `helmet-model-system\tests\test_data\Results\test\Matrices` folder to `[your-result-folder]\[your-scenario-name]\Matrices`.
+2. Select scenario with checkbox and click `Käynnistä (1) skenaariota`. When running the first model run again and again, just do #2. When you create more scenarios, always copy matrices (#1) first to a new location. (This is a demo model thing that needs to be done because we are independent of Emme.)
+
+#### Running mock assignment in command line
+Alternatively, you can run the mock assignment with the help of command line
+1. Make sure your virtual environment is activated (As described in Environment and Dependencies)
+2. Adjust the following variables in `dev-config.json` (while replacing the YOUR_PATH variable with absolute path to the helmet-model-system folder)
+    - `"SCENARIO_NAME": "test"`,
+    - `"RESULTS_PATH": "YOUR_PATH\\helmet-model-system\\Scripts\\tests\\test_data\\Results"`,
+    - `"BASELINE_DATA_PATH": "YOUR_PATH\\helmet-model-system\\Scripts\\tests\\test_data\\Base_input_data"`,
+    - `"FORECAST_DATA_PATH": "YOUR_PATH\\helmet-model-system\\Scripts\\tests\\test_data\\Scenario_input_data\\2030_test"`,
+3. Type the following to the command line: `pipenv run python helmet.py --do-not-use-emme`.
+    You can also use the shorter `pipenv run python helmet.py -m`.
+
+
 ### Visual Studio Code
 
 The following extensions are recommended when developing with Visual Studio Code:

Scripts/assignment/abstract_assignment.py

@@ -1,20 +1,25 @@
+from __future__ import annotations
 from abc import ABCMeta, abstractmethod
+from typing import Any, Dict, List, Union
 
 
 class AssignmentModel:
     __metaclass__ = ABCMeta
 
+    @property
     @abstractmethod
-    def mapping(self):
+    def mapping(self) -> Dict[int,int]:
         """Dictionary of zone numbers and corresponding indices."""
         pass
 
+    @property
     @abstractmethod
-    def zone_numbers(self):
+    def zone_numbers(self) -> List[int]:
         pass
 
+    @property
     @abstractmethod
-    def nr_zones(self):
+    def nr_zones(self) -> int:
         pass
 
     @abstractmethod
@@ -41,5 +46,5 @@ class Period:
     __metaclass__ = ABCMeta
 
     @abstractmethod
-    def assign(self):
+    def assign(self, matrices: Dict[Any, Any], iteration: Union[int, str]) -> Dict[Any, Any]:
         pass