Cellsprings Help: Springlet Programming: Class Springlet

net.jmge.prj.csprings
Class Springlet

java.lang.Object
  |
  +--net.jmge.prj.csprings.Springlet

All Implemented Interfaces:: java.lang.Cloneable

public abstract class Springlet
extends java.lang.Object
implements java.lang.Cloneable

To code your own rule or rulespace that will install into Cellsprings, you simply subclass this class. You must do a minimum of two things in your subclass. First, you must provide a default (i.e., parameterless) constructor that passes some parameters back to the superclass constructor. Second, you must override the computeCell() method. Normally, however, you will go beyond the minimum class definition and override a couple of other methods - so as to create a rulespace (parameterized rule) rather than a hardcoded rule, provide a description to the user, etc.

You should know that in general the system takes a laissez faire attitude toward your code, and for the most part doesn't insulate itself from mistakes. For example, you could mess things up royally by writing to the inherited instance variables, so treat them as though they were read-only.

A word about the cellSize field. In Cellsprings, a rule's cellsize is part of its basic definition. Whether or not your springlet parameterizes cellsize, you must pass a default value for the cellSize field back to the superclass at construction.

Another thing to note is that there is a distinction between "update time" and "edit time". The state-related inherited instance variables - mCells and the index arrays - are valid only at update time, i.e., in the beforeUniversePass() and computeCell() methods. Don't try to read them elsewhere. On the other hand, the cellSize field is always valid, though it can change only at edit time.

Version:: 1.0 beta (29-Aug-2000)
Author:: J. M. G. Elliott (tep@jmge.net)

Field Summary

protected int cellSize
          The rule's "cellsize", meaning that valid cell values are confined to the range 0..cellSize-1.

protected int[] iE
          Table of precalculated neighbor indices for the current universe, where iE[i] maps the current cell's column index to its modular increment, i.e., the column index of the toroidal East neighbor.

protected int[] iW
          (West) Like iE, but a decrement map.

protected int[] jN
          (North) Like jS, but a decrement map.

protected int[] jS
          Table of precalculated neighbor indices for the current universe, where jS[j] maps the current cell's row index to its modular increment, i.e., the row index of the toroidal South neighbor.

protected static int MAX_CELLSIZE
          Cellsprings will not run rules with cellsizes that exceed this value (currently 256); your rule's default cellsize must be between 2 and MAX_CELLSIZE, inclusive.

protected short[][] mCells
          The entire CA cell matrix at time t.

Constructor Summary

protected Springlet(int cellsize, boolean cellsize_parameterized, java.lang.String[][] paramdefs)
          This is the only constructor, hence subclasses are required to call it in their own constructors, which themselves must not take parameters.

Method Summary

protected void beforeUniversePass()
          An optional override that provides the opportunity to do any setup that might need doing prior to each universe pass.

protected java.lang.Object clone()
          If your subclass defines any mutable instance variables, you should override this method to enable Cellsprings to manage your springlet properly.

protected abstract int computeCell(int i, int j)
          You are required to override this method - it's the cell update method whose definition constitutes your rule proper.

java.lang.String[] getDescription()
          Override this method to provide some textual info about your rule or rule-family to the Cellsprings end-user.

protected boolean parameterChanged(java.lang.String name, java.lang.String value)
          Override this method only if you have defined your own runtime parameters.

Methods inherited from class java.lang.Object

equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Detail

MAX_CELLSIZE

protected static final int MAX_CELLSIZE

Cellsprings will not run rules with cellsizes that exceed this value (currently 256); your rule's default cellsize must be between 2 and MAX_CELLSIZE, inclusive.

See Also:: cellSize

mCells

protected short[][] mCells

The entire CA cell matrix at time t.

iE

protected int[] iE

Table of precalculated neighbor indices for the current universe, where iE[i] maps the current cell's column index to its modular increment, i.e., the column index of the toroidal East neighbor.

See Also:: iW

iW

protected int[] iW

(West) Like iE, but a decrement map.

See Also:: iE

jS

protected int[] jS

Table of precalculated neighbor indices for the current universe, where jS[j] maps the current cell's row index to its modular increment, i.e., the row index of the toroidal South neighbor.

See Also:: jN

jN

protected int[] jN

(North) Like jS, but a decrement map.

See Also:: jS

cellSize

protected int cellSize

The rule's "cellsize", meaning that valid cell values are confined to the range 0..cellSize-1.

See Also:: MAX_CELLSIZE

Constructor Detail

Springlet

protected Springlet(int cellsize,
                    boolean cellsize_parameterized,
                    java.lang.String[][] paramdefs)

This is the only constructor, hence subclasses are required to call it in their own constructors, which themselves must not take parameters.

