1. Introduction to CompuCell3D Outline: 1.What is CompuCell3D? 2.Why use CompuCell3D? 3.Demo simulations 4.Glazier-Graner-Hogeweg (GGH) model – an overview 5.CompuCell3D architecture and terminology 6.XML 101 7.Building first CompuCell3D simulation 8.Visualization package – CompuCell Player 9.Python scripting inside CompuCell3D

2. What is CompuCell3D? 1.CompuCell3D is a modeling environment used to build, test, run and visualize GGH-based simulations 2.CompuCell3D has built-in scripting language (Python) that allows users to quite easily write extension modules that are essential for building sophisticated biological models. 3.CompuCell3D thus is NOT a specialized software 4.Running CompuCell3D simulations DOES NOT recompilation 5.CompuCell3D model is described using CompuCell3D XML syntax and in the case of using Python language, a Python script(s) 6.CompuCell3D platform is distributed with a GUI front end – CompuCell Player or simply Player. The Player provides 2- and 3-D visualization capabilities. 7.Models developed by one CompuCell3D user can be “replayed” by another user regardless the operating system/hardware on which CompuCell is installed. 8.CompuCell3D is a cross platform application with Windows port being currently developed (due end of July 2007).

3. Why use CompuCell3D? What are the alternatives? 1.CompuCell3D allows users to set up and run their simmulations within minutes, maybe hours. A typical development of a specialized GGH code takes orders of magnitudes longer time. 2.CompuCell3D simulations DO NOT need to be recompiled. If you want to change parameters (in XML or Python scripts) or logic (in Python scripts) you just make the changes and re-run the simulation. With hand-compiled simulations there is much more to do. Recompilation of every simulation is also error prone and often limits users to those who have significant programming background. 3.CompuCell3D is actively developed, maintained and supported. On www.compucell3d.org website users can download manuals, tutorials and developer documentation. CompuCell3D has approx. 10 releases each year. www.compucell3d.or 4.CompuCell3D has many users around the world. This makes it easier to collaborate or exchange modules and results saving time spent on developng new model. 5.The Biocomplexity Institute organizes training workshops and mentorship programs. Those are great opportunities to visit Bloomington and learn biological modeling using CompuCell3D. For more info see www.compucell3d.org

4. Demo simulations

5. The GGH Model – an overview Energy minimization formalism - extended by Graner and Glazier, 1992 DAH: Contact energy depending on cell types (differentiated cells) Metropolis algorithm: probability of configuration change x 20

6. CompuCell3D architecture Kernel Runs Metropolis Algorithm Plugins Calculate change in energy PDE Solvers Python Interpreter Biologo Code Generator Visualization, Steering, User Interface Lattice monitoring Object oriented implementation in C++ and Python

7. CompuCellPlayer CompuCell3D Kernel Plugins Python Typical “run-time” architecture of CompuCell CompuCell can be run in a variety of ways: Through the Player with or without Python interpreter As a Python script As a stand alone computational kernel+plugins

8. CompuCell3D terminology 1.Spin-copy attempt is an event where program randomly picks a lattice site in an attempt to copy its spin to a neighboring lattice site. 2.Monte Carlo Step (MCS) consists of series spin-copy attempts. Usually the number of spin copy-attempts in single MCS is equal to the number of lattice sites, but this is can be customized 3.CompuCell3D Plugin is a software module that either calculates an energy term in a Hamiltonian or implements action in response to spin copy (lattice monitors). Note that not all spin-copy attempts will trigger lattice monitors to run. 4.Steppables are CompuCell3D modules that are run every MCS after all spin- copy attempts for a given MCS have been exhausted. Most of Steppables are implemented in Python. Most customizations of CompuCell3D simulations is done through Steppables 5.Steppers are modules that are run for those spin-copy attempts that actually resulted in energy calculation. They are run regardless whether actual spin-copy occurred or not. For example cell mitosis is implemented in the form of stepper. 6.Fixed Steppers are modules that are run every spin-copy attempt.

9. Spin copy “blue” pixel (newCell) replaces “yellow” pixel (oldCell) Change pixel MCS 21 10000 spin- copy attempts MCS 22 MCS 23 MCS 24 10000 spin- copy attempts Run Steppables Run Steppables Run Steppables 100x100x1 square lattice = 10000 lattice sites (pixels) CompuCell3D terminology – visual guide

