edu.brook.ascape.model
Class ScapeGraph

java.lang.Object
  |
  +--edu.brook.ascape.model.AscapeObject
        |
        +--edu.brook.ascape.model.Agent
              |
              +--edu.brook.ascape.model.Cell
                    |
                    +--edu.brook.ascape.model.CellOccupant
                          |
                          +--edu.brook.ascape.model.Scape
                                |
                                +--edu.brook.ascape.model.ScapeGraph

Direct Known Subclasses:

ScapeArray1D, ScapeArray2D, ScapeVector

public abstract class ScapeGraph

extends Scape

A scape with discrete nodes.

Since:

1.0.1

Version:

1.5

See Also:

Serialized Form

Field Summary

protected CoordinateDiscrete

extent The extent (furthest valid point) of the graph.

Fields inherited from class edu.brook.ascape.model.Scape

AGENT_ORDER, agentsPerIteration, ALL_AGENTS, autoCreate, cellsRequestUpdates, COLLECT_STATS_RULE, collectStats, COMPLETE_TOUR, copyrightAndCredits, CREATE_RULE, CREATE_SCAPE_RULE, dataGroup, demoModelClasses, demoModelNames, description, drawFeatureObservable, drawFeatures, earliestPeriod, executionOrder, executionStyle, geometry, home, INITIAL_RULES_RULE, initialRules, INTERNAL_START_RULE, ITERATE_SCAPE_RULE, iteration, latestPeriod, membersActive, PAUSE_RULE, paused, period, periodName, prototypeAgent, REPEATED_DRAW, restartAfterAutoStop, RESUME_RULE, RULE_ORDER, rules, running, scapeListeners, selfView, standardOutView, START_RULE, startOnOpen, startPeriod, step, STOP_RULE, stopPeriod, updatedListeners, updatedMembers, version

Fields inherited from class edu.brook.ascape.model.CellOccupant

MOVE_RANDOM_LOCATION_RULE, PLAY_HOST_RULE, PLAY_NEIGHBORS_RULE, PLAY_OTHER, RANDOM_WALK_AVAILABLE_RULE, RANDOM_WALK_RULE

Fields inherited from class edu.brook.ascape.model.Cell

cellsNear, coordinate, neighbors, thisUpdate

Fields inherited from class edu.brook.ascape.model.Agent

DEATH_RULE, deleteMarker, FISSIONING_RULE, FORCE_DIE_RULE, FORCE_FISSION_RULE, FORCE_MOVE_RULE, INITIALIZE_RULE, initialized, ITERATE_AND_UPDATE_RULE, ITERATE_RULE, METABOLISM_RULE, MOVEMENT_RULE, UPDATE_RULE

Fields inherited from class edu.brook.ascape.model.AscapeObject

ARBITRARY_SEED, count, name, scape

Constructor Summary

ScapeGraph()
Constructs a graph.

ScapeGraph(Cell prototypeAgent)

ScapeGraph(Geometry geometry, Cell prototypeAgent)

ScapeGraph(java.lang.String name, Geometry geometry, Cell prototypeAgent, CoordinateDiscrete extent)
Constructs a graph of provided extent, to be populated with clones of provided agent.

Method Summary

