Cellular Dynamic Simulator User Guide for Beta 2, (v0.403)

07/30/2010

1

Part I. Getting Ready 1. Installation and Usage . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5 1-1. Requirements 1-2. Running the Simulator and Initializer 2. Terminology . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6 3. Getting Started . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7 Part II. Cellular Dynamic Simulator 1. The Basics . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8 1-1. Design 1-2. Parallelization 1-3. Features in Brief 2. Features in Detail . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10 2-1. Meshes and Sub surfaces 2-2. Reactions 2-3. Transport 2-4. Binding 2-5. Permeability 2-6. Events and Actions 2-7. Functions 2-8. Integration 2-9. Modules 3. Running Cds.jar . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 22 3-1. Command line arguments 4. Potential Issues . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 22 4-1. "Escapes" in the DbmGridWorld 4-2. Memory Limit 4-3. Other Issues Part III. CDS Initializer 1. Running CdsInit.jar . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 24 1-1. The grid panels 1-2. The toolbar 1-3. The grid panels 1-4. The properties frame 1-5. Prefabricated meshes 1-6. Hotkeys 2. Creating a world . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 26 2-1. Creating a compartment 2-2. Creating an element 2-3. Adding elements into a compartment 2-4. Adding elements onto a compartment 2-5. Adding elements onto elements 2-6. Adding moving compartments to a compartment 2-7. Adding elements to a group of moving compartments 2-8. Adding elements to the World

2

3. Modifying a World . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 28 3-1. Adding properties to an object 3-2. Object selection 3-3. Object translation 3-4. Object scaling 3-5. Object rotation 3-6. Mesh merging 4. Mesh Editor . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 30 4-1. Selecting faces and nodes 4-2. Naming a set of faces 4-3. Editing element meshes 5. Modifying Properties . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 31 5-1. Definitions Panel 5-2. World Panel 5-3. Reactions 5-4. Modules 5-5. Events 5-6. Functions 5-7. Odes 6. Notes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 32 Part IV. CDS Visualizer 1. Running CdsViz.jar . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 34 1-1. Properties tree 1-2. VCR controls 1-3. View and control window 1-4. Menu options. 1-5. Full Screen 2. Movie Recording . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 36 3. Trajectories . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 36 4. Properties Pane and Changing Properties . . . . . . . . . . . . . . . . . . . 37 4-1. Sphere Divisions 4-2. Shaders Part V. Walk Through 1. First Steps . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 39 1-1. Adding the first compartment 1-2. Creating an element 1-3. Adding the element to the compartment 1-4. Modifying the element properties 1-5. Sample Run 2. Adding More Complexity . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 41 2-1. Adding Reactions 2-2. Tracking Population 2-3. Modifying World Properties 2-4. Re-run the simulation

3

Part VI. Writing Custom Modules for the Initializer 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 43 2. The Code . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 43 3. Walk Through . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 44 3-1. The DendriteCreatorExample Module 3-2. Creating and compiling 3-3. Setting up the Cds file 3-4. Executing the module 3-5. Viewing the creation 3-6. Additional Info Part VII. Writing Custom Modules for the Simulator 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 47 2. The Code . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 47 2-1. Extending the Module class 3. Compiling and Implementation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 49

4

I. Getting Ready 1. Installation and Usage Three applications are included in the package, Cds.jar which is the simulator, CdsInit.jar the Initializer for creating simulations, and CdsViz.jar for viewing rendered animations of a completed simulation or a simulation file. 1-1. Requirements: Cds and CdsInit were compiled with Java 1.6.0_20. It is required to have at least version 1.6 of the Java Runtime Environment installed which can be downloaded for free from http://java.sun.com/javase/downloads/?intcmp=1281. CdsViz require two extra libraries for movie making and 3D rendering. These are the Java Media Framework (http://java.sun.com/javase/technologies/desktop/media/jmf /2.1.1/download.html) and Java3D (http://java.sun.com/javase/technologies/desktop /java3d/index.jsp). If these links ever become broken, searching the Java site for "Java3d" and "JMF" will return the appropriate links. 1-2. Running the Simulator (Cds.jar) and Initializer (CdsInit.jar)

