Agent-based model simulator for air quality and pandemic risk assessment in architectural spaces

Overview

Agent-based model simulation for air quality and pandemic risk assessment in architectural spaces.

PyPI Status PyPI Version License Actions Top Language Github Issues

User Guide

archABM is a fast and open source agent-based modelling framework that simulates complex human-building-interaction patterns and estimates indoor air quality across an entire building, while taking into account potential airborne virus concentrations.


Disclaimer: archABM is an evolving research tool designed to familiarize the interested user with factors influencing the potential indoor airborne transmission of viruses (such as SARS-CoV-2) and the generation of carbon-dioxide (CO2) indoors. Calculations of virus and CO2 levels within ArchABM are based on recently published aerosol models [1,2], which however have not been validated in the context of agent-based modeling (ABM) yet. We note that uncertainty in and intrinsic variability of model parameters as well as underlying assumptions concerning model parameters may lead to errors regarding the simulated results. Use of archABM is the sole responsibility of the user. It is being made available without guarantee or warranty of any kind. The authors do not accept any liability from its use.

[1] Peng, Zhe, and Jose L. Jimenez. "Exhaled CO2 as a COVID-19 infection risk proxy for different indoor environments and activities." Environmental Science & Technology Letters 8.5 (2021): 392-397.

[2] Lelieveld, Jos, et al. "Model calculations of aerosol transmission and infection risk of COVID-19 in indoor environments." International journal of environmental research and public health 17.21 (2020): 8114.


Installation

As the compiled archABM package is hosted on the Python Package Index (PyPI) you can easily install it with pip. To install archABM, run this command in your terminal of choice:

$ pip install archABM

or, alternatively:

$ python -m pip install archABM

If you want to get archABM's latest version, you can refer to the repository hosted at github:

python -m pip install https://github.com/Vicomtech/ArchABM/archive/main.zip

Getting Started

Use the following template to run a simulation with archABM:

from archABM.engine import Engine
import json
import pandas as pd

# Read config data from JSON
def read_json(file_path):
    with open(str(file_path)) as json_file:
        result = json.load(json_file)
    return result

config_data = read_json("config.json")
# WARNING - for further processing ->
# config_data["options"]["return_output"] = True

# Create ArchABM simulation engine
simulation = Engine(config_data)

# Run simulation
results = simulation.run()

# Create dataframes based on the results
df_people = pd.DataFrame(results["results"]["people"])
df_places = pd.DataFrame(results["results"]["places"])

Developers can also use the command-line interface with the main.py file from the source code repository.

$ python main.py config.json

To run an example, use the config.json found at the data directory of archABM repository.

Check the --help option to get more information about the optional parameters:

$ python main.py --help
Usage: main.py [OPTIONS] CONFIG_FILE

  ArchABM simulation helper

Arguments:
  CONFIG_FILE  The name of the configuration file  [required]

Options:
  -i, --interactive     Interactive CLI mode  [default: False]
  -l, --save-log        Save events logs  [default: False]
  -c, --save-config     Save configuration file  [default: True]
  -t, --save-csv        Export results to csv format  [default: True]
  -j, --save-json       Export results to json format  [default: False]
  -o, --return-output   Return results dictionary  [default: False]
  --install-completion  Install completion for the current shell.
  --show-completion     Show completion for the current shell, to copy it or
                        customize the installation.

  --help                Show this message and exit.

Inputs

In order to run a simulation, information about the event types, people, places, and the aerosol model must be provided to the ArchABM framework.

