How to run abmSHARE with Google Colab#

On This link you can find a Sandbox example with a simple input folder that contans all input data the abmSHARE model needs. You can also find a predefined Google Colab notebooks to run a short default simulation, download its output and analyze the results in another Google Colab notebook.

Google Colab is a hosted Jupyter Notebook service that requires no setup to use and provides free access to computing resources, including GPUs and TPUs. For more information see Google Colab information.

These interactive notebooks allow the user to try the abmSHARE model, test it, and run it with different parameters. The recommended way of running the abmSHARE is to install it on a local device or run in HPC with parallel simulation processing enabled due to its demands on RAM capacity.

How to Run the abmSHARE Model#

Google Colab Default Simulation#

Link to the Google Drive ABMShare_data folder and click on the Collab file ABMShare_run.ipynb file to open the Notebook.

This notebook will let you clone and install the most recent version of abmSHARE model. You can also use this notebook locally. For instructions see the official Github repo. Full documentation of the abmSHARE model is available at the official SHARE-CZ SITE.

A default simulation is run in a Google Colab notebook structure prepared for an example with 20,000 population in each of eight NUTS2 regions in the Czech Republic.

After you run this default simulation and become familiar with the basic features, it is recommended that you download your own copy of this notebook by running - File -> Save Copy on Disc, change parameters and make your own simulations.

You can run the simulation with input data copied in to current runtime, or Mount your Google Disc contained in the sandbox folder with all neccessary input data. In the file manager it will be the drive folder. THIS IS NOT CLEAR.

The simulation is run in five notebook cells:

1. Installation#

Click on the play icon to execute this cell.

It will install the latest version of abmSHARE in the current Google Colab Runtime.

2. Input data#

This cell downloads the sandbox input data to you current Google Colab Runtime (or to your current location if you run the simulation locally).

The default simulation is run on all eight NUTS2 regions in the Czech Republic. Each region has a population of 20,000 agents.

You can download example input data as well as this notebook from Google Drive.

You can also prepare your own input data and parameters in your Google drive and mount that folder to your current Google Colab Runtime.

3. Editing default paths#

This cell is optional (everything will work if you run the cell without changing its content).

abmSHARE is build upon various input files, which has interdependencies and those are defined by absolute paths to these files. If you want to use your own path, change the code in the cell by replacing the default <Path_to_sandbox> with your own path.

You can run it with any pattern. The function goes through all directories recursively and it will replace any string path in all csv|xlsx|json|yaml files.

4. Running the simulation#

Using the default or your own path for the main configuration file, you can run the simulation.

The simulation requires only one configuration file by default. The main configuration file contains correct paths for all dependent configuration files in each module. All details are described in the documentation.

You can see the aggregate intermediate results for each day N of the simulation on the screen:

Day: N   Infections   [ new / total ]   Deaths   [ new / total ]

After the simulation is complete, its output is saved in the default outputs/ directory in a folder whose name has the current time stamp.

Each simulation is saved in its own folder. You can change the output folder in the save_settings section in main configuration file.

5. Download the results#

The results are stored in csv and xlsx files for each region and for the aggregate outcomes.

Multiple files cannot be easily downloaded in Google Colab. To download all input and output data, run this cell to create a zip file Output_ABMShare.zip to the default directory /content/ABMShare_data/outputs.

Then you can right click the zipped file to download it and use your own analytic and graphic tools to analyze the results.

Additional instructions:#

The input sandbox of the Google Disc will be downloaded in current Google Colab Runtime content that can be accessed by clicking the folder image on the left sidebar in Figure 1.

Figure 1 - Google Colab Runtime content
Figure 1

The default sandbox has a predefined pattern <Path_to_sandbox> but you can also choose another pattern. The replacement pattern must contain the full path to the sandbox folder with all input/output directories and files. To get the full path follow Figure 2 by right-clicking the proper directory and select Copy Full Path.

Figure 2 - Copy full path
Figure 2