10. XML 101 XML stands for eXtensible Markup Manguage. It is NOT a programming language. Its main purpose is to standarize information exchange between different applications. XML Example: It is too early to be in class TimesNewRoman 12

11. Defining basic properties of the simulation like lattice dimension, number of Monte Carlo Steps, Temperature and ratio of spin-copy attempts to number of lattice sites (Flip2DimRatio). section has to be included in every CompuCell3D simulation 10 2 Defining properties of Volume Energy term – cell target volume and lambda parameter: 25 2.0... CompuCell related example

12. Building your first CompuCell3D simulation All simulation parameters are controlled by the config file. The config file allows you to only add those features needed for your current simulation, enabling better use of system resources. Cell Define Lattice and Simulation Parameters 10 2 1 …

13. Define cell types used in the simulation Cell Each CompuCell3D xml file must list all cell types that will used in the simulation Notice that Medium is listed with TypeId =0. This is both convention and a REQUIREMENT in CompuCell3D. Reassigning Medium to a different TypeId may give undefined results. This limitation will be fixed in one of the next CompuCell3D releases

14. Define Energy Terms of the Hamiltonian and their parameters Cell Volume volume volumeEnergy(cell) 25 1.0 Surface area surfaceEnergy(cell) 21 0.5 Contact contactEnergy( cell1, cell2) 0 0 0.1 0.5 3.0 0.5

15. Lay out cells on the lattice You may use CompuCell3D stock initializers BlobInitialize or UniformInitializer: 0 5 yes 40 1,2 0 5 UniformInitializer will creates filling specified box with rectangular cells (side length is given by width parameter). Cell types will be randomly chosen between 1 and 2. You may include many sections specifying different regions.

16. XML initializers You may initialize simple geometries of cell clusters directly from XML 1,2 0 5 Specify box size and position Specify cell types – here the box will be filled with cells whose types are randomly chosen (either 1 or 2) Choose cell size and space between cells

17. Use PIFInitializer to create sophisticated initial conditions. PIF file allows you to compose cells from single pixels or from larger rectangular blocks The syntax of the PIF file is Cell_id Cell_type x_low x_high y_low y_high z_low z_high Example: 0 amoeba 10 15 10 15 0 0 Creates rectangular cell with x-coordinates ranging from 10 to 15 (inclusive), y coordinates ranging from 10 to 15 (inclusive) and z coordinates ranging from 0 to 0 inclusive. To add extra pixel to the cell you would include the following (note that cell_id is the same): 0 amoeba 16 16 10 10 0 0 Adding another cell is also easy 0 bacterium 25 30 25 30 0 0

18. Putting it all together - cellsort_2D.xml 10 2 1 25 1.0 21 0.5 0 0 0.1 0.5 3.0 0.5 0 5 yes 40 Coding the same simulation in C/C++/Java/Fortran would take you at least 1000 lines of code…

19. CompuCellPlayer – the best way to run simulations Steering bar allows users to start or pause the simulation, zoom in, zoom out, to switch between 2D and 3D visualization, change view modes (cell field, pressure field, chemical concentration field, velocity field etc..) Player can output multiple views during single simulation run – Add Screenshot function Information bar

20. Opening a simulation in the Player Go to File->Open Simulation ; Click Simulation xml file -> Browse… button

21. Capabilities of CompuCellPlayer Provides wide range of visualization - cell field plots, concentration plots, vector field plots in both 2- and 3-D Allows to store multiple lattice views in a single run. For example users can store multiple projections of the cell lattice, concentration fields, various 3D views etc… in a single run. Can be run in GUI and silent mode (i.e. without displaying GUI but still saving screenshots) Is ready to be used on clusters that do not have X-server installed. This feature is essential for doing “production runs” of your simulations. Concentration fields and vector fields initialized from Python level can easily be displayed in the Player Configurable from XML level for those users who prefer typing to clicking

