Package: archABM
Agent-based model simulation for air quality and pandemic risk assessment in architectural spaces.User GuidearchABMis 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.InstallationAs the compiledarchABMpackage is hosted on the Python Package
Index (PyPI) you can easily install it withpip. To installarchABM, run this command in your terminal of choice:$ pip install archABMor, alternatively:$ python -m pip install archABMIf you want to getarchABM's latest version, you can refer to the
repository hosted at github:python -m pip install https://github.com/Vicomtech/ArchABM/archive/main.zipGetting StartedUse the following template to run a simulation with archABM:# Import modulesimportjsonimportpandasaspdfromarchABM.engineimportEngine# Read configuration examplefromarchABM.configimportconfig# Alternatively, get configuration from "config.json" example# Create ArchABM simulation enginesimulation=Engine(config)# Run simulationresults=simulation.run()# Create dataframes based on the resultsdf_people=pd.DataFrame(results["results"]["people"])df_places=pd.DataFrame(results["results"]["places"])This example uses the default configuration file built-in the library.
Alternatively, you can download and modify theconfig.jsonfile found at thedatadirectory ofarchABMrepository.Developers can also use the command-line interface with themain.pyfile from the source code repository.$pythonmain.pyconfig.jsonCheck the--helpoption 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.To run an example with the CLI, download theconfig.jsonfile found at thedatadirectory ofarchABMrepository.InputsIn order to run a simulation, information about theeventtypes,people,places, and theaerosol modelmust be provided to the
ArchABM framework.EventsAttributeDescriptionTypenameEvent namestringscheduleWhen an event is permitted to happen, in minuteslist of tuplesdurationEvent duration lower and upper bounds, in minutesinteger,integernumber of repetitionsNumber of repetitions lower and upper boundsinteger,integermask efficiencyMask efficiency during an event [0-1]floatcollectiveEvent is invoked by one person but involves manybooleanallowWhether such event is allowed in the simulationbooleanPlacesAttributeDescriptionTypenamePlace namestringactivityActivity or event occurring at that placestringdepartmentDepartment namestringbuildingBuilding namestringareaRoom floor area in square metersfloatheightRoom height in meters.floatcapacityRoom people capacity.integerheightRoom height in meters.floatventilationPassive ventilation in hours-1floatrecirculated_flow_rateActive ventilation in cubic meters per hourfloatallowWhether such place is allowed in the simulationbooleanPeopleAttributeDescriptionTypedepartmentDepartment namestringbuildingBuilding namestringnum_peopleNumber of peopleintegerAerosol ModelAttributeDescriptionTypepressureAmbient pressure in atmfloattemperatureAmbient temperature in Celsius degreesfloatCO2_backgroundBackground CO2 concentration in ppmfloatdecay_rateDecay rate of virus in hours-1floatdeposition_rateDeposition to surfaces in hours-1floathepa_flow_rateHepa filter flow rate in cubic meters per hourfloatfilter_efficiencyAir conditioning filter efficiencyfloatducts_removalAir ducts removal lossfloatother_removalExtraordinary air removalfloatfraction_immuneFraction of people immune to the virusfloatbreathing_rateMean breathing flow rate in cubic meters per hourfloatCO2_emission_personCO2 emission rate at 273K and 1atmfloatquanta_exhalationQuanta exhalation rate in quanta per hourfloatquanta_enhancementQuanta enhancement due to variantsfloatpeople_with_masksFraction of people using maskfloatOptionsAttributeDescriptionTypemovement_buildingsAllow people enter to other buildingsbooleanmovement_departmentAllow people enter to other departmentsbooleannumber_runsNumber of simulations runs to executeintegersave_logSave events logsbooleansave_configSave configuration filebooleansave_csvExport the results to csv formatbooleansave_jsonExport the results to json formatbooleanreturn_outputReturn a dictionary with the resultsbooleandirectoryDirectory name to save resultsstringratio_infectedRatio of infected to total number of peoplefloatmodelAerosol model to be used in the simulationstringExample config.jsonconfig.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}}}}OutputsSimulation outputs are stored by default in theresultsdirectory. 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-%fformat.By default, three files are saved after a simulation:config.jsonstores a copy of the input configuration.people.csvstores every person's state along time.places.csvstores every places's state along time.archABMoffers the possibility of exporting the results inJSONandCSVformat. To export inJSONformat, use the--save-jsonparameter when running archABM. By default, the--save-csvparameter
is set to true.Alternatively,archABMcan also be configured to yield more detailed
information. Theapp.logfile saves the log of the actions and events
occurred during the simulation. To export this file, use the--save-logparameter when running archABM.Citing archABMIf you use ArchABM in your work or project, please cite the following article, published in theBuilding and Environmentjournal.
(https://doi.org/10.1016/j.buildenv.2021.108495):Bibtex entry:@article{MARTINEZ2021108495,title={ArchABM: An agent-based simulator of human interaction with the built environment. CO2 and viral load analysis for indoor air quality},journal={Building and Environment},pages={108495},year={2021},issn={0360-1323},doi={https://doi.org/10.1016/j.buildenv.2021.108495},url={https://www.sciencedirect.com/science/article/pii/S036013232100891X},author={Iñigo Martinez and Jan L. Bruse and Ane M. Florez-Tapia and Elisabeth Viles and Igor G. Olaizola},keywords={Agent-based modeling, Indoor air quality, Building ventilation, Aerosol model, Building design, Simulation}}