abstract int	countWithin(Cell origin, Conditional condition, boolean includeOrigin, double maximumDistance) Returns the number of cells within the supplied distance that meet the supplied condition.
void	executeOnMembers(java.lang.Object[] rules) Executes the provided rules on every member of the graph, according to the rule settings and the execution order of the scape.
HostCell[]	findAvailable() Returns cells that are available, that is, uncoccupied.
HostCell[]	findAvailable(Cell[] candidates) Returns cells that are available, that is, uncoccupied.
Cell[]	findCells(Conditional condition) Finds cells that meet some condition.
Cell[]	findCells(Conditional condition, Cell[] candidates) Finds cells that meet some condition.
static Cell	findMaximumCell(DataPoint point, Cell[] candidates) Finds the cell that has the highest value for some data point.
Cell	findMaximumWithin(Cell origin, DataPoint point, int distance, boolean includeOrigin)
abstract Cell	findNearestCell(Cell origin, Conditional condition) Finds the nearest cell that meets some condition.
abstract Cell	findNearestCell(Cell origin, Conditional condition, boolean includeOrigin) Finds the nearest cell that meets some condition.
abstract Cell	findNearestCell(Cell origin, Conditional condition, boolean includeOrigin, double maximumDistance) Finds the nearest cell that meets some condition.
CellOccupant[]	findOccupants() Returns cells that are available, that is, uncoccupied.
CellOccupant[]	findOccupants(Cell[] candidates) Returns all cell occupants of the provided cells.
abstract Cell	findRandomCell() Returns a cell randomly selected from the lattice.
Cell	findRandomCell(Cell excludeCell) Returns a random unoccupied discrete location in the space given with the lattice.
Cell[]	findRandomCells(Cell excludeCell, int num) Returns a group of unique cells randomly selected from the lattice.
Cell[]	findRandomCells(int num) Returns a group of unique cells randomly selected from the lattice.
abstract CoordinateDiscrete	findRandomCoordinate() Returns a random location in the space defined by the graph.
Cell	findRandomUnoccupiedCell() Returns a random unoccupied discrete location in the space.
Cell	findRandomUnoccupiedCell(Cell excludeCell) Returns a random unoccupied discrete location in the space.
abstract Cell	getCell(CoordinateDiscrete coordinate) Returns the cell existing at the specified coordinate.
abstract Cell[]	getCells() Returns all cells in the scape as an array.
abstract Cell[]	getCellsNear(Cell origin, int distance, boolean includeOrigin) Returns cells that are near the provided cell.
abstract int	getDistance(Cell origin, Cell target)
CoordinateDiscrete	getExtent() Returns the size of dimensions for this scape.
int	getSize() Returns the size, or number of cells, (the product of all extents) of this graph.
abstract boolean	hasWithin(Cell origin, Conditional condition, boolean includeOrigin, double maximumDistance) Returns true of there is a cell within the supplied distance that meets the supplied condition.
abstract void	setCell(CoordinateDiscrete coordinate, Cell cell) Returns the cell existing at the specified coordinate.
void	setExtent(CoordinateDiscrete extent) Sets the size of the scape.

Methods inherited from class edu.brook.ascape.model.Scape

addDrawFeature, addInitialRule, addInitialRule, addRule, addRule, addScapeListener, addStatCollector, addStatCollectors, addView, addView, addView, addViews, addViews, addViews, clone, close, closeAndOpenNew, closeAndOpenNewFinally, closeFinally, contentsToString, createOrder, createScape, createSelfView, createViews, execute, execute, executeOnMembers, executeOnMembers, executeOnMembers, executeOnRoot, executeOnRoot, exit, getAgents, getAgentsNear, getAgentsPerIteration, getAllScapes, getCollectStats, getCustomizer, getData, getDescription, getDrawFeatures, getDrawFeaturesObservable, getExecutionOrder, getExecutionStyle, getGeometry, getHome, getInitialRules, getIteration, getName, getPeriod, getPeriodDescription, getPeriodName, getPrototypeAgent, getRoot, getRules, getStandardOutView, getStartPeriod, getStatCollectors, getStopPeriod, initialize, isAllViewsUpdated, isAutoCreate, isCellsRequestUpdates, isMembersActive, isMutable, isPaused, isRoot, isRunning, isStartOnOpen, isValidPeriod, isViewSelf, iterateScape, iterator, listenerOrMemberUpdated, listenerUpdated, main, memberUpdated, notifyViews, onSetup, onStart, onStop, onUpdate, open, open, open, open, open, parseSettingArgs, pause, quit, quitFinally, randomIterator, randomizeOrder, removeScapeListener, requestRestart, respondControl, restart, resume, retrieveAllAccessors, retrieveAllAccessorsOrdered, run, save, save, save, setAgentsPerIteration, setAutoCreate, setAutoRestart, setCellsRequestUpdates, setCollectStats, setCollectStats, setCustomizer, setDescription, setEarliestPeriod, setExecutionOrder, setExecutionStyle, setGeometry, setHome, setInternalPaused, setInternalRunning, setLatestPeriod, setMembersActive, setPaused, setPeriodName, setPrototypeAgent, setRunning, setStartOnOpen, setStartPeriod, setStopPeriod, setViewSelf, start, stop, toString, waitForViewsUpdate

