## org.ascape.model
Class CellOccupant

    java.lang.Object
      org.ascape.model.AscapeObject
          org.ascape.model.Agent
              org.ascape.model.LocatedAgent
                  org.ascape.model.Cell
                      org.ascape.model.CellOccupant

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

Direct Known Subclasses:
  BasicMovementAgent, BasicMovementStateAgent, Bug, Bug, Bug, Bug, ComplexMovementAgent, Firm, Flea, HeatBug, Individual, Individual, Individual, Individual, Individual, Instrument, MethodsAgent, OperationsAgent, Player, Rat, Scape, StateAgent, SugarAgent, Trader

    public class CellOccupant

extends Cell

An occupant of a cell within a lattice.

Since:
  1.0
Version:
  3.0, 1.9.2 fixed a bug in moveToward and moveAway
Author:
  Miles Parker
See Also:
  Serialized Form

Field Summary
`static Rule` `PLAY_HOST_RULE` An rule causing the target agent to interact with each of its neighbors as specified by the Agent.play() method.
`static Rule` `RANDOM_WALK_AVAILABLE_RULE` A rule causing the taget agent to take a random walk.

Fields inherited from class org.ascape.model.Cell
`CALCULATE_NEIGHBORS_RULE, neighbors, PLAY_NEIGHBORS_RULE, PLAY_RANDOM_NEIGHBOR_RULE`

Fields inherited from class org.ascape.model.LocatedAgent
`agentSize, coordinate, MOVE_RANDOM_LOCATION_RULE, RANDOM_WALK_RULE, thisUpdate`

Fields inherited from class org.ascape.model.Agent
`DEATH_RULE, FISSIONING_RULE, FORCE_DIE_RULE, FORCE_FISSION_RULE, FORCE_MOVE_RULE, INITIALIZE_RULE, ITERATE_AND_UPDATE_RULE, ITERATE_RULE, METABOLISM_RULE, MOVEMENT_RULE, PLAY_OTHER, UPDATE_RULE`

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

Constructor Summary
`CellOccupant()`

Method Summary
`java.lang.Object` `clone()` Clone this occupant, making host cell and coordinate null, since for a base cell occupant it is illegal for more than one cell to occupy the same location.
`void` `die()` Removes the agent from play, causing it to vacate its host cell.
`java.util.List` `findAvailableNeighbors()` Returns unoccupied cells neighboring this cell's location on the host cell's lattice.
`LocatedAgent` `findNearest()` Returns the closest agent.
`LocatedAgent` `findNearest(Conditional condition)` Returns the closest agent within the specified distance from this agent that meet some condition.
`LocatedAgent` `findNearest(Conditional condition, boolean includeSelf, double distance)` Returns the closest agent within the specified distance from this agent that meet some condition.
`LocatedAgent` `findNearest(Conditional condition, double distance)` Returns the closest agent within the specified distance from this agent that meet some condition.
`LocatedAgent` `findNearest(double distance)` Returns the closest agent within the specified distance from this agent that meet some condition.
`java.util.List` `findNeighbors()` Returns this cells neighbors, that is, the set of cells adjoining this cell as defined by the scape's geometry.
`java.util.List` `findNeighborsOnHost()` Overides the getNeighbors method to return the cell's occupants neighboring this cell's location on its host cell's lattice.
`Node` `findRandomAvailableNeighbor()` Find random neighbor.
`Node` `findRandomNeighbor()` Returns a cell randomly selected from among this cell's neighbors.
`Cell` `findRandomNeighborOnHost()` Returns a random neighbor on host, if any exist neighboring this cell's location on its host cell's lattice.
`java.util.List` `findWithin(Conditional condition, boolean includeSelf, double distance)` Returns all agents within the specified distance of the agent on the host scape.
`java.util.List` `findWithin(Conditional condition, double distance)` Returns all agents within the specified distance of the agent on the host scape.
`java.util.List` `findWithin(double distance)` Returns all agents within the specified distance of the agent on the host scape.
`Coordinate` `getCoordinate()` Gets a coordinate the location of this cell within the relevant Host Scape.
`HostCell` `getHostCell()` Returns the cell that this cell occupies in the host cell's lattice.
`Scape` `getHostScape()` Returns the lattice that hosts this cell.
`void` `leave()` Removes this cell from the current host cell.
`void` `moveAway(LocatedAgent targetCell)` Move one step away from the occupant of the supplied host cell.
`void` `moveTo(HostCell hostCell)` Assigns this cell as the occupant of the supplied host cell.
`void` `moveToRandomLocation()` Moves this cell to a random unoccupied location on the host scape.
`void` `moveToward(LocatedAgent targetCell)` Move one step toward the occupant of the supplied host cell.
`void` `playNeighbors()` Interact with each neighbor as specified by the Agent.play() method.
`void` `playRandomNeighbor()` Interact with each neighbor as specified by the Agent.play() method.
`void` `randomWalk()` Picks a random neighboring location on the host cell's lattice.
`void` `randomWalkAvailable()` Picks a random available neighboring location on the host cell's lattice.
`void` `setHostCell(HostCell hostCell)` Sets the cell that this cell occupies in the host cell's lattice.
`void` `setHostScape(Scape hostScape)` Sets the lattice that hosts this cell.

