BharatSim Documentation

Welcome to the documentation for BharatSim!

BharatSim is a collaborative project between Ashoka University and Thoughtworks, funded by the Bill & Melinda Gates Foundation. Its ongoing development at Ashoka University is funded by the Mphasis F1 Foundation.

BharatSim was originally designed to run decision-critical scenarios for India during the COVID-19 pandemic. Standard compartmental models that are widely used to model the spread of infectious diseases largely ignore individual level granularity, since they mainly consider a well-mixed population. Such models are ill-suited for predicting and analysing complex real-world phenomena. Realistic systems involve interactions between individuals with different personal attributes (age, weight, height, and comorbidities) and geographies. These interactions can potentially lead to emergent phenomena, especially in scenarios such as pandemics where different individuals are affected differently, based on their attributes.

An agent-based approach allow modellers to account for individual-level heterogeneity, and can thus be used to simulate intricate scenarios of varying complexity in which agents interact with each other and their environment. The results of such simulations could, in principle, be used to guide policy-level interventions like lockdowns and vaccination drives.

BharatSim’s vision is to build a simulation framework that is distributed, multi-scale, and agent-based for use by the scientific community. It aims to provide the user with a synthetic population tailored to the Indian context, and a modelling framework that can easily be customised to address a range of questions. The framework has two components:

• Simulation engine: Given a Synthetic Population, the simulation engine can support large-scale simulations with multi-million agents, incorporating daily behaviours and policy-level interventions. It structures this information by treating agents and locations as nodes, and the relations between them as edges on a graph network. This way modellers can analyse how the network structure of the population affects the spread of the disease. The simulation engine is written in Scala, and allows modellers to directly specify their models using a domain-specific, high-level language. This domain-specific language is also based on the Scala programming language, thus allowing modellers to extend their knowledge of Scala when creating their models.

• Visualization engine: BharatSim also includes a dashboard visualisation tool that allows the user to create and view multiple types of graphs at the same time. The visualisation engine was developed to plot and analyse the outputs generated by the simulation engine, but can be used as an independent application as well. It possesses a customisable dashboard system that is flexible, allowing users to produce graphs that study both the temporal and spatial variation of disease spread.

In this tutorial documentation, we look be looking at BharatSim in detail, introducing the novice programmer to both components. The tutorial assumes a familiarity with (or at least an eagerness to learn) Object-oriented Programming. Prior familiarity with Scala or Java is desirable, but not a prerequisite.

Introduction

• Introduction
• Synthetic Population

Epidemiology

• A Basic Introduction to Epidemic Modelling
  • The SIR Model
    • Mean-field or “Well-mixed” solution to this model
    • Stochastic solutions to this model
  • Introducing a network structure
  • Sojourn times in different compartments
  • Other Compartmental Models
    • The SEIR Model
    • The SAIR Model
    • The SIRS Model
  • Exercises

The Simulation Engine

• Getting Started
  • Setup Requirements
    • Installing JDK
    • Installing Scala with Coursier
  • Setting up an IDE and First Run
    • IntelliJ Idea
    • Visual Studio Code
  • Running Scala on Command Line
• Framework Basics
  • Components of the Simulation Engine
    • Graphs, Nodes, and Relations
    • Agents and Behaviours
    • Networks
    • Schedules
    • Finite State Machine
      • Stateful Agent
      • Actions
      • Transitions
  • Inputs and Outputs in BharatSim
    • Reading inputs from a synthetic population
      • Using the framework-defined functions
      • Creating the user-defined mapping function
    • Writing outputs to a CSV file
      • Saving your output to a CSV file
        • Output at a single instant of time
        • Output at every time step
  • Interventions in BharatSim
    • Intervention
      • Example using the Intervention object
    • IntervalBasedIntervention
      • Example using the IntervalBasedIntervention object
    • OffsetBasedIntervention
      • Example suing the OffsetBasedIntervention object
    • SingleInvocationIntervention
      • Example using the SingleInvocationIntervention object
• Writing your First Program
  • Single Location SIR
    • Creating an Empty Class
    • Implementing a single-location SIR
    • Inputting a File
  • Introduction of Disease Dynamics
    • The Required Classes
    • Writing output to a file
  • Expanding the Network
    • Implementing multiple houses, offices, and schools
  • Introduction of Social Interventions
    • Quarantine
  • FSM in SIR
• Miscellaneous
  • Assembling an Executable .jar file
  • Importing a .jar file as a Library
  • Using args in main method
  • Saving location-level information from the simulation
• Other examples
  • Houses on a lattice
• Known Issues
  • java.util.NoSuchElementException on fetchActiveState