Abstract

We developed a software tool in collaboration with the Team Hannover iGEM, which enables the user to run a molecular dynamics simulation of biofilm growth. The program is implemented in python and documented in detail on both Wikis and GitHub repository. The software tool not only provides the numerical model but various functions to visualize the results and access the data. The software is optimized to make use of the full computational power of the local machine. All of the used parameters and formulas are well documented. In our example notebook, we explain in detail how to adapt the model for its purposes. We implemented a specific class, to enable the user to switch easily between simulation constants and even different compositions of biofilms. Furthermore, we followed a comprehensive programming approach, to encourage future iGEM teams to contribute to the project.

Why did we do this?

The iGEM project of our team is to reduce pollutants like diclofenac out of wastewater. As we had limited lab time we wanted a simulation to see if our biofilm can withstands the conditions of a sewage plant. As Team Hannover developed a model that used molecular dynamics to model the behaviour of a bacteria in a biofilm, we got into contact. The iGEM project of team Hannover is the development of a "InToSens" (Inflammatory Toxin Sensor) made of biological components, which helps to diagnose the adherence of toxic biofilms to implant surfaces. By detecting the attachment of a biofilm at an early stage, they aim to maximise the chance for treatment success. Therefore, both teams are greatly interested in the mechanisms and parameters that cause and influence the formation of biofilms. The developed model takes into account a diverse set of biological and physical parameters and enables the user, to quantitatively investigate the influence of different parameters on early biofilm formation we teamed up with the iGEM Team Hannover to discuss our model throughout the development. As the both teams are interested in different biofilm compositions and influencing parameters, we made great effort to make the model as flexible as possible. In the following, we focus on a short overview and a demonstration on how to use the software. If you are interested in details on the implementation and methods, check out Teams Hannover's model Wiki page or the GitHub repository.

What do we provide?

The software tool includes the implementation of three class and utility function to store, access and visualize the data generated in the simulation (Figure 1). The main part of the code is the implementation of three classes.

The bacteria class is our object-orientated representation of the bacteria in the biofilm. Instances of the bacteria class have parameters regarding their movement and interaction with other bacteria and the surrounding media. Additionally, the parameters are completed with a set of biological inspired parameters. Throughout the simulation, the parameters of each bacteria are exported in a dictionary and save in the convenient JSON format.

In the biofilm class the simulation takes place. An initial configuration of bacteria can be spawned and are stored in a list as a parameter of the biofilm instance. A biofilm class method iterates over this list, updates the parameters of each bacteria and calculates interaction forces using a biophysical potential and drag force. Because the computation gets complex quickly, we use multiprocessing to use all of the CPU cores of the users local machine.

The constants class represents the interface, with which the user can specify the simulation constants like duration, step size and output paths. Furthermore, constants like the number of initial bacteria and the bacterial strain, of which the biofilm consist, can be set with methods of this class. Selecting a bacterial strain results in different properties of the bacteria in the simulated biofilm. We provide the regarding constants of two bacterial strains Escherichia coli and Bacillus subtilis, between which the user can choose. Each strain comes with a dictionary of constants regarding the biological properties of this strain. All constants are well researched and documented on our wiki as well as in the code itself. The implementation of additional strains is intuitive, which makes the software tool easily extendable. The user can run a simulation and set the parameters on their one local machine by writing few lines of python code or even less, if he wants to use the default values.

Below you can see a class diagram of our software tool:

Application

Prerequisites

Because the software tool is implemented in the python language, there are a few requisites before we can dive into the code. First of all the user will need an installation of python on its machine. We recommend the installation of the open-source distribution "anaconda". With this, the user can make use of all the features included in our tool. The installation of anaconda includes python itself, the development enviroment (IDE) Spyder and Jupyter, a web based tool for interactive programming. Once you installed anaconda, our software tool has to be copied to the local machine. Open up a console and navigate in the the folder, in which you want to clone the repository Then type

    git clone https://github.com/igemsoftwareadmin/Hannover.git

As mentioned above, our model uses a number of open-source python packages, which you will need to install. Open up a anaconda console and navigate in the env folder of our repository. By typing

    conda env create -f biofilm_model_env.yml

you will get all of the needed packages. This file stores the settings of our so called “python enviroment”, which includes all the tools needed for running our software. Activate the above environment by typing

    conda activate biofilm_model_env

