org.ascape.model.space
Class Discrete

java.lang.Object
  org.ascape.model.space.CollectionSpace
      org.ascape.model.space.Discrete

All Implemented Interfaces:

java.io.Serializable, java.lang.Cloneable, java.lang.Iterable, java.util.Collection, Space, RandomFunctions

Direct Known Subclasses:

Array, Graph

public abstract class Discrete
extends CollectionSpace

A space with discrete nodes. Any space that has some kind of underyling discrete trucutre should implement this class.

Since:

1.0.1

Version:

3.0

Author:

Miles Parker

See Also:

Serialized Form

Nested Class Summary

Nested classes/interfaces inherited from class org.ascape.model.space.CollectionSpace

CollectionSpace.ClosestDataPoint, CollectionSpace.ConditionalIterator, CollectionSpace.CSIterator, CollectionSpace.CSMutableIterator, CollectionSpace.ListMutableRandomIterator, CollectionSpace.ListRandomIterator, CollectionSpace.MutableSubIterator, CollectionSpace.SubIterator

Field Summary

static boolean

performanceWarning The performance warning.

Fields inherited from class org.ascape.model.space.CollectionSpace

collection, ESTIMATED_MAXIMUM_SIZE, extent, geometry

Constructor Summary

Discrete()
Constructs a discrete space.

Discrete(CoordinateDiscrete extent)
Constructs a discrete space of provided extent.

Method Summary

protected java.util.Iterator	bfsWithinIterator(Location origin, Conditional condition, boolean includeSelf, double distance) This is the findWithin code from Graph.
double	calculateDistance(Coordinate origin, Coordinate target) Returns the shortest distance between one Location and another.
static int	calculateDistance(int o, int t, int bound) Calculate distance.
java.util.List	calculateNeighbors(Node cell) Calculate neighbors.
java.util.List	findAvailable() Returns cells that are available, that is, uncoccupied.
java.util.List	findAvailable(java.util.Collection candidates) Returns cells that are available, that is, uncoccupied.
abstract Node	findCellAway(Node origin, Node target) Returns the cell within immediate neighborhood furthest away from the requestd cell.
protected Node	findCellAwayBFS(Node origin, Node target) Find cell away BFS.
abstract Node	findCellToward(Node origin, Node target) Returns the next cell within immediate neighborhood toward the requested cell.
protected Node	findCellTowardBFS(Node origin, Node target) Find cell toward BFS.
Location	findNearestAvailable(Location origin, Conditional condition, boolean includeOrigin, double distance)
Location	findNearestBFS(Coordinate origin, Conditional condition, boolean includeOrigin, double distance) Finds the nearest agent that meets some condition.
java.util.List	findNeighbors(Node location)
java.util.List	findOccupants() Returns cells that are available, that is, uncoccupied.
static java.util.List	findOccupants(java.util.Collection candidates) Returns all cell occupants of the provided cells.
Node	findRandomAvailable()
Node	findRandomAvailable(Conditional condition)
Location	findRandomAvailable(Node origin, Conditional condition, boolean includeSelf, double distance)
Location	findRandomAvailableNeighbor(Node location)
Location	findRandomNeighbor(Node location)
Location	findRandomNeighbor(Node location, Conditional condition)
Node	findRandomUnoccupiedCell() Deprecated.
Node	findRandomUnoccupiedCell(Node excludeCell) Returns a random unoccupied discrete location in the space.
java.util.List	findWithinDefault(Coordinate origin, boolean includeSelf, double dist) Find within default.
Node[]	getCells() Returns all agents in the space as an array of cells (use this method to avoid coercion of members to Node.)
Node[]	getCellsNearDefault(Node origin, boolean includeSelf, int distance) Deprecated.
int	getDistance(Node origin, Node target) Deprecated. use calculateDistance instead.
int	getMaximumRank() Gets the maximum rank.
int	getSize() Returns the size, or number of cells, (the product of all extents) of this graph.

Methods inherited from class org.ascape.model.space.CollectionSpace

add, add, addAll, calculateDistance, clear, clone, conditionalIterator, conditionalIterator, construct, contains, containsAll, countWithin, createOrder, createSpatialConditional, deleteSweep, filter, find, findMaximum, findMaximum, findMaximumWithin, findMinimum, findMinimum, findMinimumWithin, findNearest, findNearest, findRandom, findRandom, findRandom, findRandom, findRandomCoordinate, findRandomWithin, findWithin, get, getContext, getExtent, getGeometry, getRandom, hasWithin, initialize, isDeleteSweepNeeded, isEmpty, isMutable, isPeriodic, iterator, iteratorCount, iteratorToList, moveAway, moveToward, newLocation, newLocation, populate, randomInRange, randomInRange, randomIs, randomizeOrder, randomToLimit, remove, removeAll, retainAll, safeIterator, safeIterator, safeIterators, safeRandomIterator, set, setContext, setExtent, setExtent, setGeometry, setPeriodic, setRandom, setSize, size, toArray, toArray, toList, withinIterator

Methods inherited from class java.lang.Object

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

Methods inherited from interface java.util.Collection

equals, hashCode

Field Detail

performanceWarning

public static boolean performanceWarning

The performance warning.

Constructor Detail

Discrete

public Discrete()

Constructs a discrete space.

Discrete

public Discrete(CoordinateDiscrete extent)

Constructs a discrete space of provided extent.

Parameters:

extent - a coordinate describing the size of this space

Method Detail

calculateNeighbors

public java.util.List calculateNeighbors(Node cell)

Calculate neighbors.

Parameters:

cell - the cell

Returns:

the list

getSize

public int getSize()

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

Specified by:

getSize in interface Space

Overrides:

getSize in class CollectionSpace

Returns:

the size

findOccupants

public java.util.List findOccupants()

Returns cells that are available, that is, uncoccupied.

Returns:

the list

findRandomNeighbor

public Location findRandomNeighbor(Node location)

findRandomNeighbor

public Location findRandomNeighbor(Node location,
                                   Conditional condition)

findNeighbors

public java.util.List findNeighbors(Node location)

findRandomAvailableNeighbor

public Location findRandomAvailableNeighbor(Node location)

findRandomAvailable

public Location findRandomAvailable(Node origin,
                                    Conditional condition,
                                    boolean includeSelf,
                                    double distance)

findOccupants

public static java.util.List findOccupants(java.util.Collection candidates)

Returns all cell occupants of the provided cells.

Parameters:

candidates - the cells to return occupants of

Returns:

the list

findAvailable

public java.util.List findAvailable()

Returns cells that are available, that is, uncoccupied.

Returns:

the list

findAvailable

public java.util.List findAvailable(java.util.Collection candidates)

Returns cells that are available, that is, uncoccupied.

Parameters:

candidates - the cells to return available cells from

Returns:

the list

getCells

public Node[] getCells()

Returns all agents in the space as an array of cells (use this method to avoid coercion of members to Node.)

Returns:

the cells

findRandomUnoccupiedCell

public Node findRandomUnoccupiedCell()

Deprecated.

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.

Returns:

the node

findRandomAvailable

public Node findRandomAvailable()

findRandomAvailable

public Node findRandomAvailable(Conditional condition)

findNearestAvailable

public Location findNearestAvailable(Location origin,
                                     Conditional condition,
                                     boolean includeOrigin,
                                     double distance)

findRandomUnoccupiedCell

public Node findRandomUnoccupiedCell(Node 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.

Parameters:

excludeCell - the exclude cell

Returns:

the node

getCellsNearDefault

public final Node[] getCellsNearDefault(Node origin,
                                        boolean includeSelf,
                                        int distance)

Deprecated.

This method returns cells near using a default method that simply scans through every cell in the lattice, checking that it is within 'distance' of central cell. This method should work with any space graph implementation that implements geteDistance properly. Obviously very poor performance in all but extremely large distances. This method is really only intended to support conditions where other more specific methods do not apply. This method works for any geometry, hence it is n ot designed for any specific geometry. Therefore, any calling methods should first check to make sure that the distance doesn't cover the whole space -- if it does, the calling method should simply use the getLocations method. An calling methods should first check to see that

Parameters:

origin - the agent to find cells near

includeSelf - should supplied agent be included in the return set

distance - the distance to form centralCells to return cells

Returns:

the cells near default

findWithinDefault

public java.util.List findWithinDefault(Coordinate origin,
                                        boolean includeSelf,
                                        double dist)

Find within default.

Parameters:

origin - the origin

includeSelf - the include self

dist - the dist

Returns:

the list

findCellToward

public abstract Node findCellToward(Node origin,
                                    Node target)

Returns the next cell within immediate neighborhood toward the requested cell.

Parameters:

origin - the current cell

target - the cell that we are moving toward

Returns:

the node

findCellAway

public abstract Node findCellAway(Node origin,
                                  Node target)

Returns the cell within immediate neighborhood furthest away from the requestd cell.

Parameters:

origin - the current cell

target - the cell that we are moving toward

Returns:

the node

getMaximumRank

public int getMaximumRank()

Gets the maximum rank.

Returns:

the maximum rank

getDistance

public int getDistance(Node origin,
                       Node target)

Deprecated. use calculateDistance instead.

Returns the shortest distance between one cell and the other.

Parameters:

origin - the starting cell

target - the ending cell

Returns:

the distance

findNearestBFS

public Location findNearestBFS(Coordinate origin,
                               Conditional condition,
                               boolean includeOrigin,
                               double distance)

Finds the nearest agent that meets some condition. Spaces without coordinate meaing should override this method.

Parameters:

origin - the coordinate to find agents near

condition - the condition that found agent must meet

includeOrigin - if the origin should be included

distance - the maximum distance around the origin to look

Returns:

the location

bfsWithinIterator

protected java.util.Iterator bfsWithinIterator(Location origin,
                                               Conditional condition,
                                               boolean includeSelf,
                                               double distance)

This is the findWithin code from Graph. This can be used by this class's findWithin, when distance is greater than 1. dist = 1 is the same as findNeighbors.

Parameters:

origin - the origin

condition - the condition

includeSelf - the include self

distance - the distance

Returns:

the iterator

calculateDistance

public double calculateDistance(Coordinate origin,
                                Coordinate target)

Description copied from class: CollectionSpace

Returns the shortest distance between one Location and another. Warning: this default method only returns a coordinate specific distance. It uses no information about the context context; for example wether it is a periodic (wrapping) space or not. Therefore, if you implement your own versions of CollectionSpace, ensure that you have properly implemented a version of this method. (All Ascape spaces properly overide this method.)

Specified by:

calculateDistance in interface Space

Overrides:

calculateDistance in class CollectionSpace

Parameters:

origin - one Location

target - another Location

Returns:

the double

findCellTowardBFS

protected Node findCellTowardBFS(Node origin,
                                 Node target)

Find cell toward BFS.

Parameters:

origin - the origin

target - the target

Returns:

the node

findCellAwayBFS

protected Node findCellAwayBFS(Node origin,
                               Node target)

Find cell away BFS.

Parameters:

origin - the origin

target - the target

Returns:

the node

calculateDistance

public static int calculateDistance(int o,
                                    int t,
                                    int bound)

Calculate distance.

Parameters:

o - the o

t - the t

bound - the bound

Returns:

the int