Parameters:: cellsize - Default number of allowable cellstates under your rulespace, from 2 to MAX_CELLSIZE.; cellsize_parameterized - Pass 'true' to allow the user to change the cellSize field.; paramdefs - An array of key-value pairs, defining parameters for the user to set. For best results, parameter names should be short and devoid of spaces. Also, don't use the name "C", as it is reserved for system use. If you don't want to define any parameters of your own, pass 'null'.

Method Detail

getDescription

public java.lang.String[] getDescription()

Override this method to provide some textual info about your rule or rule-family to the Cellsprings end-user.

Returns:: The lines comprising your description.

parameterChanged

protected boolean parameterChanged(java.lang.String name,
                                   java.lang.String value)

Override this method only if you have defined your own runtime parameters. The Cellsprings RuleTool may call this method with a new value for any parameter in the list you passed at construction. (Such a call can happen at any time during "edit time", but not once your rule is installed into a CA universe.) Normally you'd use the opportunity to save the new value to an instance variable you've defined for the purpose. This method also provides a mechanism for input validation: if you return 'false', the value will revert to its previous value.

Parameters:: name - The name of the parameter that has been updated.; value - The new value for the parameter.
Returns:: 'true' if parameter value is valid, 'false' otherwise

beforeUniversePass

protected void beforeUniversePass()

An optional override that provides the opportunity to do any setup that might need doing prior to each universe pass.

computeCell

protected abstract int computeCell(int i,
                                   int j)

You are required to override this method - it's the cell update method whose definition constitutes your rule proper. The method will be called for each cell in turn as the updater traverses the universe. The current cell position is passed in terms of zero-based column and row indices. Your rule's mission is to return the next value for the specified cell, given its present value and the values of its neighbors. Here are the inherited instance variables available to you:

  protected short[][] mCells;    // current cell matrix
  protected int[]     iE, iW, jS, jN; // toroidal nearest-neighbor indices
  protected int       cellSize;  // (since it may be parameterized)

Of course, since you have access to the entire cell matrix, you are free to define the neighborhood and universe topology differently from the nearest-neighbor and toroidal implied by the inherited index arrays. "It's your CA, we just connect you to it."

Parameters:: i - Column index of current cell.; j - Row index of current cell.
Returns:: Current cell's updated value, as determined by your rule algorithm. Must be in the range 0..cellSize-1.
See Also:: mCells, iE, iW, jS, jN, cellSize

clone

protected java.lang.Object clone()

If your subclass defines any mutable instance variables, you should override this method to enable Cellsprings to manage your springlet properly. (In case you're not familiar with this particular Java song and dance, a field is generally "mutable" if it is not a primitive, String, or primitive-type wrapper. There's an override example in the sample springlet code.)

Overrides:: clone in class java.lang.Object

Returns:: A new instance that is a copy of the present instance.

Field Summary
`protected int`	`cellSize` The rule's "cellsize", meaning that valid cell values are confined to the range 0..cellSize-1.
`protected int[]`	`iE` Table of precalculated neighbor indices for the current universe, where iE[i] maps the current cell's column index to its modular increment, i.e., the column index of the toroidal East neighbor.
`protected int[]`	`iW` (West) Like iE, but a decrement map.
`protected int[]`	`jN` (North) Like jS, but a decrement map.
`protected int[]`	`jS` Table of precalculated neighbor indices for the current universe, where jS[j] maps the current cell's row index to its modular increment, i.e., the row index of the toroidal South neighbor.
`protected static int`	`MAX_CELLSIZE` Cellsprings will not run rules with cellsizes that exceed this value (currently 256); your rule's default cellsize must be between 2 and MAX_CELLSIZE, inclusive.
`protected short[][]`	`mCells` The entire CA cell matrix at time t.

Constructor Summary
`protected`	`Springlet(int cellsize, boolean cellsize_parameterized, java.lang.String[][] paramdefs)` This is the only constructor, hence subclasses are required to call it in their own constructors, which themselves must not take parameters.

Method Summary
`protected void`	`beforeUniversePass()` An optional override that provides the opportunity to do any setup that might need doing prior to each universe pass.
`protected java.lang.Object`	`clone()` If your subclass defines any mutable instance variables, you should override this method to enable Cellsprings to manage your springlet properly.
`protected abstract int`	`computeCell(int i, int j)` You are required to override this method - it's the cell update method whose definition constitutes your rule proper.
`java.lang.String[]`	`getDescription()` Override this method to provide some textual info about your rule or rule-family to the Cellsprings end-user.
`protected boolean`	`parameterChanged(java.lang.String name, java.lang.String value)` Override this method only if you have defined your own runtime parameters.

net.jmge.prj.csprings Class Springlet