22. Running the simulation After typing the XML file in your favorite editor all you need to do to run the simulation is to open the XML file in the Player and hit “Play” button. Screenshots from the simulations are automatically stored in the directory with name composed of simulation file name and a time at which simulation was started As you can see this setting CompuCell3D simulation was reasonably simple. It is quite likely that if you were to code entire simulation in C/C++/Java etc. you would need much more time. We hope that now you understand why using CompuCell3D saves you a lot of time and allows you to concentrate on biological modeling and not on writing low level computer code. During last year we have improved CompuCell3D performance so that it is on par with hand-written code. Yet, if you really to have the fastest GGH code in the world you should write code your own simulation directly in C or even better in assmbly language. Before you do it, make sure you want to spend time rewriting the code that already exist. We hope you will enjoy CompuCell3D and for more information please visit www.compucell3d.org.

23. scripting inside CompuCell3D XML gives you the ability to change simulation parameters using human-readable syntax but does not allow users to implement more complex cell behaviors, sophisticated cell type transition rules, inter-cell signaling or connecting to intracellular models Python scripting capabilities in CompuCell3D allw users to accomplish abovementioned tasks (and much more) and are the reasons why CompuCell3D is called simulation environment, not simulation application. Python scripting capabilities allow users to use rich set of Python modules and third party libraries and provide level flexibility comparable with packages such as Matlab or Mathematica

24. Python scripting prerequisites To make full use of Python scripting users should be familiar with Python programming language. They do not need to be experts though. CompuCell3D comes with template and example codes that make Python scripting inside CompuCell3D quite easy even for beginners. Python scripting in CompuCell3D typically requires users to develop a class that implements required logic. If you are unfamiliar with concept of class, think of it as a type that has several data members (such as floats, integers, other classes) and set of functions that operate on those internal members but can also take external arguments. Class is a generalization of “C” structure or “Pascal” record. Fortunately CompuCell3D comes with plenty of examples that users can adapt to serve their needs. This does not require thorough programming knowledge. If you are unfamiliar with Python scripting, reading (and doing) “CompuCell3D Python Scripting Tutorials” should quickly get you up-to-speed.

25. Where do you begin? You will still need XML file describing which plugins and/or steppables CompuCell3D is to use. In the future releases we might change this requirement but for now it appeared as the best way of ensuring proper module initialization In addition to XML file you will need to write Python script that implements main CompuCell3D logic i.e. reads XML file, initializes modules and executes calls in a loop Metropolis algorithm. This file will also call set up and initialize your modules written in Python. CompuCell3D comes with many examples of such files so in fact preparing one is reduced to minor modification of existing one. Once you have XML and Python scripts ready you opent them up in the Player and start running simulaitons

26. What can you do in Python? You may implement any CompuCell3D module using Python – energy functions, lattice monitors, steppers, steppables, fixed steppers. You need to remember that Python is an interpreted language and thus executes orders of magnitudes slower than for example C++. This means that although you can easily develop energy functions (remember, they are the most frequently called modules in CompuCell3D) in Python, you will probably want to avoid using them with your “production runs”. In this it makes sense to implement those functions in C++, which is not too difficult and we provide comprehensive Developers documentation. Since lattice monitors are called less frequently than energy functions, the performance degradation due to lattice monitor being implemented in Python is much smaller. That same is true for steppers, fixed steppers and steppables. Notice that CompuCell3D kernel that is called from Python, as well as other core CompuCell3D modules called from Python run at native speeds, as they are implemented in C++ with only their API exposed to Python. Therefore if you run CompuCell3D through Python script but decide not to implement new Python modules, your speed of run will be essentially identical as if you ran CompuCell3D using just XML file.

27. If Python is slow, what is the advantage of using it inside CompuCell3D Rapid development – no compilation is necessary. Write or modify your script and run Portability – script developed by you on one machine (e.g. Mac) is ready to use under linux Model integration - you can quite easily implement hooks to subcellular models. We have been able to set up CompuCell3D simulation that was using SBW network intracell simulators within few minutes. T Rich set of external libraries – you may tap into rich Python library repositories that exist for essentially any task Agile development – developing and refining your model is an iterative process. Working at the compiled language stage will force you to spend significant portion of your time waiting for the program to compile. With Python you eliminate this step thus increase productivity. Users should first prototype their models in Python and once they are ready to be used for production runs, rewrite the once causing significant slowdown in C++.

