City-Scale epidemic simulator

This repository houses the source code of the city-scale epidemic simulator developed by a team of researchers of IISc Bangalore, and TIFR Mumbai, developed to model the spread of CovID-19 in Indian demographics. This README document will help you familiarize yourself with the directory structure of the project and also provides the steps to run the simulator on your local machines.

The source code for the simulator is organized into three major directories each of which represent one stage of the simulator's workflow.

|- .
  |- staticInst/
  |- simulator/  
  |- cpp-simulator/
  |- README.md

StaticInst/ - Generates static files to instantiate a city based on Demographics data

The first stage of the simulator workflow is to generate static information required to instantiate a city. To instantiate a Bangalore city with the mentioned configurations run the command

python parse_and_instantiate.py -c city_name -n target_population -i inputPath -o outputPath

The above script instantiates a synthetic city with the specified population where each individual being assigned to a house, school, workplace and community centre based on their age, and commute distance. The instantiated outputs are in the form of JSON files and will be available in the specified output directory.

A detailed description of the input files, the script and instructions to run are available at staticInst/README.md

simulator/ - Javascript simulator

The simulator folder contains the javascript based epidemic simulator. The simulator is designed to run on a browser. The simulator is to be served via a webserver. The below command (based on the OS), run in the repo root directory, will serve the simulator files via a webserver on port 8000. The port number can changed to any available port number.

On Windows: python -m http.server 8000. On Linux: python -m SimpleHTTPServer 8000

Once, the web-server is running, you can open your web browser and access localhost:8000 or 127.0.0.1:8000 to access the simulator. If you press the Run button on the webpage, you should be able to view plots generated by the simulator. In addition, if you need to download the simulator outputs for independent processing, you could disable the 'WEBPAGE_VERSION' flag in sim.js to download the simulator outputs in .csv format.

The simulator injests the city-wide instatiation files generated using the scripts in staticInst. The minimum files the simulator expects are:

• individuals.json - Information about individuals in the synthetic city.
• houses.json - Information about households in the city.
• workplaces.json - Information about workplaces in the city.
• schools.json - Information about schools in the city
• commonArea.json - Information about the community spaces in the city
• wardCentreDistance.json - Information about the inter-ward distances.
• fractionPopulation.json - Information about fraction of the population residing in each ward.

simulator/python_scripts_CPP/ and simulator/python_scripts_CPP/plotting_scripts

These subfolders in simulator contains: 1) the main calibration script (tune_model_CPP.py) that can be used to calibrate (tune) the cpp-simulator beta values to a given fatalities time series, and 2) plotting scripts that can be used to generate plots from the cpp-simulator outputs.

cpp-simulator/ - CPP simulator

This folder contains the cpp-version of the simulator. The CPP simulator evolved from the JS simulator. Please read the cpp-simulator/README.md for more details.