org.primordion.xholon.base
Interface ITurtle

All Superinterfaces:

IXholon

All Known Implementing Classes:

Turtle

public interface ITurtle

extends IXholon

A turtle is an agent in the turtle mechanism. The turtle mechanism is based on Logo and NetLogo. The abbreviated version of a turtle command (fd bk rt lt) should be used instead of the unabbreviated command.

Since:

0.5 (Created on February 24, 2007)

Author:

Ken Webb

See Also:

NetLogo website http://ccl.northwestern.edu/netlogo/

TODO add (May 15 2007): beep downhill downhill4 inCone inRadius patchAhead patchAt patchAtHeadingAndDistance patchHere patchLeftAndAhead patchRightAndAhead stamp stampErase turtlesAt turtlesHere turtlesOn uphill uphill4 with

Field Summary

static int	COMMANDID_NONE
static int	FILTERID_NONE
static int	PENMODE_DOWN
static int	PENMODE_ERASE
static int	PENMODE_UP
static int	WHENMOVED_INIT

Fields inherited from interface org.primordion.xholon.base.IXholon

DEFAULT_SIZE_MSG_Q, NINCLUDE_PSC, NINCLUDE_PSx, NINCLUDE_PxC, NINCLUDE_Pxx, NINCLUDE_xSC, NINCLUDE_xSx, NINCLUDE_xxC, NINCLUDE_xxx

Method Summary