28. Your first CompuCell3D Python script. Make sure you have your copy of Python Scripting Tutorials Begin with template code (the file will be called CellInfoPrinter.py) def mainfcn(): import sys #appending path to CompuCell related Python modules from os import environ from os import getcwd sys.path.append(environ["SWIG_LIB_INSTALL_DIR"]) sys.path.append(environ["PYTHON_MODULE_PATH"]) sys.path.append(getcwd()+"/examples_PythonTutorial") import SystemUtils SystemUtils.initializeSystemResources() import CompuCell import PlayerPython CompuCell.initializePlugins() # Create a Simulator. This returns a Python object that wraps Simulator. sim = CompuCell.Simulator()

29. simthread.setSimulator(sim) simulationFileName=simthread.getSimulationFileName() print "simulationFileName=",simulationFileName # Add the Python specific extensions reg = sim.getClassRegistry() CompuCell.parseConfig(simulationFileName, sim) dim=sim.getPotts().getCellFieldG().getDim() #after all xml steppables and plugins have been loaded we call sim.extraInit() extraInit to complete initialization simthread.preStartInit() sim.start() simthread.postStartInit() screenUpdateFrequency=simthread.getScreenUpdateFrequency()

30. from PySteppables import SteppableRegistry steppableRegistry=SteppableRegistry() ########## HERE YOU WILL REGISTER YOUR STEPPABLE ########### steppableRegistry.init(sim) steppableRegistry.start() for i in range(sim.getNumSteps()): sim.step(i) steppableRegistry.step(i) if not i % screenUpdateFrequency: simthread.loopWork(i) simthread.loopWorkPostEvent(i) sim.finish() steppableRegistry.finish() mainfcn()

31. Opening a simulation with Python script in the Player Go to File->Open Simulation ; Choose xml file. Click Python script “Browse…” button to select python script. Do not forget to check “ Run Python script” check box!

32. Hopefully you are not scared. All the code presented above is a template code with one place holder to register your newly developed steppable. We will first teach you how to develop a steppable because steppables are most likely to be developed in Python anyway. class InfoPrinterSteppable(SteppablePy): def __init__(self,_simulator,_frequency=10): SteppablePy.__init__(self,_frequency) self.simulator=_simulator self.inventory=self.simulator.getPotts().getCellInventory() self.cellList=CellList(self.inventory) def start(self): print "This function is called once before simulation" def step(self,mcs): print "This function is called every 10 MCS“ for cell in self.cellList: print "CELL ID=",cell.id, " CELL TYPE=",cell.type," volume=",cell.volume Let’s take a look at the module that prints cell id, cell type and cell volume for every cell in the simulation. Iterating over all cells is probably most frequently used task in steppables:

33. If you are non-programmer it may looks a bit strange, but imagine how much more would be required to write do the same in C/C++. Much more. Let’s explain the code: class InfoPrinterSteppable(SteppablePy): def __init__(self,_simulator,_frequency=10): SteppablePy.__init__(self,_frequency) self.simulator=_simulator self.inventory=self.simulator.getPotts().getCellInventory() self.cellList=CellList(self.inventory) First line defines our steppable class. Each class has to have __init__method that is called when object of this class is created. You can pass any arguments to this method, but the first argument must be “self”. This is required by Python language. First line in __init__ method initializes Base class SteppablePy. Do not worry if you do not understand it. Treat it as a boiler plate code. Line self.simulator=_simulator stores a pointer or reference to simulator object as a member variable. This way, later on whenever we decide to reference simulator we would use self.simmulator instead of getting simulator some other, more complicated way. Notice, that whenever you access member variable you prepend their name with keyword “self” Subsequently we get reference to cell inventoryt (C++ object) and use it to create iterable cellList (self.cellList=CellList(self.inventory)) Notice, “self” shows up again.

34. def step(self,mcs): print "This function is called every 10 MCS“ for cell in self.cellList: print "CELL ID=",cell.id, " CELL TYPE=",cell.type," volume=",cell.volume Above function implements core functionality of our steppable. It informs that it is called every 10 MCS – see how we set frequency parameter in the __init__ function. The last two lines do actual iteration over each cell in the cell inventory Notice that it is really easy to do the iteration: for cell in self.cellList: Now you can see how storing CellType object as self.cellList comes handy. All we need to do is to pass iterable cell list (self.cellList) to the “for” loop. Actual printing is done in line print "CELL ID=",cell.id, " CELL TYPE=",cell.type," volume=",cell.volume For each cell in inventory “cell” variable of the for loop will be initialized with different cell from inventory. All you need to do is to print cell.id, cell.type, and cell.volume. It is pretty simple.

