simulator.AgentContainer Class Reference

Class to store all the agents, call them, and manage shoving/erosion of located agents. More...

Public Member Functions
	AgentContainer (Simulator aSimulator, XMLParser root, double agentTimeStep) throws Exception
	Creates the agent grid in which all agents in the biofilm simulations are stored, as well as erosion and species grids. More...
void	step (Simulator aSim)
	Iterates through each grid cell on the agent grid, stepping all agents that are within that grid space. More...
double	followPressure ()
	Compute pressure field and apply resulting advection movement to affected agents. More...
void	shoveAllLocated (boolean fullRelax, boolean shoveOnly, double maxShoveIter, double gainMin, double gainMax)
	Solve spatial spreading through application of shoving (acts only on located agents) More...
void	relaxGrid ()
	Used during initialisation to start from a coherent state. More...
void	getPotentialShovers (int index, double range, LinkedList< LocatedAgent > nbList)
	Explore grid cells around the current one and returns all agents that may shove this agent. More...
void	registerBirth (SpecialisedAgent anAgent)
	Registers the birth of an agent and adds this to the agent grid. More...
void	registerDeath (SpecialisedAgent anAgent)
	Register the death of an agent, by adding it to a list of agents that will be removed from the simulation. More...
int	removeAllDead ()
	Iterates through the _agentToKill list and removes these agents from the grid. Returns the number of dead cells removed. More...
void	agentFlushedAway (double agentTimeStep)
	Removes a number of agents from the system according to the dilution set for the chemostat. More...
void	removeLocated (SpecialisedAgent anAgent)
	Remove an agent from the grid. More...
void	registerMove (LocatedAgent anAgent)
	Update the position of the agent on the agent grid. More...
void	fitAgentMassOnGrid (SpatialGrid biomassGrid)
	Iterates through each square of the agent grid to calculate total biomass in that grid space, storing this on the supplied biomass grid. More...
void	fitAgentVolumeRateOnGrid (SpatialGrid biomassGrid)
	Iterates through each square of the agent grid to calculate total volume in that grid space, storing this on the supplied biomass grid. More...
void	writeGrids (Simulator aSim, ResultFile bufferState, ResultFile bufferSum) throws Exception
	Summarise the agents in this container in simulation output, the form of a total biomass grid. More...
void	writeReport (Simulator aSim, ResultFile bufferState, ResultFile bufferSum) throws Exception
	Write simulation output to XML files, summarising information for each species and plasmid on the agent grid. More...
void	writeReportDeath (Simulator aSim, ResultFile bufferStateDeath, ResultFile bufferSumDeath) throws Exception
	Output information on agents that have been removed from the simulation. Will enable investigators to find out why this is the case. More...
void	checkGridSize (Simulator aSimulator, XMLParser root)
	Checks the grid size, dependent on whether this is a biofilm or chemostat simulation, and sets suitable dimensions. More...
void	createShovGrid (Simulator aSimulator)
	Creates the shoving grid, padded of LocatedGroups. More...
void	createOutputGrid (Simulator aSim)
	Creates the output species and erosion grids. More...
void	shrinkOnBorder ()
void	removeOnBorder (AgentContainer agentGrid)
	Performs the discrete removal of agents over the whole _close group together, instead of considering each Located Group seperately. More...
void	calcDetPriority (AgentContainer agentGrid, LocatedGroup aBorderElement, double ratio)
	Calculate detachment priorties. More...
boolean	isValid (DiscreteVector dC)
	Check that the coordinates expressed in a DiscreteVector are defined on this grid (the grid is padded but dc uses shifted coordinates) More...
boolean	isValid (ContinuousVector cC)
	Check that the coordinates expressed in a ContinuousVector are defined on this grid (the grid is padded but dc uses shifted coordinates) More...
int	getIndexedPosition (ContinuousVector cc)
	Find the voxel a continuous coordinate lies in and return the index. More...
int	getIndexedPosition (DiscreteVector dc)
	Find the voxel a discrete vector coordinate lies in and return the index. More...
DiscreteVector	getGridPosition (ContinuousVector cC)
	Takes a ContinuousVector as input (in microns) and returns a DiscreteVector expressing its location on the grid (in voxels) More...
DiscreteVector	getGridPosition (int index)
	Takes an voxel integer index and returns a DiscreteVector containing the X,Y, and Z coordinates of that voxel. More...
ContinuousVector	getGridLocation (int index)
	Takes an voxel integer index and returns a ContinuousVector containing the X,Y, and Z coordinates of the centre of that voxel. More...