void	aggregate(double amount) Aggregate by keeping a count of the number of individuals of a given "breed".
void	back(double distance) Move back a given distance.
void	beep() Make a single short beep sound.
void	bk(double distance) Move back a given distance.
boolean	canMove(double distance) Can this turtle legally move the specified distance, given its current heading?
void	die() Remove yourself permanently from the gene pool.
double	distance(IXholon turtleOrPatch) Return the distance between self and the specified turtle or patch.
double	distancexy(double x, double y) Return the distance between yourself and the specified x, y coordinates.
double	downhill() "Return the turtle heading in the direction of the minimum value of the variable patch-variable, of the patches in a one-patch radius of the turtle."
double	downhill4() "Return the turtle heading in the direction of the minimum value of the variable patch-variable, of the patches in a one-patch radius of the turtle."
double	dx() Returns the delta in the x direction if the turtle moved one unit along its current heading.
double	dy() Returns the delta in the y direction if the turtle moved one unit along its current heading.
void	face(IXholon turtleOrPatch) Turn to face the specified turtle or patch.
void	facexy(double x, double y) Turn to face the specified x, y coordinates.
void	fd(double distance) Move forward a given distance.
void	forward(double distance) Move forward a given distance.
int	getBreed() Get the turtle's breed id.
int	getColor() Get the turtle's color.
double	getHeading() Get the turtle's heading.
boolean	getIsHidden() Get the turtle's hide status.
java.lang.String	getLabel() Get the turtle's label, a String that helps to identify it.
int	getMaxPxcor() Return the maximum Patch x coordinate.
int	getMaxPycor() Return the maximum Patch y coordinate.
int	getMinPxcor() Return the minimum Patch x coordinate.
int	getMinPycor() Return the minimum Patch y coordinate.
int	getPcolor() Get the patch's pcolor.
int	getPenMode() Get the turtle's pen mode.
java.lang.String	getPlabel() Get the patch's label, a String that helps to identify it.
int	getPxcor() Get the patch's x coordinate.
int	getPycor() Get the patch's y coordinate.
int	getWho() Get the turtle's who id.
int	getWorldHeight() Return the height of the world (the grid height).
int	getWorldWidth() Return the width of the world (the grid width).
double	getXcor() Get the turtle's x coordinate.
double	getYcor() Get the turtle's y coordinate.
boolean	hasAlreadyMoved() Has this turtle already moved this time step? This method is required to prevent turtles from moving multiple times in the same time step, which would happen when a turtle moves to a patch that hasn't yet been reached in the tree traversal this time step.
void	hatch(int numTurtles, int commandId) Hatch a specified number of new turtles, each identical to this turtle.
void	hideTurtle() Hide from view.
void	home() Go home, by returning to the home coordinates.
void	ht() Hide from view.
java.util.Vector	inCone(double distance, double angle) Return agents that fall within a cone defined by the distance and angle .
void	initWhenMoved(int when) Initialize the whenMoved variable.
java.util.Vector	inRadius(int radius) Return a list of all neighbors (turtles) within the specified radius.
java.util.Vector	inRadius(int radius, int filterId) Return a list of all neighbors (turtles) within the specified radius.
void	jump(double distance) Jump forward a given distance, without effecting any intervening patches or turtles.
void	jump(IPatch aPatch) Jump directly to the specified patch.
void	jump(ITurtle aTurtle) Jump directly to the patch that the specified turtle is currently in.
void	left(double angle) Turn left a given angle.
void	lt(double angle) Turn left a given angle.
java.util.Vector	neighbors() Return the 8 surrounding neighbor patches.
java.util.Vector	neighbors4() Return the 4 surrounding neighbor patches.
java.util.Vector	otherTurtlesHere() Return all other turtles that are also currently located at this turtle's patch.
IPatch	patchAhead(double distance) Return the single patch that is the given distance along the turtle's current heading.
IPatch	patchAt(int dx, int dy) Return the single patch at the specified x and y relative distance.
IPatch	patchAtHeadingAndDistance(double heading, double distance) Return the single patch at the specified absolute heading and relative distance.
IPatch	patchHere() Return the patch that the turtle is currently on.
IPatch	patchLeftAndAhead(double distance, double angle) Return the single patch that is the given distance from the turtle, in the direction turned left the given angle from the turtle's current heading.
IPatch	patchRightAndAhead(double distance, double angle) Return the single patch that is the given distance from the turtle, in the direction turned right the given angle from the turtle's current heading.
void	pd() Set the pen down, so it is able to draw.
void	pe() Set the pen to erase.
void	penDown() Set the pen down, so it is able to draw.
void	penErase() Set the pen to erase.
void	penUp() Set the pen up, so it is unable to draw.
void	pu() Set the pen up, so it is unable to draw.
void	right(double angle) Turn right a given angle.
void	rt(double angle) Turn right a given angle.
void	setBreed(int breed) Set or change the turtle's breed id.
void	setColor(int color) Set the turtle's color.
void	setHeading(double heading) Set the turtle's heading.
void	setIsHidden(boolean isHidden) Set the turtle's hide status.
void	setLabel(java.lang.String label) Set or change the turtle's label.
void	setPcolor(int pcolor) Set the patch's pcolor.
void	setPenMode(int penMode) Set the turtle's pen mode.
void	setPlabel(java.lang.String plabel) Set or change the patch's label.
void	setPxcor(int pxcor) Set the patch's x coordinate.
void	setPycor(int pycor) Set the patch's y coordinate.
void	setWho(int who) Set the turtle's who id.
void	setXcor(double xcor) Set the turtle's x coordinate.
void	setxy(double x, double y) Set the turtle's x and y coordinates, and move to that location.
void	setYcor(double ycor) Set the turtle's y coordinate.
void	showTurtle() Show in the viewer.
void	st() Show in the viewer.
void	stamp() Leave an inprint or stamp of self at the current patch.
void	stampErase() Erase any inprint or stamp at the current patch.
double	towards(IXholon turtleOrPatch) Return the heading between self and the specified turtle or patch.
double	towardsxy(double x, double y) Return the heading between self and the specified x, y coordinates.
java.util.Vector	turtlesAt(int dx, int dy) Return the turtles located at the single patch at the specified x and y relative distance.
java.util.Vector	turtlesHere() Return the turtles located at the current patch.
java.util.Vector	turtlesOn() Return the turtles that are on the given patch or patches, or standing on the same patch as the given turtle or turtles.
double	uphill() "Return the turtle heading in the direction of the maximum value of the variable patch-variable, of the patches in a one-patch radius of the turtle."
double	uphill4() "Return the turtle heading in the direction of the maximum value of the variable patch-variable, of the patches in a one-patch radius of the turtle."
java.util.Vector	with(java.util.Vector vIn, int filterId) Filters the input vector to produce an output vector.

