BharatSim Documentation

Welcome to this BharatSim Tutorial!

BharatSim is a collaborative project between Ashoka University and Thoughtworks, funded by the Bill & Melinda Gates Foundation. Its vision is to build a simulation framework that is distributed, multi-scale, and agent-based for use by the scientific community. It was originally designed to run decision-critical scenarios for India during the COVID-19 pandemic. Real-world 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. 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. Agent-based modeling accounts for individual differences and allows us to simulate scenarios of varying complexity. These simulations can guide policy level interventions (eg. lockdowns).

BharatSim 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, locations, and their relations like nodes and edges on a 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 textit{Scala} programming language, thus allowing modellers to extend their knowledge of textit{Scala} when creating their models.

• Visualization engine: BharatSim also includes a dashboard visualisation tool that allows the user to view multiple types of results at the same time. The visualisation engine can be used to plot and analyse the outputs generated by the simulation engine. It possesses a customizable 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 by no means 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
  • Setting up Scala
    • 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
  • Inputs and Outputs in BharatSim
    • Inputs
      • Using the framework-defined functions
      • Using the User-Defined function
    • Outputs
      • 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
  • Optimisation
    • PerTickCache
      • Example for PerTickCache implementation:
    • Outputting data to a csv
      • The target to be optimized
      • A (naive) approach to help
      • The fastest solution
• 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