double	getAgentTimeStep ()
	Return the agent time step. More...
double	getResolution ()
	Return the resolution of the grid. More...
int[]	getGridDescription ()
	Return the dimensions of the grid (nI,nJ,nK) as an array. More...
int	get_nJ ()
	Return the number of grid cells in the J direction. More...
int	get_nK ()
	Return the number of grid cells in the K direction. More...
LocatedGroup[]	getShovingGrid ()
	Return the shoving grid. More...
LevelSet	getLevelSet ()
	Return the levelset used for modelling detachment. More...
int	getVoxelStatus (int gridVoxel)
	Return the status of a given grid voxel, to determine if the voxel is within a biofilm or not. More...
LocatedGroup	returnGroupInVoxel (int gridVoxel)
	Return the located group of agents in an agent grid voxel. More...

Public Attributes
Domain	domain
Simulator	mySim
LinkedList< SpecialisedAgent >	agentList
ListIterator< SpecialisedAgent >	agentIter
LinkedList< SpecialisedAgent >	_agentToKill = new LinkedList<SpecialisedAgent>()
boolean	is3D
final double	AGENTTIMESTEP
LevelSet	_levelset

Protected Member Functions
double	performMove (boolean pushOnly, boolean isSynchro, double gain)
	Moves an agent as a result of shoving or pushing due to growth. More...
void	refreshGroupStatus ()
	Refresh the space occupation map as agents may have moved. More...
void	markForSloughing ()
	Perform connected volume filtration (connected to bottom) to determine which agents should be marked for sloughing. More...

Protected Attributes
double[][][]	_erosionGrid

Detailed Description

Class to store all the agents, call them, and manage shoving/erosion of located agents.

Class to store all the agents, call them, and manage shoving/erosion of located agents

Author

Andreas Doetsch (andre.nosp@m.as.d.nosp@m.oetsc.nosp@m.h@he.nosp@m.lmhol.nosp@m.tz-h.nosp@m.zi.de), Helmholtz Centre for Infection Research (Germany)

Laurent Lardon (lardo.nosp@m.nl@s.nosp@m.upagr.nosp@m.o.in.nosp@m.ra.fr), INRA, France

Sonia Martins (SCM80.nosp@m.8@bh.nosp@m.am.ac.nosp@m..uk), Centre for Systems Biology, University of Birmingham (UK)

Constructor & Destructor Documentation

simulator.AgentContainer.AgentContainer	(	Simulator	aSimulator,
		XMLParser	root,
		double	agentTimeStep
	)		throws Exception

Creates the agent grid in which all agents in the biofilm simulations are stored, as well as erosion and species grids.

All agents are stored within a grid, called the agentGrid. This is similar to that for solutes but serves a purpose unique to agents. This constructor initialises this grid with parameters taken from the XML file

Parameters

aSimulator	The simulation object used to simulate the conditions specified in the protocol file
root	The agentGrid markup from the XML file
agentTimeStep	The agent time step as specified in the XML protocol file

Exceptions

Exception

Exception thrown should this data not be present in the protocol file

Member Function Documentation

void simulator.AgentContainer.agentFlushedAway

(

double

agentTimeStep

)

Removes a number of agents from the system according to the dilution set for the chemostat.

Removes a number of agents from the system according to the dilution set for the chemostat. The global time step should be set to 0.10*(1/D) so that around 10% of the agents will be removed from the system in each iteration. Remember, agents stand for all type of particles that can be removed (aka deleted) from the system, from bacteria to eps.

Parameters

agentTimeStep

- this should be the same as the global timeStep or lower

void simulator.AgentContainer.calcDetPriority	(	AgentContainer	agentGrid,
		LocatedGroup	aBorderElement,
		double	ratio
	)

Calculate detachment priorties.

Calculate detachment priorties

Parameters

agentGrid	This agent grid of located agents
aBorderElement	Group of located agents that are on the border
ratio	Ratio value set for that LocatedGroup

void simulator.AgentContainer.checkGridSize	(	Simulator	aSimulator,
		XMLParser	root
	)

Checks the grid size, dependent on whether this is a biofilm or chemostat simulation, and sets suitable dimensions.

Checks the grid size, dependent on whether this is a biofilm or chemostat simulation, and sets suitable dimensions

Parameters

aSimulator	The simulation object used to simulate the conditions specified in the protocol file
root	The agentGrid markup from the XML file

void simulator.AgentContainer.createOutputGrid

(

Simulator

aSim

)

Creates the output species and erosion grids.

Creates the output species and erosion grids. There is one erosion grid, but one grid for each species in the simulation