Methods inherited from class edu.brook.ascape.model.CellOccupant

die, getAvailableNeighboringCells, getCellsNearOnHost, getHostCell, getHostScape, getNeighborsOnHost, leave, moveAway, moveTo, moveToRandomLocation, moveToward, randomWalk, randomWalkAvailable, setHostScape

Methods inherited from class edu.brook.ascape.model.Cell

countNeighbors, countWithin, findMaximumWithin, findNearestCell, findNearestCell, findNearestCell, findRandomNeighbor, getCellsNear, getCoordinate, getDistance, getNeighbors, getNeighbors, getNetwork, getOccupant, hasWithin, isAvailable, isUpdateNeeded, removeOccupant, requestUpdate, requestUpdateNext, setCoordinate, setNeighbors, setNetwork, setOccupant

Methods inherited from class edu.brook.ascape.model.Agent

death, deathCondition, execute, execute, fission, fissionCondition, fissioning, getColor, getColor, getImage, getImage, getModel, isDelete, isInitialized, iterate, markForDeletion, metabolism, move, movement, movementCondition, play, scapeCreated, update

Methods inherited from class edu.brook.ascape.model.AscapeObject

getRandom, getRandomSeed, getScape, randomInRange, randomInRange, randomIs, randomToLimit, reseed, setName, setRandom, setRandomSeed, setScape

Methods inherited from class java.lang.Object

equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait

Field Detail

extent

protected CoordinateDiscrete extent

The extent (furthest valid point) of the graph. This parameter will make sense for some graphs, but not for others.

Constructor Detail

ScapeGraph

public ScapeGraph()

Constructs a graph.

ScapeGraph

public ScapeGraph(java.lang.String name,
                  Geometry geometry,
                  Cell prototypeAgent,
                  CoordinateDiscrete extent)

Constructs a graph of provided extent, to be populated with clones of provided agent.

Parameters:

name - a descriptive name for the scape

geometry - the strucutre of the graph

prototypeAgent - the agent whose clones will be used to populate this scape

extent - a coordinate describing the size of this scape

ScapeGraph

public ScapeGraph(Geometry geometry,
                  Cell prototypeAgent)

Parameters:

geometry -

prototypeAgent -

ScapeGraph

public ScapeGraph(Cell prototypeAgent)

Parameters:

prototypeAgent -

Method Detail

getExtent

public CoordinateDiscrete getExtent()

Returns the size of dimensions for this scape.

setExtent

public void setExtent(CoordinateDiscrete extent)

Sets the size of the scape. The extent defines the limit of the lattice (exclusive) from the origin (inclusive), so that the extent also represents the size of the lattice. It is an error to set extent while a scape is running.

Parameters:

extent - a coordinate at the maximum extent

getSize

public int getSize()

Returns the size, or number of cells, (the product of all extents) of this graph.

Overrides:

getSize in class Scape

executeOnMembers

public void executeOnMembers(java.lang.Object[] rules)

Executes the provided rules on every member of the graph, according to the rule settings and the execution order of the scape.

Overrides:

executeOnMembers in class Scape

findOccupants

public CellOccupant[] findOccupants()

Returns cells that are available, that is, uncoccupied.

findOccupants

public CellOccupant[] findOccupants(Cell[] candidates)

Returns all cell occupants of the provided cells.

Parameters:

candidates - the cells to return occupants of

findAvailable

public HostCell[] findAvailable()

Returns cells that are available, that is, uncoccupied.

findAvailable

public HostCell[] findAvailable(Cell[] candidates)

Returns cells that are available, that is, uncoccupied.

Parameters:

candidates - the cells to return available cells from

getCells

public abstract Cell[] getCells()

Returns all cells in the scape as an array.

getCell

public abstract Cell getCell(CoordinateDiscrete coordinate)

Returns the cell existing at the specified coordinate. (Will be made non-abstract to support n-dimensional ScapeGraphs.)

setCell

public abstract void setCell(CoordinateDiscrete coordinate,
                             Cell cell)

Returns the cell existing at the specified coordinate.

findRandomCell

public abstract Cell findRandomCell()

Returns a cell randomly selected from the lattice.

findRandomCell

public Cell findRandomCell(Cell excludeCell)

