FocalPointPlasticity Plugin
FocalPointPlasticity
puts constraints on the
distance between cells’ center of masses. A key feature of this plugin is that
the list of “focal point plasticity neighbors” can change as the
simulation evolves and user has to specifies the maximum number of “focal point
plasticity neighbors” a given cell can have. Let’s look at relatively
simple CC3DML syntax of FocalPointPlasticityPlugin
(see
Demos/PluginDemos/FocalPointPlasticity/FocalPointPlasticity example and we will show more complex
examples later):
<Plugin Name="FocalPointPlasticity">
<Parameters Type1="Condensing" Type2="NonCondensing">
<Lambda>10.0</Lambda>
<ActivationEnergy>-50.0</ActivationEnergy>
<TargetDistance>7</TargetDistance>
<MaxDistance>20.0</MaxDistance>
<MaxNumberOfJunctions>2</MaxNumberOfJunctions>
</Parameters>
<Parameters Type1="Condensing" Type2="Condensing">
<Lambda>10.0</Lambda>
<ActivationEnergy>-50.0</ActivationEnergy>
<TargetDistance>7</TargetDistance>
<MaxDistance>20.0</MaxDistance>
<MaxNumberOfJunctions>2</MaxNumberOfJunctions>
</Parameters>
<NeighborOrder>1</NeighborOrder>
</Plugin>
Parameters
section describes properties of links between cells.
MaxNumberOfJunctions
, ActivationEnergy
, MaxDistance
and NeighborOrder
are responsible for establishing connections between cells. CC3D
constantly monitors pixel copies and during pixel copy between two
neighboring cells/subcells it checks if those cells are already
participating in focal point plasticity constraint. If they are not,
CC3D will check if connection can be made (e.g. Condensing
cells can
have up to two connections with Condensing
cells and up to 2 connections
with NonCondensing
cells – see first line of Parameters
section and
MaxNumberOfJunctions
tag). The NeighborOrder
parameter determines the
pixel vicinity of the pixel that is about to be overwritten which CC3D
will scan in search of the new link between cells. NeighborOrder 1
(which is default value if you do not specify this parameter) means that
only nearest pixel neighbors will be visited. The ActivationEnergy
parameter is added to overall energy in order to increase the odds of
pixel copy which would lead to new connection.
Once cells are linked the energy calculation is carried out according to the formula:
where \(l_{ij}\) is a distance between center of masses of cells i
and j
and \(L_{ij}\) is
a target length corresponding to \(l_{ij}\).
\(\lambda_{ij}\) and \(L_{ij}\) between different cell types are
specified using Lambda
and TargetDistance
tags. The MaxDistance
determines the distance between cells’ center of masses past which the link
between those cells break. When the link breaks, then in order for the
two cells to reconnect they would need to come in contact again.
However it is usually more likely that there will be other
cells in the vicinity of separated cells so it is more likely to
establish new link than restore broken one.
The above example was one of the simplest examples of use of
FocalPointPlasticity
. A more complicated one involves compartmental
cells. In this case each cell has separate “internal” list of links
between cells belonging to the same cluster and another list between
cells belonging to different clusters. The energy contributions from
both lists are summed up and everything that we have said when
discussing example above applies to compartmental cells. Sample syntax
of the FocalPointPlasticity
plugin which includes compartmental cells is
shown below. We use InternalParameters
tag/section to describe links
between cells of the same cluster (see Demos/PluginDemos/FocalPointPlasticity/FocalPointPlasticityCompartments
example):
<Plugin Name="FocalPointPlasticity">
<Parameters Type1="Top" Type2="Top">
<Lambda>10.0</Lambda>
<ActivationEnergy>-50.0</ActivationEnergy>
<TargetDistance>7</TargetDistance>
<MaxDistance>20.0</MaxDistance>
<MaxNumberOfJunctions NeighborOrder="1">1</MaxNumberOfJunctions>
</Parameters>
<Parameters Type1="Bottom" Type2="Bottom">
<Lambda>10.0</Lambda>
<ActivationEnergy>-50.0</ActivationEnergy>
<TargetDistance>7</TargetDistance>
<MaxDistance>20.0</MaxDistance>
<MaxNumberOfJunctions NeighborOrder="1">1</MaxNumberOfJunctions>
</Parameters>
<InternalParameters Type1="Top" Type2="Center">
<Lambda>10.0</Lambda>
<ActivationEnergy>-50.0</ActivationEnergy>
<TargetDistance>7</TargetDistance>
<MaxDistance>20.0</MaxDistance>
<MaxNumberOfJunctions>1</MaxNumberOfJunctions>
</InternalParameters>
<InternalParameters Type1="Bottom" Type2="Center">
<Lambda>10.0</Lambda>
<ActivationEnergy>-50.0</ActivationEnergy>
<TargetDistance>7</TargetDistance>
<MaxDistance>20.0</MaxDistance>
<MaxNumberOfJunctions>1</MaxNumberOfJunctions>
</InternalParameters>
<NeighborOrder>1</NeighborOrder>
</Plugin>
We can also specify link constituent law and change it to different form that “spring relation”. To do this we use the following syntax inside FocalPointPlasticity CC3DML plugin:
<LinkConstituentLaw>
<!--The following variables lare defined by default: Lambda,Length,TargetLength-->
<Variable Name='LambdaExtra' Value='1.0'/>
<Formula>LambdaExtra*Lambda*(Length-TargetLength)^2</Formula>
</LinkConstituentLaw>
By default CC3D defines 3 variables (Lambda
, Length
, TargetLength
) which
correspond to \(\lambda_{ij}\) , \(l_{ij}\) and \(L_{ij}\) from the formula
above. We can also define extra variables in the CC3DML (e.g.
LambdaExtra
). The actual link constituent law obeys muParser
syntax
convention. Once link constituent law is defined it is applied to all
focal point plasticity links. The example demonstrating the use of
custom link constituent law can be found in
Demos/PluginDemos/FocalPointPlasticityCustom.
Sometimes it is necessary to modify link parameters individually for
every cell pair. In this case we would manipulate FocalPointPlasticity
links using Python scripting. Example
Demos/PluginDemos/FocalPointPlasticity/FocalPointPlasticityCompartments demonstrates exactly this
situation. You still need to include CC3DML section as the one shown
above for compartmental cells, because we need to tell CC3D how to link
cells. The only notable difference is that in the CC3DML we have to
include <Local/>
tag to signal that we will set link parameters (Lambda
,
TargetDistance
, MaxDistance
) individually for each cell pair:
<Plugin Name="FocalPointPlasticity">
<Local/>
<Parameters Type1="Top" Type2="Top">
<Lambda>10.0</Lambda>
<ActivationEnergy>-50.0</ActivationEnergy>
<TargetDistance>7</TargetDistance>
<MaxDistance>20.0</MaxDistance>
<MaxNumberOfJunctions NeighborOrder="1">1</MaxNumberOfJunctions>
</Parameters>
...
</Plugin>
Python steppable where we manipulate cell-cell focal point plasticity link properties is shown below:
class FocalPointPlasticityCompartmentsParams(SteppablePy):
def __init__(self, _simulator, _frequency=10):
SteppablePy.__init__(self, _frequency)
self.simulator = _simulator
self.focalPointPlasticityPlugin = CompuCell.getFocalPointPlasticityPlugin()
self.inventory = self.simulator.getPotts().getCellInventory()
self.cellList = CellList(self.inventory)
def step(self, mcs):
for cell in self.cellList:
for fppd in InternalFocalPointPlasticityDataList(self.focalPointPlasticityPlugin, cell):
self.focalPointPlasticityPlugin.setInternalFocalPointPlasticityParameters(cell, fppd.neighborAddress,
0.0, 0.0, 0.0)
The syntax to change focal point plasticity parameters (or as here internal parameters) is as follows:
setFocalPointPlasticityParameters(cell1, cell2, lambda, targetDistance, maxDistance)
setInternalFocalPointPlasticityParameters(cell1, cell2, lambda, targetDistance, maxDistance)
Similarly, to inspect current values of the focal point plasticity parameters we would use the following Python construct:
for cell in self.cellList:
for fppd in InternalFocalPointPlasticityDataList(self.focalPointPlasticityPlugin, cell):
print "fppd.neighborId", fppd.neighborAddress.id
" lambda=", fppd.lambdaDistance
For non-internal parameters we simply use FocalPointPlasticityDataList
instead of InternalFocalPointPlasticityDataList
.
Examples Demos/PluginDemos/FocalPointPlasticity… show in relatively simple way how
to use FocalPointPlasticity
plugin. Those examples also contain useful
comments.
Note
When using FocalPointPlasticity
Plugin from Mitosis
module one might
need to break or create focal point plasticity links. To do so
FocalPointPlasticity
Plugin provides 4 convenience functions which can
be invoked from the Python level:
deleteFocalPointPlasticityLink(cell1, cell2)
deleteInternalFocalPointPlasticityLink(cell1, cell2)
createFocalPointPlasticityLink(cell1, cell2, lambda , targetDistance, maxDistance)
createInternalFocalPointPlasticityLink(cell1, cell2, lambda , targetDistance, maxDistance)
Working on the Basis of Links
Note
All functionality described in this section is relevant for CC3D versions 4.2.4+.
CC3D performs all link calculations on the basis of link objects. That is,
every link as described so far is an object with properties and functions that, much like CellG
objects, can be created, destroyed and manipulated. As such, CC3DML specification tells CC3D to simulate links
and what types of links should be automatically created, but links can also be individually accessed, manipulated,
created and destroyed in Python. FocalPointPlasticity
Plugin always uses the basis of links for link calculations,
and so the <Local/>
tag in CC3DML FocalPointPlasticity
Plugin specification is no longer necessary.
CC3D describes three types of links
FocalPointPlasticityLink
: a link between two cells
FocalPointPlasticityInternalLink
: a link between two cells of the same cluster
FocalPointPlasticityAnchor
: a link between a cell and a point
FocalPointPlasticityLink
objects are automatically created from the CC3DML FocalPointPlasticity
Plugin
specification in the tag Parameters
,
FocalPointPlasticityInternalLink
objects are automatically created from CC3DML specification in the tag
InternalParameters
, and FocalPointPlasticityAnchor
objects are only created in Python.
CompuCell3D/core/Demos/PluginDemos/FocalPointPlasticityLinks demonstrates basic usage of
FocalPointPlasticityLink
, the pattern of which is mostly the same for FocalPointPlasticityInternalLink
and FocalPointPlasticityAnchor
except for naming conventions of certain properties, functions and objects.
CC3D adopts the convention that for every link with a cell pair (i.e., FocalPointPlasticityLink
and
FocalPointPlasticityInternalLink
), one cell is the initiator cell (i.e., the cell that initated the link), and
the other cell is the initiated cell. Using this convention, every link has the following API for manipulating
link properties,
# --------------
# | Properties |
# --------------
# Link length; automatically updated by CC3D
length
# Link tension = 2 * lambda * (distance - target_distance); automatically updated by CC3D
tension
# A general python dictionary
dict
# SBML solvers (as on CellG)
sbml
# -----------
# | Methods |
# -----------
# Given one cell, returns the other cell of a link
getOtherCell(self, _cell: CellG) -> CellG
# Returns True if the cell is the initiator
isInitiator(self, _cell: CellG) -> bool
# Get lambda distance
getLambdaDistance(self) -> float
# Set lambda distance
setLambdaDistance(self, _lm: float) -> None
# Get target distance
getTargetDistance(self) -> float
# Set target distance
setTargetDistance(self, _td: float) -> None
# Get maximum distance
getMaxDistance(self) -> float
# Set maximum distance
setMaxDistance(self, _md: float) -> None
# Get maximum number of junctions
getMaxNumberOfJunctions(self) -> int
# Set maximum number of junctions
setMaxNumberOfJunctions(self, _mnj: int) -> None
# Get activation energy
getActivationEnergy(self) -> float
# Set activation energy
setActivationEnergy(self, _ae: float) -> None
# Get neighbor order
getNeighborOrder(self) -> int
# Set neighbor order
setNeighborOrder(self, _no: int) -> None
# Get initialization step; automatically recorded at instantiation
getInitMCS(self) -> int
So, for example, the value of \(\lambda_{ij}\) for a link can be retrieved with link.getLambdaDistance()
,
and can be set with link.setLambdaDistance(lambda_ij)
for some float-valued variable lambda_ij
. Links
automatically created by CC3D according to CC3DML specification are initialized with properties accordingly.
Additionally, FocalPointPlasticityLink
and FocalPointPlasticityInternalLink
objects have the property
cellPair
, which contains, in order, the initiator and initiated cells of the link, while
each FocalPointPlasticityAnchor
has the property cell
(i.e., the linked cell) and additional methods related
to its anchor point,
Steppables have built-in method for creating and destroying each type of link,
# Create a link between two cells
new_fpp_link(self, initiator: CellG, initiated: CellG, lambda_distance: float, target_distance: float,
max_distance: float) -> FocalPointPlasticityLink
# Create an internal link between two cells of a cluster
new_fpp_internal_link(self, initiator: CellG, initiated: CellG, lambda_distance: float,
target_distance: float, max_distance: float) -> FocalPointPlasticityInternalLink
# Create an anchor
# Anchor point can be specified by individual components x, y and z, or by Point3D pt
new_fpp_anchor(self, cell: CellG, lambda_distance: float, target_distance: float,
max_distance: float, x: float = 0.0, y: float = 0.0, z: float = 0.0,
pt: Point3D = None) -> FocalPointPlasticityAnchor
# Destroy a link type FocalPointPlasticityLink, FocalPointPlasticityInternalLink or FocalPointPlasticityAnchor
delete_fpp_link(self, _link) -> None
# Destroy all links attached to a cell by link type
# links, internal_links and anchors selects which type, or all types if not specified
remove_all_cell_fpp_links(self, _cell: CellG, links: bool = False, internal_links: bool = False,
anchors: bool = False) -> None
Steppables also have built-in methods for retrieving information about links in simulation, by cell, and by cell pair. These methods are as follows,
# Get number of links
get_number_of_fpp_links(self) -> int
# Get number of internal links
get_number_of_fpp_internal_links(self) -> int
# Get number of anchors
get_number_of_fpp_anchors(self) -> int
# Get link associated with two cells
get_fpp_link_by_cells(self, cell1: CellG, cell2: CellG) -> FocalPointPlasticityLink
# Get internal link associated with two cells
get_fpp_internal_link_by_cells(self, cell1: CellG, cell2: CellG) -> FocalPointPlasticityInternalLink
# Get anchor assicated with a cell and anchor id
get_fpp_anchor_by_cell_and_id(self, cell: CompuCell.CellG, anchor_id: int) -> FocalPointPlasticityAnchor
# Get list of links by cell
get_fpp_links_by_cell(self, _cell: CellG) -> FPPLinkList
# Get list of internal links by cell
get_fpp_internal_links_by_cell(self, _cell: CellG) -> FPPInternalLinkList
# Get list of anchors by cell
get_fpp_anchors_by_cell(self, _cell: CellG) -> FPPAnchorList
# Get list of cells linked to a cell
get_fpp_linked_cells(self, _cell: CompuCell.CellG) -> mvectorCellGPtr
# Get list of cells internally linked to a cell
get_fpp_internal_linked_cells(self, _cell: CellG) -> mvectorCellGPtr
# Get number of link junctions by type for a cell
get_number_of_fpp_junctions_by_type(self, _cell: CellG, _type: int) -> int
# Get number of internal link junctions by type for a cell
get_number_of_fpp_internal_junctions_by_type(self, _cell: CompuCell.CellG, _type: int) -> int