Tutorial Part I

• The Basics:
  • Your First Cell
  • Controlling Size
  • Color Example
  • Different STATEs
  • U_VAR variables
  • CHANGE_STATE
  • POISSON
  • G_VAR gradients
• Cooler Stuff:
  • V_VAR vectors and MIGRATE
  • MITOSIS
  • GAP_JUNCTIONS
  • A Lizard?

• Using Fields:
  • Easier Way to Make Scrums
  • ADJUST_SCALE
  • Using Neoblasts
  • MOD_PP_LOCATION

• Demonstration with Flatworm
  • Make a Flatworm
  • Regeneration
  • Regeneration With Morphpallaxis
  • Parasagital and Intercalary Regeneration
  • Body Region Duplication (Split Head)

• Demonstration of Octonal Treatment

FileName: tutorial_01.cyr

Load or enter the code above and hit Compile Rules.

Tab over to the Monitor console. Within the Manual Placement widget, you should see myFirstState listed as one of the STATES. (The other three, Default_Blue, Default_Yellow, and OBSTRUCTION are always present... we'll ignore them.)

Select myFirstState and click the checkbox next to Manual Placement.

Move your mouse over to the Petri Dish and draw your cell... it doesn't really matter what shape. A single small blob will suffice.

Check the Toggle radio button and hit Iterate. Your cell should come alive.

This basic process is how you will begin all the tutorials.

Let's turn now to the program itself.

The Internal Variable GOAL_AREA is set to 200. This command is triggered only on the first pass through the Rules due to the ENTERING_STATE condition. CYCELL will try to keep the cell at 200 nodes.

If you put your mouse over the cell and press SPACE, some data about the cell will be displayed in the Monitor textbox. You'll notice the data may show your cell has fewer (or more) than 200 nodes, especially if you place some more cells and move them so that they adhere to one another. We'll address this in the next tutorial.

FileName: tutorial_02.cyr

Compile the Rules, place a myFirstState cell, and Iterate.

In your monitor, you should see that the ACTUAL_AREA hovers around 200.

We accomplished this by letting GOAL_AREA float instead of setting it directly.

The workhorse here is TYPICAL_AREA. This Internal Variable is not used directly by the program in the way that GOAL_AREA is. Instead, it's just a handy built-in variable as this little size-controlling feedback loop is used so frequently. (In fact, these first three lines -- or at least a version of them -- will be used in almost all the STATEs below. We at CYCELL got so tired defining a U_VAR to handle this for every single set of Rules, that we made TYPICAL_AREA a built-in variable.)

The Rules start by setting TYPICAL_AREA to 200. The second and third lines compare the ACTUAL_AREA of the cell to the TYPICAL_AREA. If the former is smaller than the latter, we add 1 to GOAL_AREA, and vice versa.

As an analogy, this little feedback loop is like a cruise-control in your car. TYPICAL_AREA is the speed setting on your cruise-control, ACTUAL_AREA is your speed, and GOAL_AREA is your accelerator/brake (controlled automatically by the cruise-control.)

When cells are squished together, or migrating, or stretched out, the Area component of their energy function may get overwhelmed by the other energy factors. This little technique will allow your cell's GOAL_AREA to adjust to ensure that the cell's size remains more or less where your want it. You can experiment changing the 1 to 0.1 on the second and third lines. This simply controls how quickly the cell is going to get to your desired TYPICAL_AREA... if you make the values too high, of course, the cell may explode.

FileName: tutorial_03.cyr

Compile the Rules, place a myFirstState cell, and Iterate.

The default colors suck. Change them. Here, we've just added an RGB command that will set the cell's color upon its first pass through this state's rules.

We could have also put the RGB command on the last time. The only difference is that in the former placement, the command will be processed only if the ENTERING_STATE condition evaluates true (which only happens once.) In the current placement, however, the command will be processed every cycle. Now, the RGB command takes microseconds to process... so, it doesn't really matter. But, some commands (and conditions) can hog CPU cycles, so get into the habit of writing your Rules with efficiency in mind.

FileName: tutorial_04.cyr

Our Rules now have three different STATEs. Each has been assigned a different color and size. They should all be present in the Manual Placement widget. Create a bunch of each. Drag them around. You'll notice that cells of the same STATE adhere to one another a bit more than cells of different STATEs. As we haven't defined any specific ADHESIONS values, the defaults are being used. We'll get to ADHESIONS in a bit.

FileName: tutorial_05.cyr

Here, we have declared two U_VAR variables: apple and bear. Not very creative names. If you want to sound cool, you can name your variables things like "methionine" or "triose_phosphate_isomerase." It's up to you.

Upon entering the Skin_Cell state, both variables are set to certain values.

On the fifth line in the state, we add 1 to apple and subtract 2 from bear. This will occur every cycle.

The next two lines show how variables can be used in conditions: if apple is greater than 254, it's reset to 0. Likewise, bear gets set back to 255 if it hits 0.

You can do many things with variables. Here, we use them to control the color.

In the Eye_Cell state, we use the apple variable to control the size. And, we use the bear variable as a Boolean toggle switch. That is, bear starts off at 0, and so long as it remains 0, apple will increase by 5. But, when apple hits 500, bear is set to 1 and henceforth apple's value will be reduced by 5. When apple reaches 0, bear is set back to 0 and the process repeats. All the while, of course, the size is tracking apple causing the cell to grow and shrink. Notice the use of the 'not' signifier (the !) on the fifth sentence in the Eye_Cell state. This condition could just as well have been written as bear(0,INF].

Keep in mind that a cell will only process the portion of the Rules pertaining to its particular STATE. So, a cell in the Eye_Cell state will have it's apple and bear variables changed only by commands in the Eye_Cell portion of the Rules.

FileName: tutorial_06.cyr

Here, we use apple as a timer. It starts at 0 in the Skin_Cell state. When it reaches 100, the STATE will change to Eye_Cell. Once in Eye_Cell, the counter is reset to 0 and once it reaches 75, it's back to Skin_Cell.

Not very exciting. But, place a dozen or so of each type of cell in the Petri Dish... you'll witness how the ADHESIONS can really affect their behavior.

This would also be good time to Monitor a cell and check Debug Monitored Cell. Watch the debug console carefully. You will notice that the cell "Returns" from the Rules immediately after CHANGE_STATE is processed. CHANGE_STATE (along with MITOSIS, DIE, and of course END) will terminate the Rules upon being processed.

Finally, if you place a bunch of cells, you'll notice that they all switch back and forth in a regular manner... very unlife-like. We'll fix that in the following section with the POISSON condition.

FileName: tutorial_07.cyr

There are just a few subtle changes in Skin_Cell. Instead of incrementing apple each time, we're only going to increment it if POISSON[10] evaluates true. The Rules will only pass this condition, on average, every 10 times the condition is evaluated. The key is "on average." You never know when it's going to evaluate true, but you can rest assured that in the long-run, it will tend toward every 10 cycles... on average.

(Since apple is only being incremented every 10 times on average, we've made it increment by 10 just so that we'll get, more or less, the same pace as the last example.)

Similar changes have been made in Eye_Cell.

Now, when you place a few dozen cells of each type, they will switch back and forth in Poisson-ishy random manner.

You will note that the conditionals in the last line of each STATE have changed a bit. For instance, instead of apple[75], we now have apple[75,INF]. Why? As we're incrementing apple by 4 in Eye_Cell, it will never equal 75. In short, don't use 'equal to' if a 'greater than' or 'less than' will do; with larger sets of Rules, it would have been easy to have introduced a bug by changing the apple increment from 1 to 4 without remembering that 75 isn't a multiple of 4.

FileName: tutorial_08.cyr

We've defined two G_VAR variables, each with very scientific names: ooze and mucous.

Incorporating some of the lessons learned so far, you'll notice that apple and cat are being used to make the Skin_Cell and Eye_Cell swell every so often. Why do we make it swell? No reason... just looks cool. But, you'll notice that when the cell does swell, it also processes the command EMIT.

The Skin_Cell will emit ooze, and the Eye_cell will emit mucous.

When the EMIT command is processed, every Node in the cell will set the referenced G_VAR variable to 1.0. From that point on, the value will diffuse from Node to Node, decreasing in value the farther it diffuses. You can check Draw Gradient to watch.

Each G_VAR variable has a built-in default color. The first G_VAR declared will be red, the second green, and so forth. (Although you may declare as many G_VARs as you wish, there are only 7 built-in colors; the default color for higher-numbered G_VAR is white.)

Note that the values diminish very quickly. If you are going to have a cell change its behavior based on a G_VAR value that is diffusing through the Petri Dish, you'll probably be dealing with 1/100ths or 1/1000ths. To get a feeling for the drop-off in the values as a function of distance, place a Probe_Cell and drag it around some Skin_Cells and Eye_Cells. It will turn red when near ooze and green when near mucous. You can adjust the levels in the conditional (or, better yet, Monitor the cell and watch the values) to get a feel for the way G_VAR values diffuse.

(We've been asked why the mucous(ooze,INF) and ooze(mucous,INF] conditions are present in the last two lines. They are to cover cases when both ooze and mucous are at levels strong enough to trigger the color change; we wish to turn the cell red only if there is more ooze than mucous and vice versa.)

G_VARs have a very important purpose... they allow cells to communicate across distances. Without question, this occurs in real biological systems. As you'll see, though, its a very imprecise way to send signals.

FileName: tutorial_09.cyr

Cells move. Their movement is a vital component of morphogenesis.

In order to tell the cell which way to move, we need to declare a V_VAR. We'll call ours myFirstVector.

We set the direction of a V_VAR with the SET_VEC command. We can have our vector point towards the highest concentration of a particular U_VAR variable in adjoining cells. We can set an actual value ourselves, using the Cartesian coordinate system. Or, we can have it point towards a concentration of a G_VAR variable in the Petri Dish.

Here, we'll explore the second and third possibilities.

Let's start with the last cell first.
The Comet_Cell sets the V_VAR to (0.5, 0.5). This means our vector will point down and to the right. (CYCELL uses graphics-style coordinates... the Y-axis increases in value from top to bottom.) Once we have set the V_VAR, we use it as the curly-bracket parameter in the MIGRATE command.

Now, Uranus_Cell, Venus_Cell, and Asteroid_Cell have their V_VARs set to point to ooze. Our Sun_Cell conveniently emits ooze.

The MIGRATE command for Asteroid_Cell is straightforward; the offset angle is set to 0, so it will just move in the direction of myFirstVector with a 'force' of -60.

The MIGRATE command for Uranus_Cell and Venus_Cell utilize the 'offset-angle' parameter, with one set to 90 and the other to -90. The end result is they will travel at right angles to the direction of myFirstVector.

PUTTING IT ALL TOGETHER: Place a Sun_Cell in the middle of the Petri Dish. Sprinkle a few Uranus_Cells and Venus_Cells around it. When the ooze diffuses out to your 'planets,' they will start orbiting. Yes, CYCELL can double as an orbital mechanics simulator. (Not really.)

Check Draw Vectors to see the directions your cells are trying to travel.

FileName: tutorial_10.cyr

The MITOSIS command causes a cell to split. A few general principles must be remembered.

• First, after a split, there will be two different cells. Each cell will contain exactly one-half the values of the U_VARs in the original cell. (However, the Internal Variable TYPICAL_AREA will remain the same for both cells.)
• Second, depending on the configuration of the cell, the MITOSIS command may not be processed. For instance, if the 'daughter' cells would contain 5 or less Nodes, mitosis will be skipped. Likewise, if the cell is stretched or squished to the extent that a clean cleavage line can't be established, mitosis will be skipped.
• Third, after mitosis, neither daughter cell will be considered to be entering its state for the first time unless, as we'll see below, the MITOSIS command explicitly commands the daughter to be a different state than the mother.
• Finally, oftentimes we will refer to 'mother' cell and 'daughter' cell. This view of mitosis is not technically correct... It implies that the original cell had an offspring. In reality, each of the two resulting cells have just as much claim to being the 'original' cell as the other. This view carries with it some subtle implications that we'll touch on when we describe the bud_1 and bud_2 states.

Another thing to notice is the use of ADHESIONS. As we will have a few different types of cells working together, their ADHESIONS values have been set to be consistent. The syntax of ADHESIONS is straightforward. (To try it out, in the previous tutorial, make the Uranus_Cells and Venus_Cells stick together and watch them try to navigate in opposite directions around the 'sun'... sort of cruel, but interesting.)

With that out of the way, let's start with unchecked_growth. This cell type will undergo mitosis continuously, so long as ACTUAL_AREA is large enough. (If this condition were to be removed, the cell would immediately try to split again and again, getting smaller and smaller each time.)

Now, unchecked_growth will completely fill up the Petri Dish.

How does one stop the cells from splitting?

This is actually a very good question. What makes your nose stop growing? Nobody really knows. In fact, there is a fairly good chance you will die someday precisely because a few cells in your body mutate and lose their ability to know when to stop growing. (i.e. cancer.)

There are many techniques you can come up with in CYCELL to limit cell-growth. We've implemented one, as an example, in the next state.

You'll notice that controlled_growth sets the U_VAR growth_factor to 1000 when it first enters the state. After every division, the value of this variable will be halved. You can do the math and calculate how many divisions are possible before the growth_factor[10,INF] condition is no longer triggered. (You also may notice that this is NOT a very good way of making a scrum with large numbers of cells as the initial value of growth_factor would need to be enormous. But, there are other techniques... this one is just quick and easy.)

With bud_1 we begin taking advantage of MITOSIS parameters. MITOSIS{stalk} will perform mitosis, but it will result in a 'daughter' cell belonging to STATE stalk.

You'll notice that the cleavage plane of the cell is random.

With bud_2 we take control of how our cell divides. Directional mitosis is a thing in real biological systems. As with MIGRATE, we use a V_VAR vector to get things going.

In the example, SET_VEC{cleavage}[stalk] will set cleavage to a vector pointing towards the average location of adjoining stalk cells. (If there are no adjoining stalk cells, the vector will point in a random direction.)

We use the V_VAR in the MITOSIS command to direct the cell to split along a line parallel to the vector. Importantly, though, we've also set an offset angle of 90; thus, the cleavage line will be perpendicular to the vector. We've finally set the third parameter to CCW (counter-clockwise) which directs which of the two resulting cells will be assigned to state stalk. Phew. In short, we can grow tendrils and whatnot in a specific direction. Change CCW to CW. Change 90 to 45. You should get the gist of it.

We first place a cell from the uncontrolled_growth state. Then, we place a couple of controlled_growth cells. Then, we place a bud_1 and a couple bud_2s.

The cell types bud_1 and bud_2 will grow forever. The quick technique we used for controlled_growth isn't all that useful here. If we wanted our bud_2 to make a long snaking tendril with 100 or so cells and then stop, our growth_factor variable would need to start out at something like 2^100. That's silly.

You will be tempted to think that there must be some kind of counter that we could implement that will tell our bud_2 cell to quit dividing after, say, 100 splits. But, it doesn't work that way, and that's precisely what we were getting out with the fourth point in the "Brief Overview" section above. Specifically, although it might look like its the same bud_2 cell moving along and spitting out stalk cells, in reality after mitosis we're left with two brand-new cells, so to speak, who have never undergone mitosis before! Not to get all philosophical about it, but in truth, a cell can't undergo mitosis more than once, for after mitosis it's no longer the same cell.

What we really want is a way to count the generations of a cell. That's a tricky thing to keep track of. For, after mitosis, every variable into which we could encode such a counter is chopped in two, making it very unwieldy to maintain some permanent record of a cell's biography. (Not impossible... just unwieldy.)

FileName: tutorial_11.cyr

There's a lot of stuff going on with this one. We'll walk you through it.

Let's start with the end-result and work backwards. We're going to grow a scrum of Skin cells. Some of them will be Macrophages. These blueish Macrophages comprise our scrum's immune system. Occasionally, one of the Skin cells will turn into a greenish-Mutant cell! Luckily, the Mutant cell exudes a protein, which is spread from cell to cell (with a reddish-tint.) When our Macrophages sense it, they MIGRATE towards the source to attack! After the Macrophages have been in contact with it long enough, the Mutant cell will CHANGE_STATE back to a Skin cell.

Now, on to the code.

First, the ADHESIONS. As before, we are working with several types of cells. With the default adhesions, different types of cells don't adhere to each other. We've set things so that everything sticks together to the same degree, more or less. We've made our Macrophages avoid each other by assigning them a positive adhesions value. And, we've lowered the default Macrophage-SELF value just to make these types of cells a little more slithery. In short, the values are primarily for aesthetics in this set of Rules; there's nothing magical about the values, so don't get overwhelmed.

The real point of this lesson pertains to GAP_JUNCTIONS. As you already know, you can declare various U_VAR variables. But, remember that these 'variables' represent actual stuff in the cell... chemicals, proteins, or whatever. And, like real cells, this stuff can be exchanged between cells.

Unlike G_VAR stuff that just passively oozes out of a cell into the environment, U_VAR values use GAP_JUNCTIONS to engage in inter-cellular active transport. For instance, in the first line, we are telling the program that the Skin cell's level of intruder_alert will be actively transported into an adjoining Skin cell at a rate of 1% per shared membrane. This is not like osmosis where the level must be higher in one cell for it to diffuse into the other cell. Instead, the 1% per membrane will be forced into the other cell regardless of the neighbor's own level of intruder_alert. It's best to keep the rate very low... for instance, if there were 100 shared membranes between two cell's, all of the intruder_alert would be transferred on a single simulation cycle. (And, then that neighbor would transfer it all right back on the next cycle... this would be very unrealistic.) The purpose of GAP_JUNCTIONS is not to simulate a mathematically rigorous PDE solver; rather, it's just a rough way to have substances travel through cell networks in a somewhat realistic manner.

When you run these Rules, you will see the Mutant cells transport their intruder_alert into the adjoining cells. And, those cells do the same... We've linked the Skin cell's color to the level of intruder_alert so you will be able to see the spreading intruder_alert as a red tint.

The Stem cells create a modest-size scrum just to get things started. You'll notice that about every 5% of their mitoses will create a Macrophage cell. We've accomplished this using the SET_RAND command.

Once we have the appropriate number of cells in the Petri Dish (controlled, once again, by the multiple halving of a generic U_VAR) we turn all the stem cells to Skin cells.

On the 10th line under the Skin cell definition, we force the cell to turn into a Mutant. There are three conditions.

The first pertains merely to aesthetics; we don't want mutants to arise on the periphery, so we require that none of the Skin cells can have any membranes touching the MEDIUM.

The second condition requires that there not be any intruder_alert in our cell, and the third is just a POISSON to make the mutations arise at a random frequency.

The Mutant cells, when they arise, maintain a constant level of intruder_alert at 300. At each cycle, due to the GAP_JUNCTIONS definitions, a percentage of this value will be transported into their neighbors. (You'll notice in Skin cell that we decrease the value of intruder_alert by 5% each cycle, and set it to 0 when it gets below 0.1. This is to prevent the entire scrum filling up with intruder_alert.)

The 4th through 8th lines under the Skin cell definition are worth looking at. They deal with how the cell is colored. We want a reddish-tint to correspond to the level of intruder_alert. With computer graphics, to make something more red, we decrease the levels of green and blue. We've used a little throw-away U_VAR called color_aux to handle this. In short, these five-lines are more for the user's benefit (and to help with debugging) than they are with controlling the cell's behavior. So, don't get confused them... there are any number of ways to mess around with the color and whatnot, and we threw this in here just to demonstrate one way of making a 'tint'.

Meanwhile, the Macrophage cells are just hanging out. But, when their level of intruder_alert exceeds 0, they spring into action. Using SET_VEC they set a vector towards the greatest concentration of intruder_alert, and MIGRATE in that direction.

When a Macrophage makes contact with a Mutant, a counter begins. You'll notice we make the count faster depending on how many Macrophage cells are touching the Mutant. When the count reaches 100, the Mutant turns back into a normal Skin cell.