35. You need to remember this: Python distinguishes blocks of codes by their indentation. Therefore for cell in self.cellList: print "CELL ID=",cell.id print " CELL TYPE=“, cell.type print " volume=",cell.volume would result in an error because the line print " volume=",cell.volume has different indentation than other print statement and thus does belong to the “for” loop. Python will attempt executing this line once after the “for” loop is finished and will return an error that global object “cell” was not found. It was found because “cell” name is valid only inside the “for” loop body. Since the last line was not in the body, you get an error. We are using 3 spaces to indent block of codes, you may choose differently, but need to be consistent.

36. Now save the file with the steppable as, say, MySteppables.py. All you need to do is to provide hooks to your steppable in the main Python script: steppableRegistry=SteppableRegistry() ########## Steppable Registration ########### from MySteppables import InfoPrinterSteppable infoPrinter= InfoPrinterSteppable(sim) steppableRegistry.registerSteppable(infoPrinter) ##########End of Steppable Registration ########### steppableRegistry.init(sim) Notice that registering steppable requires importing your steppable from the file: from MySteppables import InfoPrinterSteppable creating steppable object: infoPrinter= InfoPrinterSteppable(sim) registering it with steppable registry: steppableRegistry.registerSteppable(infoPrinter)

37. Now, all you need to do is to open in the Player previous xml file (cellsort_2D.xml) together with newly created CellInfoPrinter.py and check Run Python check box. Notice that you are not loading directly MyStappables.py file. The module you stored to this file will be called from CellInfoPrinter.py. Try running the simulation and see if you got any performance degradation. Probably not, but you by using Python you have saved yourself a lot of tedious C++ coding, not to mention that you do not need to care about dependencies, compilation, etc.. Writing your next Python steppable will require much less effor as well, as you will quickly discover that you will be using same basic code template all over again. Instead of thinking how the code you are writing fits in the overall framework you will just concentrate on it’s core functionality and leave the rest to CompuCell3D. In case you wonder how this is all possible, it is due to Object Oriented programming. Hopefully this short tutorial will encourage you to learn more of object oriented programming. It is really worth the effort.

38. First application written in Fortran Tom ports to C Adds command line parameters, makefile Jenny ports to F90 Extends model Brad ports to C++ Models system using objects Maria implements simulation in Java for the Grid Implements original model F77 C C++ F90 Java Why CompuCell3D and why now? Typical Evolution of Research Software (in collaboration with Chris Mueller) Sounds familiar? Keep listening…

39. C1C1 C2C2 C3C3 F77 1 F77 2 F90 1 F90 2 F90 3 F90 4 C++ 1 C++ 2 C++Java Version used for paper There were 6 major versions –13 actual implementations –5 Languages 2 major versions advanced the science 4 major versions were simply software projects All versions re-implemented basic features The implementations used for the papers were not always used for the next major version Versions that advanced science A Closer Look

40. Problem: Research software applications are difficult to develop and are costing researchers time and money. Solution: Separate Research and Development and use a development model derived from industrial software development. Software Quality is improved –Applications are not single-user prototypes –Features are available to all researchers and are peer-reviewed Research Process is improved –Researchers can focus on research –Development is not a bottleneck –Reproducibility and Traceability Reproduce old experiments, trace the data/process that led to a result –Easier to integrate new/visiting researchers High-end software becomes possible –Parallel and high-performance implementations –Well designed user interfaces, visualization, databases, web applications and services Benefits

41. CompuCell3D collaboration University of Notre Dame, Indiana University People: Mark Alber, Ariel Balter, Rajiv Chaturvedi,Nan Chen, Trevor Cickovski, Jeff Coffland, Michael Crocker, Gabor Forgacs, James Glazier, Tilmann Glimm, George Hentschel, Chengbang Huang, Jesus Izaguirre, Chris Mueller, Stuart Newman, Nikodem Poplawski, Maciej Swat, Gilberto Thomas Funding agencies and institutions: NSF, ICSB Notre Dame, The Biocomplexity Institute Indiana University, NIH Users – most important part of the collaboration. Website: http://sourceforge.net/projects/compucell/ Google keyword: CompuCell3D

