Transitioning from CC3D 3.x to CC3D 4.x¶
New CC3D 4.x switches from Python 2.x to python 3.6+. This offered us an opportunity to reorganize code and simplify the way you describe your simulations. The good news is that the new way of specifying simulations in Python is much simpler than before. However we did make some changes that will require you to update your existing code to work with CC3D 4.x. We tried as much as possible to keep old API to limit the number of changes you need to make.
As a translation method we recommend starting a new CompuCell3D model with twedit++ and copying over parts of your old 3.x code into this new CompuCell3D 4.x model.
The list below summarizes key API and coding convention changes. Later we are providing step-by-step guide on how to port your simulations to CC3D 4.x .
- Introduction of
cc3d
python module. Most of your cc3d imports will begin fromimport cc3d.xxx
2. Switching from Pascal-case to more Pythonic snake-case and dropped leading
underscore from function arguments self.addSBMLToCell(_cell)
-> self.add_sbml_to_cell(cell)
.
- Changes how we declare
Steppable
class - Changes in main Python script
Main Python Script¶
Old Python script was quite verbose and contained a lot of “boiler-plate” code. We fixed it and now instead of typing
import sys
from os import environ
from os import getcwd
import string
sys.path.append(environ["PYTHON_MODULE_PATH"])
import CompuCellSetup
sim,simthread = CompuCellSetup.getCoreSimulationObjects()
#Create extra player fields here or add attributes
CompuCellSetup.initializeSimulationObjects(sim,simthread)
#Add Python steppables here
steppableRegistry=CompuCellSetup.getSteppableRegistry()
from bacterium_macrophage_2D_steering_steppables import ChemotaxisSteering
chemotaxisSteering=ChemotaxisSteering(_simulator=sim,_frequency=100)
steppableRegistry.registerSteppable(chemotaxisSteering)
CompuCellSetup.mainLoop(sim,simthread,steppableRegistry)
we write something much simpler
from cc3d import CompuCellSetup
from .bacterium_macrophage_2D_steering_steppables import ChemotaxisSteering
CompuCellSetup.register_steppable(steppable=ChemotaxisSteering(frequency=100))
CompuCellSetup.run()
We import CompuCellSetup module from cc3d
package as well as the steppable we want to instantiate. After that we
register the steppable by calling
CompuCellSetup.register_steppable(steppable=ChemotaxisSteering(frequency=100))
and then start the simulation by calling
CompuCellSetup.run()
This is much simpler than before and main change is that we no longer store references to key CC3D objects sim
- simulator object
and simthread
- object representing Player in the main script. Those objects are now handled behind-the-scenes
by the new code-base . You can still easily access them though.
Steppable Class¶
The new Steppable
class is quite similar to the old one but as before we no longer need to pass simulator
in
the constructor of the class. For exampmple.
from cc3d.core.PySteppables import *
class ChemotaxisSteering(SteppableBasePy):
def __init__(self, frequency=100):
SteppableBasePy.__init__(self, frequency)
The rest of of the steppable structure is very similar as in the CC3D 3.x.
Note that we import steppable class using
As we mentioned before, most of the CC3D-related Python modules are now submodules of the cc3d
python package
Deprecation Warnings for Old API¶
Most of the old API still works in the new CC3D. If you notice absence of certain functions please let us know and we will fix it. In the process of reworking CC3D API we removed deprecated functions or functions that were eliminated because they were not needed anymore. Old API was preserved but we added depreciation warning. It is quite likely, therefore, that when you run CC3D Simulation you may see a lot of depreciation warnings. MOsf of them will look as follows
SBMLSolverLegacy/Simulation/SBMLSolverLegacySteppables.py:47: DeprecationWarning: Call to deprecated method addSBMLToCell. (You should use : add_sbml_to_cell) -- Deprecated since version 4.0.0.
You may ignore those warnings for now but we highly encourage you to replace old API calls with eh new ones. Most
importantly, Twedit++ uses new API so if you need assistance you may always refer to CC3D Python
of Twedit++
Simplified Programmatic Steering of CC3DML Parameters¶
Previous version of CC3D allowed to programmatically change values of CC3DML parameters. For example, you could
run simulation and adjust chemotaxis lambda
from a Python script. The code that was required to make those adjustments was , at best, quite confusing and therefore this feature was a source a frustration among users. The new CC3D fixes this issue. The solution comes from the world of JavaScript and HTML. All that is required is tagging of the CC3DML
element using id
attribute and referring to it from Python script. we present a simple example below
and a separate section on programmatic steering can be found in later chapters of this manual
<Plugin Name="Chemotaxis">
<ChemicalField Name="ATTR">
<ChemotaxisByType id="macro_chem" Type="Macrophage" Lambda="20"/>
</ChemicalField>
</Plugin>
Here in the CC3DML code we added id="macro_chem"
tag to element that we want to modify from Python steppable script. One important thing to keep in mind is that the tags for different elements need to be distinct
In python script we modify Lambda
attribute as follows:
def step(self, mcs):
if mcs > 100 and not mcs % 100:
vol_cond_elem = self.get_xml_element('macro_chem')
vol_cond_elem.Lambda = float(vol_cond_elem.Lambda) - 3
where first statement vol_cond_elem = self.get_xml_element('macro_chem')
fetches a reference to the CC3DML element
and the second modifies vol_cond_elem.Lambda = float(vol_cond_elem.Lambda) - 3
assigns new value of Lambda
As a reminder we present equivalent code in the old version of CC3D
def step(self,mcs):
if mcs>100 and not mcs%100:
attrVal=float(self.getXMLAttributeValue('Lambda',['Plugin','Name','Chemotaxis'],['ChemicalField','Name','ATTR'],['ChemotaxisByType','Type','Macrophage']))
self.setXMLAttributeValue('Lambda',attrVal-3,['Plugin','Name','Chemotaxis'],['ChemicalField','Name','ATTR'],['ChemotaxisByType','Type','Macrophage'])
self.updateXML()
As you can see the new code is easy to inderstand while the old one is quite a mouthful… For this reason we completely removed the old way of programatic CC3DML steering from the new CC3D.
Accessing Fields¶
Staring with CC3D 4.0.0 all fields declared in the simulation can accessed using quite natural syntax:
self.field.FIELD_NAME
where FIELD_NAME
is replaced with actual field name:
For example to access field called fgf8
you type:
self.field.fgf_8
Like in previous releases if you are dealing with scalar fields (or a cell field) you may use slicing operators
familiar from numpy
package. For example to assign a patch of concentration of you would type:
self.field.fgf_8[10:20, 20:30, 0] = 12.3
SBML Solver¶
We also changed the way you use SBML solver. While the old syntax still works we feel that the new way of interacting with SBMLSolve submodule is more natural. Take a look at the example
model_file = 'Simulation/test_1.xml'
self.add_free_floating_sbml(model_file=model_file, model_name='Medium_dp2')
Medium_dp2 = self.sbml.Medium_dp2
Medium_dp2['S1'] = 10
Medium_dp2['S2'] = 0.5
Similarly, as in the case of regular fields, we access free floating sbml models using the followng syntax
self.sbml.Medium_dp2
where Medium_dp2
is a label that we assigned to particular free-floating SBML model (i.e. the one not associated with a particular CC3D cell).
To add and access SBML model to a particular cell we use the following syntax:
model_file = 'Simulation/test_1.xml'
cell_20 = self.fetch_cell_by_id(20)
self.add_sbml_to_cell(model_file=model_file, model_name='dp', cell=cell_20)
cell_20.sbml.dp['S1'] = 1.3
In the code snippet above we first access a cell with id=20
using self.fetch_cell_by_id
function - we assume that cel with id=20 exists
. Next we add SBML model to a cell with id=20
and then use
cell.sbml.SBML_MODEL_NAME['SPECIES_NAME'] = VALUE
to modify concentration in the SBML model
In our example the above template looks as follows:
cell_20.sbml.dp['S1'] = 1.3
We will cover SBML solver in details in later chapters
This completes transition guide.