sim.field.grid
Class SparseGrid2D

java.lang.Object
  sim.field.SparseField
      sim.field.grid.SparseGrid2D

All Implemented Interfaces:

Grid2D, java.io.Serializable

public class SparseGrid2D

extends SparseField

implements Grid2D

A storage facility for sparse objects in discrete 2D space, using HashMaps. SparseGrid2D differs from ObjectGrid2D in several respects:

• SparseGrid2D can store more than one object at a location. ObjectGrid2D cannot.
• ObjectGrid2D can store an object at more than one location (though it's bad form!).
• SparseGrid2D can efficiently (O(1)) tell you the location of an object.
• SparseGrid2D can efficiently (O(#objs)) scan through all objects. The best you can do with ObjectGrid2D is search its array (which might have many empty slots).
• Storing an object, finding its location, or changing its location, in a SparseGrid2D is O(1) but requires several HashMap lookups and/or removes, which has a significant constant overhead.
• SparseGrid2D can associate objects with any 2D integer location. ObjectGrid2D's locations are restricted to be within its array.

Generally speaking, if you have a grid of objects, one per location, you should use an ObjectGrid2D. If you have a large grid occupied by a few objects, or those objects can pile up on the same grid location, you should use a SparseGrid2D.

In either case, you might consider storing the location of an object IN THE OBJECT ITSELF if you need to query for the object location often -- it's faster than the hashtable lookup in SparseGrid2D, and certainly faster than searching the entire array of an ObjectGrid2D.

See Also:

Serialized Form

Nested Class Summary

Nested classes inherited from class sim.field.SparseField

SparseField.LocationAndIndex

Field Summary

protected int	height
protected int	width

Fields inherited from class sim.field.SparseField

allObjects, INITIAL_BAG_SIZE, LARGE_BAG_RATIO, locationAndIndexHash, MIN_BAG_SIZE, objectHash, removeEmptyBags, replaceLargeBags, REPLACEMENT_BAG_RATIO

Constructor Summary

SparseGrid2D(int width, int height)

Method Summary

int	dlx(int x, int y) Hex downleft x.
int	dly(int x, int y) Hex downleft y.
int	downx(int x, int y) Hex down x.
int	downy(int x, int y) Hex down y.
int	drx(int x, int y) Hex downright x.
int	dry(int x, int y) Hex downright y.
int	getHeight() Returns the height of the grid
Bag	getNeighborsHamiltonianDistance(int x, int y, int dist, boolean toroidal, Bag result, IntBag xPos, IntBag yPos) Gets all neighbors of a location that satisfy abs(x-X) + abs(y-Y) <= dist.
void	getNeighborsHamiltonianDistance(int x, int y, int dist, boolean toroidal, IntBag xPos, IntBag yPos) Gets all neighbors of a location that satisfy abs(x-X) + abs(y-Y) <= dist.
Bag	getNeighborsHexagonalDistance(int x, int y, int dist, boolean toroidal, Bag result, IntBag xPos, IntBag yPos) Gets all neighbors located within the hexagon centered at (X,Y) and 2*dist+1 cells from point to opposite point inclusive.
void	getNeighborsHexagonalDistance(int x, int y, int dist, boolean toroidal, IntBag xPos, IntBag yPos) Gets all neighbors located within the hexagon centered at (X,Y) and 2*dist+1 cells from point to opposite point inclusive.
Bag	getNeighborsMaxDistance(int x, int y, int dist, boolean toroidal, Bag result, IntBag xPos, IntBag yPos) Gets all neighbors of a location that satisfy max( abs(x-X) , abs(y-Y) ) <= dist.
void	getNeighborsMaxDistance(int x, int y, int dist, boolean toroidal, IntBag xPos, IntBag yPos) Gets all neighbors of a location that satisfy max( abs(x-X) , abs(y-Y) ) <= dist.
Int2D	getObjectLocation(java.lang.Object obj) Returns the object location, or null if there is no such object.
Double2D	getObjectLocationAsDouble2D(java.lang.Object obj) Returns the object location as a Double2D, or as null if there is no such object.
Bag	getObjectsAtLocation(int x, int y) Returns a bag containing all the objects at a given location, or null when there are no objects at the location.
Bag	getObjectsAtLocations(IntBag xPos, IntBag yPos, Bag result) For each location, puts all such objects into the result bag.
int	getWidth() Returns the width of the grid
int	numObjectsAtLocation(int x, int y) Returns the number of objects stored in the grid at the given location.
Bag	removeObjectsAtLocation(int x, int y) Removes all the objects stored at the given location and returns them as a Bag (which you are free to modify).
boolean	setObjectLocation(java.lang.Object obj, Int2D location) Changes the location of an object, or adds if it doesn't exist yet.
boolean	setObjectLocation(java.lang.Object obj, int x, int y) Changes the location of an object, or adds if it doesn't exist yet.
int	stx(int x) Simple [and fast] toroidal x.
int	sty(int y) Simple [and fast] toroidal y.
boolean	trb(int x, int y) Horizontal edge is on the bottom for triangle.
boolean	trt(int x, int y) Horizontal edge is on the top for triangle.
int	tx(int x) Toroidal x.
int	ty(int y) Toroidal y.
int	ulx(int x, int y) Hex upleft x.
int	uly(int x, int y) Hex upleft y.
int	upx(int x, int y) Hex up x.
int	upy(int x, int y) Hex up y.
int	urx(int x, int y) Hex upright x.
int	ury(int x, int y) Hex upright y.

Methods inherited from class sim.field.SparseField

clear, exists, getAllObjects, getObjectIndex, getObjectsAtLocation, getObjectsAtLocationOfObject, getObjectsAtLocations, getRawObjectLocation, iterator, locationBagIterator, numObjectsAtLocation, numObjectsAtLocationOfObject, remove, removeObjectsAtLocation, setObjectLocation

Methods inherited from class java.lang.Object

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

Field Detail

width

protected int width

height

protected int height

Constructor Detail

SparseGrid2D

public SparseGrid2D(int width,
                    int height)

Method Detail

getWidth

public int getWidth()

Returns the width of the grid

Specified by:

getWidth in interface Grid2D

getHeight

public int getHeight()

Returns the height of the grid

Specified by:

getHeight in interface Grid2D

tx

public final int tx(int x)

Description copied from interface: Grid2D

Toroidal x. The following definition:

final int length = this.length;
if (z >= 0) return (z % length);
final int length2 = (z % length) + length;
if (length2 < length) return length2;
return 0;

... produces the correct code and is 27 bytes, so it's likely to be inlined in Hotspot for 1.4.1.

Specified by:

tx in interface Grid2D

ty

public final int ty(int y)

Description copied from interface: Grid2D

Toroidal y. The following definition:

final int length = this.length;
if (z >= 0) return (z % length);
final int length2 = (z % length) + length;
if (length2 < length) return length2;
return 0;

... produces the correct code and is 27 bytes, so it's likely to be inlined in Hotspot for 1.4.1.

Specified by:

ty in interface Grid2D

stx

public int stx(int x)

Description copied from interface: Grid2D

Simple [and fast] toroidal x. Use this if the values you'd pass in never stray beyond (-width ... width * 2) not inclusive. It's a bit faster than the full toroidal computation as it uses if statements rather than two modulos. The following definition:
{ int width = this.width; if (x >= 0) { if (x < width) return x; return x - width; } return x + width; } ...produces the shortest code (24 bytes) and is inlined in Hotspot for 1.4.1. However in most cases removing the int width = this.width; is likely to be a little faster if most objects are usually within the toroidal region.

Specified by:

stx in interface Grid2D

sty

public int sty(int y)

Description copied from interface: Grid2D

Simple [and fast] toroidal y. Use this if the values you'd pass in never stray beyond (-height ... height * 2) not inclusive. It's a bit faster than the full toroidal computation as it uses if statements rather than two modulos. The following definition:
{ int height = this.height; if (y >= 0) { if (y < height) return y ; return y - height; } return y + height; } ...produces the shortest code (24 bytes) and is inlined in Hotspot for 1.4.1. However in most cases removing the int height = this.height; is likely to be a little faster if most objects are usually within the toroidal region.

Specified by:

sty in interface Grid2D

ulx

public int ulx(int x,
               int y)

Description copied from interface: Grid2D

Hex upleft x.

Specified by:

ulx in interface Grid2D

uly

public int uly(int x,
               int y)

Description copied from interface: Grid2D

Hex upleft y.

Specified by:

uly in interface Grid2D

urx

public int urx(int x,
               int y)

Description copied from interface: Grid2D

Hex upright x.

Specified by:

urx in interface Grid2D

ury

public int ury(int x,
               int y)

Description copied from interface: Grid2D

Hex upright y.

Specified by:

ury in interface Grid2D

dlx

public int dlx(int x,
               int y)

Description copied from interface: Grid2D

Hex downleft x.

Specified by:

dlx in interface Grid2D

dly

public int dly(int x,
               int y)

Description copied from interface: Grid2D

Hex downleft y.

Specified by:

dly in interface Grid2D

drx

public int drx(int x,
               int y)

Description copied from interface: Grid2D

Hex downright x.

Specified by:

drx in interface Grid2D

dry

public int dry(int x,
               int y)

Description copied from interface: Grid2D

Hex downright y.

Specified by:

dry in interface Grid2D

upx

public int upx(int x,
               int y)

Description copied from interface: Grid2D

Hex up x.

Specified by:

upx in interface Grid2D

upy

public int upy(int x,
               int y)

Description copied from interface: Grid2D

Hex up y.

Specified by:

upy in interface Grid2D

downx

public int downx(int x,
                 int y)

Description copied from interface: Grid2D

Hex down x.

Specified by:

downx in interface Grid2D

downy

public int downy(int x,
                 int y)

Description copied from interface: Grid2D

Hex down y.

Specified by:

downy in interface Grid2D

trb

public boolean trb(int x,
                   int y)

Description copied from interface: Grid2D

Horizontal edge is on the bottom for triangle. True if x + y is odd. One definition of this is return ((x + y) & 1) == 1;

Specified by:

trb in interface Grid2D

trt

public boolean trt(int x,
                   int y)

Description copied from interface: Grid2D

Horizontal edge is on the top for triangle. True if x + y is even. One definition of this is return ((x + y) & 1) == 0;

Specified by:

trt in interface Grid2D

numObjectsAtLocation

public int numObjectsAtLocation(int x,
                                int y)

Returns the number of objects stored in the grid at the given location.

getObjectsAtLocation

public Bag getObjectsAtLocation(int x,
                                int y)

Returns a bag containing all the objects at a given location, or null when there are no objects at the location. You should NOT MODIFY THIS BAG. This is the actual container bag, and modifying it will almost certainly break the Sparse Field object. If you want to modify the bag, make a copy and modify the copy instead, using something along the lines of new Bag(foo.getObjectsAtLocation(location)) . Furthermore, changing values in the Sparse Field may result in a different bag being used -- so you should not rely on this bag staying valid.

getObjectLocationAsDouble2D

public Double2D getObjectLocationAsDouble2D(java.lang.Object obj)

Returns the object location as a Double2D, or as null if there is no such object.

getObjectLocation

public Int2D getObjectLocation(java.lang.Object obj)

Returns the object location, or null if there is no such object.

removeObjectsAtLocation

public Bag removeObjectsAtLocation(int x,
                                   int y)

Removes all the objects stored at the given location and returns them as a Bag (which you are free to modify).

setObjectLocation

public boolean setObjectLocation(java.lang.Object obj,
                                 int x,
                                 int y)

Changes the location of an object, or adds if it doesn't exist yet. Returns false if the object is null (null objects cannot be put into the grid).

setObjectLocation

public boolean setObjectLocation(java.lang.Object obj,
                                 Int2D location)

Changes the location of an object, or adds if it doesn't exist yet. Returns false if the object is null (null objects cannot be put into the grid) or if the location is null.

getNeighborsMaxDistance

public void getNeighborsMaxDistance(int x,
                                    int y,
                                    int dist,
                                    boolean toroidal,
                                    IntBag xPos,
                                    IntBag yPos)

Description copied from interface: Grid2D

Gets all neighbors of a location that satisfy max( abs(x-X) , abs(y-Y) ) <= dist. This region forms a square 2*dist+1 cells across, centered at (X,Y). If dist==1, this is equivalent to the so-called "Moore Neighborhood" (the eight neighbors surrounding (X,Y)), plus (X,Y) itself. Places each x and y value of these locations in the provided IntBags xPos and yPos, clearing the bags first.

Specified by:

getNeighborsMaxDistance in interface Grid2D

getNeighborsHamiltonianDistance

public void getNeighborsHamiltonianDistance(int x,
                                            int y,
                                            int dist,
                                            boolean toroidal,
                                            IntBag xPos,
                                            IntBag yPos)

Description copied from interface: Grid2D

Gets all neighbors of a location that satisfy abs(x-X) + abs(y-Y) <= dist. This region forms a diamond 2*dist+1 cells from point to opposite point inclusive, centered at (X,Y). If dist==1 this is equivalent to the so-called "Von-Neumann Neighborhood" (the four neighbors above, below, left, and right of (X,Y)), plus (X,Y) itself. Places each x and y value of these locations in the provided IntBags xPos and yPos, clearing the bags first.

Specified by:

getNeighborsHamiltonianDistance in interface Grid2D

getNeighborsHexagonalDistance

public void getNeighborsHexagonalDistance(int x,
                                          int y,
                                          int dist,
                                          boolean toroidal,
                                          IntBag xPos,
                                          IntBag yPos)

Description copied from interface: Grid2D

Gets all neighbors located within the hexagon centered at (X,Y) and 2*dist+1 cells from point to opposite point inclusive. If dist==1, this is equivalent to the six neighbors immediately surrounding (X,Y), plus (X,Y) itself. Places each x and y value of these locations in the provided IntBags xPos and yPos, clearing the bags first.

Specified by:

getNeighborsHexagonalDistance in interface Grid2D

getNeighborsMaxDistance

public Bag getNeighborsMaxDistance(int x,
                                   int y,
                                   int dist,
                                   boolean toroidal,
                                   Bag result,
                                   IntBag xPos,
                                   IntBag yPos)

Gets all neighbors of a location that satisfy max( abs(x-X) , abs(y-Y) ) <= dist. This region forms a square 2*dist+1 cells across, centered at (X,Y). If dist==1, this is equivalent to the so-called "Moore Neighborhood" (the eight neighbors surrounding (X,Y)), plus (X,Y) itself. Places each x and y value of these locations in the provided IntBags xPos and yPos, clearing the bags first. Then places into the result Bag the objects at each of those locations clearning it first. Returns the result Bag. null may be passed in for the various bags, though it is more efficient to pass in a 'scratch bag' for each one.

getNeighborsHamiltonianDistance

public Bag getNeighborsHamiltonianDistance(int x,
                                           int y,
                                           int dist,
                                           boolean toroidal,
                                           Bag result,
                                           IntBag xPos,
                                           IntBag yPos)

Gets all neighbors of a location that satisfy abs(x-X) + abs(y-Y) <= dist. This region forms a diamond 2*dist+1 cells from point to opposite point inclusive, centered at (X,Y). If dist==1 this is equivalent to the so-called "Von-Neumann Neighborhood" (the four neighbors above, below, left, and right of (X,Y)), plus (X,Y) itself. Places each x and y value of these locations in the provided IntBags xPos and yPos, clearing the bags first. Then places into the result Bag the objects at each of those locations, clearning it first. Returns the result Bag (constructing one if null had been passed in). null may be passed in for the various bags, though it is more efficient to pass in a 'scratch bag' for each one.

getNeighborsHexagonalDistance

public Bag getNeighborsHexagonalDistance(int x,
                                         int y,
                                         int dist,
                                         boolean toroidal,
                                         Bag result,
                                         IntBag xPos,
                                         IntBag yPos)

Gets all neighbors located within the hexagon centered at (X,Y) and 2*dist+1 cells from point to opposite point inclusive. If dist==1, this is equivalent to the six neighbors immediately surrounding (X,Y), plus (X,Y) itself. Places each x and y value of these locations in the provided IntBags xPos and yPos, clearing the bags first. Then places into the result Bag the objects at each of those locations clearning it first. Returns the result Bag (constructing one if null had been passed in). null may be passed in for the various bags, though it is more efficient to pass in a 'scratch bag' for each one.

getObjectsAtLocations

public Bag getObjectsAtLocations(IntBag xPos,
                                 IntBag yPos,
                                 Bag result)

For each location, puts all such objects into the result bag. Returns the result bag. If the provided result bag is null, one will be created and returned.