42. Running the simulation Steering bar allows users to start or pause the simulation, zoom in, zoom out, to switch between 2D and 3D visualization, change view modes (cell field, pressure field, chemical concentration field, velocity field etc..) Player can output multiple views during single simulation run – Add Screenshot function Information bar

43. Scripting languages – extending capabilities of CompuCell3D BIOLOGO - high level, XML based language for describing parts of the simulation. BIOLOGO is translated to C++ and compiled as a CompuCell3D plugin to deliver optimal performance. It is straightforward to use Python: We will embed Python in CompuCell3D to give users similar level of flexibility as Matlab or Mathematica. Most of the low level functions will be implemented in C++ but callable from Python level. Example: Creating a PDE solver is reduced to writing several statements in BIOLOGO. <Term exp="Kronecker(x,y,z)*alpha - epsilon*C*(1-Kronecker(x,y,z)) + DiffConst*Laplacian(C)" condition="true" /> Kernel Plugin C++ BIOLOGO

44. Example simulations using CompuCell3D Dictyostelium discoideum

45. The model is based on oscilatory Fitzhugh-Nagumo type of equations (Savill Hogeweg, 1997): c – denotes cAMP concentration - activator r-refractoriness - inhibitor f(c) – piecewise linear function b=0 for excitable cells, b != 0 for autocycling cells This system of equations will produce waves of cAMP passing through the lattice. Cells respond to cAMP gradient by biasing their movement towards higher level of cAMP. We assume that cells chemotact “periodically” and only when cAMP concentration is high enough

46. Autocycling amoebae initiate waves of cAMP cAMP wave passes through amoebae and a substrate Amoebae move up the cAMP concentration gradient - chemotaxis Mound is formed with autocycling cells at the top cAMP wave propagates down the mound Dictyostelium Discoideum – early stages of aggregation

47. Cell sorting Cell sorting is a rearrangement of cells driven by local physical properties of cells (cell-cell adhesion). Different parameters lead to different final patterns: Initial configuration of condensing (red) and non-condensing (green) cells immersed in medium (blue) Checkerboard pattern arises when adhesion between red and green cells is stronger than adhesion between cells of the same type Complete sorting – adhesion between red cells is stronger then between green cells and between red and green Partial sorting – very similar to complete sorting except that the adhesion between red and green cells is higher than adhesion between green cells

48. Gastrulation Ariel Balter All higher animals undergo a process called gastrulation at the earliest stages of development. During gastrulation the embryo takes the first steps from a more-or-less uniform ball of cells towards a differentiated organism with individual organs. One of the key process that begins gastrulation is the onset of large-scale motion of cells which first deform the symmetric blastoderm (the stage preceding gastrulation). It has been hypothesized that cell motion in response to chemical attractors and repellors plays an important role in this process. Here we test a highly simplistic model of chemo-attraction/repulsion in the chick embryo. This model does capture certain features of overall cell redistribution as well as the resulting remodeling of the embryo as a whole. However it does not reproduce vortex motion observed in work done under James Glazier. Area Opaca Chemo-attractant source Chemo-repellant sourceCharacteristic bulging due to pressure from aggregating cells Area Pellucida

49. Fibronectin driven condensation as a function of cell density Nikodem Poplawski We are able to study how fibronectin-cell interaction and initial cell density affects cell condensation patterns. Fibronectin limits the size of forming clusters. High cell density results in stripes of cell condensate Medium cell density produces a mixture of condensate stripes and spots Low cell density leads to condensate spots

50. Roadmap CompuCell3D needs further development in order to become a universal framework for modeling morphogenesis: 1st quarter 2006 -Full support for scripting languages -Isolate users from XML - graphical configuration tools -Provide full diagnostics of the simulation in CompuCell Player – for example right- click should provide information about given cell 2nd-3rd quarter 2006 -Movies, scientific plots and all lattice information will be available through the Player -Parallel version 2006/2007 -Steering and parameters sweeps -Serializing simulation – users will be able to stop the simulaiton and resume it later -Project management