Methods inherited from interface org.primordion.xholon.base.IXholon

act, appendChild, appendChild, appendChild, cleanup, configure, configure, createStructure, decVal, decVal, depth, draw, getChildNodes, getFirstChild, getFirstSibling, getId, getLastChild, getLastSibling, getName, getNeighbors, getNextSibling, getNthChild, getNthSibling, getNumChildren, getNumSiblings, getParentNode, getPort, getPreviousSibling, getRoleName, getRootNode, getSiblings, getUid, getVal_boolean, getVal_byte, getVal_char, getVal_double, getVal_float, getVal_int, getVal_long, getVal_Object, getVal_short, getVal_String, getVal, getXhc, getXhcId, getXhcName, getXhType, handleNodeSelection, hasAncestor, hasChildNodes, hasChildOrSiblingNodes, hasNextSibling, hasParentNode, height, incVal, incVal, initialize, initStatics, inOrderPrint, insertAfter, insertBefore, insertFirstChild, isActiveObject, isBound, isContainer, isExternal, isInternal, isLeaf, isPassiveObject, isRootNode, performActivity, performActivity, performBooleanActivity, performBooleanActivity, performDoubleActivity, performGuard, performVoidActivity, postAct, postConfigure, postOrderPrint, postReconfigure, preAct, preConfigure, preOrderPrint, preReconfigure, print, println, processMessageQ, processReceivedMessage, reconfigure, remove, removeChild, sendMessage, sendMessage, sendMessage, setAttributeVal, setFirstChild, setId, setNextSibling, setParentChildLinks, setParentNode, setParentSiblingLinks, setPorts, setRoleName, setUid, setVal, setVal, setVal, setVal, setVal, setVal, setVal, setVal, setVal, setVal, setVariableValue, setXhc, swapNode, terminate, treeSize, writeXml

Field Detail

PENMODE_UP

public static final int PENMODE_UP

See Also:

Constant Field Values

PENMODE_DOWN

public static final int PENMODE_DOWN

See Also:

Constant Field Values

PENMODE_ERASE

public static final int PENMODE_ERASE

See Also:

Constant Field Values

WHENMOVED_INIT

public static final int WHENMOVED_INIT

See Also:

Constant Field Values

COMMANDID_NONE

public static final int COMMANDID_NONE

See Also:

Constant Field Values

FILTERID_NONE

public static final int FILTERID_NONE

See Also:

Constant Field Values

Method Detail

back

public void back(double distance)

Move back a given distance.

Parameters:

distance - A distance measured in units.

bk

public void bk(double distance)

Move back a given distance. This method implements the same functionality as back().

Parameters:

distance - A distance measured in units.

beep

public void beep()

Make a single short beep sound.

canMove

public boolean canMove(double distance)

Can this turtle legally move the specified distance, given its current heading?

Parameters:

distance - A distance measured in units.

Returns:

true or false

die

public void die()

Remove yourself permanently from the gene pool.

distance

public double distance(IXholon turtleOrPatch)

Return the distance between self and the specified turtle or patch.

Parameters:

turtleOrPatch - A turtle or patch object.

Returns:

A distance in units.

distancexy

public double distancexy(double x,
                         double y)

Return the distance between yourself and the specified x, y coordinates.

Parameters:

x - A global x coordinate.

y - A global y coordinate.

Returns:

A distance in units.

downhill

public double downhill()

"Return the turtle heading in the direction of the minimum value of the variable patch-variable, of the patches in a one-patch radius of the turtle."

Returns:

An angle between 0 and 359 degrees.

downhill4

public double downhill4()

"Return the turtle heading in the direction of the minimum value of the variable patch-variable, of the patches in a one-patch radius of the turtle."

Returns:

An angle between 0 and 359 degrees.

dx

public double dx()

Returns the delta in the x direction if the turtle moved one unit along its current heading.

dy

public double dy()

Returns the delta in the y direction if the turtle moved one unit along its current heading.

face

public void face(IXholon turtleOrPatch)

