Team:BCCS-Bristol/Modeling/HowBSimWorks

From 2009.igem.org

Revision as of 13:50, 25 September 2009 by Amaty (Talk | contribs)

BCCS-Bristol
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. We present a walkthrough of creating a fully-featured simulation of hundreds of bacteria exhibiting a classic run-and-tumble motion. All examples presented here are included with the BSim 2.0 distribution (To be uploaded soon...).

The new 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 Sun Website, including a number of 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 simualtion 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

On it way very soon.

Concept - how BSim Simulations should work

Moved to end temporarily - do we still want this here?

scene.particles.add(
  new Bacterium(position: 0 1 0, radius: 1),
  new Bacterium(position: 0 1 0, radius: 1),
  new Bacterium(position: 0 1 0, radius: 1),
  new Bead(position: 0 1 0),
);

b = new Bacterium()
b.grn(new GRN(dy/dx = -2x; dx/dz = y^2))
scene.particles.add(b);

scene.chemicalFields.add(
  new ChemicalField(chemical: aspartate),
  new ChemicalField(chemical: AHL)
)

scene.boundaries(..)
scene.dt(..)
scene.simulationTime(..)

app.renderer(new ProcessingRenderer())
app.exporters.add(
  new FileExporter(),
  new MovieExporter(),
  new ScreenshotExporter()
)
app.gui()