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.