Turn to face the specified turtle or patch.

Parameters:

turtleOrPatch - A turtle or patch object.

facexy

public void facexy(double x,
                   double y)

Turn to face the specified x, y coordinates.

Parameters:

x - A global x coordinate.

y - A global y coordinate.

forward

public void forward(double distance)

Move forward a given distance.

Parameters:

distance - A distance measured in units.

fd

public void fd(double distance)

Move forward a given distance. This method implements the same functionality as forward().

Parameters:

distance - A distance measured in units.

hatch

public void hatch(int numTurtles,
                  int commandId)

Hatch a specified number of new turtles, each identical to this turtle.

Parameters:

numTurtles - The number of new turtles to hatch.

commandId - The ID of a set of turtle commands that can be executed. by calling performActivity(int commandId) on each new turtle.

hideTurtle

public void hideTurtle()

Hide from view.

ht

public void ht()

Hide from view. This method implements the same functionality as hideTurtle().

home

public void home()

Go home, by returning to the home coordinates.

inCone

public java.util.Vector inCone(double distance,
                               double angle)

Return agents that fall within a cone defined by the distance and angle .

Parameters:

distance - A distance measured in units.

angle - An angle measured in degrees.

Returns:

A collection of ITurtle or IPatch instances.

inRadius

public java.util.Vector inRadius(int radius)

Return a list of all neighbors (turtles) within the specified radius. This works for a torus where each cell has 8 neighbors.

Parameters:

radius - Distance from the current patch. The current patch is a radius of 0 from itself.

Returns:

A vector containing zero or more turtles.

inRadius

public java.util.Vector inRadius(int radius,
                                 int filterId)

Return a list of all neighbors (turtles) within the specified radius. This works for a torus where each cell has 8 neighbors.

Parameters:

radius - Distance from the current patch. The current patch is a radius of 0 from itself.

filterId - An ID that can be used by performBooleanActivity() to select a specific filter.

Returns:

A vector containing zero or more gridCells.

jump

public void jump(double distance)

Jump forward a given distance, without effecting any intervening patches or turtles.

Parameters:

distance - A distance measured in units.

jump

public void jump(IPatch aPatch)

Jump directly to the specified patch.

Parameters:

aPatch - A patch.

jump

public void jump(ITurtle aTurtle)

Jump directly to the patch that the specified turtle is currently in.

Parameters:

aTurtle - A turtle.

left

public void left(double angle)

Turn left a given angle.

Parameters:

angle - An angle measured in degrees.

lt

public void lt(double angle)

Turn left a given angle. This method implements the same functionality as left().

Parameters:

angle - A relative angle measured in degrees.

neighbors

public java.util.Vector neighbors()

Return the 8 surrounding neighbor patches.

Returns:

A collection of IPatch instances.

neighbors4

public java.util.Vector neighbors4()

Return the 4 surrounding neighbor patches.

Returns:

A collection of IPatch instances.

otherTurtlesHere

public java.util.Vector otherTurtlesHere()

Return all other turtles that are also currently located at this turtle's patch.

Returns:

A collection of ITurtle instances.

patchAhead

public IPatch patchAhead(double distance)

Return the single patch that is the given distance along the turtle's current heading.

Parameters:

distance - A distance measured in units.

Returns:

An IPatch instance.

patchAt

public IPatch patchAt(int dx,
                      int dy)

Return the single patch at the specified x and y relative distance.

Parameters:

dx - A relative distance in the x direction, in patches.

dy - A relative distance in the y direction, in patches.

Returns:

A patch, or null.

patchAtHeadingAndDistance

public IPatch patchAtHeadingAndDistance(double heading,
                                        double distance)

Return the single patch at the specified absolute heading and relative distance.

Parameters:

heading - An absolute angle measured in degrees.

distance - A distance measured in units.

Returns:

A patch, or null.

patchHere

public IPatch patchHere()

Return the patch that the turtle is currently on.

Returns:

A patch.

patchLeftAndAhead

public IPatch patchLeftAndAhead(double distance,
                                double angle)

Return the single patch that is the given distance from the turtle, in the direction turned left the given angle from the turtle's current heading.

