RAMP-UA

This is the code repository for the RAMP Urban Analytics project.

This project contains two implementations of a microsim model which runs on a synthetic population:

1. Python / R implementation, found in microsim/microsim_model.py
2. High performance OpenCL implementation, which can run on both CPU and GPU, which is found in the microsim/opencl folder.

Further documentation on the OpenCL model can be found at microsim/opencl/doc

Both models should be logically equivalent (with some minor differences).

Environment setup

NB: The OpenCL model requires following additional installation instructions located in the OpenCL Readme

This project currently supports running on Linux and macOS.

To start working with this repository you need to clone it onto your local machine:

$ git clone https://github.com/Urban-Analytics/RAMP-UA.git
$ cd RAMP-UA

This project requires a specific conda environment in order to run so you will need the conda package manager system installed. Once conda has been installed you can create an environment for this project using the provided environment file.

$ conda env create -f environment.yml

To retrieve data to run the mode you will need to use Git Large File Storage to download the input data. Git-lfs is installed within the conda environment (you may need to run git lfs install on your first use of git lfs). To retrieve the data you run the following commands within the root of the project repository:

$ git lfs fetch
$ git lfs checkout

Next we install the RAMP-UA package into the environment using setup.py:

# if developing the code base use:
$ python setup.py develop
# for using the code base use
$ python setup.py install

Running the models

Both models can be run from the microsim/main.py script, which can be configured with various arguments to choose which model implementation to run.

Python / R model

The Python / R model runs by default, so simply run the main script with no arguments.

$ python microsim/main.py 

OpenCL model

To run the OpenCL model pass the --opencl flag to the main script, as below.

The OpenCL model runs in "headless" mode by default, however it can also be run with an interactive GUI and visualisation, to run with the GUI pass the --opencl-gui flag, as below.

Run Headless

$ python microsim/main.py --opencl

Run with GUI

$ python microsim/main.py --opencl-gui

Caching of population initialisation

The population initialisation step runs before either of the models and can be time consuming (~10 minutes or up to 2 hours). In order to run the models using a cache of previous results simply pass the --use-cache flag.

Output Dashboards

Outputs are currently written to the devon_data/output directory.

Interactive HTML dashboards can be created using the Bokeh library.

Run the command below to generate the full dashboard for the Python / R model output, which should automatically open the HTML file when it finishes.

$ python microsim/dashboard.py

Configuration YAML files for the dashboard are located in the model_parameters folder.

The OpenCL model has a more limited dashboard (this may be extended soon), which can be run as follows:

$ python microsim/opencl/ramp/opencl_dashboard.py

Creating releases

This repository takes advantage of a GitHub action for creating tagged releases using semantic versioning.

To initiate the GitHub action and create a release:

$ git checkout branch

$ git tag -a v0.1.2 -m 'tag comment about release'

$ git push --tags

Once pushed the action will initiate and attempt to create a release.

Documentation

Documentation for this package is generated using Sphinx. It uses the sphinx.ext.autodoc extension to populate the documentation from existing docstrings.

To build the documentation locally:

$ cd docs/

$ make html

If a new module is added you will need to create new .rst files using the sphinx-apidoc command.

$ cd docs/

$ sphinx-apidoc -f -o source/ ../new_module/

This will generate new .rst files from the new modules docstrings that can then be rendered into html by running make html.