Parameters

aSim	The current simulation object that is recreating the conditions specified in the protocol file

void simulator.AgentContainer.createShovGrid

(

Simulator

aSimulator

)

Creates the shoving grid, padded of LocatedGroups.

Create a vectorized array of spatial groups, build their neighbourhood and store it Note :Shoving grid is a padded of LocatedGroups

Parameters

aSimulator

The current simulation object that is recreating the conditions specified in the protocol file

void simulator.AgentContainer.fitAgentMassOnGrid

(

SpatialGrid

biomassGrid

)

Iterates through each square of the agent grid to calculate total biomass in that grid space, storing this on the supplied biomass grid.

Iterates through each square of the agent grid to calculate total biomass in that grid space, storing this on the supplied biomass grid

Parameters

biomassGrid

The biomass grid that will contain the total biomass in each grid square of the agent grid

void simulator.AgentContainer.fitAgentVolumeRateOnGrid

(

SpatialGrid

biomassGrid

)

Iterates through each square of the agent grid to calculate total volume in that grid space, storing this on the supplied biomass grid.

Iterates through each square of the agent grid to calculate total volume in that grid space, storing this on the supplied biomass grid

Parameters

biomassGrid

The biomass grid that will contain the total volume in each grid square of the agent grid

double simulator.AgentContainer.followPressure

(

)

Compute pressure field and apply resulting advection movement to affected agents.

Compute pressure field and apply resulting advection movement to affected agents

int simulator.AgentContainer.get_nJ

(

)

Return the number of grid cells in the J direction.

Return the number of grid cells in the J direction

Returns

Number of grid cells in the J direction

int simulator.AgentContainer.get_nK

(

)

Return the number of grid cells in the K direction.

Return the number of grid cells in the K direction

Returns

Number of grid cells in the K direction

double simulator.AgentContainer.getAgentTimeStep

(

)

Return the agent time step.

Return the agent time step

Returns

Double value stating the agent time step

int [] simulator.AgentContainer.getGridDescription

(

)

Return the dimensions of the grid (nI,nJ,nK) as an array.

Return the dimensions of the grid (nI,nJ,nK) as an array

Returns

An array containing the dimensions of the grid

ContinuousVector simulator.AgentContainer.getGridLocation

(

int

index

)

Takes an voxel integer index and returns a ContinuousVector containing the X,Y, and Z coordinates of the centre of that voxel.

Takes an voxel integer index and returns a ContinuousVector containing the X,Y, and Z coordinates of the centre of that voxel

Parameters

index

Integer index specifying a voxel grid space on the agent grid

Returns

A continuous vector of the coordinates of this grid

DiscreteVector simulator.AgentContainer.getGridPosition

(

ContinuousVector

cC

)

Takes a ContinuousVector as input (in microns) and returns a DiscreteVector expressing its location on the grid (in voxels)

Takes a ContinuousVector as input (in microns) and returns a DiscreteVector expressing its location on the grid (in voxels)

Parameters

cC	ContinuousVector that expresses an agent location (in microns)

Returns

A discrete vector expressing the agents position in terms of the agent grid (voxels)

DiscreteVector simulator.AgentContainer.getGridPosition

(

int

index

)

Takes an voxel integer index and returns a DiscreteVector containing the X,Y, and Z coordinates of that voxel.

Takes an voxel integer index and returns a DiscreteVector containing the X,Y, and Z coordinates of that voxel

Parameters

index

Integer index specifying a voxel grid space on the agent grid

Returns

A discrete vector of the coordinates of this grid

int simulator.AgentContainer.getIndexedPosition

(

ContinuousVector

cc

)

Find the voxel a continuous coordinate lies in and return the index.

Find the voxel a continuous coordinate lies in and return the index

Parameters

cc	the continuous coordinate to find the index for

Returns

index on the 1D (vectorized) array

int simulator.AgentContainer.getIndexedPosition

(

DiscreteVector

dc

)

Find the voxel a discrete vector coordinate lies in and return the index.

Find the voxel a discrete vector coordinate lies in and return the index

Parameters

dc	the discrete vector coordinate to find the index for

Returns

index on the 1D (vectorized) array

LevelSet simulator.AgentContainer.getLevelSet

(

)

Return the levelset used for modelling detachment.

Return the levelset used for modelling detachment

Returns

Levelset used for modelling detachment

void simulator.AgentContainer.getPotentialShovers	(	int	index,
		double	range,
		LinkedList< LocatedAgent >	nbList
	)

