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, 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.
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.

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