Events
Attribute Description Type
name Event name string
schedule When an event is permitted to happen, in minutes list of tuples
duration Event duration lower and upper bounds, in minutes integer,integer
number of repetitions Number of repetitions lower and upper bounds integer,integer
mask efficiency Mask efficiency during an event [0-1] float
collective Event is invoked by one person but involves many boolean
allow Whether such event is allowed in the simulation boolean
Places
Attribute Description Type
name Place name string
activity Activity or event occurring at that place string
department Department name string
building Building name string
area Room floor area in square meters float
height Room height in meters. float
capacity Room people capacity. integer
height Room height in meters. float
ventilation Passive ventilation in hours-1 float
recirculated_flow_rate Active ventilation in cubic meters per hour float
allow Whether such place is allowed in the simulation boolean
People
Attribute Description Type
department Department name string
building Building name string
num_people Number of people integer
Aerosol Model
Attribute Description Type
pressure Ambient pressure in atm float
temperature Ambient temperature in Celsius degrees float
CO2_background Background CO2 concentration in ppm float
decay_rate Decay rate of virus in hours-1 float
deposition_rate Deposition to surfaces in hours-1 float
hepa_flow_rate Hepa filter flow rate in cubic meters per hour float
filter_efficiency Air conditioning filter efficiency float
ducts_removal Air ducts removal loss float
other_removal Extraordinary air removal float
fraction_immune Fraction of people immune to the virus float
breathing_rate Mean breathing flow rate in cubic meters per hour float
CO2_emission_person CO2 emission rate at 273K and 1atm float
quanta_exhalation Quanta exhalation rate in quanta per hour float
quanta_enhancement Quanta enhancement due to variants float
people_with_masks Fraction of people using mask float
Options
Attribute Description Type
movement_buildings Allow people enter to other buildings boolean
movement_department Allow people enter to other departments boolean
number_runs Number of simulations runs to execute integer
save_log Save events logs boolean
save_config Save configuration file boolean
save_csv Export the results to csv format boolean
save_json Export the results to json format boolean
return_output Return a dictionary with the results boolean
directory Directory name to save results string
ratio_infected Ratio of infected to total number of people float
model Aerosol model to be used in the simulation string

Example config.json