1-2-1. Launching the Initializer (CdsInit.jar) to create a simulation. CdsInit.jar is an executable jar file. To run from a file explorer simply double click. To execute from a command prompt or terminal, use "java –jar CdsInit.jar" (assuming that Java is set in your PATH variable). Using the Initializer is detailed in Part III and Part V. 1-2-2. Launching the simulator (Cds.jar) from the Initializer. Once a simulation has been created in the Initializer, save the simulation. Then select the from the menubar "Run" and the sub item "Run." A frame will appear with argument options and an "Execute" button. Simply hit the "Execute" button to run the simulation. If the simulation file was modified since it was opened or created from scratch, then it must be saved before attempting to execute. 1-2-3. Launching the simulator (Cds.jar) from a terminal or command prompt. To launch Cds.jar, from the command line enter "java –jar Cds.jar [args] filename". For a list of arguments, use "-help". The filename is the location of the simulation file (.cds) and can include a relative path. The proper separator must be used based on the OS being used ("\" for windows, "/" for Linux). Command line arguments are explained in more detail in part III. Scripts are included with the package to simplify this. "Cds.bat" for Windows and "Cds" for Linux includes the "java -jar Cds.jar" portion of the command. Launching through the script on Windows may look like "Cds.bat [args] filename".

5

Note: Double clicking the jars may not work depending on the version of your JRE. Use the scripts if this occurs. Note: If the "Cds" script does not run due to permissions, use the command "chmod 744 Cds" to assign the proper permissions. Example: Included with the full package is a simulation called Dense that is located at "/Simulations/Examples/Dense/Dense.cds". To run this simulation, in a terminal window from the directory containing Cds.jar, the user would type: java -jar Cds.jar Simulations/Examples/Dense/Dense.cds Note: All commands and properties in Cds and its accompanying tools are case sensitive. Also, all names given to molecules, modules and functions should be unique. They don't always have to be, but it is best to always have unique names to avoid problems. 1-2-4. The "-server" flag. A typical JRE only contains one mode which is called client mode and is optimized for GUI applications. Included with the Java development kit (JDK) is another mode called server mode which will speed up computational software dramatically. With the 64-bit Java for Linux, the server mode is included and is the default. For other JREs, to get the server mode, the user must download the JDK. Within the JDK, there is a "jre/bin/server" directory. Copy that server directory into the "bin/" directory of the JRE and you will be able to use the "-server" flag when launching java. The launching command will now look like: java -server -jar Cds.jar [args] filename

2. Terminology The Cellular Dynamic Simulator is general in design, but can used to investigate specific environments. A few basic components in the simulator are used to represent many different things. World – The 3D space which contains the simulation environment. Mesh – A mesh is composed of a series of vertices and triangular faces. Each face has three references to the vertices that make up the face. The order of the vertices are such that the normal vector of a face defined by them points away from the center of the mesh. Every compartment that exists within the simulator is made from a mesh. Compartment – A static object that can contain diffusing elements. Collision detection with a compartment is performed face by face. Element – Any potentially diffusing ion, protein, or receptor. These are not necessarily mobile. Elements can exist within a volume or bound to a membrane (compartment surface).

6

Surface – A surface is an object that adds properties to a mesh such as reactions and internal state. Elements and compartments both extend a surface. Most times an element is described as an entire entity so the surface is implicit. However, for protein complexes, we can subdivide the mesh into different surfaces each with their own properties. In that particular case the general term "surface" is analogous to "subunit". MovingCompartment – A compartment with almost identical abilities as an Element, but it has an internal volume that may contain diffusing Elements. It can also have elements bound to its surface. Module – A class that is loaded by the simulator at runtime that is designed for analysis and output. Any user created module can be loaded as long as it extends the class Module.java. 3. Getting Started It is recommended to browse through Part II to get an understanding of how the simulator is designed and its features. However, before running the simulator, you must first read Part III to learn how to use the Initializer to create a simulation file. Following this guide in order will set you up with an understanding of this simulation environment and usage even though some parts will seem confusing at first. Things won't become clear until Part V where I will provide a step by step walk through of creating a simulation environment with enough complexity to get you used to most of the features. Some of the detailed explanations of features can be skipped initially and re-referenced as needed.

7

II. Cellular Dynamic Simulator 1. The Basics The Cellular Dynamic Simulator is based on an event driven algorithm. The algorithm searches for the next possible event that will occur, then advances the simulation environment by that amount of time. The event is processed, then the simulator repeats searching for the next event. An event can be a collision, reaction, user defined event, or numerous others. Every diffusing element checks neighboring diffusing and static elements for a potential collision, and is rechecked whenever it's velocity changes. This allows CDS to precisely simulate individual molecular interactions and crowded environments. Brownian motion is introduced by randomizing every diffusing element's velocity at a given time step. 1-1. Design. Cds is programmed in Java for cross platform compatibility and for an easily modifiable object oriented design.

1-1-1. Event Algorithm The core of the simulator is the CDS class which iterates through the event driven algorithm. The main loop iterates while the current simulation time is less than the end time or until an exit condition is reached. At the start of this loop, trajectories are randomized to create Brownian motion. What follows is an inner loop that continues until the next time step is reached. Within this loop, the simulator calls the world and finds the next occurring event. The world is advanced by the time until that event occurs, then the event is processed. This loops until the next time step is reached. 1-1-2. The World The world is an abstract class that contains all references to compartments, elements, user defined events, variables, and functions. Included with CDS are several types of worlds: simple, grid, and periodic. 1-1-3. Meshes to Elements Both compartments and elements are the final products of a series of parent objects. They each share many of the same properties (such as reactions and structure) that are defined by super classes. Mesh -> Surface -> Structure -> Compartment -> MovingStructure -> Element -> MovingCompartment

1-2. Parallelization

8

Multi threading is implemented in two sections of the event driven algorithm, advancing the environment and collisions detection. Collision detection is the most computationally intensive portion. Due to other optimization factors such as subdividing the world, multi threading is not very scalable and this is also an issue with memory sharing. As more threads are added, there are diminishing returns in improved performance. Typically 4 threads provides the best increase in speed given the number of cores used. Non optimized worlds with many molecules could easily be beneficial with up to 8 threads. This is considering the need to run at least 10 repetitions of a single simulation and the number of available cores is a precious resource. If 40 cores are available, running 10 simulations that each use 4 threads will have a completion time much faster than that of running 5 simulations at a time each using 8 threads and then running another 5 simulations after the first set completes. 1-3. Features in Brief The following is a brief description of CDS's features. For a more detailed description and usage, see the following sections.

1-3-1. Meshes and Sub surfaces For both compartments and elements, the default for a mesh is to assign to each face the species name. However, faces can be selected and renamed to define a unique surface. This new surface can have its own properties such as a current state, reactions, binding and transport. 1-3-2. Reactions Reactions can be in the form of association, dissociation, or spontaneous reactions. Molecular species can change in a reaction, or the species can remain the same, but undergo a state change. Reactions can be applied specifically to a sub surface within an element such as a single subunit of a four subunit receptor. 1-3-3. Transport Transport is a general functionality specifically designed for channels, but is also used to create periodic boundary conditions. It can be used to jump an element from one point in space to another (across membranes too). 1-3-4. Binding Binding and Unbinding can occur between an element and compartment or between an element and element. This is used for receptor recycling, protein aggregation, and static membrane bound elements. 1-3-5. Permeability By default all membranes are impermeable and all molecules register collisions with each other. Transparency properties can be added to any surface which would make that surface or molecule invisible to the specified target. 1-3-6. Events and Actions

9

In the event list, the user can add several types of events that can be triggered based upon a rate, a specific time, or a condition. These events can be triggered once or they can be recurring. For any event that can occur within this simulator (except bounce collisions), an action or series of actions can be associated with that event. When an instance of that event occurs, it's attached actions are processed. An action can be used to modify properties, delete elements, add new elements, modify simulation variables, and halt the simulation. 1-3-7. Variables and Functions A series of functions can be defined and then referenced by any part of the simulator (such as a reaction rate) by calling the function name. A function can be made up of almost any expression and has many functions built into it (sin(x), cos(x), min(x, y), rand(x, y), etc). Functions can also be conditional and return one of two functions based on a conditional function. Simulation variables as well as populations are stored as a variable object which can be referenced by various components of the simulator. Users can define functions which can also be referenced by name. An example of this is an ion channel that influxes an ion at a rate dependent upon the intracellular concentration of that ion. 1-3-8. Integration CDS includes an ODE integrator. Integrated variables can be referenced from other components of the simulator. Parameters within the ODE can also reference other variables from within the simulator. 1-3-9. Modules A module is extension of an abstract object that can retrieve, process information, and send actions back to the simulator. Users can create their own code to do whatever they desire. Modules that come with the simulator include VizOutput and PopulationOutput.

2. Features in Detail 2-1. Meshes and Sub surfaces The file format used to describe a mesh is a standard format called an Object file (.obj). Most 3D editing software has the ability to import and export many of the standard formats. Since the only information the simulator needs is the vertices and faces, the .obj format works well. An additional flag in this format is a group flag which allows the user to assign faces into a group. Cds uses this to label sub surfaces within a mesh that can be assigned reactions and transports specific to this region. For example, an element representing a receptor can be broken down to individual subunits each with its own reaction scheme of ligand binding and unbinding. Example:

10

When a receptor is first created, say with a name "Nmda", then every face is assigned the species name as its surface name. By selecting several faces and giving them a unique name, say "sub1", a new surface is created. For an example ligand binding to a subunit, a reaction would look like this: Nmda.sub1.state1 + glutamate -> Nmda.sub1.state2 : 1.0 This is only going to work if glutamate collides with the Nmda element on the surface defined by "sub1" and when that surface is in the "state1" state. A ligand binding to the surface defined by Nmda would be: Nmda.state1 + glutamate -> Nmda.state2 : 1.0 Another popular file format used for describing sub cellular compartments is the VRML format. The Initializer allows the importation of VRML. The current parser may not be that robust and could fail depending on the contents of a VRML file. The parser was built to handle the organization of VRML files based upon several common examples that were found. It may need to be updated in the future. Deleting non vertex and face information from the VRML file will allow it to be read by the parser. A VRML file that can easily be parsed should look like: point [ x y z, x y z, ......., x y z ]

coordIndex [ x, y, z, w, x, y, z, w, ........, x, y, z, w] 2-2. Reactions CDS is capable of zeroth order, unimolecular and bimolecular reactions. Reactions may occur as changes in species, in internal state, or in surface state. Designation of reactants and products may be in three different forms: species_name, species_name.state, species_name.surface_name.state. Association reactions take place upon collision of two molecules. The probability that a reaction will take place upon collision is determined by a value between 0.0 and 1.0 which is entered in place of the reaction rate (for 1st order reactions). If the reaction is in the form of A + B -> C : 1.0, then reactants A and B will be physically removed from the world and C will be added at the midpoint between A and B's prior location. At the time the reaction is processed, the maximum radius of A and B will be touching. If there is no room for C at that location, CDS will look for free space to place C about that point. After x iterations, in different directions and gradually increasing distance, if no room could be found, then the reaction does not take place and A and B are revived exactly as they were prior to deletion. If the reaction is in the form of A.state1 + B -> A.state2 : 1.0, then molecule B will be removed from the world and A will retain its current location and trajectory. Association reactions may also be calculated based upon a reaction radius and not the physical radius of the molecule. If valid reactions exist between two molecules, then collision detection will be based upon the reaction radius. This affects only the time until collision and not how the reaction event is processed. Another consideration with association reactions is the case where two reactions exist with the same reactants (e.g. CaM.1 + Ca -> CaM.2 : 0.15 and CaM.1 + Ca ->

11

CaM.3 : 0.25). CDS selects a random number between 0 and 1. If the random number is less than the probability of the first reaction to occur, then, the first reaction is selected to occur. Otherwise the probability of the second reaction is added to the probability of the first reaction and that value is checked against the random number again. This continues until a reaction is chosen, or there are no more valid reactions left which will result in no reaction occurring. Dissociation reactions take place as a unique event. The time until the reaction will occur is calculated from the reaction rate based upon a Poisson distribution in the same fashion as the Gillespie algorithm (Gillespie, 1976). reactionTime = -ln(random()) / rate Where random is a uniformly distributed number between 0.0 and 1.0. Like association reactions, a dissociation reaction may be in the form of C -> A + B : 0.1, A.state2 -> A.state1 + B : 0.1, or A.sub1.state2 -> A.sub1.state1 + B : 0.5. As with association reactions, CDS attempts to add the dissociated molecules about the location of the reactant. In the case of a C -> A + B reaction, the larger of the products is placed at the former location of C (let's assume the larger molecule is A). Then free space for B is searched for by choosing a random point about the former location of C and at a distance of A's radius times 1.1 plus B's radius. While free space is not found, a user specified number of new random points are tried about C's former location prior to incrementing the distance by B's radius. The number of times to increment the radius is also a user variable. If no free space is found to add B, then the reaction does not take place and a new reaction time is calculated. The total number of tries to find free space is the product of cycles per distance and the number of radius increments. This algorithm for finding free space will only occur in highly dense environments. In most cases, dissociating molecules will be placed adjacently with trajectories opposite of each other. By setting the radius increment parameter to 1, the user can force CDS to try to find adjacent space, otherwise the reaction does not occur. Surface reactions, as described so far, are inter-molecular meaning that a surface of a molecular species may only interact with another molecule. To accommodate interactions between neighboring subunits on the same protein (e.g. CaMKII), CDS allows the user to group together surfaces. For example, two subunits of CaMKII may be grouped together with a rule that checks when both subunits are in a calmodulin bound state. When the condition of this rule is met then the user can trigger state changes to switch CaMKII into an autophosphorylated state. A group may have its own internal state as well as a spontaneous first order reactions to change that state. These reaction are specified in the same manner as subunit reactions, so subunits and groups must have subunit names. 2-3. Transport The transport property is an event triggered upon collision of a diffusing molecule to a surface and is used to instantaneously move the colliding molecule from one point in space to another. The principle application of this is to transport ions across impermeable membranes. A vector is used to describe the placement of the transported molecule relative to the location of the channel (or any structure with the transport property). CDS will attempt to move the molecule to that point in space or if no room exists, then it will try to find room in a conical fashion based upon the

12

movement vector. Like dissociation reactions, if free space cannot be found within 50 tries, then the event does not take place. There are three ways of moving a molecule once it collides with the transporter. The MoveAbs property will move the molecule to some absolute point in space regardless of where the transporter or molecule are. MoveRel will move the molecule from its current location by the amount defined by the vector. MoveRelThis will move the molecule from the location of the transporter plus the vector. MoveRelThis is the typical usage. Regardless of what angle the molecule hits the transporter, the molecule will always be moved based upon the defined vector which changes based upon the rotation of the transporter (assuming the transporter is membrane bound and has an AlignTo vector defined). If the AlignTo vector is defined, when the transporter is rotated, the vector associated with the transporter is rotated as long as it is defined by MoveRel or MoveRelThis. If the vector is defined by MoveAbs, it is not rotated. These are the property values that define the transport: Target: <name> - The name of the target element to transport. Prob: 1.0 - The probability that the target will be transported upon collision. OutsideVolume: volname - Specifically state the outside volume to be transporting into. Active: True - Only transports if this value is true. MoveAbs: (0, 0, 0) - Target will be moved to the origin of the world and retain its current velocity. MoveRel: (0, 0, 10) - Target will be moved relative to its position. MoveRelThis: (10, 0, 0) - Target will be moved relative to transporter's position. If a transport is set to inactive by default, it will never transport an element unless an action switches it to an active state (see Events and Actions below). 2-4. Binding In the reaction scheme, when an association reaction occurs the reactants are physically removed from the simulation space and an instance of the specified product is created in their place. Using a molecule binding property, molecules become physically attached and move as a pair. Two types of binding can occur, an element to a membrane and an element to another element. There is no limit to the size of the chain of bound elements. Unbinding properties can also be defined and are treated as separate events. When molecule A binds to molecule B, B is checked for any unbinding events associated with molecule A. If this unbinding event is defined in the input file, an event time for that unbinding is calculated based upon a rate using the same Poisson distribution used for dissociation reactions. When a freely diffusing molecule binds to a membrane, it can be aligned based upon the normal vector of the triangle defining that part of the membrane that it collides with. If an alignment vector is specified (eg. "AlignTo: 0 0 1"), CDS will rotate the molecule such that the alignment vector points in the same direction as the normal vector. A standard convention for meshes, and one used strictly in CDS, is that all normal vectors point away from the center of the mesh. This is used to determine (for a closed compartment) what is inside and what is outside. This is particularly relevant for channel trafficking where the dissociation or transport of ions is important. When the mesh is rotated, all vectors associated with the molecule are rotated also. When adding

13

elements onto a surface in the Initializer, if the elements are to be rotated to the normal, the AlignTo property must be specified prior to adding the elements. Also when a freely diffusing molecule binds to a membrane it becomes static even though the Movable property is still true. If the Independent property is defined and set to True, then it moves independently of its parent structure. So if the Independent flag is true, then upon binding it will begin to diffuse laterally on the membrane. Membrane bound diffusing molecules have a random trajectory that lies in the plane described by the triangle that the molecule resides on. Collision detection in this mode is performed on the center point of the molecule against the three line segments that make up the triangle. When a molecule hits the edge of a triangle it will calculate a new trajectory that lies in the neighboring triangle and the molecule will rotate itself such that it is aligned to the normal vector of the new parent triangle. Two ways of binding are embedded and not embedded. For binding a channel to a membrane, embedded is the option to take and for protein aggregation, not embedding. The default is to not embed.

Example of elements initiated as embeded and laterally diffusing. Note: For membrane bound receptors to move, the LateralDiffusionCE must be specified. Binding properties:

Target: name - The name of the target element to bind. Prob: 1.0 - The probability that the target will be transported upon collision. Embed: False - False if the binding element is adjacent to the binding parent, or True if the binding element moves such that it's centroid lies on the surface of the binding parent. Independent: True - If a target becomes membrane bound, does it become immobile (False) or does it start lateral diffusion (True)? Unbinding properties: Target: name - Target to which this unbinding applies. Rate: 0.01 - Rate of unbinding. Direction: value - Value can be "In" "Out" "Same" "Either" or "Opposite".

14

2-5. Permeability By default all membranes are impermeable and all molecules register collisions with each other. Transparency properties (TransparentTo: TARGET_NAME) can be added to any surface which would make that surface or molecule invisible to the specified target. In the case of diffusing molecules, collision detection is not performed. With membranes, collision detection is performed so that transfer between two volumes can be registered. However, trajectory is not altered. When two volumes are connected, they must be connected with a permeable membrane or else population tracking will not be performed correctly. This does take into account the consideration that an element may be overlapped with the boundary when trajectory is recalculated. Information about the collision is stored until an element has moved completely into its originating volume or completely into the new volume. Transparency can be added to diffusing elements with each other. For instance, if calcium-calcium collisions would be negligible to the result, you can speed up the simulation by adding a "TransparentTo: Ca" to Ca. 2-6. Events and Actions Everything that occurs in the simulation environment is termed an event. This includes all previously mentioned properties such as collision, reaction, binding, unbinding, and transport. While a reaction for example will result in reactants forming products, CDS allows users to add additional changes that can be performed when that event occurs. The term for these changes is an Action. Actions can change properties, simulation variables, add or delete elements in a volume or surface, and can terminate the simulation. When changing element properties, this can occur for just the reacting elements, or can change properties globally. If a reaction occurs of the form A + B -> C, a local action would only affect those elements involved with the reaction. An example of this would be Action: C.Set.Movable.False. The default value for C may for it to be movable. Using this action would make it immobile upon creation after the reaction. A global action may change the properties of a population of elements such as Action: All.C.Set.Reactable.True or All.Ampa.Set.CurrentState.Open. CDS allows users to create their own events that can trigger a series of actions and provides a variety of ways on how and when these events are performed. Triggering vesicle release, channel influx, or bath application of a drug are examples of what can be handled with user events. These events can be singular or recurring and can be triggered based on an explicit time, by a rate, or conditionally. They may also be activated by another event. Events triggered by an explicit time use that value as the time until the event occurs. That event time is decreased as the simulation environment advances. Events triggered by a rate have their event time calculated by a Poisson distribution identical to that of unimolecular reactions. Conditional events are checked if their boolean function returns true or false at the start of every time step. If true, the actions associated with that event are performed, and nothing occurs if false. For singular events, once the event is processed, no new event time is calculated. For recurring events, when the event is processed, it’s event time is recalculated. Examples of actions (bold and in caps indicates user specified names):

Var.VAR_NAME.Add.10 Adds a value to the specified variable

15

Var.VAR_NAME.Subtract.52.44 Subtracts a value from the specified variable Add.COMPARTMENT_NAME.SPECIES_TYPE.100 Adds a number of the species to the compartment. World.Set.VAR_NAME.VAR_NAME = 0.01 Sets a value to a variable World.Halt Stops the simulation Event.EVENT_NAME.Activate Calculates an event time for the specified event making it active Event.EVENT_NAME.Deactivate Removes the event time for the specified event making it inactive SPECIES_TYPE.TRANSPORT_NAME.Activate Makes the transport available to handle transport events. If the transport is inactive, then any element collisions with it will register as bounces. SPECIES_TYPE.UNBINDING_NAME.Deactivate Makes the transport available to handle transport events. If the transport is inactive, then any element collisions with it will register as bounces. SPECIES_TYPE.BINDING_NAME.Set.Active.False Makes the transport available to handle transport events. If the transport is inactive, then any element collisions with it will register as bounces. SPECIES_TYPE.Degrade.Active.True Calculates an event time for degradation Id.ID_#.Set.CurrentState.STATE Sets the current state by referencing the ID. This can be used for any property modification to elements. SPECIES_TYPE.Set.CurrentState.STATE Changes the current state All.SPECIES_TYPE.Set.CurrentState.STATE Changes the current state for all of a species SPECIES_TYPE.Unbind If the molecule is bound, this forces it to unbind (assuming it has an unbinding event associated with it). SPECIES_TYPE.UNBINDING_NAME.Unbind If the target specified in the unbinding exists as a bound child, then it will unbind

16

SPECIES_TYPE.Delete Removes the element from the world.

Some of the possible actions are not yet implemented. Turning on and off transport, binding and unbinding are the only modifications to those events. Specific behaviors can be implemented by request. Activating or deactivating the unbinding is only for a bound element that has an unbinding property loaded. This doesn't affect the list of unbinding properties. So turning on and off that loaded unbinding either sets its event time to a max value, or recalculates it based upon the unbinding rate. Some aren't listed here, but are all similar. Instead of Ca.Delete to delete a particular element involved with a reaction, you can do All.Ca.Delete to remove all calcium from the world. Examples of events:

Event: e1 Conditional : Ode.Vm > -40.0 Action: All.CaChan.Set.CurrentState.1 Action: Event.e2.Activate Action: Molecule.Set.Prop.Value Event: e2 Conditional: Ode.Vm < -40.0 Action: All.CaChan.Set.CurrentState.0 Active: False Action: Event.e1.Deactivate Event: e Conditional: Volume.Spine.Population.Ca >= 100 Action: World.Halt Event: e Time: 1000.0 Action: Add.Spine.EGTA.500

2-7. Functions Many instances where CDS takes input as a parameter value can be defined as a function instead of a constant. Functions can be comprised of almost any mathematical expression and include basic functions included in the Math class of the Java language. Variables may also be called from within functions. A CDS variable is an object that stores a double precision value. Variables are passed to different parts of CDS with a reference so that many components of CDS may access the value stored within the variable. An example of a variable would be Ca population of a spine. Like actions, a code is used for designation and retrieval of variables (e.g. Volume.Spine.Population.Ca or World.Time). For example, a function describing Ca influx into a compartment may be dependent upon the Ca concentration within that compartment. Standard parameters that may take a function as input include the end time, time step, diffusion coefficient, reaction radius, and reaction rates. Functions defined in the World are recalculated at every time step and can be referenced by other functions within the simulator by name. A function defined in the

17

function list can be in the form of "func1 = exp(-World.Time)" and can be referenced by using the code "Function.func1". The following are built in Java functions that may be called from within a function. Here, x and y do not have to be scalars and can be expressions themselves.

sqrt(x) abs(x) ln(x) min(x, y) cbrt(x) exp(x) log(x) max(x, y) cos(x) sin(x) tan(x) rand(l, u) acos(x) asin(x) atan(x) floor(x) ceil(x) round(x) pow(x, y) -(x) sum(x, y, …) prod(x, y, …)

Java stored constants can be referenced such as "Pi" for Math.PI and "E" for Math.E. For logarithm, ln(x) is the natural logarithm and log(x) is the logarithm base 10. In cases such as the user defined conditional event, a boolean function is required which returns either a true or false value. Operators include "&& and ||" and comparators include <, >, <=, >=, ==, and !=. A negation (!) can also be placed in front of statement that returns a boolean. Furthermore, a function actually contains two different modes. A function can have the form of an expression such as "x + y * z – 5.0" or can be conditional such that it stores a boolean function, a function if true is returned, and a function if false is returned. This takes the form of "BOOLEAN_FUNCTION ? TRUE_FUNCTION : FALSE_FUNCTION". To better explain the dual functionality within a Function object, here is the code of the solve method:

public double solve() { if (conditional) return (condition.solve()) ? trueFunction.solve() : falseFunction.solve(); else return equation.solve(); }

Conditional functions can also be nested. The TRUE_FUNCTION or FALSE_FUNCTION themselves can be conditional. An application of this hasn't been considered, but the ability is there. F = (Condition1) ? ((Condition2) ? TrueFunc2 : FalseFunc2) : FalseFunc1 Examples: Function: Stimulus = (Time % 1000 > 0 && Time % 1000 < 10) ? 10.0 : 0.0; Function: am = 0.1 * (Ode.V + 35.0) / (1.0 - exp((-35.0 - Ode.V) / 10.0)) Function: bm = 4.0 * exp((-60.0 - Ode.V) / 18.0) 2-8. Integration CDS includes an integrator for solving a system of ordinary differential equations. ODE variables that are being integrated can also be called from various components in CDS. Likewise, parameters written in the ODEs may be CDS variables. One possible application of this would be to trigger voltage-gated channels using Hodgkin-Huxley equations. The default integration method is a fourth order Runge-Kutta method using a fixed time step that is by default the time step used for randomizing trajectories. If that time step is not small enough for accurate integration, then a smaller time step is used.

18

ODEs are integrated as the simulator progresses. At the end of each time step, the system is integrated up to the current simulation time. To define the smaller step size, add a world property called "IntegrateStep" and set the value less than the time step and as a factor of the time step. In the world property list we should see: "IntegrateStep: 0.01" 2-9. Modules Modules are extended from an abstract class such that several methods are declared, but those are not defined in the parent class. Subclasses of the Module class define the functionality of the module. A module can pull information from a component of the simulator to store or process that information. Users have the ability to extend this class to write their own code which can be used by the simulator and several modules are included in the simulator which include output. This is described in 2-9-6. Modules are defined in the "Modules" section of the input file. There is a dedicated tab on the properties frame of the Initializer for adding and editing modules. The key is the name of the class file of the module to be loaded and the value is the name which to reference this module by. For example: Key: TraceOutput Value: trace1 Key: PopulationOutput Value: pop

To add that trace module to an element, this goes into the element definition: Module: trace1

Within that module, any number of properties can be added which may initialize the module. For included modules, the possible properties are explained below. Most modules included with CDS have three similar properties, Filename, BufferSize and Interval. If Filename is not specified, a default is used, it one is specified that will be used to write the output. Output is not continuous, a buffer is filled prior to writing to disk which speeds up the simulation. The size of this buffer is specified by BufferSize. For a lot of trace and population Warning: It is possible to add a module into any object in the simulator, but some modules are designed only to work with certain objects. The VizOutput can only be added to a compartment, element or moving compartment. Any attempt to add it to a volume, or world will result in errors. If you have a module defined, but don't want to record for a particular simulation and override current files and you don't want to delete the entire module definition, you can put a key that says "Disabled" and the module will be completely dead. Also, actions can be applied to modules such as Module.MOD_NAME.Activate as well as "Deactivate". For VizOutput, an entire simulation of data might be too large, so you can turn it on and off at key times instead of recording the entire simulation.

2-9-1. VizOutput This module is designed for output to be read by the Visualizer. The module can be added to any Structure which includes Compartments, Elements

19

and MovingCompartments. Whenever velocity changes, a time stamp is written as well as the new position and rotation. This allows the Visualizer to display a continuous animation out of discrete output. The two types of files that get written is a *.trc file and a *.drp file. The trc file contains the trace data. The drp file contains default shape and coloring information. Once in the Visualizer, you have the option of changing transparency, colors, and also colors by surface and colors by state. These are possible parameters with the default values. Key: Filename Value: Trace.trc Key: Interval Value: -1.0 Key: BufferSize Value: 10000 2-9-2. Population Output This can be added into a volume to track the species population within that volume. Possible properties for this module are: Key: Filename Value: Pop.txt Key: Interval Value: -1.0 Key: BufferSize Value: 1000 Key: Parse Value: True

The world and compartments have an inherent volume to them, but this does not appear in the input file. If you want to add a PopulationOutput to this volume, you must add a volume property into the compartment with the same name as the compartment. CompartmentDef: comp1 Volume: comp1 Module: pop To track the population of the world: DbmWorld Volume: World Module: pop Abstract populations can be created in the simulator for purposes of influxing new elements, but these volumes don't track populations since there is no collision detection performed on their surfaces. Population output during simulation is not very readable. After the simulation has completed, the written file is parsed and the file is rewritten to a column format. This is required because it can be unknown what species in what states may exist in some volume. CDS assumes nothing, so it waits until completion to organize the data. 2-9-3. Trace Output This output is used to plot the 3D trajectories of diffusing molecules in space. The output can be generated in a snapshot format, or can be used to view continuous motion in the 3D Visualizer. This module takes several types of input properties which are as follows: Key: Filename Value: Trace1.txt

20

Key: Interval Value: -1.0 Key: BufferSize Value: 10000 Key: Format Value: Time, Id, Type, Pos, Vel, Rot Key: NoTime Value: True / False Key: Single2D Value: True / False Key: Separator Value: Tab / Space Key: Post Value: CubePop Key: Species Value: species_name Key: Min Value: x, y, z Key: Max Value: x, y, z Key: Divisions Value: x, y, z Key: State Value: * Key: FileName Value: CubePop.txt

The "Time", "Id", "Type", "Vel", "Rot" are flags which determine what goes into the output. The TraceOutput module must be added to either compartments or elements. The post processing CubePop tracks populations within a specific volume. 2-9-4. Reaction Output This module is used to track specific reactions and when the reactions occur and the location of the reactant. Each property in this module is labeled as follows: Reaction: Species, PreState, PostState For example, is the case “Reaction: CaM, 0, 1”, output will be written whenever there is a calmodulin reaction where the state switches from 0 to 1. As many of these reactions can be added into a single ReactionModule. Key: Filename Value: Reaction.txt Key: Interval Value: -1.0 Key: BufferSize Value: 10000 Key: Reaction Value: species, pre_state, post_state Key: SurfaceReaction Value: species, surface_name, pre_state, post_state 2-9-5. Single Tracking. This module is designed to track the location of a diffusing molecule. One specific feature here that is lacking in the VizOutput and TraceOutput is that this module takes into account location change with a periodic boundary. So if you wish to calculate the mean squared distance, you have the locations of a molecule as if it had existed in infinite space and not a boundary condition. The unique option for this module is Mode which can be either Absolute or Relative. The default is absolute which gives the actual location in the world; relative mode subtracts out the starting location such that the first output is 0, 0, 0. To work properly in a periodic world, this module must also be added to the PeriodicWorld. Key: Filename Value: SingleTrack.txt Key: Interval Value: -1.0 Key: BufferSize Value: 10000 Key: Mode Value: Absolute

21

2-9-6. Variable Output To track variables, add the VariableOutput module to any variable container. The World and Surfaces are variable containers. Example usage is as follows: Key: Var Value: Time Key: Var Value: Ode.V Key: Var Value: Ode.h Key: Var Value: Time, V, h Key: Interval Value: 10.0 2-9-7. Creating Custom Modules. In the downloaded CDS package, there is a directory "CustomModules" which has sample code of a very simple module that does nothing but report to standard output what was passed to it. This "TestModule.java" is the source code. To compile this class we need the Java Developers Kit which includes the compiler "javac.exe". Since the module references CDS classes, we need to include Cds.jar in the classpath when compiling. From the command line, in the directory which contains both Cds.jar and TestModule.java, type "javac –cp Cds.jar;./ TestModule.java". This assumes that javac.exe is in the PATH and the semi-colon needs to be changed to a colon in Linux. Within the initializer, we would reference the module by adding a new module, editing the module field and entering "TestModule, mod_name". Where the mod_name can be anything, but is how the module will be referenced from the components that we add it to. If you make a Jar compilation of modules, you can load these into the simulator with "Module: <jarName>, <className>, <name>". If just compiling as a stand-alone class, use "Module: <className>, <name>". The compiled file must be placed in the "lib\cdsmodules" directory.

3. Running Cds.jar To run the simulator, in the command line type "java –jar Cds.jar [args] filename.cds". The filename can include a relative path. Paths for meshes within the simulation file are converted to the appropriate format for the OS. The standard test platform in our testing is running CdsInit on a Windows workstation and Cds on a Linux cluster. 3-1. Command line arguments -seed 4357 Sets the seed for the random number generator. -threads 2 Defines the number of threads to use. -verbose ewv Determines what to add to standard output. Where 'e' stands for errors, 'w' for warnings, and 'v' for verbose which is general information and should never be used. The default is no standard output.

22

-log evw Determines what to add to the log file. Where 'e' stands for errors, 'w' for warnings, and 'v' for verbose. The default is to add errors and warnings to the log. -outdir [path] Designates a location for all output files to be written to. The default is to use the location of the simulation input file. If the path does not end in a slash, then the last string following a slash will prepend the filenames. -help Prints information the command line arguments to screen. 4. Potential Issues 4-1. "Escapes" in the DbmGridWorld If all molecules are contained within closed compartments and there are warnings in the log file about molecules being deleted because they're out of bounds, then collision detection is failing at some point. This is probably due to setting the number of divisions too high. If the division number is too high then there are possible collisions that aren't being checked by CDS. Also, the algorithm has been modified such that the time till collision in physical space is not equal to the event time. The difference between the old and new algorithm is negligible except in very crowded environments where molecules may travel greater distances over a small time. In those simulations, the number of divisions might need to be dramatically reduced to avoid the problem. When in doubt of the collision detection, set the number of divisions to "1" and see if there are any escapes, there will be no optimization, but there shouldn't be any escapes. Highly dense environments that weren't optimized have been tested to 100 million iterations with no failures. 4-2. Memory limit Java has a maximum memory limit built in. If your simulation or the Initializer/Visualizer crashes because of this limit, add these arguments to the java command "-Xms512m -Xmx1024m". So it will look like "java -Xms512m -Xmx1024m -jar Cds.jar [SimFile]". The same goes with CdsInit.jar and CdsViz.jar. 4-3. Other Issues Any bugs or errors that come up should be addressed to Michael.J.Byrne@uth.tmc.edu. Please attach all files regarding the failed simulation and a description of what the simulation is attempting to accomplish.

23

III. CDS Initializer 1. Running CdsInit.jar CdsInit is packaged as an executable jar file and can be run by double clicking it from the file explorer. If this doesn't work, set the property for .jar files such that it opens with "javaw.exe" located in the Java directory. CdsInit was compiled with Java version 1.6.0_13. Upon running, the main window will show up with four equal sized boxes, three of them black. A always-on-top properties frame will appear as well. An empty world is created when the Initializer is loaded. 1-1. The grid panels The menu bar just has two menus, the file menu and options menu. The file menu has the basic options of creating a new world, loading a world, saving, and exiting. When a new world is created it has no associated filename so trying to "save" will call the "save as…" method and a file chooser will prompt the user to pick a file destination. The options menu has a flag for snapping to the grid when translating objects and a window for editing the dimensions of the grid.

1-1-1. Interacting with the world. To zoom in and out, scroll the mouse wheel when the cursor is over a grid panel. To move the view, left click and hold while dragging the mouse. To center on the origin, right click and hit the center button that appears on the popup menu.

1-2. The toolbar The toolbar has two features separated by dividers. The first are two icons, one that signifies "object mode" and one that signifies "mesh mode." In object mode, objects can be selected, dragged, scaled, and rotated. In mesh mode, a single object can be selected and individual vertices and faces of the mesh that makes up that object can be modified. 1-3. The grid panels The four panels in the main window are for different view of the world. A 3D view (not yet implemented), a ZY view, a XY view, and XZ view. These views represent front, side, and top down views. These views are used to visually see the placement of objects in the world and to edit the physical properties the objects (translation, rotation, etc). Left clicking and dragging a grid panel will move your view of the world. Scrolling the mouse wheel will zoom your view in and out. 1-4. The properties frame

24

The floating properties frame is used to create the world and to modify intrinsic properties of compartments and elements. Also to add reactions and events to the simulation file.

1-4-1. Definitions panel The definitions panel is the principle component to add compartments and elements to the world and to modify the properties of those objects. There are two panels here, the left one contains a list of the defined compartments and elements. The right panel shows the properties of a selected compartment or element. Right clicking on the left panel will show a popup menu with options of adding an object (either creating a new one of loading a previously saved one). With an object selected on the left panel, the right panel becomes active. Right clicking on the right panel will show a popup menu with options of adding properties, or if you right click on a property, options of modifying or deleting that property.

The icon showing a cursor will select a compartment in the world that corresponds to the highlighted compartment definition. A highlighted element group will also be selected in the world when that group definition is highlighted and the icon clicked. This also works for individual elements, but not for the base element definition. This is useful when it is not clear in the world where a certain compartment is. Double click on a compartment definition or a element instance and the camera will center on that object. 1-4-2. World panel The world panel displays information on the bounds of the world and optimization options. The current implementation of optimization is to divide the world into a grid of uniform subspaces. When collision detection is performed, only elements in neighboring subspaces need to be checked since there is no possibility of two elements on either side of the world colliding. The auto optimize feature determines the number of divisions of the grid based upon the diffusion coefficient of the currently defined elements. The grid size must be at least two times the maximum distance an element can travel in a time step. Also in this panel is defining simulation duration and step size. 1-4-3. Reactions panel The reactions panel stores a list of reaction sets and each set can contain a reaction. 1-4-4. Modules panel This panel stores a list of modules and properties for those modules. 1-4-5. Events panel The events panel has a list of user defined events and actions associated with those events.

25

1-4-6. Function panel The functions panel stores a list of functions that can be referenced from other components of the simulator such as the rate of a reaction. 1-4-7. ODEs panel This panel stores a list of individual or systems of ODEs.

1-5. Prefabricated meshes The MeshFactory class has several different meshes that are automatically generated based upon some user specified input arguments. These meshes include: triangle, pyramid, cube, sphere, cubic spine, sphere spine, spine, and cylinder. So inputs may include length, width, radii and so forth. Some meshes also take a "resolution" input. This is an integer value >= 1 and dictates how many triangles will make up the mesh. For a sphere, a value of 1 would make a sphere that is diamond shaped (a north and south pole and four points along the equator). A value of 5 would make a mesh that is pretty spherical but doesn't use too many triangles. A value of 10 produces a mesh made of 1258 triangles and is very close to a true sphere. I don't recommend ever going higher than 10. Most of the time a resolution of 5 or so is sufficient (for a compartment, elements should be much lower, 2 or 3). For low resolution meshes based on spheres and cylinders, the actual volume is less than the actual shape with the same radius. The position of nodes is located at a distance of the radius from the center of the mesh. For cylinders, if you wish the mesh to have the same volume as a theoretical cylinder given a radius r, then use the following equation to come up with a new radius rn to give the same volume as a true cylinder.

Where n is the number of sides of the cylinder (n = 4 x Resolution), and r is the original radius given by the user. As n approaches infinity, rn and r become equal. 1-6. Hotkeys Ctrl-s: Save Ctrl-o: Open Ctrl-r: Run Ctrl-z: Undo Ctrl-y: Redo 2. Creating a world To create a new world, select "new" from the file menu. All of the grid panels are now empty and everything in the properties frame is empty except for the basic simulation properties.

26

2-1. Creating a compartment To create a compartment, go to the definitions tab of the properties frame. Either click the "Add New Compartment" button or right click on the left panel to bring up a popup menu. A dialog box will appear asking for the name and the next one will ask whether to make a new mesh or to load a mesh. Complex meshes can be generated using free 3D software such as Blender which can be exported as an .obj file and loaded into this Initializer. Meshes can be created within the Initializer such as basic primitives as well as some predefined compartments.

2-1-1. A note on mesh filenames When meshes are created, an explorer browser pops up and requests that the mesh is saved. If this is canceled, the mesh is saved into the default path which is the location of CdsInit.jar. If a path is chosen, then the Initializer will store the absolute path. When the simulation file is saved however, the absolute path is removed and replaced with a relative path with respect to the location of the simulation file.

2-2. Creating an element Elements are different from compartments in the sense that a compartment is defined once and has a single instance. Elements can be defined in the Initializer yet have no presence in the world. Right click on the definitions panel and select "Add New Element" to create an element definition. When elements are added into the world, they will inherit properties defined in this base definition. 2-3. Adding elements into a compartment When a new element is defined, it does not yet exist in the world. Elements are added into the world by "groups". Even if just adding a single element, it must be added as a group. All elements created as a group inherit at least one property defined in that group and that is the name of the parent volume or surface. Once an element is defined as well as a compartment (for placement), right click on the compartment in the definitions panel. A popup menu will appear with several different options. Hold the mouse over "Add Group Into", then select the menu with the compartment name that appears to the right. The first option will be to choose the element to be added and the choices are: a new element, load a previously saved element, and a list of defined elements. The next dialog boxes that popup will ask for a group name and whether to add the elements uniformly or on-lattice. If uniform, the user specifies how many elements to add and they are randomly distributed within the volume. If lattice, elements are added within the volume based on a grid. The user can choose what percentage of the total number that can fit within the grid are actually added into the world. If the space you are adding elements to is dense, room for some of the elements may not be found and the attempt to add an element of a group will fail. The log frame under the help menu will indicate of how many elements attempted to add into a compartment, how many were added successfully. 2-4. Adding elements onto a compartment

27

When a new element is defined, it does not yet exist in the world. Once an element is defined as well as a compartment, right click on the compartment in the definitions panel. A popup menu will appear with several different options. Hold the mouse over "Add Group Onto", then select the menu with the compartment name that appears to the right. The first option will be to choose the element to be added and the choices are: a new element, load a previously saved element, and a list of defined elements. The next dialog boxes that popup will ask for a group name and how many elements to be added uniformly on the surface. If the surface you are adding elements to is dense or small, room for some of the elements may not be found and the attempt to add an element of a group will fail. The log frame under the help menu will indicate of how many elements attempted to add onto a compartment, how many were added successfully. 2-5. Adding elements onto elements A group of elements can be added onto an existing group of elements. If there are 10 instances of the existing group, then the new group added onto it will have 10 instances. On a group in the definitions panel, right click and two options in the popup menu are "Add Group to Adjacently" and "Add Group to Embeded". If adding adjacently, for each instance in the existing group, an element is added adjacently to that instance. They are positioned such that the two elements are touching. If embeded, the center of the adding element is located on the surface of the existing element instance. 2-5. Adding moving compartments to a compartment This process is identical to adding elements to a compartment. Moving compartments are added as a group. 2-6. Adding elements to a group of moving compartments The user chooses the number of elements to be added to each moving compartment. A separate group of elements is created for each moving compartment in the group. So if there are 10 moving compartments and 10 elements to be added to each moving compartment, then a total of 100 elements will be added distributed among 10 groups. The group names are created based upon the name and id of the moving compartments. 2-7. Adding elements to the World Elements are added to the World in the same manner as compartments. Right click on a element definition and the popup menu will have an "Add To World" option. 3. Modifying a World 3-1. Adding properties to an object Within the definitions tab of the properties window, the definitions panel is to the left and the properties panel to the right. The properties panel is empty until a compartment or element is selected from the definitions panel. Then it's properties will appear in the right panel (if it has any properties).

28

3-1-1. Nested Properties In the case of elements, there exists a base definition. Within that definition can be multiple groups, and within each group are multiple instances of elements that exist in the world. Both the base definition, the group, and the individual elements can have properties added to them. The group will inherit all properties defined in the base definition, and the individual elements will inherit all the properties defined in the base definition and then the group definition. For example, calcium can be completely defined by the base definition and not have any properties defined in the groups or individual calcium. However, if you want to see the 3D trajectory of a single calcium, you can select one of the individual calcium and add an output module to it.

3-2. Object selection Left clicking on a mesh in the 2D views will select that object. Selection is based on how close the pointer is to a node. Shift + clicking will select multiple objects. 3-3. Object translation With an object selected, left click and hold within the selection area, then drag the object. Clicking outside the selected area will just pan the camera. When objects are membrane bound, if they're dragged, they remain bound to the surface. If they are aligned to the normal, then they rotate as they are dragged from triangle to triangle. To see this, try adding 50 cylindrical elements onto a sphere with an AlignTo property of 0 0 1. Then select the whole group and drag them around. 3-4. Object scaling When an object is selected, nodes appear on the sides and top and bottom of the selection rectangle. By left clicking and dragging these nodes, you can scale the mesh. Also, while the mesh is selected, right click and a popup menu will appear with a transform menu with scaling sub-menus. 3-5. Object rotation While the mesh is selected, right click and a popup menu will appear with a transform menu with rotation sub-menus.

3-6. Mesh merging The merge mode is for merging two meshes. The first mesh selected will have no changes in its nodes and the second mesh selected will have its selected nodes moved onto the first. The number of nodes selected must the same for each mesh. It does the closest nodes so anything too irregular might not merge correctly. Step 1 is to select the 1st mesh in the object mode and hit enter. Step 2 is to go into mesh mode (the mode switching is done automatically after hitting enter) and select the nodes of the 1st mesh then hit enter. Step 3 is to select the 2nd mesh in object mode and hit enter. Step 4 is to go into mesh mode and select the nodes of the 2nd mesh then hit enter. If all goes right, the nodes of the 2nd mesh will be moved onto the nodes of the first mesh

29

and the connection between the two will be flush (assuming of course that the number of nodes selected for the two of them are the same). It does try to create new nodes to make up for the discrepancy but I wouldn't trust that at all. Especially there would be a lack of triangles at that point. 4. Mesh Editor The default mode in the Initializer for selection is the object mode. When an object is selected, the entire mesh is selected. In the toolbar, the first two icons on the left switch between object mode and mesh mode. With a single compartment selected, click on the 2nd icon which is a box with its nodes highlighted. The user now has the ability to modify triangles within the mesh. 4-1. Selecting faces and nodes To select a group of triangles, hold CRTL, left click in the 2D view and hold while dragging the mouse over the triangles desired to be selected and then release the mouse. To select additional triangles, do the same thing on hold SHIFT+CRTL. To clear, use the CTRL key and make a selection in empty space. Both nodes and triangles within the selection box will appear selected. Any kind of movement such as translation, scaling and rotation is all performed on nodes, and the triangles change shape based on the three nodes that define each one. Eight crosses will appear outside the selection, four on the sides and four on the corners.

4-1-1. Translation. With nodes selected, left click and hold while dragging the mouse. 4-1-2. Scaling. With nodes selected, left click and hold on a red cross on the top, side, bottom or right then move the mouse. Left/bottom to make smaller or right/top to make larger. 4-1-3. Rotation. With nodes selected, left click and hold on a red cross on the corners then move the mouse left or right. Left = counter clockwise, Right = clockwise. 4-1-4. Adding face from selected nodes. A new triangle can be created if three nodes are selected. With three selected, right click and under the Faces menu, click add Face. 4-1-5. Deleting nodes and faces. Deleting any selected faces will allow the nodes that made up those faces to remain. If nodes are selected and deleted, any triangles associated with those nodes will be deleted as well. 4-1-6. Adding Nodes. Adding nodes is a two step process. To add a node you have to click such that three values are chosen. This is impossible by clicking in a 2D view. Right click at the point where you wish to add a node, select the Nodes menu and click Add Node. The two coordinates of the new Node are now saved, but you will notice that nothing has happened. Next, in another 2D pane,

30

you have to repeat the process to get the third dimension for the node placement. Only the missing value will be put into the new node. Upon that last action, the new node will appear. If you first click the Add Node menu item in the XY plane, the x and y values will be stored in a new 3D vector. If you were to try and add a node again in the XY plane, the input will be ignored. If you then try adding the node in the XZ plane, the y coordinate of the mouse will be set as the Z value of the new node and the current x coordinate of the mouse will be ignored since we already have a x coordinate from the XY plane. If the snap to grid mode is on, then the new node will snap.

4-2. Naming a set of faces With triangles of a mesh selected, right click and a popup menu will appear with an option to set a surface name. Enter in a name and that area will now be named. 4-3. Editing element meshes It's not allowed to select an element and modify its mesh like a compartment. Elements location and rotation are applied to the mesh for each instance, so a particular instance of an element is not a perfect representation of the mesh describing an element. To edit an element mesh, under the element definition, under the shape property, there will be a path to the filename of the mesh. Right click on the path and an option will appear called "edit". Click on that and a separate mesh editor window will appear with only that element's mesh in the grid panes. In the file menu, you can cancel and any changes are disregarded, or if you select Okay, the modified mesh is reapplied to all instances of that element in the world. 5. Modifying Properties The five panels on the properties frame work in a similar fashion. By default these panels are all empty. To add properties, right click in the empty panel and a popup menu will appear with options to add properties. Or the add button at the top to insert the standard property for that panel. 5-1. Definitions Panel Two sub-panels are located within the definitions panel. As discussed in 2-1, the left panel is where compartments and elements are listed. Left clicking on anything in that panel loads up its properties in the right panel. If no definition is selected in the left panel, then the properties panel will be empty. With properties listed, right click on a property to bring up a popup menu to modify that property, or right click in empty space below the listed properties to bring up a popup menu that has options to add new properties. 5-2. World Panel The right sub-panel has three simulation variables that can be edited, but no others can be added here. The left sub-panel contains properties for the world. This includes dissociation search properties, modules and abstract volumes. The world itself

31

is populatable so that PopulationOutput modules can be added to the self volume labeled "World". 5-3. Reactions Reactions are grouped into sets so that a group of reactions can be created, saved, and reloaded. For example, a particular Ca-Calmodulin reaction scheme may be part of one reaction set. A reaction set is at the top level and reactions are children to a reaction set. Likewise actions are children to a particular reaction. When right clicking on a reaction set property, a popup appears with an option to add a reaction. When right clicking a reaction, a popup appears with an option to add an action. 5-4. Modules For each module, the root key is the path and name of the Java class that represents that module and the value is the name of the module that CDS uses to reference it. When adding a module, a list comes up with the modules that come with CDS so the user does not have to type in the information. For example, the module property for VizOutput will look like: Module: VizOutput, trace. When adding properties to the module, the user must enter in a key and value since custom modules are allowed, any number of properties might be added based upon the creator of that module. In the case of elements, a module added to the base definition will be included in every instance of that element. If you want to visualize every since calcium, the VizOutput would be added to the base definition. If you want to visualize a single calcium, the module has to be added as a property to that specific instance. 5-5. Events This panel contains a list of events. Each event may contain a series of actions and properties that describe the event. 5-6. Functions Functions take the form of a name followed by an expression. The name given to a function is how that function will be referenced by the simulator. For example: Function: x = 14.2 + Math.exp(-World.Time / 5.0). From other components of the simulator, you can reference the value of this expression by entering Function.x. 5-7. Odes Odes are slightly different in that the key is the variable name and the value is the equation. So entering dV/dt as the key and -V / 50.0 : 10.0 and the value would look from the panel to be dV/dt = -V / 50.0 : 10.0. 10.0 is the initial value. Any initial value not defined will be 0.0. To reference a variable from within CDS, you would use the code Ode.V (you can also just use V, just make sure all elements, functions, and odes have unique names). The key can actually be just the variable name since the d/dt portion gets separated out anyway. 6. Notes

32

6-1. Units Units may be adjusted from the "Options -> Units" menu. These should be adjusted when a blank simulation is first created. If units such as distance are changed after values are entered into the simulation, all units are updated and all meshes are scaled based upon the units change. ONLY VALUES that are numbers are changed. The Initializer cannot modify functions and it is up to the user to do so. When changing values such as the diffusion coefficient, the currently selected units are displayed to remind the user.

6-2. View Restriction If there is too much clutter on the screen and you wish to view a specific region in detail, click the view restrictor icon. Hold CTRL, click the mouse and drag a rectangle over the region you wish to view. Upon releasing the mouse, everything outside of the rectangle will be made invisible.

33

IV. CDS Visualizer 1. Running CdsViz.jar CdsViz is packaged as an executable jar file and can be run by double clicking it. All windows first appear blank. CdsViz opens up .trc files that are written from the VizOutput module. Also located in the same location as the .trc file is a .drp file which stores default rendering properties and mesh locations for the simulation. The .drp file has the same filename as the .trc file. 1-1. Properties tree When the file is loaded, a hierarchal tree of all compartments and elements are shown on the left panel. Elements start out with their base definition and group showing and the individual elements within groups are collapsed. Right click over tree to bring up a popup window with rendering and coloring properties. When updating properties at the top of the tree, all groups and elements inherit those properties. 1-2. VCR controls There is a pause button and three modes of playback (frame by frame, play and fast forward) in both forward and backward motion. In play mode, the time it takes to play back one unit of simulation time is 1 second. Fast forward scales the normal play by some multiplier. A slider to the right of the playback controls allows easy manipulation of this multiplier. Since the multiplier can also be a value much smaller than 1, the fast forward mode can also be a slow motion. Clicking on the text that shows the value of the multiplier brings up a input box to manually set your own multiplier. 1-3. View and control window The viewing window shows the rendered view of the world. This window also allows the user to control the viewing camera. To rotate the view, left-click and drag the mouse. To pan, right-click and drag the mouse. To zoom in and out, click the mouse wheel and drag the mouse up to zoom in and down to zoom out. 1-4. Menu options.

1-4-1. Show Trajectory. A visualization file must already be open for this option. This allows the user to view the trajectory of a single element. The element is removed from the visualization and many static instances of that element are placed into the world where each static instance represents the location of that element at some time. The user chooses the number of instances to view where the time in between each one is equal. 1-4-2. Clear Trajectory. Clears a loaded trajectory and brings back the continuous instance of the trajected element.

34

1-4-3. Open Trajectory. This is opens a visualization file, but only loads the static components except for the single instance the user wishes to see a trajectory of. 1-4-4. Open ReactionOutput. Data from the reaction output files contain a time stamp as well as the location of the element at the time the reaction took place. The visualization file must already be opened from the same simulation that wrote the reaction file. Along with the visualization data, static instances of the reaction locations are added into the world so the user can see where reactions took place. Any number of reaction output files can be loaded into the simulation. 1-4-5. Show Time / Resolution. Shows the current time and view resolution in the lower left hand corner of the view. Resolution here is important since the screenshots and movies output exactly the size of the view. 1-4-6. Show Axis. Displays three arrows pointing in the positive x, y and z directions. 1-4-7. Take Screenshot. Writes an image of the current view and saves it as ScreenShot.* in the directory as CdsViz.jar. 1-4-8. High Res Screenshot. Renders the current view to an off screen display and saves the result. 1-4-9. Screenshot Format. Lets the user pick the format of the screenshot. Either bmp, jpg, gif or png. 1-4-10. High Res Screenshot Resolution. User must specify the size of the high resolution screenshot. Older graphics cards may be limited to 2000x2000 pixels, but modern cards may support around 4000x4000. This is variable depending on the current memory allocation within the card. If your card cannot handle a resolution, the program will crash. 1-4-11. Save Defaults. If default properties for the currently loaded simulation have been changed, this saves the changes by overwriting the .drp file. 1-4-12. Lighting. Allows you to select from pre defined lighting schemes, edit schemes and create your own schemes. If the default lighting scheme is selected, you can edit it by going to Properties -> Lighting -> Edit. Once there you can add new lights, delete lights, change the color of lights and light properties such as direction. If you want to save modifications, click SaveAs and enter the name of your new lighting scheme. This scheme will be added to the drop down menu in Properties -> Lights for easy switching between saved schemes.

35

1-4-13. Background Color. Select a different background color for the view. 1-4-14. Thick lines. Makes wireframe renderings much thicker. When taking screenshots, lines tend to look too small, so for publishing, the thick lines should be on. This option requires a visualization file to be reloaded. 1-4-15. Anti-aliasing. Eliminates the staircase effect on lines. Requires a good graphics card. This option requires a visualization file to be reloaded. 1-4-16. Auto Camera. Under Camera -> Auto Camera, there are several options for camera movement. All these are the same as the mouse control, but these allow for smooth motion when rendering. They can also be hot keyed. To activate these through the keyboard, first click on the view to select it, then type 'x' for x-axis rotation and similarly 'y' and 'z'. For panning, 'l r u d" for left, right, up, or down. And '+' and '-' for zooming. For rotating, the default is positive rotating, for negative axis rotation hold 'alt' and 'x', 'y', or 'z' to rotate in the negative direction. If you want to stop movement, hit the same key again that you used to start the movement. 1-4-17. Camera Factor. Rotate, pan and zoom have scaling factors associated with them to control mouse sensitivity. The higher the number, the more sensitive the mouse will be. These also affect the auto camera as well. 1-4-18. Camera Look. Sets the camera pointing from the direction of your choosing and pointing towards the origin. 1-4-19. Set FPS. Sets the frames per second that movies are recorded at.

1-5. Full Screen To go into full screen mode, hit Esc. And once in full screen mode hit Esc again to return to normal. Once in full screen mode, hit F1 to bring up the playback controls. 2. Movie Recording The recorder button is the red circle at the far right corner. While the animation is live, the rendered view will be added to the movie. This only saves Quicktime movies. Absolutely anything that is seen in the viewing area is added to the movie and this is while in play or forward / rewind modes. When paused, the movie will be recording. So during a pause you can switch views, change lighting or can properties. These properties can be changed while the movie is rendering, but you have to make sure that none of the popup menus overlap with the view or else they will be in the movie. Click the record button again to stop the recording. The convention in which the movies are encoded is really just as a series of compressed images. Some video conversion software has problems with loading this encoding. Software called AVS is very inexpensive and can convert any movie type to

36

any other movie type. So Quicktime movies can be converted into avis or mpegs and compressed to much smaller file sizes without losing much quality. 3. Trajectories Instead of viewing each molecule as they diffuse, you may choose to select a single molecule to view all its positions over the entire time course. One option for doing this is to load up a simulation with Tools -> Trajectory -> Open Trajectory. A popup comes up asking you what molecule ID you want to track and the number of intervals to load up. Usually 500 intervals is a good number. If a simulation is 500 ms long, then an instance of that molecule is created at its position at every 1 ms. When this is loaded up, all static molecules are loaded, but any diffusing molecules other than the one being selected are discarded. When a regular simulation is loaded, you can choose to switch between different trajectories while also viewing all other diffusing molecules. However, this requires that the raw data remain loaded into memory. This option is done with Tools -> Trajectory -> Show Trajectory. 4. Properties Pane and Changing Properties When a trace file is loaded, a list of all elements and compartments are displayed in the properties pane on the left side. Groups of elements are also shown while the individual instances within groups are collapsed. Double clicking on the on any of the nodes in the tree will expand or collapse that part of the tree. To select properties, you can left click to select one, hold "ctrl" and left click to select/deselect multiple nodes, or hold "shift" and left click and drag the mouse to select all nodes in the drawn rectangle. To view the properties frame to adjust the coloring and viewing properties, right click on a property. The frame that appears has options to make visible, view as wireframe, adjust transparency and change colors for different surfaces and different states. Any settings made to an element definition will be applied to all children, any settings made to a group will be applied to all instances in that group. To view properties from an instance in the view, left click on the element/compartment, then press the "p" button. The properties frame will appear with the id of that element appearing in the title bar of the properties frame. Even invisible or wireframe compartments will interfere sometimes with selecting the element that you desire, so it may be necessary to zoom in to select. 4-1. Sphere Divisions. When an element is defined by a sphere, the user can change the number of divisions (the higher the number, the closer to a perfect sphere). For this change to take effect, the default properties must be saved and the trace file reloaded. Meshes will have a division of 1 which doesn't mean anything and has no impact on the mesh if changed.

37

4-2. Shaders. In the upper right corner of the properties frame there is a blue square. This is intentionally hidden since shaders require powerful graphics cards (Must support at least OpenGL 2.0). The frame that comes up has a pull down of a few shaders and doesn't currently allow any modification of the shader attributes. Shaders will allow for very smooth lighting and shading over objects even if they are a low resolution. The images shown below have a moderately high resolution, but the lighting has a bricked effect where individual triangles can be seen. The shaders smooth out those effects.

Normal "Lights" Shader

"Phong" Shader "Smooth" Shader

38

V. Walk Through 1. First Steps First, execute CdsInit.jar by double clicking on it. The main window will appear with the three grid panels which start out solid black. A floating properties window will appear also with several tabs in it. The tab that always starts out selected is the definitions tab. Note: Mesh filename paths are saved as relative to the location of the simulation file. 1-1. Adding the first compartment In the properties window, right click on the definitions panel which is the left gray panel. Select the "Add New Compartment" option. A dialog box will appear asking for the compartment name; let's call it "Spine". The next dialog box will ask whether to create a new mesh for this compartment or load a mesh from an .obj file. Let's create a new mesh. The next dialog box will contain a combo box of different types of pre-defined meshes. For this example, lets create a sphere. The next dialog asks for a radius; enter a value of 250.0. The next dialog asks for the resolution. This is an integer value that has to be greater than or equal to 1. A resolution of 1 will create a diamond shape (a north and south pole with four points along the equator). The higher the resolution, the closer to a perfect sphere you get. A resolution of 6 has a good triangle count so enter that. Next, a file browser pops up so we can save our mesh. Let's save it in the same directory as CdsInit.jar which will be the default. For simplicity, name the file the same as the species name. A grid now appears with our sphere centered at the origin (minor grid lines are gray, major grid lines are blue, and the lines traveling through the origin are cyan). To zoom in and zoom out, use the scroll wheel on the mouse. To move the view of the grid, left click and hold in the grid then move the mouse. In the definitions panel, the definition for the Spine appears and in the properties panel on the right side, are its mesh filename, id, and location. The Id is 0 and the location is at the origin (vectors are defined in the form "(1.0, 2.0, 3.0)"). The Id and Location are the only properties not available for modification by the user. 1-2. Creating an element This step follows very similarly to 1-1. Right click on empty space in the definitions panel to view the popup and select "Add New Element". Let's call this element "Ca" with a new sphere that has a radius of 0.5 (this is a very large radius, but let's use it so that it will be easily viewable in the Visualizer). Again, for simplicity, name the mesh file the same as the species name. For elements, there is a Sphere, New Mesh, and Load Mesh option. The Sphere option creates a primitive sphere with the specified radius. For simple diffusing elements it is preferred to use this instead of meshes.

39

When the element is created, the only property that appears in the properties panel is the mesh filename. There is no id or location because this is only the definition of an element and there is no physical instance of this element in the world. 1-3. Adding the element to the compartment Now it's time to add our Ca element into the world. Elements are added into the world by adding a group (can be any size >= 1) of elements into or onto a compartment. Right click on the Spine definition ("CompartmentDef: Spine"). A popup menu will appear. Select "Add Group Into" and a menu will appear to the right with just one item which is the Spine, so click on that. A dialog will appear asking what element definition to use. The options are to create a new definition, load a previously saved definition, then a list of all currently defined definitions in our definitions panel. So the options we see now are just "New", "Load", and "Ca". Select "Ca" and click okay. The next dialog asks for the group name which isn't very important; just call it "CaGrp". The next dialog asks how to distribute the elements. The two current options are uniformly within the volume or on-lattice. Select uniform then for the next dialog box which asks for the number of elements to add, type 100. In our grid panels we now see 100 dots distributed around our spine. In the definitions panel, there is now a sub-tree under "ElementDef: Ca" which is labeled "Group: CaGrp". Double click on the group label to expand the tree. Select the first element which is labeled "Element: 1" by left clicking on it. Here we see the id which is 1, and the location which is within the spine. Left clicking on the group will show a property "Parent: Spine" which lets the simulator know what compartment this group was added to. 1-4. Modifying the element properties To view a definition's properties, left click on that definition in the left panel. The properties will then appear on the right panel. Right clicking anywhere in the blank space of the properties panel will show a popup menu with options to add properties. Right clicking on a property will show a popup menu with options on modifying or deleting that property. Select Ca and right click in the properties panel. Click "Add" and a dialog will appear with a combo box of different properties. Select "Movable" and click okay. All elements are by default stationary, so we have to assign properties to make them diffusing elements. Add another property called "DiffusionCE". Once added, right click on "DiffusionCE" and select the "Edit" option in the popup menu. Enter in a new value of "225.0". Since we are adding these properties to the base definition, all Ca groups and individual elements will inherit these properties.

1-4-1. Creating visual output In the "Modules" tab of the properties frame, click the "Add New Module" button and a list of predefined modules will appear. Select VizOutput from the list and hit enter. A module will be created with some default properties and a default name "trace". The name is how we will reference the module. Go back to the "Definitions" tab and select the Spine compartment. Add a new "module" property to the Spine. Right click on the newly created module

40

property and select the "Edit" option from the popup menu. Rename the module "trace". Right click on the module property and select "Copy To... -> All". This will make a copy of this property in all definitions (although the only other definition is Ca currently).

1-5. Sample Run Go to the file menu and save this simulation as "Example". Run style 1: In a terminal, go to the directory which has CdsInit.jar and Cds.jar and is where we saved our meshes and simulation file. Type "java –jar Cds.jar Example.cds" and hit enter. This should take about 20 seconds to run. Run style 2: Click on the Run -> Run menu and a frame will appear with command line options. With the default settings, hit the execute button. Three files that have been written to the directory that the simulation file is located in are "log.txt", "Trace.trc" and "Trace.drp". Try loading up the Visualizer and opening the Trace.trc file. By default, only errors and warnings are included in the log file. 2. Adding More Complexity Right now we have a simulation of a single compartment, single diffusing species, and no reactions. For the next step, let's repeat steps 1-2 to 1-4 only with CaM (calmodulin) and use a radius of 2.0, add 25 of them to the Spine and set a diffusion coefficient of 20.0 (nm^2 / us). Also add the "Movable: True" and "Module: trace" properties. Also add a "CurrentState" property and give it a "0" value. We will need this for adding reactions. 2-1. Adding Reactions Go to the "Reactions" tab and click the "Add New Reaction" button. This adds a new reaction set which is how reaction schemes can be grouped together. Right click on the reaction set and add a reaction. A reaction "A + B -> C : 1.0" will appear. Change this to "CaM.0 + Ca -> CaM.1 : 1.0" by right clicking the reaction and hitting the "Edit" menu item. So there will be a 100% chance of the reaction occurring when a CaM in the 0 state collides with a Ca. Right click on this newly added reaction and select "Copy". Right click on the reaction set, or any reaction within the set and hit the "Paste" menu item. Keep pasting and editing the reactions to get a list like this: CaM.0 + Ca -> CaM.1 : 1.0 CaM.1 + Ca -> CaM.2 : 1.0 CaM.2 + Ca -> CaM.3 : 1.0 CaM.3 + Ca -> CaM.4 : 1.0 2-2. Tracking Population Go to the "Modules" tab and add a new module. Select the PopulationOutput from the list. Right click on the module and add a new property to it. Enter "Interval" for the key and "1.0" for the value. This will make it so we only record the population at 1

41

unit intervals. The default value here is "-1.0" which will update the output whenever there is a population change. 2-3. Modifying World Properties Go to the "World" tab. On the right side edit the time step to "0.1" and the end time to "1000.0". 2-4. Re-run the simulation This should take about 5 min. The previously written files will be written over and there will be a new file "pop.txt". 3-1. Example Simulations There are several example simulations included in the full package. These simulations will allow you to see how various features are implemented. Some examples are followed by numbers. A "1" indicates a simplified example, and as numbers increase so does the complexity of the simulation.

42

VI. Writing Custom Modules for the Initializer 1. Introduction Creating some specialized environments may not only be difficult and very time consuming to accomplish by hand, but may even be impossible. Much like modules for the simulator, modules for the Initializer may be loaded into it, and have full control over all the methods that control creation of the simulation environment. This section will provide code as an example of how to accomplish this and show some of the possibilities of what can be done with custom code. 2. The Code A custom module must extend the abstract Module class. There is one abstract method declared in the Module class that any user created sub classes must define. This is the method that the Initializer calls when the user hits the "Execute Module" button. A minimal example of a module that does nothing is as follows: package lib.initmodules; import java.awt.Window; import edu.cds.init.world.Module; import edu.cds.init.world.BasicWorld; public class DendriteCreatorExample extends Module { public DendriteCreatorExample () { } public void init(BasicWorld world, Window w) { // Perform Tasks Here } } Included in the lib/initmodules/src directory is example code called DendriteCreatorExample.java and also a batch file to compile it. The "compile.bat" file will work without modification assuming that the "JAVA_HOME" path is set in the operating system to the location of the JDK. When I type "echo %JAVA_HOME%" what is returned is: "C:\Program Files (x86)\Java\Jdk.1.6.0_13" The user can always manually type the complete path into the compile.bat file. The following section will show step by step how to use the DendriteCreatorExample.

43

3. Walk Through 3-1. The DendriteCreatorExample Module This module is designed to create a section of dendrite and populate it with a specified density of dendritic spines. The dendrite is cylindrical and the spines have cylindrical necks and spherical heads. A single CaMKII is placed at the center and binding targets are added about a postsynaptic density on the spine heads. The reason this must be automated in a module is that to create a free flow of molecules from the dendrite compartment to the spines, triangles must be deleted at the locations where we add the spines and new triangles must be created to create a surface flush to the end of the spine neck (pictures of the final product are shown below). 3-2. Creating and compiling The basics of the code is described in the previous section. Included in the lib/initmodules/src directory is the source code for the DendriteCreatorExample. Here I will not go into detail of how geometry is created or different ways the module interacts with the World object. To see how the code works in detail, refer to the source code and follow the code linearly starting with the init() method. Comments in the code will give you a description of the tasks being performed. Once the code is complete, running the compile.bat script will compile the code and place the class file in the lib/initmodules folder. Any module wishing to be loading into the Initializer must be placed here. 3-3. Setting up the Cds file A module may be setup to create a simulation entirely on its own or may require some information to already exist in the simulation environment. The present example requires that the CaMKII and PSD95 elements already be defined in the Cds file. Once the basic file has been created, it should be saved prior to executing the Module. The following is the simple Cds file before the Module does its work. This example is located in Simulations/Examples/DendriteCreator. The Cds file prior to execution of the module: <?xml version='1.0' encoding='utf-8'?> <Cds> <World Value="DbmWorld"> <DissociateCycles Value="10" /> <DissociateRadiusIncrements Value="5" /> <TimeUnit Value="-6" /> <DistanceUnit Value="-9" /> <ConcentrationUnit Value="-6" /> <ModifiedAlgorithm Value="True" /> </World> <SimulationProperties> <StartTime Value="0.0" /> <EndTime Value="100.0" /> <TimeStep Value="1.0" /> </SimulationProperties>

44

<Modules /> <OdeSystem /> <Functions /> <Events /> <Reactions /> <Definitions> <ElementDef Value="CaMKII"> <Shape Value="Sphere"> <Radius Value="10.0" /> </Shape> <Movable Value="True" /> <DiffusionCE Value="1.6" /> </ElementDef> <ElementDef Value="PSD95"> <Shape Value="Mesh"> <File Value="PSD95.obj" /> </Shape> <AlignTo Value="0 0 -1" /> <Binding Value="b1"> <Target Value="CaMKII" /> </Binding> </ElementDef> </Definitions> </Cds> 3-4. Executing the module Once the basic simulation file has been created and saved (or the example loaded), hit the "Load Module" button and enter the class name into the dialog box (DendriteCreatorExample). Then hit the "Execute Module" button. The behavior you will witness is the exact same as if you were manually performing tasks in the Initializer except that it occurs in rapid succession. 3-5. Viewing the creation Once the simulation environment has been created, save the file. Run the Visualizer and open the Sim.cds file to see the environment that has been created.

45

A view of the stitching. Without this, there would not exist a closed compartment and leaks would occur. The only triangles across the hole exist on the spine mesh. The dendrite mesh has holes at these locations.

3-6. Additional Info In the current example, all of the parameters are hard coded. To allow the user to enter parameters during the Module execution to avoid recompiling, the following code can be used to open up a dialog box to enter information. double parameter = Double.parseDouble((String) JOptionPane.showInputDialog(w, "", "", JOptionPane.PLAIN_MESSAGE, null, null, null)); Where "w" is the Window passed to the info(BasicWorld, Window) method. Other information about the parameters passed to this dialog box can be found at the Java API documentation. http://java.sun.com/javase/6/docs/api/ see javax.swing.JOptionPane Also, the code performing these operations doesn't have to be a single file. One class must extend the module class and contain the init method, but other than that, it can call many different classes and all the classes can even be packaged together in a jar file.

46

VII. Writing Custom Modules for the Simulator 1. Introduction Currently modules have the ability to be added to the world, structures, surfaces, and volumes. Every time an event occurs within an object containing a module or modules, it sends a reference of itself to all its attached modules along with an id of the event that occurred. Modules also have the ability to be involved with the event driven algorithm themselves. By default, the findNextEventTime method returns the maximum double value effectively disabling this feature by default. Users in their own modules can modify this code so modules can pull and retrieve information from objects outside of events occurring with other components of the simulation. For example, a PopulationOutput module can pull a reference to all Volumes that it was attached to an initialization, then set an event time that is recurring at some interval. Each time the event time reaches zero, it pulls all the population information from the Volume information it stores. The Module class is designed to provide a lot of flexibility to the user. Not only can a vast amount of information be retrieved, but modules can also feedback onto the simulator through actions. 2. The Code The following is the code from the abstract Module class. Every custom module must extend this class.

package edu.cds.modules; import edu.cds.util.Node; import edu.cds.event.Action; import edu.cds.event.EventTimeInfo; import java.util.StringTokenizer; public abstract class Module { String name; boolean active = true; boolean enabled = true; public Module() { } public void advanceTime(EventTimeInfo eventTime) { } public void apply(Action action) { if (!action.get().equals(name))

47

return; String k = action.getNext(); if (k.equals("Activate")) active = true; else if (k.equals("Deactivate")) active = false; } public void define(Node<String, String> node) { StringTokenizer tokenizer = new StringTokenizer(node.getV(), " ;:,\t"); while (tokenizer.countTokens() > 1) tokenizer.nextToken(); name = tokenizer.nextToken(); if (node.hasNode("Active")) active = Boolean.parseBoolean(node.getNode("Active").getV()); if (node.hasNode("Disabled")) enabled = false; } public abstract void end(); public double getEventTime() { return Double.MAX_VALUE; } public String getName() { return name; } public void handleEvent() { } public abstract void init(Object o); public abstract void retrieve(Object o, int id); }

2-1. Extending the Module class For a subclass of an abstract class to be capable of instantiation, it must define all abstract methods of its parent. In the Module class, these methods include end, init, and retrieve. These three methods must be defined to have a working module. The ModuleExample class in the lib/cdsmodules directory is a very simplistic module to illustrate the basic components of how a module may work. The init method is called after the simulation file has been read, but before the event driven algorithm starts. Often this method does not have any task that needs to be performed and can be empty. An example of an empty method is the handleEvent

48

method in the previous code. The retrieve method is what is called for every module within an object that has an occurring event. For further examples, look at the source code under the src/edu/cds/modules directory to see how the modules included with Cds are implemented.

The list of event IDs in the Info class.

Reactions are events with (id % 3 == 0 && id != 0) Ids requiring trajectory update are even. Negative Ids indicate deletion from world. E is for Element or MovingCompartment, C is for Compartment This may be a little confusing, but for a single event, there may be separate IDs, especially regarding elements and compartments.

STEP = 0 Time step event W_E_A = 2 Element added to World W_E_D = -2 Element deleted from World END = 1 Simulation ended PW_E = 8 Element moved because of periodic boundary. EE_C = 10 Element bounce collision with Element EC_E = 100 Element bounce collision with Comp (for Ele) EC_C = 101 Element bounce collision with Comp (for Comp) EE_CREE_A = 33 Association occurred in E-E reaction EE_CREE_D = -33 Deletion due to E-E Collision Reaction EE_CREE_N = 34 New Element due to E-E association EE_CBEE = 68 Two elements bind after collision EE_CTM = 80 E-E transport, E being transported EE_CTBM = 83 E-E transport, E handling transport EC_CR_D = -99 E-C reaction deleting Element EC_CRW = 101 E-C reaction for Comp EC_CB = 110 E-C collision, C binding E EC_CBW = 113 E-C binding for Comp EC_CT_D = -122 E-C collision, C transport failed and E deletion EC_CT = 122 E-C collision, C transport for E EC_CTW = 121 E-C transport for Comp E_RES = 213 Reaction - Element - Spon E_RES_D = 212 Reaction - Element - Spon Deleting Reactant E_RES_N = 214 Reaction - Element - Spon New Product E_RED = 219 Element dissociating element E_RED_N = 220 Element dissociating new element E_RED_D = -220 Element deleted after dissociation E_GR = 225 Element Group reaction E_U = 230 Element Unbinding POP_UPD = 503 Population Vol/Sur Update E_VC = 507 Element's Volume Changed UND = 666 I'm not sure what this is FORCE_VIZ = 1000 Force VizOutput to record output

3. Compiling and Implementation The source code of the ModuleExample is located in the lib/cdsmodules/src folder. Also in that directory is a compile.bat file that will compile all Java files within that directory and copy the compiled class files into the lib/cdsmodules directory. The

49

50

compile file contains the "%JAVA_HOME%" path which needs to be set to the location of the Jdk or the Jdk location needs to be explicitly written into the compile script. To use a custom module, within the Initializer's properties frame, go to the Module tab. Click "Add New Module" and a combo box will come up with "New" and a list of the included modules. Click "New". The default value that is shown illustrates the full potential format to load a class and a class packaged into a Jar file. Since we just have a single compiled class, this value needs to be edited to "lib.cdsmodules.ModuleExample, modname". Add the module to any component within Cds by referencing the "modname". Run the simulation and an output file "Test.txt" will appear in the simulation folder. This module as an example doesn't do anything but pull some information from various Cds components and writes that information to a file. For more detailed capabilities of modules, see the source code for the modules that came with Cds.