Methods inherited from class org.ascape.model.Cell
`calculateNeighbors, countNeighbors, findOccupants, findRelative, getDistance, getNeighbors, getNeighbors, getNetwork, getOccupant, hostedCondition, initialize, isAvailable, removeOccupant, setNeighbors, setNeighborsList, setNetwork, setOccupant, toString`

Methods inherited from class org.ascape.model.LocatedAgent
`calculateDistance, calculateDistance, countWithin, countWithin, countWithin, findMaximumWithin, findWithin, getAgentSize, hasWithin, hasWithin, hasWithin, isUpdateNeeded, moveAway, moveAway, moveTo, moveToward, moveToward, requestUpdate, requestUpdateNext, setAgentSize, setCoordinate`

Methods inherited from class org.ascape.model.Agent
`clearDeleteMarker, death, deathCondition, execute, execute, fission, fissionCondition, fissioning, getColor, getColor, getImage, getImage, getIteration, getPlatformColor, getRoot, isDelete, isInitialized, iterate, markForDeletion, metabolism, move, movement, movementCondition, play, scapeCreated, setInitialized, setScape, update`

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`

Methods inherited from interface org.ascape.model.space.Location
`clearDeleteMarker, isDelete, markForDeletion, setCoordinate`

Field Detail

### PLAY_HOST_RULE

    public static final Rule PLAY_HOST_RULE

  An rule causing the target agent to interact with each of its neighbors as specified by the Agent.play() method.

### RANDOM_WALK_AVAILABLE_RULE

    public static final Rule RANDOM_WALK_AVAILABLE_RULE

  A rule causing the taget agent to take a random walk. The agent takes a step in a random direction out of any open directions, that is, into a random unoccupied neighboring cell. If no neighboring cells are unoccupied, nothing happens. Note the difference between this rule and RANDOM_WALK_RULE.

Constructor Detail

### CellOccupant

    public CellOccupant()

Method Detail

### leave

    public void leave()

  Removes this cell from the current host cell.

### moveTo

    public void moveTo(HostCell hostCell)

  Assigns this cell as the occupant of the supplied host cell.

  Parameters:
    `hostCell` - the host to assign this cell to

### moveToward

    public void moveToward(LocatedAgent targetCell)

  Move one step toward the occupant of the supplied host cell. Assumes Moore like space for now. i.e. allow diagonal moves. Warning: temporary, only works for cells on 2D lattices now.

  Overrides:
    `moveToward` in class `LocatedAgent`
  Parameters:
    `targetCell` - the host to move towards

### moveAway

    public void moveAway(LocatedAgent targetCell)

  Move one step away from the occupant of the supplied host cell. Warning: temporary, only works for cells on 2D lattices now.

  Overrides:
    `moveAway` in class `LocatedAgent`
  Parameters:
    `targetCell` - the host to move towards

### getCoordinate

    public Coordinate getCoordinate()

  Gets a coordinate the location of this cell within the relevant Host Scape.

  Specified by:
    `getCoordinate` in interface `Location`
  Overrides:
    `getCoordinate` in class `LocatedAgent`
  Returns:
    the coordinate

### moveToRandomLocation

    public void moveToRandomLocation()

  Moves this cell to a random unoccupied location on the host scape.

  Overrides:
    `moveToRandomLocation` in class `LocatedAgent`

### die

    public void die()

  Removes the agent from play, causing it to vacate its host cell.

  Overrides:
    `die` in class `Agent`

### getHostCell

    public HostCell getHostCell()

  Returns the cell that this cell occupies in the host cell's lattice.

### setHostCell

    public void setHostCell(HostCell hostCell)

  Sets the cell that this cell occupies in the host cell's lattice. JMiller 7/24/01

### getHostScape

    public Scape getHostScape()

  Returns the lattice that hosts this cell.

### setHostScape

    public void setHostScape(Scape hostScape)

  Sets the lattice that hosts this cell.

### findRandomNeighborOnHost

    public Cell findRandomNeighborOnHost()

  Returns a random neighbor on host, if any exist neighboring this cell's location on its host cell's lattice.

### findRandomAvailableNeighbor

    public Node findRandomAvailableNeighbor()

  Description copied from interface: `Node`
  Find random neighbor.

  Specified by:
    `findRandomAvailableNeighbor` in interface `Node`
  Overrides:
    `findRandomAvailableNeighbor` in class `Cell`
  Returns:
    the node

### findRandomNeighbor

    public Node findRandomNeighbor()

  Description copied from class: `Cell`
  Returns a cell randomly selected from among this cell's neighbors.

  Specified by:
    `findRandomNeighbor` in interface `Node`
  Overrides:
    `findRandomNeighbor` in class `Cell`
  Returns:
    the node

### findNeighbors

    public java.util.List findNeighbors()

  Description copied from class: `Cell`
  Returns this cells neighbors, that is, the set of cells adjoining this cell as defined by the scape's geometry. Note: returned as unmodifieable list for perforamnce reasons. If you need to modify this list, make a copy.

  Specified by:
    `findNeighbors` in interface `Node`
  Overrides:
    `findNeighbors` in class `Cell`
  Returns:
    the list

### findNeighborsOnHost

    public java.util.List findNeighborsOnHost()

  Overides the getNeighbors method to return the cell's occupants neighboring this cell's location on its host cell's lattice.

### findWithin

    public java.util.List findWithin(Conditional condition,
                                     double distance)

  Returns all agents within the specified distance of the agent on the host scape.

  Overrides:
    `findWithin` in class `LocatedAgent`
  Parameters:
    `condition` - the condition that found agent must meet
    `distance` - the distance agents must be within to be included

### findWithin

    public java.util.List findWithin(double distance)

  Returns all agents within the specified distance of the agent on the host scape.

  Overrides:
    `findWithin` in class `LocatedAgent`
  Parameters:
    `distance` - the distance agents must be within to be included

### findWithin

    public java.util.List findWithin(Conditional condition,
                                     boolean includeSelf,
                                     double distance)

  Returns all agents within the specified distance of the agent on the host scape.

  Overrides:
    `findWithin` in class `LocatedAgent`
  Parameters:
    `condition` - the condition that found agent must meet
    `includeSelf` - whether or not the starting agent should be included in the search
    `distance` - the distance agents must be within to be included

### findNearest

    public LocatedAgent findNearest()

  Returns the closest agent.

  Overrides:
    `findNearest` in class `LocatedAgent`

### findNearest

    public LocatedAgent findNearest(double distance)

  Returns the closest agent within the specified distance from this agent that meet some condition.

  Overrides:
    `findNearest` in class `LocatedAgent`
  Parameters:
    `distance` - the distance agents must be within to be included

### findNearest

    public LocatedAgent findNearest(Conditional condition)

  Returns the closest agent within the specified distance from this agent that meet some condition.

  Overrides:
    `findNearest` in class `LocatedAgent`
  Parameters:
    `condition` - the condition the agent must meet to be included

### findNearest

    public LocatedAgent findNearest(Conditional condition,
                                    double distance)

  Returns the closest agent within the specified distance from this agent that meet some condition.

  Overrides:
    `findNearest` in class `LocatedAgent`
  Parameters:
    `condition` - the condition the agent must meet to be included
    `distance` - the distance agents must be within to be included

### findNearest

    public LocatedAgent findNearest(Conditional condition,
                                    boolean includeSelf,
                                    double distance)

  Returns the closest agent within the specified distance from this agent that meet some condition.

  Overrides:
    `findNearest` in class `LocatedAgent`
  Parameters:
    `condition` - the condition the agent must meet to be included
    `includeSelf` - if the calling agent should be included in the search
    `distance` - the distance agents must be within to be included

### findAvailableNeighbors

    public java.util.List findAvailableNeighbors()

  Returns unoccupied cells neighboring this cell's location on the host cell's lattice.

### playRandomNeighbor

    public void playRandomNeighbor()

  Interact with each neighbor as specified by the Agent.play() method.

  Overrides:
    `playRandomNeighbor` in class `Cell`

### playNeighbors

    public void playNeighbors()

  Interact with each neighbor as specified by the Agent.play() method.

  Overrides:
    `playNeighbors` in class `Cell`

### randomWalk

    public void randomWalk()

  Picks a random neighboring location on the host cell's lattice. If that location is unoccupied, moves this agent to it. Note the distinction between this method and `randomWalkAvailable`. In this case, a random neighboring cell is slected. If, and only if, that cell is unoccupied, does the agent move to it. This means, for instance, that a neighboring cell might be available but the cell occupant migh select an occupied cell and thus not move.

  Overrides:
    `randomWalk` in class `LocatedAgent`
  See Also:
    `this.randomWalkAvailable()`

### randomWalkAvailable

    public void randomWalkAvailable()

  Picks a random available neighboring location on the host cell's lattice. If no locations are available, stays put. Note the distinction between this method and `randomWalk`. In this case, all available neigbors are first found, and then one of those cells is randomly selected and moved to. This means that if there is even one unoccpied cell available, the cell occupant will move to it.

  See Also:
    `this.randomWalk`

### clone

    public java.lang.Object clone()

  Clone this occupant, making host cell and coordinate null, since for a base cell occupant it is illegal for more than one cell to occupy the same location.

  Specified by:
    `clone` in interface `Location`
  Overrides:
    `clone` in class `Cell`
  Returns:
    the object