config.json
{
    "events": [{
            "activity": "home",
            "schedule": [
                [0, 480],
                [1020, 1440]
            ],
            "repeat_min": 0,
            "repeat_max": null,
            "duration_min": 300,
            "duration_max": 360,
            "mask_efficiency": null,
            "collective": false,
            "shared": false,
            "allow": true
        },
        {
            "activity": "work",
            "schedule": [
                [480, 1020]
            ],
            "repeat_min": 0,
            "repeat_max": null,
            "duration_min": 30,
            "duration_max": 60,
            "mask_efficiency": 0.0,
            "collective": false,
            "shared": true,
            "allow": true
        },
        {
            "activity": "meeting",
            "schedule": [
                [540, 960]
            ],
            "repeat_min": 0,
            "repeat_max": 5,
            "duration_min": 20,
            "duration_max": 90,
            "mask_efficiency": 0.0,
            "collective": true,
            "shared": true,
            "allow": true
        },
        {
            "activity": "lunch",
            "schedule": [
                [780, 900]
            ],
            "repeat_min": 1,
            "repeat_max": 1,
            "duration_min": 20,
            "duration_max": 45,
            "mask_efficiency": 0.0,
            "collective": true,
            "shared": true,
            "allow": true
        },
        {
            "activity": "coffee",
            "schedule": [
                [600, 660],
                [900, 960]
            ],
            "repeat_min": 0,
            "repeat_max": 2,
            "duration_min": 5,
            "duration_max": 15,
            "mask_efficiency": 0.0,
            "collective": true,
            "shared": true,
            "allow": true
        },
        {
            "activity": "restroom",
            "schedule": [
                [480, 1020]
            ],
            "repeat_min": 0,
            "repeat_max": 4,
            "duration_min": 3,
            "duration_max": 6,
            "mask_efficiency": 0.0,
            "collective": false,
            "shared": true,
            "allow": true
        }
    ],
    "places": [{
            "name": "home",
            "activity": "home",
            "building": null,
            "department": null,
            "area": null,
            "height": null,
            "capacity": null,
            "ventilation": null,
            "recirculated_flow_rate": null,
            "allow": true
        },
        {
            "name": "open_office",
            "activity": "work",
            "building": "building1",
            "department": ["department1", "department2", "department3", "department4"],
            "area": 330.0,
            "height": 2.7,
            "capacity": 60,
            "ventilation": 1.5,
            "recirculated_flow_rate": 0,
            "allow": true
        },
        {
            "name": "it_office",
            "activity": "work",
            "building": "building1",
            "department": ["department4"],
            "area": 52.0,
            "height": 2.7,
            "capacity": 10,
            "ventilation": 1.5,
            "recirculated_flow_rate": 0,
            "allow": true
        },
        {
            "name": "chief_office_A",
            "activity": "work",
            "building": "building1",
            "department": ["department5", "department6", "department7"],
            "area": 21.0,
            "height": 2.7,
            "capacity": 5,
            "ventilation": 1.5,
            "recirculated_flow_rate": 0,
            "allow": true
        },
        {
            "name": "chief_office_B",
            "activity": "work",
            "building": "building1",
            "department": ["department5", "department6", "department7"],
            "area": 21.0,
            "height": 2.7,
            "capacity": 5,
            "ventilation": 1.5,
            "recirculated_flow_rate": 0,
            "allow": true
        },
        {
            "name": "chief_office_C",
            "activity": "work",
            "building": "building1",
            "department": ["department5", "department6", "department7"],
            "area": 24.0,
            "height": 2.7,
            "capacity": 5,
            "ventilation": 1.5,
            "recirculated_flow_rate": 0,
            "allow": true
        },
        {
            "name": "meeting_A",
            "activity": "meeting",
            "building": "building1",
            "department": ["department1", "department2", "department3", "department5", "department6", "department7"],
            "area": 16.0,
            "height": 2.7,
            "capacity": 6,
            "ventilation": 1.0,
            "recirculated_flow_rate": 0,
            "allow": true
        },
        {
            "name": "meeting_B",
            "activity": "meeting",
            "building": "building1",
            "department": ["department1", "department2", "department3", "department5", "department6", "department7"],
            "area": 16.0,
            "height": 2.7,
            "capacity": 6,
            "ventilation": 1.0,
            "recirculated_flow_rate": 0,
            "allow": true
        },
        {
            "name": "meeting_C",
            "activity": "meeting",
            "building": "building1",
            "department": ["department1", "department2", "department3", "department5", "department6", "department7"],
            "area": 11.0,
            "height": 2.7,
            "capacity": 4,
            "ventilation": 1.0,
            "recirculated_flow_rate": 0,
            "allow": true
        },
        {
            "name": "meeting_D",
            "activity": "meeting",
            "building": "building1",
            "department": null,
            "area": 66.0,
            "height": 2.7,
            "capacity": 24,
            "ventilation": 1.5,
            "recirculated_flow_rate": 0,
            "allow": true
        },
        {
            "name": "coffee_A",
            "activity": "coffee",
            "building": "building1",
            "department": null,
            "area": 25.0,
            "height": 2.7,
            "capacity": 10,
            "ventilation": 1.5,
            "recirculated_flow_rate": 0,
            "allow": true
        },
        {
            "name": "coffee_B",
            "activity": "coffee",
            "building": "building1",
            "department": null,
            "area": 55.0,
            "height": 2.7,
            "capacity": 20,
            "ventilation": 1.5,
            "recirculated_flow_rate": 0,
            "allow": true
        },
        {
            "name": "restroom_A",
            "activity": "restroom",
            "building": "building1",
            "department": null,
            "area": 20.0,
            "height": 2.7,
            "capacity": 4,
            "ventilation": 1.0,
            "recirculated_flow_rate": 0,
            "allow": true
        },
        {
            "name": "restroom_B",
            "activity": "restroom",
            "building": "building1",
            "department": ["department1", "department2", "department3", "department4", "department5", "department6"],
            "area": 20.0,
            "height": 2.7,
            "capacity": 4,
            "ventilation": 1.0,
            "recirculated_flow_rate": 0,
            "allow": true
        },
        {
            "name": "lunch",
            "activity": "lunch",
            "building": "building1",
            "department": null,
            "area": 150.0,
            "height": 2.7,
            "capacity": 60,
            "ventilation": 1.5,
            "recirculated_flow_rate": 0,
            "allow": true
        }
    ],
    "people": [{
            "department": "department1",
            "building": "building1",
            "num_people": 16
        },
        {
            "department": "department2",
            "building": "building1",
            "num_people": 16
        },
        {
            "department": "department3",
            "building": "building1",
            "num_people": 16
        },
        {
            "department": "department4",
            "building": "building1",
            "num_people": 7
        },
        {
            "department": "department5",
            "building": "building1",
            "num_people": 2
        },
        {
            "department": "department6",
            "building": "building1",
            "num_people": 2
        },
        {
            "department": "department7",
            "building": "building1",
            "num_people": 1
        }
    ],
    "options": {
        "movement_buildings": true,
        "movement_department": false,
        "number_runs": 1,
        "save_log": true,
        "save_config": true,
        "save_csv": false,
        "save_json": false,
        "return_output": false,
        "directory": null,
        "ratio_infected": 0.05,
        "model": "Colorado",
        "model_parameters": {
            "Colorado": {
                "pressure": 0.95,
                "temperature": 20,
                "CO2_background": 415,
                "decay_rate": 0.62,
                "deposition_rate": 0.3,
                "hepa_flow_rate": 0.0,
                "recirculated_flow_rate": 300,
                "filter_efficiency": 0.20,
                "ducts_removal": 0.10,
                "other_removal": 0.00,
                "fraction_immune": 0,
                "breathing_rate": 0.52,
                "CO2_emission_person": 0.005,
                "quanta_exhalation": 25,
                "quanta_enhancement": 1,
                "people_with_masks": 1.00
            }
        }
    }
}

