## org.ascape.model
Class Agent

    java.lang.Object
      org.ascape.model.AscapeObject
          org.ascape.model.Agent

All Implemented Interfaces:
  java.io.Serializable, java.lang.Cloneable, HasName, RandomFunctions

Direct Known Subclasses:
  LocatedAgent

    public class Agent

extends AscapeObject
implements java.lang.Cloneable

The base class for all modeled objects in ascape. Note that an ascape agent is actually a superset of the general understanding of a software 'agent'. Ascape agents need not be mobile or autonomous, but are always capable of being so. For instance, a lattice cell is a subclass of this class and within its own lattice has no opportunity to move, obviously. The same cell, however, may move upon some other lattice or collection of agents.
To represent agent state simply provide member variables along with getters and setters in subclasses, and create StatCollectors to make aggregate values available. To provide behavior add rules to the parent scape. A simple way to do this is to override the `scapeCreated` method. There are a number of rules that act simply to call a cooresponding method or methods in Agent. For instance, `METABOLISM_RULE` will call the `metabolism` method on the appropriate agents
. `ITERATE_RULE` is added to the parent scape by default, and calls the `iterate` method, but it is typically preferrable to use more granular and flexible rules. To get rid of this iterate rule, overide `scapeCreated`, or call `clearRules` on the parent scape. You should do this whenever agent level processing is not required for a given scape; it can take time to iterate through some scapes, and there is no way for the engine to determine at runtime that an iterate method is a non-op.

Since:
  1.0
Version:
  1.2.5
Author:
  Miles Parker
See Also:
  Serialized Form

Field Summary
`static Rule` `DEATH_RULE` A rule calling the death method of the target agent.
`static Rule` `FISSIONING_RULE` A rule calling the fissioning method of the target agent.
`static Rule` `FORCE_DIE_RULE` A rule calling the die method of the target agent.
`static Rule` `FORCE_FISSION_RULE` A rule calling the fission method of the target agent.
`static Rule` `FORCE_MOVE_RULE` An rule calling the move method of the target agent, causing the agent to move regradless of what the movement condition method returns.
`static Rule` `INITIALIZE_RULE` A rule causing the target and all its children scapes to be initialized.
`static Rule` `ITERATE_AND_UPDATE_RULE` A rule calling the iterate method on each agent in a scape and then the update method on each agent in a seperate, subsequent step.
`static Rule` `ITERATE_RULE` An rule calling the iterate method of the target agent.
`static Rule` `METABOLISM_RULE` An rule calling the metabolism method of the target agent.
`static Rule` `MOVEMENT_RULE` An rule calling the default movement method of the target agent.
`static Rule` `PLAY_OTHER` A rule causing the target agent to interact with another agent in its scape using the Agent.play() method.
`static Rule` `UPDATE_RULE` A rule calling the update method of the target agent.

Fields inherited from class org.ascape.model.AscapeObject
`ARBITRARY_SEED, name, PLATFORM_DEFAULT_COLOR, scape`

Constructor Summary
`Agent()`