Parameters:

distance - A distance measured in units.

angle - An angle measured in degrees.

Returns:

A patch, or null.

patchRightAndAhead

public IPatch patchRightAndAhead(double distance,
                                 double angle)

Return the single patch that is the given distance from the turtle, in the direction turned right the given angle from the turtle's current heading.

Parameters:

distance - A distance measured in units.

angle - An angle measured in degrees.

Returns:

A patch, or null.

penDown

public void penDown()

Set the pen down, so it is able to draw.

pd

public void pd()

Set the pen down, so it is able to draw. This method implements the same functionality as penDown().

penErase

public void penErase()

Set the pen to erase.

pe

public void pe()

Set the pen to erase. This method implements the same functionality as penErase().

penUp

public void penUp()

Set the pen up, so it is unable to draw.

pu

public void pu()

Set the pen up, so it is unable to draw. This method implements the same functionality as penUp().

right

public void right(double angle)

Turn right a given angle.

Parameters:

angle - An angle measured in degrees.

rt

public void rt(double angle)

Turn right a given angle. This method implements the same functionality as right().

Parameters:

angle - A relative angle measured in degrees.

setxy

public void setxy(double x,
                  double y)

Set the turtle's x and y coordinates, and move to that location.

Parameters:

x - New value for the turtle's x coordinate.

y - New value for the turtle's y coordinate.

showTurtle

public void showTurtle()

Show in the viewer.

st

public void st()

Show in the viewer. This method implements the same functionality as showTurtle().

stamp

public void stamp()

Leave an inprint or stamp of self at the current patch.

stampErase

public void stampErase()

Erase any inprint or stamp at the current patch.

towards

public double towards(IXholon turtleOrPatch)

Return the heading between self and the specified turtle or patch.

Parameters:

turtleOrPatch - A turtle or patch object.

Returns:

A A heading angle in degrees.

towardsxy

public double towardsxy(double x,
                        double y)

Return the heading between self and the specified x, y coordinates.

Parameters:

x - A global x coordinate.

y - A global y coordinate.

Returns:

A heading angle in degrees.

turtlesAt

public java.util.Vector turtlesAt(int dx,
                                  int dy)

Return the turtles located at the single patch at the specified x and y relative distance.

Parameters:

dx - A relative distance in the x direction, in patches.

dy - A relative distance in the y direction, in patches.

Returns:

A collection of ITurtle instances.

turtlesHere

public java.util.Vector turtlesHere()

Return the turtles located at the current patch.

Returns:

A collection of ITurtle instances.

turtlesOn

public java.util.Vector turtlesOn()

Return the turtles that are on the given patch or patches, or standing on the same patch as the given turtle or turtles.

Returns:

A collection of ITurtle instances.

uphill

public double uphill()

"Return the turtle heading in the direction of the maximum value of the variable patch-variable, of the patches in a one-patch radius of the turtle."

Returns:

An angle between 0 and 359 degrees.

uphill4

public double uphill4()

"Return the turtle heading in the direction of the maximum value of the variable patch-variable, of the patches in a one-patch radius of the turtle."

Returns:

An angle between 0 and 359 degrees.

with

public java.util.Vector with(java.util.Vector vIn,
                             int filterId)

Filters the input vector to produce an output vector.

Parameters:

vIn - A collection of ITurtle instances.

Returns:

A filtered collection of ITurtle instances.

getBreed

public int getBreed()

Get the turtle's breed id.

setBreed

public void setBreed(int breed)

Set or change the turtle's breed id. Warning: Use caution when changing the breed.

Parameters:

breed - A breed id.

getColor

public int getColor()

Get the turtle's color.

Returns:

A color value, as defined in ITurtlePatchColor.

setColor

public void setColor(int color)

Set the turtle's color. NetLogo: set color value

Parameters:

color - A color value, as defined in ITurtlePatchColor.

getHeading

public double getHeading()

Get the turtle's heading.

Returns:

An absolute angle measured in degrees.

setHeading

public void setHeading(double heading)

Set the turtle's heading. NetLogo: set heading value

Parameters:

heading - An absolute angle measured in degrees.

getIsHidden

public boolean getIsHidden()

Get the turtle's hide status. Is it hidden or visible?

Returns:

true or false

setIsHidden

public void setIsHidden(boolean isHidden)

Set the turtle's hide status.

Parameters:

isHidden - hidden (true) or visible (false)

getLabel

public java.lang.String getLabel()

Get the turtle's label, a String that helps to identify it.

Returns:

A label.

setLabel

public void setLabel(java.lang.String label)

Set or change the turtle's label. Warning: Use caution when changing the label.

Parameters:

label -

getPenMode

public int getPenMode()

Get the turtle's pen mode.

Returns:

A pen mode, one of PENMODE_UP, PENMODE_DOWN, or PENMODE_ERASE.

setPenMode

public void setPenMode(int penMode)

Set the turtle's pen mode.

Parameters:

penMode - A pen mode, one of PENMODE_UP, PENMODE_DOWN, or PENMODE_ERASE.

getWho

public int getWho()

Get the turtle's who id.

Returns:

A who id.

setWho

public void setWho(int who)

Set the turtle's who id. Warning: Use caution when changing the who id.

Parameters:

who - A who id.

getXcor

public double getXcor()

Get the turtle's x coordinate.

Returns:

The xcor value.

setXcor

public void setXcor(double xcor)

Set the turtle's x coordinate.

Parameters:

xcor - An xcor value.

getYcor

public double getYcor()

Get the turtle's y coordinate.

Returns:

The ycor value.

setYcor

public void setYcor(double ycor)

Set the turtle's y coordinate.

Parameters:

ycor - An ycor value.

getPcolor

public int getPcolor()

Get the patch's pcolor.

Returns:

A pcolor value, as defined in ITurtlePatchColor.

setPcolor

public void setPcolor(int pcolor)

Set the patch's pcolor. NetLogo: set pcolor value

Parameters:

pcolor - A pcolor value, as defined in ITurtlePatchColor.

getPlabel

public java.lang.String getPlabel()

Get the patch's label, a String that helps to identify it.

Returns:

A label.

setPlabel

public void setPlabel(java.lang.String plabel)

Set or change the patch's label. Warning: Use caution when changing the label.

getPxcor

public int getPxcor()

Get the patch's x coordinate.

Returns:

The pxcor value.

setPxcor

public void setPxcor(int pxcor)

Set the patch's x coordinate.

getPycor

public int getPycor()

Get the patch's y coordinate.

Returns:

The pycor value.

setPycor

public void setPycor(int pycor)

Set the patch's y coordinate.

getMaxPxcor

public int getMaxPxcor()

Return the maximum Patch x coordinate.

Returns:

A Patch coordinate.

getMaxPycor

public int getMaxPycor()

Return the maximum Patch y coordinate.

Returns:

A Patch coordinate.

getMinPxcor

public int getMinPxcor()

Return the minimum Patch x coordinate.

Returns:

A Patch coordinate.

getMinPycor

public int getMinPycor()

Return the minimum Patch y coordinate.

Returns:

A Patch coordinate.

getWorldWidth

public int getWorldWidth()

Return the width of the world (the grid width).

Returns:

The width in Patch units.

getWorldHeight

public int getWorldHeight()

Return the height of the world (the grid height).

Returns:

The height in Patch units.

hasAlreadyMoved

public boolean hasAlreadyMoved()

Has this turtle already moved this time step? This method is required to prevent turtles from moving multiple times in the same time step, which would happen when a turtle moves to a patch that hasn't yet been reached in the tree traversal this time step. It would perform its action, move to a new patch postion, and subsequently be re-executed as a child of the second patch.

initWhenMoved

public void initWhenMoved(int when)

Initialize the whenMoved variable. This is intended for internal use only.

Parameters:

when - A time step, normally WHENMOVED_INIT (-1).

aggregate

public void aggregate(double amount)

Aggregate by keeping a count of the number of individuals of a given "breed".

Parameters:

amount - The amount to increment or decrement the current population count. The amount can be a positive (increment) or negative (decrement) number.