Explore grid cells around the current one and returns all agents that may shove this agent.

Explore grid cells around the current one and returns all agents that may shove this agent. Includes grid cells on the other side of the cyclic boundary

Parameters

index	The integer index of the grid square on the agent grid
range	maximal range to screen for shoving agents
nbList,:	the list of located agents

double simulator.AgentContainer.getResolution

(

)

Return the resolution of the grid.

Return the resolution of the grid

Returns

Resolution of the agent grid

LocatedGroup [] simulator.AgentContainer.getShovingGrid

(

)

Return the shoving grid.

Return the shoving grid

Returns

LocatedGroup containing the calculated shoving information

int simulator.AgentContainer.getVoxelStatus

(

int

gridVoxel

)

Return the status of a given grid voxel, to determine if the voxel is within a biofilm or not.

Return the status of a given grid voxel, to determine if the voxel is within a biofilm or not

Parameters

gridVoxel

Integer of the grid voxel whos status is being queried

Returns

Integer showing the status of that grid voxel

boolean simulator.AgentContainer.isValid

(

DiscreteVector

dC

)

Check that the coordinates expressed in a DiscreteVector are defined on this grid (the grid is padded but dc uses shifted coordinates)

Check that these coordinates expressed in a DiscreteVector are defined on this grid (the grid is padded but dc uses shifted coordinates)

Returns

Boolean stating whether or not the DiscreteVector is valid

boolean simulator.AgentContainer.isValid

(

ContinuousVector

cC

)

Check that the coordinates expressed in a ContinuousVector are defined on this grid (the grid is padded but dc uses shifted coordinates)

Check that these coordinates expressed in a ContinuousVector are defined on this grid (the grid is padded but dc uses shifted coordinates)

Returns

Boolean stating whether or not the ContinuousVector are valid

void simulator.AgentContainer.markForSloughing ( )

protected

Perform connected volume filtration (connected to bottom) to determine which agents should be marked for sloughing.

Perform connected volume filtration (connected to bottom) to determine which agents should be marked for sloughing

double simulator.AgentContainer.performMove ( boolean  pushOnly, boolean  isSynchro, double  gain  )

protected

Moves an agent as a result of shoving or pushing due to growth.

Moves an agent as a result of shoving or pushing due to growth

Parameters

pushOnly	Boolean noting whether to apply shoving only or to also apply agent pushing
isSynchro
gain

void simulator.AgentContainer.refreshGroupStatus ( )

protected

Refresh the space occupation map as agents may have moved.

Refresh the space occupation map as agents may have moved. Each grid square has a status: -1:outside, 0:carrier,1:biofilm, 2:liquid, 3:bulk

void simulator.AgentContainer.registerBirth

(

SpecialisedAgent

anAgent

)

Registers the birth of an agent and adds this to the agent grid.

Registers the birth of an agent and adds this to the agent grid

Parameters

anAgent

New agent to add to the agent grid

void simulator.AgentContainer.registerDeath

(

SpecialisedAgent

anAgent

)

Register the death of an agent, by adding it to a list of agents that will be removed from the simulation.

Register the death of an agent, by adding it to a list of agents that will be removed from the simulation

Parameters

anAgent

SpecialisedAgent object that will be removed from the simulation

void simulator.AgentContainer.registerMove

(

LocatedAgent

anAgent

)

Update the position of the agent on the agent grid.

Update the position of the agent on the agent grid. The agent may have moved due to shoving, pushing, or growth

Parameters

anAgent

Agent that has moved and needs the location updated

void simulator.AgentContainer.relaxGrid

(

)

Used during initialisation to start from a coherent state.

Used during initialisation to start from a coherent state

int simulator.AgentContainer.removeAllDead

(

)

Iterates through the _agentToKill list and removes these agents from the grid. Returns the number of dead cells removed.

Iterates through the _agentToKill list and removes these agents from the grid. These cells should be assumed to be dead

Returns

Number of dead cells removed from the simulation

void simulator.AgentContainer.removeLocated

(

SpecialisedAgent

anAgent

)

Remove an agent from the grid.

Remove an agent from the grid

Parameters

anAgent

Agent to be removed from the grid

void simulator.AgentContainer.removeOnBorder

(

AgentContainer

agentGrid

)

Performs the discrete removal of agents over the whole _close group together, instead of considering each Located Group seperately.

Performs the discrete removal of agents over the whole _close group together, instead of considering each Located Group seperately. Note also that here tallyVariable is cumulative: whatever remains rolls over to the next time-step. This eliminates any timestep issues.

Parameters

agentGrid