Method Summary
`void` `clearDeleteMarker()` Resets the marker for deletion.
`java.lang.Object` `clone()` Clones the agent.
`void` `death()` Perform the death rule; if the death condition is met, kill the agent.
`boolean` `deathCondition()` Conditions under which this agent should die.
`void` `die()` "Kill" the agent.
`void` `execute(Rule rule)` Causes the provided rule to be executed upon this agent.
`void` `execute(Rule[] rules)` Causes the provided rules to be executed upon this agent.
`void` `fission()` Override to reproduce agent, creating a new agent.
`boolean` `fissionCondition()` Conditions under which this agent should fission.
`void` `fissioning()` Perform the fissioning rule; if the fission condition is met, fission.
`java.awt.Color` `getColor()` This agent's default color, used by many simple views.
`java.awt.Color` `getColor(java.lang.Object object)` Provides the default color for an agent.
`java.awt.Image` `getImage()` This agent's default image, used by many simple views.
`java.awt.Image` `getImage(java.lang.Object object)` Provides the default image for an agent.
`int` `getIteration()` Returns the current count of iteration.
`java.lang.Object` `getPlatformColor()` The agent color as platform specific (i.e.
`Scape` `getRoot()` Gets the rootmost parent scape for this agent.
`void` `initialize()` Initialize any values.
`boolean` `isDelete()` Is this agent marked for deletion?.
`boolean` `isInitialized()` Has this agent been initialized?
`void` `iterate()` Iterate this agent.
`void` `markForDeletion()` Sets the agent to be deleted when the next deletion sweep occurs.
`void` `metabolism()` Performs default metabolism for this agent.
`void` `move()` Override to move this agent based on movement condition.
`void` `movement()` Perform the movement rule; by default, if the movement condition is met, move.
`boolean` `movementCondition()` Conditions under which this agent should move.
`void` `play(Agent agent)` Interact in some way with the supplied agent.
`void` `scapeCreated()` Notifies the prototype agent that a new scape has been created, allowing rules to be added directly from an agent class.
`protected void` `setInitialized(boolean initialized)` Sets the initialization state of the agent.
`void` `setScape(Scape scape)` Sets the scape for this agent.
`java.lang.String` `toString()` A string representation of this agent.
`void` `update()` Update this agent.

Methods inherited from class org.ascape.model.AscapeObject
`diffDeep, diffDeep, diffDeepBFS, diffDeepDFS, diffDeepValidate, diffDeepVisit, equalsDeep, equalsDeep, equalsDeep, getComparisonStream, getName, getRandom, getRandomSeed, getScape, randomInRange, randomInRange, randomIs, randomToLimit, reseed, setComparisonStream, setName, setRandom, setRandomSeed`

Methods inherited from class java.lang.Object
`equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait`

Field Detail

### INITIALIZE_RULE

    public static final Rule INITIALIZE_RULE

  A rule causing the target and all its children scapes to be initialized.

### UPDATE_RULE

    public static final Rule UPDATE_RULE

  A rule calling the update method of the target agent. The update method is intended to provide a means for performing basic agent housekeeping, and not behavior that could change the state of other agents or the lattice.

### ITERATE_AND_UPDATE_RULE

    public static final Rule ITERATE_AND_UPDATE_RULE

  A rule calling the iterate method on each agent in a scape and then the update method on each agent in a seperate, subsequent step. This rule is designed to facilitate simple synchronous updating. By calculating a temporary value in the iterate method for each agent, and then assiging that value to the agent permanentaly in a subsequent step, synchronous (effectivly simultaneous) processes can be modelled. For this to work properly, the scape's execution order must be by rule, not by agent.

### DEATH_RULE

    public static final Rule DEATH_RULE

  A rule calling the death method of the target agent.

### FORCE_DIE_RULE

    public static final Rule FORCE_DIE_RULE

  A rule calling the die method of the target agent. Kills the agent regardless of deathCondition.

### FISSIONING_RULE

    public static final Rule FISSIONING_RULE

  A rule calling the fissioning method of the target agent. By default, this calls the fissioning rule, which calls move if the agent's fissionCondition method returns true.

### FORCE_FISSION_RULE

    public static final Rule FORCE_FISSION_RULE

  A rule calling the fission method of the target agent. Forces the agent to fission, regardless of fission condition.

### METABOLISM_RULE

    public static final Rule METABOLISM_RULE

  An rule calling the metabolism method of the target agent.

### MOVEMENT_RULE

    public static final Rule MOVEMENT_RULE

  An rule calling the default movement method of the target agent. By default, this calls the movement condition rule, which calls move if the agent's movementCondition method returns true.

### FORCE_MOVE_RULE

    public static final Rule FORCE_MOVE_RULE

  An rule calling the move method of the target agent, causing the agent to move regradless of what the movement condition method returns.

### PLAY_OTHER

    public static final Rule PLAY_OTHER

  A rule causing the target agent to interact with another agent in its scape using the Agent.play() method.

### ITERATE_RULE

    public static final Rule ITERATE_RULE

  An rule calling the iterate method of the target agent. This rule is different than the iterate scape rule. This provides a simple way to provide a general iterate method for each agent, while still using the general rule mechanism. This is not the 'recommended' way to do things; it is more flexible, powerful, and maintainable to add specialized rules to an existing scape.

Constructor Detail

### Agent

    public Agent()

Method Detail

### scapeCreated

    public void scapeCreated()

  Notifies the prototype agent that a new scape has been created, allowing rules to be added directly from an agent class. This is especially useful if you don't want a lot of public rules classes around, since you can add the rules directly from within an agent java file. Guaranteed to be called only once for a new model; will only be called if the parent scape is assigned a prototype agent. Override to add rules to the agent's scape, to override subclass default rules, etc... for instance, you might use this method to create special purpose value collectors, or anything else that is related to the agent and needs to be created once per model. (See norms.NormsCell for an example.) By default, adds a default iterate rule, which calls iterate on each agent for every iteration. You should always override this rule for custom agents (or call scape.clearRules()) so that the overhead of the iterate rule isn't incurred. Edited - Iterate rule is no longer added by default.

### deathCondition

    public boolean deathCondition()

  Conditions under which this agent should die. Returns false by default.

  Returns:
    true if the agent should die
  See Also:
    `death()`

### death

    public void death()

  Perform the death rule; if the death condition is met, kill the agent.

  See Also:
    `deathCondition()`, `DEATH_RULE`

### die

    public void die()

  "Kill" the agent. If the agent is a member of a mutable scape, remove it from the scape.

### fissionCondition

    public boolean fissionCondition()

  Conditions under which this agent should fission. Returns false by default.

  Returns:
    true if the agent should fission
  See Also:
    `fission()`

### fissioning

    public void fissioning()

  Perform the fissioning rule; if the fission condition is met, fission.

  See Also:
    `fissionCondition()`, `FISSIONING_RULE`

### fission

    public void fission()

  Override to reproduce agent, creating a new agent.

### movementCondition

    public boolean movementCondition()

  Conditions under which this agent should move. Returns false by default.

  See Also:
    `movement()`

### movement

    public void movement()

  Perform the movement rule; by default, if the movement condition is met, move.

  See Also:
    `movementCondition()`, `MOVEMENT_RULE`

### move

    public void move()

  Override to move this agent based on movement condition. To provide a general purpose movement function, overide movement instead

  See Also:
    `movement()`

### metabolism

    public void metabolism()

  Performs default metabolism for this agent.

  See Also:
    `METABOLISM_RULE`

### play

    public void play(Agent agent)

  Interact in some way with the supplied agent. To use, simply add a Play rule to the agent's scape and overide this method. (Other play methods may be supplied later.)

  See Also:
    `Cell.PLAY_NEIGHBORS_RULE`, `Cell.PLAY_RANDOM_NEIGHBOR_RULE`, `PLAY_OTHER`

### iterate

    public void iterate()

  Iterate this agent. By default, called automatically on each agent each iteration. Use clearRules or overide scapeCreated to prevent this.

  See Also:
    `scapeCreated()`, `ITERATE_RULE`

### update

    public void update()

  Update this agent.

  See Also:
    `UPDATE_RULE`

### initialize

    public void initialize()

  Initialize any values. This method will be called automatically when the parent scape is initialized or started, so override this to provide initial values, location, etc... Any parent models of this agent's scape can be assumed to be initialized. Of course, other agents within the scape should be assumed not to have been initialized.

### execute

    public void execute(Rule[] rules)

  Causes the provided rules to be executed upon this agent.

  Parameters:
    `rules` - an array of rules to be executed

### execute

    public void execute(Rule rule)

  Causes the provided rule to be executed upon this agent.

  Parameters:
    `rule` - a rule to be executed

### getRoot

    public Scape getRoot()

  Gets the rootmost parent scape for this agent.

### getIteration

    public int getIteration()

  Returns the current count of iteration. For non-scape agents, the parent's scape iteration will be returned. For scapes, this method is overriden to return it's own iteration.

### getPlatformColor

    public java.lang.Object getPlatformColor()

  The agent color as platform specific (i.e. non-AWT).

### getColor

    public java.awt.Color getColor()

  This agent's default color, used by many simple views. Black is default; override to provide an appropriate color.

### getColor

    public java.awt.Color getColor(java.lang.Object object)

  Provides the default color for an agent. Simply calls the getColor method for the object.

### getImage

    public java.awt.Image getImage()

  This agent's default image, used by many simple views. No default; override to provide an appropriate image.

### getImage

    public java.awt.Image getImage(java.lang.Object object)

  Provides the default image for an agent. Simply calls the getImage method for the object.

### isInitialized

    public boolean isInitialized()

  Has this agent been initialized?

### setScape

    public void setScape(Scape scape)

  Sets the scape for this agent. (If the agent is marked for deletion, we need to force the deletion in the agent's parent scape.

  Overrides:
    `setScape` in class `AscapeObject`
  Parameters:
    `scape` - the scape this agent is belongs to

### setInitialized

    protected void setInitialized(boolean initialized)

  Sets the initialization state of the agent.

### isDelete

    public boolean isDelete()

  Is this agent marked for deletion?.

### markForDeletion

    public void markForDeletion()

  Sets the agent to be deleted when the next deletion sweep occurs. Used when agent deletion can be safely postponed, that is, when the state of other agents is not a factor in the deletion rules for agents.

### clearDeleteMarker

    public void clearDeleteMarker()

  Resets the marker for deletion. The agtent will no longer be deleted on the next deletion pass.

### toString

    public java.lang.String toString()

  A string representation of this agent.

  Overrides:
    `toString` in class `AscapeObject`

### clone

    public java.lang.Object clone()

  Clones the agent. Can be overriden so that a deep copy is made of any member objects that you do not want to share between agents. Typically, this applies to all agent member objects. Warning: The default behavior of this method is to perform a shallow copy. This is not appropriate for most agent state! For any member objects in the model you must either a) construct a new object at `initialize()` or b) preform a deep clone of that object by overriding this method. If you do not do one of these things, you will end up sharing members across agents. This can be a very diffuclt problem to debug!

  Overrides:
    `clone` in class `AscapeObject`