and install the BiofilmSimulation software tool via pip:

    pip install BiofilmSimulation

Now you got everything you need, to start our BiofilmSimulation tool on your computer. We note that the terminal commands can slightly differ depending on the operating system installed on your local machine. If you are having trouble installing the module, open an issue at our GitHub page.

How to run it

To directly start with the simulation type

    jupyter-notebook

This will open up a webbrowser running with Jupyter. Navigate to the folder, in which you just cloned the repository and jump into the example by clicking on the example.ipynb file. If the browser does not show up automatically, open it manually and connect to

    http://localhost:8888/

In the jupyter notebook, we explaisn how to use our software tool the intended way. We included explanation of the functions and briefly analyze the results. For more detailed explanation of the outputs, check out Hannover's Model page.

How to modify the source code

Our code is easily extendable. Here we present some approaches to modify the source code. The BiofilmSimulation module provides constants of two bacterial strains. If you want to add more strains, you can do so by researching the needed constants and storing them in a python dictionary. The dictionary has to be in the following format

    ecoli_dic = {
    "LENGTH": np.abs(np.random.normal(loc=1, scale=0.14)),
    # [um]
    "WIDTH": 0.5 ,  # [um]
    "MASS": 10 ** (-12),  # [kg]
    "MORTALITY_RATE": 0.01,  # [% / 100]
    "CRITICAL_LENGTH": 3.5,  # [um]
    "FREE_MEAN_SPEED": 50,  # [um / s]
    "DOUBLING_TIME": 1200,  # [s]
    "GROWTH_RATE": 1 / 1200,  # [um / s]
    "MOTION_ACTIVATION_PROBABILITY": 0.005,  # [% / 100]
    "MOTION_DEACTIVATION_PROBABILITY": 0.01  # [% / 100]
}

Open up the source code in constants.py in a editior of your choice. If you installed anaconda you can use the Spyder IDE, which comes with the anaconda installation. By copying the

    get_ecoli_constants(key: str = None)

function and replacing the dictionary choosing a unique function name you already did half of the work. Now, you will have to add your function to the set_bacteria_constants() method. Add an elif statement at the end of the function in the following way:

    def set_bacteria_constants(self, default=True):
    """ set constants according to selected bacteria strain """
    if self.bac_type == "B.Sub." and default:
    self.bac_constants = Constants.get_bsub_constants()
    elif self.bac_type == "E.Coli." and default:
    self.bac_constants = Constants.get_ecoli_constants()
    elif self.bac_type == "Your_bacteria_strain_name" and default:
    self.bac_constants = Constants.your_unique_function_name()

and you are done.
Now you can run the simulation with your bacterial strain by specifying

    constants = Constants(bac_type="Your_bacteria_strain_name" ) 

in your custom script or in the example_usage script.
A neat feature of the code is, that the bacteria can easily be extended by additional parameters. When adding a new parameter like "self.some_protein_concentration" to the "__init__" function and updating the return value of the "get_bacteria_dict" function accordingly, the new parameter will be automatically stored in the output data and can be accessed with our data handling function. This allows to easily extend the bacteria properties in the simulation. Further extensions, e.g. adding new forces are also possible but will require a little bit more effort. For this we suggest that you look at the implementation of the "update_acting_forces" method of the bacteria class and the formulas in the formulas.py script.
Another possible contribution can be the implementation of new visualization methods. Almost all of our visualization functions make use of the "get_data_to_parameter" function in the data_handling.py script. This functions enables you to pass the parameter you are interested in, e.g. the "velocity" and get a pandas array with the respective data for each bacteria for every time step.

We are excited which contributions you will add to the open-source project!

Parameter List

The parameter below are the one we store in our dictionaries and used for our B. subtilis simulations. Click here to the results of our simulations.

Table 1: General

Parameter	Unit	expected value	Varianz	reference
Maximum bacteria substrate adhesion force	N	7 * 1E-9	0	[1]
Maximum bacteria- bacteria adhesion force	N	6.81 * 1E-9	0	[1]
Effective viscosity of EPS	Pa * s	log(1E5)	0	[2]
Effective viscosity of water	Pa * s	0.7805 * 1E-3	0