The agent grid

LocatedGroup simulator.AgentContainer.returnGroupInVoxel

(

int

gridVoxel

)

Return the located group of agents in an agent grid voxel.

Parameters

gridVoxel

Integer of the grid voxel for which the located group is to be returned

Returns

LocatedGroup containing the agents within that grid voxel

void simulator.AgentContainer.shoveAllLocated	(	boolean	fullRelax,
		boolean	shoveOnly,
		double	maxShoveIter,
		double	gainMin,
		double	gainMax
	)

Solve spatial spreading through application of shoving (acts only on located agents)

Solve spatial spreading through application of shoving (acts only on located agents)

Parameters

fullRelax	Boolean noting whether a full relax of the grid is applied
shoveOnly	Boolean noting whether to apply shoving only or to also apply agent pushing
maxShoveIter	The maximum number of shoving iterations that should be applied to find a new position
gainMin	Specified minimum amount of gain to be found
gainMax	Specified maximum amount of gain to be found

void simulator.AgentContainer.shrinkOnBorder

(

)

Find the border points which go through a process of erosion (erosion and sloughing have changed the configuration)

void simulator.AgentContainer.step

(

Simulator

aSim

)

Iterates through each grid cell on the agent grid, stepping all agents that are within that grid space.

Iterates through each grid cell on the agent grid, stepping all agents that are within that grid space

Parameters

aSim	The simulation object used to simulate the conditions specified in the protocol file

void simulator.AgentContainer.writeGrids	(	Simulator	aSim,
		ResultFile	bufferState,
		ResultFile	bufferSum
	)		throws Exception

Summarise the agents in this container in simulation output, the form of a total biomass grid.

Summarise the agents in this container in simulation output, the form of a total biomass grid

Parameters

aSim	The simulation object used to simulate the conditions specified in the protocol file
bufferState	The agent_state result file output buffer
bufferSum	The agent_sum result file output buffer

Exceptions

Exception

Exception thrown if there are issues writing to these buffers

void simulator.AgentContainer.writeReport	(	Simulator	aSim,
		ResultFile	bufferState,
		ResultFile	bufferSum
	)		throws Exception

Write simulation output to XML files, summarising information for each species and plasmid on the agent grid.

Write simulation output to XML files, summarising information for each species and plasmid on the agent grid. These files are written out as agent_state([simulation step number]).XML and agent_sum([simulation step number]).XML

Parameters

aSim	The simulation object used to simulate the conditions specified in the protocol file
bufferState	The agent_state result file output buffer
bufferSum	The agent_sum result file output buffer

Exceptions

Exception

Exception thrown if there are issues writing to these buffers

void simulator.AgentContainer.writeReportDeath	(	Simulator	aSim,
		ResultFile	bufferStateDeath,
		ResultFile	bufferSumDeath
	)		throws Exception

Output information on agents that have been removed from the simulation. Will enable investigators to find out why this is the case.

Output information on agents that have been removed from the simulation. Will enable investigators to find out why this is the case

Parameters

aSim	The simulation object used to simulate the conditions specified in the protocol file
bufferStateDeath	The agent_state_death result file output buffer
bufferSumDeath	The agent_sum_death result file output buffer

Exceptions

Exception

Exception thrown if there are issues writing to these buffers

Member Data Documentation

LinkedList<SpecialisedAgent> simulator.AgentContainer._agentToKill = new LinkedList<SpecialisedAgent>()

Temporary containers used to store agents who will be added or removed. Visibility public so that it can be accessed from LocatedGroup in killAll()

double [][][] simulator.AgentContainer._erosionGrid

protected

3D array that captures erosion in the agent grid

LevelSet simulator.AgentContainer._levelset

Solver used for modelling detachment

ListIterator<SpecialisedAgent> simulator.AgentContainer.agentIter

Iterator for all agents in this grid

LinkedList<SpecialisedAgent> simulator.AgentContainer.agentList

Container for all agents (even the non located ones)

final double simulator.AgentContainer.AGENTTIMESTEP

Allows you to define a smaller timestep for agent behaviors and interactions. Read in by Simulator class. This is a local copy

Domain simulator.AgentContainer.domain

Computational domain to which this grid is assigned

boolean simulator.AgentContainer.is3D

Boolean noting whether the grid is 3D or 2D

Simulator simulator.AgentContainer.mySim

Local copy of the simulation object used to create the conditions specified in the protocol file

---

The documentation for this class was generated from the following file:

• /home/kieran/Dropbox/workspace/iDynoMiCS/src/simulator/AgentContainer.java