Returns a random unoccupied discrete location in the space given with the lattice.

Parameters:

excludeCell - a cell to exclude from get (typically origin)

findRandomCells

public Cell[] findRandomCells(Cell excludeCell,
                              int num)

Returns a group of unique cells randomly selected from the lattice.

findRandomCells

public Cell[] findRandomCells(int num)

Returns a group of unique cells randomly selected from the lattice.

findRandomUnoccupiedCell

public Cell findRandomUnoccupiedCell()

Returns a random unoccupied discrete location in the space. Returns null if no random locations are available, but an unoccupied location, even if only one exists. This method first tries testing random locations within the grid, and the first n (10) are found to be unnoccupied, the number of random locations is assumed to be sparse, and a search of all random locations is done.

findRandomUnoccupiedCell

public Cell findRandomUnoccupiedCell(Cell excludeCell)

Returns a random unoccupied discrete location in the space. Returns null if no random locations are available, but an unoccupied location, even if only one exists. This method first tries testing random locations within the grid, and the first n (10) are found to be unnoccupied, the number of random locations is assumed to be sparse, and a search of all random locations is done.

findCells

public Cell[] findCells(Conditional condition)

Finds cells that meet some condition. Can be expensive is the population is large.

Parameters:

condition - the condition that found cell must meet

findCells

public Cell[] findCells(Conditional condition,
                        Cell[] candidates)

Finds cells that meet some condition. Can be expensive is the population is large.

Parameters:

condition - the condition that found cell must meet

findMaximumCell

public static Cell findMaximumCell(DataPoint point,
                                   Cell[] candidates)

Finds the cell that has the highest value for some data point. If multiple cells have the highest values, returns random cell from said cells. Can be expensive is the population is large. Passing an empty candidate array will is an error and will result in an ArrayIndexOutOfBounds exception.

Parameters:

point - the data point for the maximum value to look for

candidates - the cells to look for maximum values within

findMaximumWithin

public Cell findMaximumWithin(Cell origin,
                              DataPoint point,
                              int distance,
                              boolean includeOrigin)

getCellsNear

public abstract Cell[] getCellsNear(Cell origin,
                                    int distance,
                                    boolean includeOrigin)

Returns cells that are near the provided cell.

Parameters:

origin - the agent to find cells near

distance - the distance to form centralCells to return cells

includeOrigin - should supplied agent be included in the return set

findNearestCell

public abstract Cell findNearestCell(Cell origin,
                                     Conditional condition)

Finds the nearest cell that meets some condition.

Parameters:

origin - the agent to find cells near

condition - the condition that found cell must meet

findNearestCell

public abstract Cell findNearestCell(Cell origin,
                                     Conditional condition,
                                     boolean includeOrigin)

Finds the nearest cell that meets some condition.

Parameters:

origin - the agent to find cells near

condition - the condition that found cell must meet

includeOrigin - should supplied agent be included in the search

findNearestCell

public abstract Cell findNearestCell(Cell origin,
                                     Conditional condition,
                                     boolean includeOrigin,
                                     double maximumDistance)

Finds the nearest cell that meets some condition.

Parameters:

origin - the agent to find cells near

condition - the condition that found cell must meet

includeOrigin - should supplied agent be included in the search

maximumDistance - the maximum distance to search within

hasWithin

public abstract boolean hasWithin(Cell origin,
                                  Conditional condition,
                                  boolean includeOrigin,
                                  double maximumDistance)

Returns true of there is a cell within the supplied distance that meets the supplied condition.

Parameters:

origin - the agent to find cells near

condition - the condition that found cell must meet

includeOrigin - should supplied agent be included in the search

maximumDistance - the distance to search within

countWithin

public abstract int countWithin(Cell origin,
                                Conditional condition,
                                boolean includeOrigin,
                                double maximumDistance)

Returns the number of cells within the supplied distance that meet the supplied condition.

Parameters:

origin - the agent to find cells near

condition - the condition that found cell must meet

includeOrigin - should supplied agent be included in the search

maximumDistance - the distance to search within

getDistance

public abstract int getDistance(Cell origin,
                                Cell target)

findRandomCoordinate

public abstract CoordinateDiscrete findRandomCoordinate()

Returns a random location in the space defined by the graph.