Difference between revisions of "Chemotaxis"

From Biocellion
Jump to: navigation, search
 
(4 intermediate revisions by the same user not shown)
Line 1: Line 1:
This tutorial will guide you through the steps of adding a chemotactic force to the cells in your simulation. Existing requirements for chemotaxis include a population of agents, a chemical field to contain a chemoattractant, and a method of adding/moving chemoattractant concentrations throughout the field (such as secretion and diffusion with decay). The agents will move along the chemical gradient toward the chemoattractant.
+
This tutorial will guide you through the steps of adding a chemotactic force to the cells in your simulation. Existing requirements for chemotaxis include a population of agents, a diffusing chemical field to spread a chemoattractant, and a method of adding/changing chemoattractant concentrations throughout the field (such as secretion and decay). The agents will move along the chemical gradient toward the chemoattractant.
  
 
This page focuses on the approach and implementation specific to the chemotactic force, which samples the chemical field for its chemoattractant concentrations.
 
This page focuses on the approach and implementation specific to the chemotactic force, which samples the chemical field for its chemoattractant concentrations.
Line 16: Line 16:
 
== Implementation ==
 
== Implementation ==
  
The following code implements the method described above. The code is broken into individual snippets in order to illustrate the steps, but the code may be viewed in whole [https://github.com/djholt/biocellion-chemotaxis/blob/master/model_routine_agent.cpp here]. The code is part of the <code>ModelRoutine::adjustSpAgent()</code> method within <tt>model_routine_agent.cpp</tt>.
+
The following code implements the method described above. The code is broken into individual snippets in order to illustrate the steps, but the code may be viewed in whole [https://github.com/djholt/biocellion-chemotaxis/blob/master/model_routine_agent.cpp here]. This code is part of the <code>ModelRoutine::adjustSpAgent()</code> method within <tt>model_routine_agent.cpp</tt>.
  
  
Calculate a random, normalized forward vector, and a backward vector in the opposite direction.
+
Calculate a random, normalized forward vector, and a backward vector in the opposite direction. In code, <code>fwdDir</code> represents <math>\vec c</math>, and <code>bckDir</code> represents <math>-\vec c</math>.
 
  <nowiki>
 
  <nowiki>
 
/* forward and backward direction vectors */
 
/* forward and backward direction vectors */
Line 40: Line 40:
  
  
Determine which two neighbor boxes (of the 26 neighbors) intersect with the forward and backward vectors, and then read the forward and backward chemoattractant values.
+
Determine which two neighbor boxes (of the 26 neighbors) intersect with the forward and backward vectors, and then read the forward and backward chemoattractant values. In code, <code>fwdVal</code> represents <math>C^+</math>, and <code>bckVal</code> represents <math>C^-</math>.
 
  <nowiki>
 
  <nowiki>
 
/* find the nearest neighbor interface (x, y, or z) in both the
 
/* find the nearest neighbor interface (x, y, or z) in both the
Line 67: Line 67:
  
  
Calculate the chemotactic force, apply it (if it's positive), and finally limit the force if it moves the particle more than the width of a single box.
+
Calculate the chemotactic force, apply it (if it's positive), and finally limit the force if it would move the particle more than the width of a single box. In code, <code>chemForce</code> represents <math>\triangle F</math>, and <code>A_CELL_CHEMOTAXIS_FORCE_STRENGTH</code> represents <math>\lambda</math>.
 
  <nowiki>
 
  <nowiki>
 
/* calculate the chemotactic force, and apply it if positive */
 
/* calculate the chemotactic force, and apply it if positive */
Line 90: Line 90:
 
== Steps ==
 
== Steps ==
  
# A
+
A reference implementation of the following steps (including the prerequisite steps) can be found [https://github.com/djholt/biocellion-chemotaxis here]. It was written and tested against Biocellion v1.1.
# B
+
 
 +
=== Prerequisites ===
 +
 
 +
# Supply a population of agents which will exhibit chemotactic forces (and possibly other biomechanical forces). See the <code>ModelRoutine::addSpAgents()</code> method within <tt>model_routine_agent.cpp</tt>.
 +
# Introduce a chemical field that allows for the diffusing and decay of a chemoattractant. See the methods within <tt>model_routine_grid.cpp</tt>.
 +
# Provide a method to allow for production of a chemoattractant within the field, such as cell secretion. See the <code>ModelRoutine::updateIfGridVar()</code> method within <tt>model_routine_grid.cpp</tt> for a simple implementation of cell secretion, whereby all agents continuously secrete chemoattractant at a constant rate.
 +
 
 +
=== Chemotaxis ===
 +
 
 +
# Declare and provide values for all necessary constant parameters within <tt>model_define.h</tt>. Relevant parameters from the reference implementation include:
 +
## DIFFUSIBLE_ELEM_DECAY_RATE (used in <tt>model_routine_grid.cpp</tt>).
 +
## DIFFUSIBLE_ELEM_DIFFUSION_COEFFICIENT (used in <tt>model_routine_grid.cpp</tt>).
 +
## A_CELL_CHEMOATTRACTANT_SECRETION_RATE (used in <tt>model_routine_grid.cpp</tt>).
 +
## A_CELL_CHEMOTAXIS_FORCE_STRENGTH (used in <tt>model_routine_agent.cpp</tt>).
 +
# Add the code which calculates and applies the chemotactic forces (described in detail above) to the <code>ModelRoutine::adjustSpAgent()</code> method within <tt>model_routine_agent.cpp</tt>.
 +
# If using the chemotaxis code directly from the reference implementation, do not forget to include the <code>findNearestInterface()</code> function that is declared within <tt>model_routine_agent.cpp</tt>.
 +
 
 +
=== Run and Visualize ===
 +
 
 +
After running the simulation, open ParaView and load the agent and chemoattractant output files. Visualize the agents by rendering a glyph for the agent output, and visualize the chemoattractant by rendering a slice for each partition of the chemoattractant output. As time progresses, the chemotactic force should move the agents along the chemical gradient, toward the higher concentrations of chemoattractant within the field.
 +
 
 +
== Resources ==
 +
 
 +
* [https://github.com/djholt/biocellion-chemotaxis Chemotaxis reference implementation]

Latest revision as of 05:45, 16 December 2016

This tutorial will guide you through the steps of adding a chemotactic force to the cells in your simulation. Existing requirements for chemotaxis include a population of agents, a diffusing chemical field to spread a chemoattractant, and a method of adding/changing chemoattractant concentrations throughout the field (such as secretion and decay). The agents will move along the chemical gradient toward the chemoattractant.

This page focuses on the approach and implementation specific to the chemotactic force, which samples the chemical field for its chemoattractant concentrations.

Method

In this example, a simple method is used to calculate the chemotactic force on a particle which responds to a chemoattractant , as follows:

  1. Create a random unit vector , as a potential chemotactic force acting on .
  2. In the direction of , sample ahead of , as , and behind , as .
  3. Calculate the chemotactic force using:
  4. If , then apply the force as:

Here, is a constant scaling parameter that represents the strength of the chemotactic force along the chemical gradient. In code, this parameter will be defined as a global constant value.

Implementation

The following code implements the method described above. The code is broken into individual snippets in order to illustrate the steps, but the code may be viewed in whole here. This code is part of the ModelRoutine::adjustSpAgent() method within model_routine_agent.cpp.


Calculate a random, normalized forward vector, and a backward vector in the opposite direction. In code, fwdDir represents , and bckDir represents .

/* forward and backward direction vectors */
VReal fwdDir;
VReal bckDir;
REAL mag = 0.0;

/* calculate a random forward vector, and its magnitude */
for (S32 dim = 0; dim < DIMENSION; dim++) {
  fwdDir[dim] = -0.5 + Util::getModelRand(MODEL_RNG_UNIFORM);
  mag += fwdDir[dim] * fwdDir[dim];
}
mag = sqrt(mag);

/* normalize the forward vector, and set the backward vector */
for (S32 dim = 0; dim < DIMENSION; dim++) {
  fwdDir[dim] /= mag; // normalize
  bckDir[dim] = -fwdDir[dim];
}


Determine which two neighbor boxes (of the 26 neighbors) intersect with the forward and backward vectors, and then read the forward and backward chemoattractant values. In code, fwdVal represents , and bckVal represents .

/* find the nearest neighbor interface (x, y, or z) in both the
   forward and backward directions (using a separate function) */
S32 fwdInt = findNearestInterface(vOffset, fwdDir);
S32 bckInt = findNearestInterface(vOffset, bckDir);

/* calculate the offset ([-1,0,1] in all dimensions) for each of the two neighbors */
VIdx fwdOffset;
VIdx bckOffset;
for (S32 dim = 0; dim < DIMENSION; dim++) {
  fwdOffset[dim] = dim == fwdInt ? (fwdDir[fwdInt] > 0 ? 1 : -1) : 0;
  bckOffset[dim] = dim == bckInt ? (bckDir[bckInt] > 0 ? 1 : -1) : 0;
}

/* read the chemoattractant values from each of the two neighbors */
NbrBox<REAL> nbr = v_gridPhiNbrBox[DIFFUSIBLE_ELEM_CHEMOATTRACTANT];
REAL fwdVal = 0.0;
REAL bckVal = 0.0;
if (nbr.getValidFlag(fwdOffset)) {
  fwdVal = nbr.getVal(fwdOffset);
}
if (nbr.getValidFlag(bckOffset)) {
  bckVal = nbr.getVal(bckOffset);
}


Calculate the chemotactic force, apply it (if it's positive), and finally limit the force if it would move the particle more than the width of a single box. In code, chemForce represents , and A_CELL_CHEMOTAXIS_FORCE_STRENGTH represents .

/* calculate the chemotactic force, and apply it if positive */
disp = mechIntrctData.force;
REAL chemForce = A_CELL_CHEMOTAXIS_FORCE_STRENGTH[state.getType()] * (fwdVal - bckVal);
if (chemForce > 0) {
  for (S32 dim = 0; dim < DIMENSION; dim++) {
    disp[dim] += fwdDir[dim] * chemForce;
  }
}

/* limit the maximum displacement within a single time step */
for( S32 dim = 0 ; dim < DIMENSION ; dim++ ) {
  if( disp[dim] > IF_GRID_SPACING ) {
    disp[dim] = IF_GRID_SPACING;
  }
  else if( disp[dim] < ( IF_GRID_SPACING * -1.0 ) ) {
    disp[dim] = IF_GRID_SPACING * -1.0;
  }
}

Steps

A reference implementation of the following steps (including the prerequisite steps) can be found here. It was written and tested against Biocellion v1.1.

Prerequisites

  1. Supply a population of agents which will exhibit chemotactic forces (and possibly other biomechanical forces). See the ModelRoutine::addSpAgents() method within model_routine_agent.cpp.
  2. Introduce a chemical field that allows for the diffusing and decay of a chemoattractant. See the methods within model_routine_grid.cpp.
  3. Provide a method to allow for production of a chemoattractant within the field, such as cell secretion. See the ModelRoutine::updateIfGridVar() method within model_routine_grid.cpp for a simple implementation of cell secretion, whereby all agents continuously secrete chemoattractant at a constant rate.

Chemotaxis

  1. Declare and provide values for all necessary constant parameters within model_define.h. Relevant parameters from the reference implementation include:
    1. DIFFUSIBLE_ELEM_DECAY_RATE (used in model_routine_grid.cpp).
    2. DIFFUSIBLE_ELEM_DIFFUSION_COEFFICIENT (used in model_routine_grid.cpp).
    3. A_CELL_CHEMOATTRACTANT_SECRETION_RATE (used in model_routine_grid.cpp).
    4. A_CELL_CHEMOTAXIS_FORCE_STRENGTH (used in model_routine_agent.cpp).
  2. Add the code which calculates and applies the chemotactic forces (described in detail above) to the ModelRoutine::adjustSpAgent() method within model_routine_agent.cpp.
  3. If using the chemotaxis code directly from the reference implementation, do not forget to include the findNearestInterface() function that is declared within model_routine_agent.cpp.

Run and Visualize

After running the simulation, open ParaView and load the agent and chemoattractant output files. Visualize the agents by rendering a glyph for the agent output, and visualize the chemoattractant by rendering a slice for each partition of the chemoattractant output. As time progresses, the chemotactic force should move the agents along the chemical gradient, toward the higher concentrations of chemoattractant within the field.

Resources