"
Team:BCCS-Bristol/Modeling/HowBSimWorks
From 2009.igem.org
iGEM 2009
Contents |
How BSim works
In this section we discuss the new structure of BSim simulations and the improvements made in how they are specified. All examples presented here are included with the BSim 2009 distribution (To be uploaded soon...).
We present two walkthroughs for creating basic simulations in BSim:
- The first tutorial describes the basics of a BSim simulation file, and the steps required to create a single bacterium.
- The second tutorial provides a detailed overview of the core features of a BSim simulation file. In the simulation, we create 100 bacteria exhibiting classic run and tumble behaviour and detect collisions between the bacteria by changing their colour from green to red (any such activity can also be easily logged and imported into a numerical analysis package e.g. MATLAB or Excel). The following video shows the simulation running over a 100x100x100 micron volume for 30 seconds.
New Simulation Structure
When we set out to restructure BSim it was decided that it should be made much more versatile and adaptable, and that as much as possible of the physics and coding should effectively be behind the scenes. This would allow stronger focus on the biological aspects of the simulation. To this end BSim has now been rebuilt as an environment where the user takes various functionalities already in place and uses them to create a simulation tailored to their specific requirements.
The creation of a BSim simulation requires a basic working knowledge of the Java programming language. However as stated above, in designing the new structure of the BSim environment we have endeavoured to provide a toolkit that would also be useful to people without a programming background. The BSim distribution will include complete documentation for all available functions, and numerous example simulations showcasing the available features.
Comprehensive and complete Java documentation can be found on the [http://java.sun.com/javase/reference/index.jsp Sun Website], including a number of [http://java.sun.com/docs/books/tutorial/ tutorial trails]. However for help on a specific function it is often easier to perform an internet search for "Java" followed by the name of the function.
Example 1: The simplest simulation!
Arguably the simplest simulation would be a single bacterium floating around in a viscous medium. In this example we define an example file in which we create a new simulation, add a single bacterium with classic run-tumble motion, and define parameters for drawing the bacterium.
Step 1: Create the simulation file. Create a new java file called "BSimSimplestExample.java". Now we define the class that will contain the simulation and the "main" method which is called when running the simulation.
public class BSimSimplestExample {
public static void main(String[] args) {
}
}
Step 2: Define a new BSim simulation. We must now write the code to define the simulation inside our "main" method. Here we define a new instance of the BSim simulation environment as follows:
BSim sim = new BSim();
Step 3: Create a bacterium. This is a single line in which we define one bacterium instance. When creating the bacteriun we need to specify that the bacterium is attached to our simulation "sim" variable, and specify the starting position of the bacterium using the "Vector3d" constructor which specifies an "X, Y, Z" position in the 3D environment.
final BSimBacterium bacterium = new BSimBacterium(sim, new Vector3d(50,50,50));
Step 4: Create a "BSimTicker". A BSimTicker object will iterate at every time-step of the simulation, so we must specify here what we want to occur as the simulation runs. First we assign the ticker to our simulation object, then define what we want to occur at each time-step using the "tick()" method. In this case all we want the bacterium to do is perform run-tumble motion through our environment, which is its default "action()" method. We then need to update the position of the bacterium for that time-step.
sim.setTicker(new BSimTicker() {
@Override
public void tick() {
bacterium.action();
bacterium.updatePosition();
}
});
Step 5: Create a "drawer" object to display the simulation. The "drawer" defines what should be drawn (to screen or to a file) at each time step. Here we simply specify the size of our display area as 800 by 600 pixels when we create a new BSimP3DDrawer object, and then specify that we want our bacterium "bacterium" drawn as a green coloured sphere.
sim.setDrawer(new BSimP3DDrawer(sim, 800,600) {
@Override
public void scene(PGraphics3D p3d) {
draw(bacterium,Color.GREEN);
}
});
Step 6: Draw the simulation to screen. The final step of a simulation definition is to specify what we want to do with the generated data. In this case we just want to show the motion of the bacterium on the screen, so we add the following line at the end of our "main" method:
sim.preview();
This tells BSim to create a new window when the simulation is run and draw the bacterium's behaviour to the screen.
The result? Congratulations, you have created your first running, tumbling bacterium!
Example 2: BSimTutorialExample; A detailed outline of a complete simulation specification
The tutorial example was designed to show the user how to implement many of the features one by one in a clear modular fashion, and with an explanation of the options available for each of the features.