Outputs

Simulation outputs are stored by default in the results directory. The subfolder with the results of an specific simulation have the date and time of the moment when it was launched as a name in %Y-%m-%d_%H-%M-%S-%f format.

By default, three files are saved after a simulation:

  • config.json stores a copy of the input configuration.
  • people.csv stores every person's state along time.
  • places.csv stores every places's state along time.

archABM offers the possibility of exporting the results in JSON and CSV format. To export in JSON format, use the --save-json parameter when running archABM. By default, the --save-csv parameter is set to true.

Alternatively, archABM can also be configured to yield more detailed information. The app.log file saves the log of the actions and events occurred during the simulation. To export this file, use the --save-log parameter when running archABM.


Citing archABM

If you use ArchABM in your work or project, please cite the following article, published in Building and Environment (DOI...): [Full REF]

@article{
}
Owner
Vicomtech
Applied Research in Visual Computing & Interaction and Artificial Inteligence - Official Github Account - Member of Basque Research & Technology Alliance, BRTA
Vicomtech
A framework that constructs deep neural networks, autoencoders, logistic regressors, and linear networks

A framework that constructs deep neural networks, autoencoders, logistic regressors, and linear networks without the use of any outside machine learning libraries - all from scratch.

Kordel K. France 2 Nov 14, 2022
Robot Reinforcement Learning on the Constraint Manifold

Implementation of "Robot Reinforcement Learning on the Constraint Manifold"

31 Dec 05, 2022
Official code for "Simpler is Better: Few-shot Semantic Segmentation with Classifier Weight Transformer. ICCV2021".

Simpler is Better: Few-shot Semantic Segmentation with Classifier Weight Transformer. ICCV2021. Introduction We proposed a novel model training paradi

Lucas 103 Dec 14, 2022
Who calls the shots? Rethinking Few-Shot Learning for Audio (WASPAA 2021)

rethink-audio-fsl This repo contains the source code for the paper "Who calls the shots? Rethinking Few-Shot Learning for Audio." (WASPAA 2021) Table

Yu Wang 34 Dec 24, 2022
Boosting Adversarial Attacks with Enhanced Momentum (BMVC 2021)

EMI-FGSM This repository contains code to reproduce results from the paper: Boosting Adversarial Attacks with Enhanced Momentum (BMVC 2021) Xiaosen Wa

John Hopcroft Lab at HUST 10 Sep 26, 2022
Pathdreamer: A World Model for Indoor Navigation

Pathdreamer: A World Model for Indoor Navigation This repository hosts the open source code for Pathdreamer, to be presented at ICCV 2021. Paper | Pro

Google Research 122 Jan 04, 2023
Trans-Encoder: Unsupervised sentence-pair modelling through self- and mutual-distillations

Trans-Encoder: Unsupervised sentence-pair modelling through self- and mutual-distillations Code repo for paper Trans-Encoder: Unsupervised sentence-pa

Amazon 101 Dec 29, 2022
Face Synthetics dataset is a collection of diverse synthetic face images with ground truth labels.

The Face Synthetics dataset Face Synthetics dataset is a collection of diverse synthetic face images with ground truth labels. It was introduced in ou

Microsoft 608 Jan 02, 2023
Official pytorch implementation of the AAAI 2021 paper Semantic Grouping Network for Video Captioning

Semantic Grouping Network for Video Captioning Hobin Ryu, Sunghun Kang, Haeyong Kang, and Chang D. Yoo. AAAI 2021. [arxiv] Environment Ubuntu 16.04 CU

Hobin Ryu 43 Nov 25, 2022
A High-Quality Real Time Upscaler for Anime Video

Anime4K Anime4K is a set of open-source, high-quality real-time anime upscaling/denoising algorithms that can be implemented in any programming langua

15.7k Jan 06, 2023
Code for our paper: Online Variational Filtering and Parameter Learning

Variational Filtering To run phi learning on linear gaussian (Fig1a) python linear_gaussian_phi_learning.py To run phi and theta learning on linear g

16 Aug 14, 2022
Official implementation for the paper "Attentive Prototypes for Source-free Unsupervised Domain Adaptive 3D Object Detection"

Attentive Prototypes for Source-free Unsupervised Domain Adaptive 3D Object Detection PyTorch code release of the paper "Attentive Prototypes for Sour

Deepti Hegde 23 Oct 17, 2022
Official implementation of Protected Attribute Suppression System, ICCV 2021

Official implementation of Protected Attribute Suppression System, ICCV 2021

Prithviraj Dhar 6 Jan 01, 2023
Pre-trained NFNets with 99% of the accuracy of the official paper

NFNet Pytorch Implementation This repo contains pretrained NFNet models F0-F6 with high ImageNet accuracy from the paper High-Performance Large-Scale

Benjamin Schmidt 133 Dec 09, 2022
Autonomous Driving on Curvy Roads without Reliance on Frenet Frame: A Cartesian-based Trajectory Planning Method

C++/ROS Source Codes for "Autonomous Driving on Curvy Roads without Reliance on Frenet Frame: A Cartesian-based Trajectory Planning Method" published in IEEE Trans. Intelligent Transportation Systems

Bai Li 88 Dec 23, 2022
Automatic Idiomatic Expression Detection

IDentifier of Idiomatic Expressions via Semantic Compatibility (DISC) An Idiomatic identifier that detects the presence and span of idiomatic expressi

5 Jun 09, 2022
WaveFake: A Data Set to Facilitate Audio DeepFake Detection

WaveFake: A Data Set to Facilitate Audio DeepFake Detection This is the code repository for our NeurIPS 2021 (Track on Datasets and Benchmarks) paper

Chair for Sys­tems Se­cu­ri­ty 27 Dec 22, 2022
​TextWorld is a sandbox learning environment for the training and evaluation of reinforcement learning (RL) agents on text-based games.

TextWorld A text-based game generator and extensible sandbox learning environment for training and testing reinforcement learning (RL) agents. Also ch

Microsoft 983 Dec 23, 2022
Explainable Zero-Shot Topic Extraction

Zero-Shot Topic Extraction with Common-Sense Knowledge Graph This repository contains the code for reproducing the results reported in the paper "Expl

D2K Lab 56 Dec 14, 2022
an implementation of 3D Ken Burns Effect from a Single Image using PyTorch

3d-ken-burns This is a reference implementation of 3D Ken Burns Effect from a Single Image [1] using PyTorch. Given a single input image, it animates

Simon Niklaus 1.4k Dec 28, 2022