org.ascape.model
Class Scape

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

All Implemented Interfaces:

java.io.Serializable, java.lang.Cloneable, java.lang.Iterable, java.util.Collection, java.util.EventListener, ControlListener, ScapeListener, Location, Node, SpaceContext, HasName, RandomFunctions

Direct Known Subclasses:

ScapeTime

public class Scape
extends CellOccupant
implements SpaceContext, java.util.Collection, ControlListener, ScapeListener

The base class for all collections of agents within ascape. Provides services to identify other scape members, execute rules on members, support scape views, and other features. Also provides methods for model creation and use; a model is simply a special use of a scape.

While scapes are essentially collections of agents, there is no assumption that these collections must be discrete. While there are currently no scapes representing continuous space, there is no strong reason why a scape couldn't do so. Continuous (or at least very fine-grained!) time may also be supported at some point. Scapes are the basic building block of ascape models. Pick a scape appropriate for your model. For example, you might want to create a model that uses cells in a 2-dimensional array. Simply create an instance of the scape you want:

 Scape lattice = new Scape(new Array2DVonNeumann());
 lattice.setExtent(new Coordinate2DDiscrete(x, y));
 lattice.setPrototypeAgent(new MyPrototypeCell());
 

In this example, extent defines the size of the lattice, and prototype agent is the agent that wil be cloned to populate the lattice.
All ascape models are made up of at least one scape. All scapes are agents and so can belong to other scapes. Models are built as a hierarchy of scapes. Typically, this hierarchy is quite simple; a 'root' scape, usually a ScapeList, is created, and other scapes are added to it:

 root = new Scape();
 root.add(lattice);
 

Or simply subclass Scape as a model, and use it as the root:

 public class MyModel extends Scape {
     ...
     public MyModel() {
         add(lattice);
         ...
     }
 

To provide behavior for your agents, you add rules to be executed upon them. (If members are scapes, the rules can be executed on their members as well.)

 lattice.addRule(new MyRule());
 

Rules are executed once for every iteration, on every agent. Some rules are added by default, or are used by the scape internally. (For example, initialization and rule iteration itself are both managed by rules.) For more information, see the documentation for Rule.

To observe a scape, you attach views to it:

 lattice.addView(new Overhead2DView());
 

This registers the view as a listener of the scape and automatically provides a window for it if appropriate. The scape uses an event based Model View Controller design. After each iteration, each scape sends an update event to each of its views, and then waits for the views to update. It is every view's responsibility to inform its scape when it has updated, which it does by sending a control event. More general control events are used to control scape execution. Usually, you simply add a control bar view, which gives the user complete control over model execution.

 lattice.addView(new ControlBarView());
 

(A model scape adds a control bar automatically.) Scapes can automatically collect statistics on their members. (See StatCollectorCSA documentation for a description of how stats are created.) Here is an example of how this might be done:

 agents.addStatCollectors({new StatCollectorCSA() {
     public double getValue(Object object) {
         return ((MyAgent) object).getMyInterestingValue();
     }
     public String getName() {
         return "Interesting Value";
     }
  },setPro
  ...
 }
 

Once statistics have been added to a view, data on each member is gathered for every agent; once before the scape is iterated, and then following the execution of each iteration. (See StatCollector documentation for more information on how to collect statistics.) To view your data, you can add a chart view to your scape:

 ChartView myChart = new ChartView();
 lattice.addView(myChart);
 

You can double-click on a chart to select statistics to view, or add them in code.

 chart.addSeries("Average Interesting Value", Color.blue);
 

Finally, if you haven't added a control view, or you want the model to begin running upon execution, tell it to start. (Control events can be sent to any scape in the model, unless the event is scape specific. Model scapes start automatically; you can easily override this behavior.)

 lattice.start();
 

or send it

 lattice.respondControl(ControlEvent.REQUEST_START);
 

Scapes are initialized and iterated hierarchically. The initialization and iteration process are rules, and their behavior is well defined. For example, if you use a vector for your root scape, scapes will be initialized and iterated in the order in which they were added to the root. Of course, this is an imporant consideration whenever there are dependencies between scapes. On initialization, each scape first instantiates all of its members, and then initializes them. After initialization, statistics are gathered, and views are requested to update. Then, each rule is executed on its scape, statistics are gathered, and views are requested to update. This continues until a control event stops or pauses the model, or the iteration limit provided with setAutoStopAt is reached.

As stated, all scapes classes may act as a complete ascape model application. Using the construct methods, basic views and services are automatically added to a model. Scape can be used as a common common class for both applets and full applications, simplifing maintenance and guaranteeing that web page models will behave consistently with desktop applications.

Examples:

 <code>
     public class MyModel extends Scape {
        ...
        createScape() {
            [Instantiate and add scapes to model, add rules to the model]
        }
        createViews() {
            [and views to the model.]
        }
        ...
     }
 </code>
 

Application:

 java org.ascape.model.Scape mypath.MyModel
 <BR>
 

Applet:

 <APPLET name=AppletName codebase=[path] <param name="Scape" value="mypath.MyModel">></APPLET><BR>
 

Note that it is neccesary to call Model with your model's fully qualified class name as the parameter. To allow your model to be invoked directly, override main.

Since:

1.0

Version:

3.0

Author:

Miles Parker

See Also:

Rule, ScapeListener, StatCollector, ControlEvent, Serialized Form

Nested Class Summary

class	Scape.ConditionalIterator
class	Scape.DrawFeatureObservable Just a class for a delegated proxy for draw features.

Field Summary

static int	AGENT_ORDER Symbol for by agent execution order.
protected int	agentsPerIteration The number of agents to execute each rule across for each iteration.
static int	ALL_AGENTS The symbol to execute rules against all agents in each iteration.
static Rule	CLEAR_STATS_RULE A rule causing all children and members that are scapes to iterate.
static Rule	COLLECT_STATS_RULE A rule causing all children and members that are scapes to iterate.
static java.util.Comparator	COMPARE_ORDERED_QUALIFIERS
static int	COMPLETE_TOUR Symbol for complete tour excution style.
static java.lang.String	copyrightAndCredits Copyright and credits information for ascape w/ HTML style tags.
static Rule	CREATE_GRAPHIC_VIEW_RULE A rule causing graphic views to be created for scape and all subscapes.
static Rule	CREATE_RULE A rule causing the target scape and all its children scapes to be populated if auto create is set to true.
static Rule	CREATE_SCAPE_RULE A rule causing the target scape to be populated.
static Rule	CREATE_VIEW_RULE A rule causing viwews to be created for scape and all subscapes.
static Rule	EXECUTE_RULES_RULE A rule causing all children and members that are scapes to iterate.
static Rule	INITIAL_RULES_RULE A rule causing the targets initial rules to be executed on its members.
protected VectorSelection	initialRules The rules that this scape will execute on its members upon initializtion.
protected Agent	prototypeAgent An agent which which may be cloned to produce members of this collection.
static int	REPEATED_DRAW Symbol for repeated random draw execution style.
static int	RULE_ORDER Symbol for by rule execution order.
static java.lang.String	version The current version of the Ascape framework as a whole.

Fields inherited from class org.ascape.model.CellOccupant

PLAY_HOST_RULE, RANDOM_WALK_AVAILABLE_RULE

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, scape

Constructor Summary

Scape()
Constructs a scape with default list topology.

Scape(CollectionSpace space)
Constructs a scape.

Scape(CollectionSpace space, java.lang.String name, Agent prototypeAgent)
Constructs a scape of provided geometry, to be populated with clones of provided agent.

Scape(java.lang.String name, Agent prototypeAgent)
Constructs a scape of provided geometry, to be populated with clones of provided agent.

Method Summary

void	add(int index, java.lang.Object a) Adds the supplied object (agent) to this collection.
void	add(int index, java.lang.Object o, boolean isParent) Adds the supplied object (assumed to be an agent) to this collection.
boolean	add(java.lang.Object a) Adds the supplied object (agent) to this collection.
boolean	add(java.lang.Object agent, boolean isParent) Adds the supplied object (assumed to be an agent) to this collection.
boolean	addAll(java.util.Collection c) Adds all of the agent in the specified collection to the end of the scape.
void	addDrawFeature(PlatformDrawFeature feature) Adds the provided draw feature to this scape.
void	addInitialRule(Rule rule) Adds a rule to be executed once following initialization.
void	addInitialRule(Rule rule, boolean select) Adds a rule to be executed once following initialization.
void	addRule(Rule rule) Adds a rule to this scape, automatically selecting it.
void	addRule(Rule rule, boolean select) Adds a rule to this scape.
void	addScapeListener(ScapeListener listener) Adds an observer to this scape.
void	addScapeListenerFirst(ScapeListener listener) Adds an observer to this scape.
void	addStatCollector(StatCollector stat) Adds the specified stat collector to this scape for automatic collection by the scape.
StatCollector	addStatCollectorIfNew(StatCollector stat) Adds the specified stat collector iff and only if it hasn't allready been added.
void	addStatCollectors(StatCollector[] stats) Adds the specified stat collectors to this scape for automatic collection by the scape.
void	addView(ScapeListener view) Adds a view to this scape.
void	addView(ScapeListener view, boolean createFrame) Adds a view to this scape.
void	addView(ScapeListener view, boolean createFrame, boolean forceGUI) Adds a view to this scape.
void	addViews(ScapeListener[] views) Adds a view to this scape.
void	addViews(ScapeListener[] views, boolean createFrame) Adds an array of views to this scape.
void	addViews(ScapeListener[] views, boolean createFrame, boolean forceGUI) Adds an array of views to this scape.
void	assignParameters(java.lang.String[] args) Sets values for the models paramters based on supplied array of key value pairs, reporting if any of the keys (parameter names) are not found.
void	assignParameters(java.lang.String[] args, boolean reportNotFound) Sets values for the models paramters based on supplied array of key value pairs.
double	calculateDistance(Coordinate origin, Coordinate target) Returns the shortest distance between one LocatedAgent and another.
double	calculateDistance(LocatedAgent origin, LocatedAgent target) Returns the shortest distance between one agent and another.
void	clear() Removes all agents from the scape.
java.lang.Object	clone() Overides the clone method to do a deep clone of member state so that such state will not be shared between scapes.
void	construct() Contructs the basic scape structure.
boolean	contains(java.lang.Object o) Returns true if the scape collection contains the object (agent.)
boolean	containsAll(java.util.Collection c) Returns true if this collection contains all of agents in the specified collection.
java.lang.String	contentsToString() Returns a string composed of descriptions of the contents.
int	countWithin(Coordinate origin, Conditional condition, boolean includeSelf, double distance) Returns the number of agents within the specified distance of the agent that meet some condition.
void	createGraphicViews() Override to create any graphical views for the scape.
void	createNonGraphicViews() Overide to create and non-graphical views for the scape.
void	createScape() Create this scape; contruct it, populate it, add rules, create statistic collectors, etc.
void	createSelfView() Makes the scape a view of itself.
void	createViews() Constructs the views for this scape.
void	createViews(java.lang.String[] args)
void	environmentQuiting(ScapeEvent scapeEvent) Method called as the entire envornmnet is about to be exited.
void	execute(java.util.List rules, java.util.List agents) Executes the provided rules on the supplied agentArray.
void	execute(Rule rule, java.util.List agents) Executes the provided rule on every member of the lattice, according to the rule settings and the execution order of this scape.
void	executeOnMembers() Executes all of this scapes selected rules on its members.
void	executeOnMembers(java.lang.Object[] rules) Executes the provided rules on every member of the collection, according to the rule settings and the execution order of the scape.
void	executeOnMembers(Rule rule) Executes the provided rule on every member of the lattice, according to the rule settings and the execution order of this scape.
void	executeOnMembers(VectorSelection ruleSelection) Executes the provided rules on every member of the lattice, according to the rule settings and the execution order of this scape.
void	executeOnRoot(Rule rule) Propogates the rule for execution up to the root of the scape tree, then propogates down to all nodes.
void	executeOnRoot(Rule[] rules) Propogates the rule for execution up to the root of the scape tree, then propogates down to all nodes.
java.util.List	find(Conditional condition) Find the maximum cell of some data point.
LocatedAgent	findMaximum(DataPoint point) Returns the agent with the maximum value.
LocatedAgent	findMaximum(java.util.Iterator iter, DataPoint dataPoint) Find the maximum cell of some data point.
LocatedAgent	findMaximumWithin(Coordinate coordinate, DataPoint dataPoint, Conditional condition, boolean includeSelf, double distance)
LocatedAgent	findMinimum(DataPoint point) Returns the agent with the minimum value.
LocatedAgent	findMinimum(java.util.Iterator iter, DataPoint dataPoint)
LocatedAgent	findMinimumWithin(Coordinate coordinate, DataPoint dataPoint, Conditional condition, boolean includeSelf, double distance)
LocatedAgent	findNearest(Coordinate origin, Conditional condition, boolean includeOrigin, double distance) Finds the nearest agent that meets some condition.
LocatedAgent	findRandom() Returns an agent randomly selected from the collection.
Agent	findRandom(Conditional condition) Returns an agent randomly that matches a condition.
Agent	findRandom(Location excludeAgent) Returns a random unoccupied discrete location in the space given with the lattice.
Coordinate	findRandomCoordinate() Returns a coordinate randomly selected from the collection's space.
java.util.List	findWithin(Coordinate origin, Conditional condition, boolean includeSelf, double distance) Returns all agents within the specified distance of the agent.
LocatedAgent	get(Coordinate coordinate) Returns the cell existing at the specified coordinate.
java.lang.Object	get(int index) Returns the cell existing at the specified location.
int	getAgentsPerIteration() Returns the number of agents to iterate through each iteration cycle.
java.util.List	getAllScapes() Returns all scapes that are composed with this scape.
CollectStats	getCollectStats() Returns the value collection rule in effect; null if no value collection.
DataGroup	getData() Convenience method for obtaining sata for current run.
java.lang.String	getDescription() Returns a long (paragraph length suggested) description of the scape.
java.util.Vector	getDrawFeatures() Returns, as a vector, the draw features available for interpretation of members of this scape.
java.util.Observable	getDrawFeaturesObservable() Returns an observable delegate that notifies users of draw features that a change has occurred.
RuntimeEnvironment	getEnvironment() Returns the runtime environment, if any, for this scape.
int	getExecutionOrder() Returns the execution order that has been set for this scape.
int	getExecutionStyle() Returns the execution style that has been set for this scape.
Coordinate	getExtent() Returns the extent of the scape.
java.lang.String	getHome() Returns the path in which all files should by default be stored to and retrieved from.
java.lang.String	getHTMLDescription() Returns a long (paragraph length suggested) description of the scape.
VectorSelection	getInitialRules() Returns all the rules executed following scape initialization.
int	getIteration() Returns current count of iterations.
int	getIterationsPerRedraw() Returns the number of iterations to perform before updating views.
Runner	getModel() Deprecated. please use #getRunner().
java.lang.String	getName() Returns the name of this scape, the model name if this is root and there is no name set.
int	getPausePeriod() Returns the period to pause on.
int	getPeriod() Returns the current period, which is just the iteration plus the period begin.
java.lang.String	getPeriodDescription() Returns a string description of the current period, i.e.
java.lang.String	getPeriodName() Returns the name that periods are referred to by.
Location	getPrototype() Gets the prototype.
Agent	getPrototypeAgent() Returns the agent that is cloned to populate this scape.
Scape	getRoot() Returns the root of this scape, which may be this scape.
VectorSelection	getRules() Returns all rules that this scape might execute.
Runner	getRunner() Returns the runtime model environment, which manages model-wide state such as run status.
java.util.ArrayList	getScapeListeners() Returns all listeners for this scape.
int	getSize() Returns the size, or number of agents, of this Scape.
Space	getSpace()
int	getStartPeriod() Returns the period this scape begins running at.
StatCollector[]	getStatCollectors() Returns the stat collectors currently calcualting stats for this scape.
int	getStopPeriod() Returns the period this scape stops running at.
Scape	getSuperScape()
int	getThreadCount()
AbstractUIEnvironment	getUIEnvironment() Returns the user environment for this scape.
AbstractUIEnvironment	getUserEnvironment() Deprecated. retained for backward compatability, please use #getUIEnvironment instead.
boolean	hasWithin(Coordinate origin, Conditional condition, boolean includeSelf, double distance) Returns if there are agents within the specified distance of the origin that meet some Condition.
void	initialize() Initializes the state of the scape.
boolean	isAllViewsUpdated() Have all views and views of memebers of this scape been updated? [The grammer is terrible, but it fits the text pattern!]
boolean	isAutoCreate() Is the scape responsible for creating itself and its members, or are other classes responsible for creating the scape? If true (default) calls the createScape method on model construction, typically causing the scape to be populated with clones of prototype agent.
boolean	isCellsRequestUpdates() Do cells request view updates manually or are all cells automatically updated every view cycle? While requiring cells to request updates manually adds a little to complication to model design and maintenance, manual requests allow a significant boost in view performance, as all cells do not have to be drawn every cycle.
boolean	isEmpty() Are there no agents in this scape?
boolean	isGraphic() Returns false the scape is not a graphical user interface component.
boolean	isHome(Location a) Checks if is home.
boolean	isLifeOfScape() Returns true (default) if the listener is intended to be used only for the current scape; certainly true in this case.
boolean	isListenersAndMembersCurrent()
boolean	isMembersActive() Are members of this active scape model participants, that is, do they have rules executed upon them? Default is true.
boolean	isMutable()
boolean	isPaused() Has the scape been requested to pause? Note: indicates that a pause has been requested, not neccesarily that the simulation is paused; it may be completing its current iteration.
boolean	isPeriodic()
boolean	isPopulateOnCreate() Is the scape populated when the scape is created? That is, is the populate scape method called when create scape is executed? (Typically, the populate scape method will fill each cell with clones of the prototype cell, but of course this behavior can be overidden.) True by default.
boolean	isRoot() Is this scape the root within its entire simulation context? That is, does this root not have any parent scapes?
boolean	isRunning() Has the scape been requested to run? Note: if false, indicates that a stop has been requested, not neccesarily that it has occured, as the simulation continues the current iteration.
boolean	isScapeListener(ScapeListener listener) Returns true if and only if the argument is an observer of this scape.
boolean	isSerializable()
boolean	isStartOnOpen() Does the scape automatically start upon opening? True by default.
boolean	isUpdateNeeded() Has a view update been requested for this cell?
boolean	isValidPeriod(int period) Is the supplied period a valid period for this scape?
boolean	isViewSelf() Does the scape view itself? True by default for root scape when createViews is used, false otherwise.
java.util.Iterator	iterator() Returns an iterator across all agents in this scape.
protected void	listenerOrMemberUpdated() Called whenever a listener or member scape of this scape has been updated.
void	listenerUpdated(ScapeListener listener) Called whenever a listener has been updated.
void	memberUpdated(Scape member) Called whenever a member has been updated.
void	moveAway(LocatedAgent origin, Coordinate target, double distance) Moves an agent toward the specified agent.
void	moveToward(LocatedAgent origin, Coordinate target, double distance) Moves an agent toward the specified agent.
Agent	newAgent() Creates a new agent in this collection by cloning the prototype agent, adding it in an arbitrary place (typically at the end of a list), and initializing it.
Agent	newAgent(boolean randomLocation) Creates a new agent in this collection by cloning the prototype agent, adding it to a random or arbitrary (last in most cases) place in the collection, and initializing it.
void	notifyViews(int id) Notifies all scape listeners that this scapes state has changed.
void	notifyViews(ScapeEvent event) Notifies all scape listeners that this scapes state has changed.
void	populate() Populates the scape with clones of the prototype agent.
java.lang.Object	remove(int index) Removes the object at the index from this collection.
boolean	remove(java.lang.Object o) Removes the supplied object (agent) from this collection.
boolean	removeAll(java.util.Collection c) Removes all of the agnets contained in the collection.
boolean	removeDrawFeature(PlatformDrawFeature feature) Removes the provided draw feature.
void	removeScapeListener(ScapeListener listener) Removes the observer from this scape.
void	respondControl(ControlEvent control) Responds to any control events fired at this scape.
void	respondDrawFeature(DrawFeatureEvent event) This is for grid communication of changes in draw feature.
boolean	retainAll(java.util.Collection c) Retains only the elements in the scape that are in the specified collection.
java.util.List	retrieveAllAccessors() Returns all property accessors for this scape and recursivly for all member scapes of this scape.
java.util.List	retrieveAllAccessorsOrdered() Returns all property accessors for this scape and recursivly for all member scapes of this scape.
java.util.List	retrieveModelAccessorsOrdered() Returns all property accessors for this scape (excluding inappropriate/disabled accessors such as size) and recursivly for all member scapes of this scape.
void	save(java.io.File file) Save the state of the scape to a file.
void	save(java.io.OutputStream os) Save the state of the scape to an output stream.
void	scapeAdded(ScapeEvent scapeEvent) Add a scape to this listener.
void	scapeClosing(ScapeEvent scapeEvent) If the scape has delegated a view to itself, called each time a scape sends a "closing" event.
void	scapeDeserialized(ScapeEvent scapeEvent) If the scape has delegated a view to itself, called each time a scape sends a "deserialized" event.
void	scapeInitialized(ScapeEvent scapeEvent) If the scape has delegated a view to itself, called each time a scape sends a "initialize" event, indicating it has been initialized.
void	scapeIterated(ScapeEvent scapeEvent) If the scape has delegated a view to itself, called each time the scape is iterated.
ResetableIterator	scapeIterator()
protected ResetableIterator	scapeIterator(int start, int limit)
ResetableIterator[]	scapeIterators(int count) Returns multiple independently thread safe scape iterators across all agents in this scape.
void	scapeNotification(ScapeEvent scapeEvent) If the scape has delegated a view to itself, called each time the scape is updated.
RandomIterator	scapeRandomIterator()
void	scapeRemoved(ScapeEvent scapeEvent) Notifies the listener that the scape has removed it.
void	scapeSetup(ScapeEvent scapeEvent) If the scape has delegated a view to itself, called each time a scape sends a "setup" method, indicating it needs to be setup for a run.
void	scapeStarted(ScapeEvent scapeEvent) If the scape has delegated a view to itself, called each time the scape is started.
void	scapeStopped(ScapeEvent scapeEvent) If the scape has delegated a view to itself, called each time the scape is stopped.
Agent	search(java.util.Comparator comparator, java.lang.Object key) Searches through the scape for an object (agent) that matches the supplied key and comparator.
Agent	searchMax(java.util.Comparator comparator) Searches through the scape for an object (agent) that has the minimum value as defined by the comparator.
Agent	searchMin(java.util.Comparator comparator) Searches through the scape for an object (agent) that has the minimum value as defined by the comparator.
void	set(Coordinate coordinate, LocatedAgent agent) Sets the agent at the specified coordinate to the supplied agent.
void	set(Coordinate coordinate, LocatedAgent agent, boolean isParent) Sets the agent at the specified coordinate to the supplied agent.
void	set(int index, java.lang.Object agent) Sets the specified location to the provided agent.
void	set(int index, java.lang.Object agent, boolean isParent) Sets the specified location to the provided agent.
void	setAgentsPerIteration(int agentsPerIteration) Sets the number of agents to iterate through each iteration cycle.
void	setAutoCreate(boolean autoCreate) Sets wether the scape is responsible for creating itself and its members, or other model components handle this.
void	setAutoRestart(boolean autoRestart) Should the scape be automatically restarted upon stopping at its stop period? Setting this value to true allows easy cycling of models for demonstrations, model explorations, etc.
void	setCellsRequestUpdates(boolean cellsRequestUpdates) Should cells request view updates manually or are all cells automatically updated every view cycle? See above.
void	setCollectStats(boolean collect) If true, turns on value (typically for statistics) collection, else turns off stat collection.
void	setCollectStats(CollectStats collectStats) Sets the value collection rule to the one supplied.
void	setDescription(java.lang.String description) Returns a long (paragraph length suggested) description of the scape.
void	setEarliestPeriod(int earliestPeriod) Sets the earliest period this scape is expected to be run at.
void	setExecutionOrder(int symbol) Sets the order of rule execution for this scape.
void	setExecutionStyle(int symbol) Sets the style that rules will be executed upon this scape.
void	setExtent(Coordinate extent) Sets the size of the scape.
void	setExtent(int xval) Sets the size of the scape.
void	setExtent(int xval, int yval) Sets the size of the scape.
void	setHome(java.lang.String home) Sets the path in which to store all scape related files.
void	setHTMLDescription(java.lang.String description) Returns a long (paragraph length suggested) description of the scape.
void	setInitialRules(VectorSelection initialRules)
void	setIterationsPerRedraw(int iterationsPerRedraw) Sets the number of iterations to perform before updating views, and propagates this setting to all scapes and views in the model.
void	setIterationsPerRedraw(int iterationsPerRedraw, boolean propagate) Sets the number of iterations to perform before updating views, and optionally propagates this setting to all scapes and views in the model.
void	setLatestPeriod(int latestPeriod) Sets the latest period this scape is expected to be run at.
void	setMembersActive(boolean membersActive) Sets whether members of this scape actively execute rules upon members.
void	setPaused(boolean pause) Sets the paused state for all parent and member scapes.
void	setPausePeriod(int pausePeriod) Causes the model to pause at the specified period.
void	setPeriodic(boolean periodic)
void	setPeriodName(java.lang.String name) Sets the name that periods are referred to by.
void	setPopulateOnCreate(boolean populateOnCreate) Sets wether the scape is responsible for populating itself.
void	setPrototypeAgent(Agent prototypeAgent) Sets the prototype agent, the agent that, in default implementations, will be cloned to populate this scape.
void	setRunner(Runner _runner)
void	setRunning(boolean running) Sets the running state for all scapes.
void	setSerializable(boolean serializable)
void	setSize(int size) Sets the size of the collection, filling with clones of prototype agent.
void	setSpace(Space space)
void	setStartOnOpen(boolean startOnOpen) Should the scape be automatically started upon opening? True by default.
void	setStartPeriod(int startPeriod) Sets the start period for this scape.
void	setStopPeriod(int stopPeriod) Sets the stop period for this scape.
void	setSuperScape(Scape superScape)
void	setThreadCount(int threadCount)
void	setViewSelf(boolean viewSelf) Sets wether the scape is a view of itself.
int	size() Returns the number of agents in the scape.
java.lang.Object[]	toArray() Returns an array containing all of the elements in this collection in proper sequence.
java.lang.Object[]	toArray(java.lang.Object[] a) Returns an array containing the current agents in this scape; the runtime type is specified by the passed array.
java.lang.String	toString() Returns a string representation of this scape.
java.util.Iterator	withinIterator(Coordinate origin, Conditional condition, boolean includeSelf, double distance) Returns an iteration across all agents the specified distance from the origin.

Methods inherited from class org.ascape.model.CellOccupant

die, findAvailableNeighbors, findNearest, findNearest, findNearest, findNearest, findNearest, findNeighbors, findNeighborsOnHost, findRandomAvailableNeighbor, findRandomNeighbor, findRandomNeighborOnHost, findWithin, findWithin, findWithin, getCoordinate, getHostCell, getHostScape, leave, moveAway, moveTo, moveToRandomLocation, moveToward, playNeighbors, playRandomNeighbor, randomWalk, randomWalkAvailable, setHostCell, setHostScape

Methods inherited from class org.ascape.model.Cell

calculateNeighbors, countNeighbors, findOccupants, findRelative, getDistance, getNeighbors, getNeighbors, getNetwork, getOccupant, hostedCondition, isAvailable, removeOccupant, setNeighbors, setNeighborsList, setNetwork, setOccupant

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, 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, 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 java.util.Collection

equals, hashCode

Methods inherited from interface org.ascape.model.event.ScapeListener

getScape

Methods inherited from interface org.ascape.model.space.Location

clearDeleteMarker, isDelete, markForDeletion, setCoordinate

Field Detail

version

public static final java.lang.String version

The current version of the Ascape framework as a whole. Returns "3.0" We keep this in Scape since it is typically the invoked class.

See Also:

Constant Field Values

copyrightAndCredits

public static final java.lang.String copyrightAndCredits

Copyright and credits information for ascape w/ HTML style tags. Again, we keep this in Scape since it is typically the invoked class.

See Also:

Constant Field Values

CREATE_RULE

public static final Rule CREATE_RULE

A rule causing the target scape and all its children scapes to be populated if auto create is set to true.

CREATE_VIEW_RULE

public static final Rule CREATE_VIEW_RULE

A rule causing viwews to be created for scape and all subscapes. Creates views for the resulting scapes.

CREATE_GRAPHIC_VIEW_RULE

public static final Rule CREATE_GRAPHIC_VIEW_RULE

A rule causing graphic views to be created for scape and all subscapes.

CREATE_SCAPE_RULE

public static final Rule CREATE_SCAPE_RULE

A rule causing the target scape to be populated.

INITIAL_RULES_RULE

public static final Rule INITIAL_RULES_RULE

A rule causing the targets initial rules to be executed on its members.

EXECUTE_RULES_RULE

public static final Rule EXECUTE_RULES_RULE

A rule causing all children and members that are scapes to iterate. Executes all rules that have been added to each scape, increments the scape counter, and collectes and stores statistics for any scapes with a statistics collection rule.

CLEAR_STATS_RULE

public static final Rule CLEAR_STATS_RULE

A rule causing all children and members that are scapes to iterate. Executes all rules that have been added to each scape, increments the scape counter, and collectes and stores statistics for any scapes with a statistics collection rule.

COLLECT_STATS_RULE

public static final Rule COLLECT_STATS_RULE

A rule causing all children and members that are scapes to iterate. Executes all rules that have been added to each scape, increments the scape counter, and collectes and stores statistics for any scapes with a statistics collection rule.

ALL_AGENTS

public static final int ALL_AGENTS

The symbol to execute rules against all agents in each iteration.

See Also:

Constant Field Values

AGENT_ORDER

public static final int AGENT_ORDER

Symbol for by agent execution order.

See Also:

Constant Field Values

RULE_ORDER

public static final int RULE_ORDER

Symbol for by rule execution order.

See Also:

Constant Field Values

COMPLETE_TOUR

public static final int COMPLETE_TOUR

Symbol for complete tour excution style.

See Also:

Constant Field Values

REPEATED_DRAW

public static final int REPEATED_DRAW

Symbol for repeated random draw execution style.

See Also:

Constant Field Values

prototypeAgent

protected Agent prototypeAgent

An agent which which may be cloned to produce members of this collection. By default, all scapes which have a known number of members are initialized with clones of this agent.

initialRules

protected VectorSelection initialRules

The rules that this scape will execute on its members upon initializtion.

agentsPerIteration

protected int agentsPerIteration

The number of agents to execute each rule across for each iteration.

COMPARE_ORDERED_QUALIFIERS

public static final java.util.Comparator COMPARE_ORDERED_QUALIFIERS

Constructor Detail

Scape

public Scape()

Constructs a scape with default list topology.

Scape

public Scape(CollectionSpace space)

Constructs a scape.

Parameters:

space - the topology for this scape

Scape

public Scape(java.lang.String name,
             Agent prototypeAgent)

Constructs a scape of provided geometry, to be populated with clones of provided agent.

Parameters:

name - a descriptive name for the scape

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

Scape

public Scape(CollectionSpace space,
             java.lang.String name,
             Agent prototypeAgent)

Constructs a scape of provided geometry, to be populated with clones of provided agent.

Parameters:

name - a descriptive name for the scape

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

space - the topology for this scape

Method Detail

getSize

public int getSize()

Returns the size, or number of agents, of this Scape.

setPrototypeAgent

public void setPrototypeAgent(Agent prototypeAgent)

Sets the prototype agent, the agent that, in default implementations, will be cloned to populate this scape. It is an error to call while the scape is running.

Parameters:

prototypeAgent - the agent whose clones will populate this scape

getPrototypeAgent

public Agent getPrototypeAgent()

Returns the agent that is cloned to populate this scape.

getAgentsPerIteration

public int getAgentsPerIteration()

Returns the number of agents to iterate through each iteration cycle. *@param returns the number of iterations per cycle

setAgentsPerIteration

public void setAgentsPerIteration(int agentsPerIteration)

Sets the number of agents to iterate through each iteration cycle. By default, set to iterate through all agents. *@param agentsPerIteration the number of agents to iterate against per cycle, ALL_AGENTS for all agents

getIterationsPerRedraw

public int getIterationsPerRedraw()

Returns the number of iterations to perform before updating views.

setIterationsPerRedraw

public void setIterationsPerRedraw(int iterationsPerRedraw)

Sets the number of iterations to perform before updating views, and propagates this setting to all scapes and views in the model.

setIterationsPerRedraw

public void setIterationsPerRedraw(int iterationsPerRedraw,
                                   boolean propagate)

Sets the number of iterations to perform before updating views, and optionally propagates this setting to all scapes and views in the model.

getExecutionOrder

public int getExecutionOrder()

Returns the execution order that has been set for this scape.

setExecutionOrder

public void setExecutionOrder(int symbol)

Sets the order of rule execution for this scape. If 'rule order', each rule is executed on every agent in turn. If 'agent order', every rule is executed on each agent in turn. Execution order can be profoundly significant to a model's dynamics. For 'synchrounous' style rules that subclass ExecuteAndUpdate, 'by rule' execution is the only order that makes sense.

Parameters:

symbol - RULE_ORDER for by rule execution, AGENT_ORDER for by agent execution

getExecutionStyle

public int getExecutionStyle()

Returns the execution style that has been set for this scape.

setExecutionStyle

public void setExecutionStyle(int symbol)

Sets the style that rules will be executed upon this scape. If complete tour, every agent is visited once and only once (assuming agents per iteration is set to 'all agents'.) If repeated draw, a random agent is picked n times for execution. (Actually, if execution order is by agent, each rule is then executed upon the picked agent, so that there are n total draws. But if execution order is by rule, then for each rule, a random agent is picked, which means that there are actually (rules X n) draws. In practice, this combination does not seem to make much sense in any case.) A complete tour style of execution seems generally more plausible, but a repeated draw approach can produce different and interesting results.

Parameters:

symbol - one of COMPLETE_TOUR or REPEATED_DRAW

getExtent

public Coordinate getExtent()

Returns the extent of the scape. The extent can be thought of as the most extreme point in the scape. For discrete scape's this will simply be the furthest cell, so that for a 20x20 grid, the extent would be {20, 20}. For continuous spaces it will be the maximum boundary of the space. For lists, it will be the size of lists. Therefore, this method should net be confused with the scape's "size". Note that scape graphs will not have useful extents, but all other scapes do.

setExtent

public void setExtent(Coordinate extent)

Sets the size of the scape. Note that scape graphs will not have useful extents, but all other scapes do. It is an error to set extent while a scape is running.

Parameters:

extent - a coordinate at the maximum extent

setExtent

public void setExtent(int xval)

Sets the size of the scape. Note that scape graphs will not have useful extents, but all other scapes do. It is an error to set extent while a scape is running.

Parameters:

xval - coordinate 1 of the extent

Throws:

java.lang.RuntimeException - if the scape is currently running

setExtent

public void setExtent(int xval,
                      int yval)

Sets the size of the scape. Note that scape graphs will not have useful extents, but all other scapes do. It is an error to set extent while a scape is running.

Parameters:

xval - coordinate 1 of the extent

yval - coordinate 2 of the extent

Throws:

java.lang.RuntimeException - if the scape is currently running

java.lang.UnsupportedOperationException - if the underlying space isn't appropriate

getName

public java.lang.String getName()

Returns the name of this scape, the model name if this is root and there is no name set.

Specified by:

getName in interface SpaceContext

Specified by:

getName in interface HasName

Overrides:

getName in class AscapeObject

Returns:

the name

getDescription

public java.lang.String getDescription()

Returns a long (paragraph length suggested) description of the scape. The root scape should describe the model as a whole; subscapes should describe themselves. Plantext. If no description is provided, return the standar toString() description. This description is automatically loaded from a file called "About[ModelClassName].html" located in the the same directory as the .class file for the model, if such a file exists. To use this feature simply create such a file and place it in the appropriate directory. You can include any normal html style tags in this file, they will be stripped from the non-html description.

setDescription

public void setDescription(java.lang.String description)

Returns a long (paragraph length suggested) description of the scape. The root scape should describe the model as a whole; subscapes should describe themselves. If no description is provided, return the standar toString() description.

getHTMLDescription

public java.lang.String getHTMLDescription()

Returns a long (paragraph length suggested) description of the scape. The root scape should describe the model as a whole; subscapes should describe themselves. Includes html tags as appropriate. This description is automatically loaded from a file called "About[ModelClassName].html" located in the the same directory as the .class file for the model, if such a file exists. To use this feature simply create such a file and place it in the appropriate directory. You can include any normal html style tags in this file, they will be stripped from the non-html description. If no description is provided, return the standar toString() description.

setHTMLDescription

public void setHTMLDescription(java.lang.String description)

Returns a long (paragraph length suggested) description of the scape. The root scape should describe the model as a whole; subscapes should describe themselves. Should include html tags as appropriate. If no description is provided, return the standar toString() description.

getRoot

public final Scape getRoot()

Returns the root of this scape, which may be this scape.

Overrides:

getRoot in class Agent

isRoot

public boolean isRoot()

Is this scape the root within its entire simulation context? That is, does this root not have any parent scapes?

isUpdateNeeded

public boolean isUpdateNeeded()

Has a view update been requested for this cell?

construct

public void construct()

Contructs the basic scape structure. Instantiates the agents, but does not populate them. It is not neccesary to set extent before initializing a collection, unless you want to have a populated vecotr to begin with.

populate

public void populate()

Populates the scape with clones of the prototype agent. Prototype agent should be set before calling this method.

createScape

public void createScape()

Create this scape; contruct it, populate it, add rules, create statistic collectors, etc. Called automatically at model construction, unless isAutoCreate is set to false. By default, automatically populates all members with clones of the prototype agent. Of course, this behavior can be overridden or embellished. To turn off the populate behavior, set populate on create to false.

See Also:

setPopulateOnCreate(boolean)

initialize

public void initialize()

Initializes the state of the scape. This is the appropriate place to put any initialization that is dependent on the state of other ascape objects. If autoCreate is true, calls createScape() on the scape. Note that for root scapes, autoCreate is always false. Objects are initialized in the order they are added to parent scapes.

Specified by:

initialize in interface Location

Overrides:

initialize in class Cell

getIteration

public final int getIteration()

Returns current count of iterations.

Overrides:

getIteration in class Agent

getPeriod

public final int getPeriod()

Returns the current period, which is just the iteration plus the period begin.

getPeriodName

public java.lang.String getPeriodName()

Returns the name that periods are referred to by.

getPeriodDescription

public java.lang.String getPeriodDescription()

Returns a string description of the current period, i.e. "Iteration 1", "Year 1900", "StarDate 3465.29."

setPeriodName

public void setPeriodName(java.lang.String name)

Sets the name that periods are referred to by.

addRule

public void addRule(Rule rule)

Adds a rule to this scape, automatically selecting it.

addRule

public void addRule(Rule rule,
                    boolean select)

Adds a rule to this scape. Allows setting whether rule be should be selected (run) automatically? If the selection is not changed, rules are executed in the order they are added.

Parameters:

rule - the rule to add

select - if rule should be run false if rule should just be made available to be run

getRules

public VectorSelection getRules()

Returns all rules that this scape might execute.

addInitialRule

public void addInitialRule(Rule rule)

Adds a rule to be executed once following initialization. Rule is automatically selected for running.

Parameters:

rule - to be executed at simulation start

addInitialRule

public void addInitialRule(Rule rule,
                           boolean select)

Adds a rule to be executed once following initialization. If the selection is not chagned, rules are executed in the order they are added.

Parameters:

rule - to be executed at simulation start

select - if rule should be run false if rule should just be made available to be run

getInitialRules

public VectorSelection getInitialRules()

Returns all the rules executed following scape initialization.

setInitialRules

public void setInitialRules(VectorSelection initialRules)

addView

public void addView(ScapeListener view)

Adds a view to this scape. Takes care of basic housekeeping, including registering view as listener, and creating window for view to be displayed within.

Parameters:

view - ComponentView to display in window

addView

public void addView(ScapeListener view,
                    boolean createFrame,
                    boolean forceGUI)

Adds a view to this scape. Takes care of basic housekeeping, including registering view as listener, and creating window for view to be displayed within. This version of the method allow the adding of a view without regard to the GUI setting. This method might be useful for instace when temporaily instrumenting a non-gui run with diagnostics. Normally addScapeListener should be used.

Parameters:

view - ComponentView to display in window

createFrame - should the view be placed within a new window frame?

forceGUI - add a GUI view witout regard to the display GUI setting

addView

public void addView(ScapeListener view,
                    boolean createFrame)

Adds a view to this scape. Takes care of basic housekeeping, including registering view as listener, and creating window for view to be displayed within. An important exception occurs when a GUI view is added and display GUI is set to false. In this case, the view will _not_ be added. This makes it easy to add views in many model components without worrying about checking for GUI display state. Views can be added regardless of the value of display GUI by using addViewForce. Note: Even with the conveneince of this method, it is often nec

Parameters:

view - ComponentView to display in window

createFrame - should the view be placed within a new window frame?

addViews

public void addViews(ScapeListener[] views)

Adds a view to this scape. Takes care of basic housekeeping, including registering view as listener, and creating window for view to be displayed within.

Parameters:

views - ComponentView to display in window

addViews

public void addViews(ScapeListener[] views,
                     boolean createFrame,
                     boolean forceGUI)

Adds an array of views to this scape. Takes care of basic housekeeping, including registering the views as listeners, and creating window for view to be displayed within. This version of the method allow the adding of a view without regard to the GUI setting. This method might be useful for instace when temporaily instrumenting a non-gui run with diagnostics. Normally addScapeListener should be used.

Parameters:

views - ComponentViews array to display in window

createFrame - should the view be placed within a new window frame?

forceGUI - add a GUI view witout regard to the dispaly GUI setting

addViews

public void addViews(ScapeListener[] views,
                     boolean createFrame)

Adds an array of views to this scape. Takes care of basic housekeeping, including registering the views as listeners, and creating window for view to be displayed within. An important exception occurs when GUI views are added and display GUI is set to false. In this case, the views will _not_ be added. This makes it easy to add views in many model components without worrying about checking for GUI display state. Views can be added regardless of the value of dispaly GUI by using addViewForce.

Parameters:

views - ComponentViews to display in window

createFrame - should the view be placed within a new window frame?

addScapeListener

public void addScapeListener(ScapeListener listener)

Adds an observer to this scape. This observer will be notified when the scape has finished iterating, and is expected to notify this scape when it has updated itself. This method also adds the scape to the listener as a control listener.

Parameters:

listener - the listern to add

addScapeListenerFirst

public void addScapeListenerFirst(ScapeListener listener)

Adds an observer to this scape. This version simple adds the new listener to the beginning of the list. This can be useful if there are listeners that need to be called first.

Parameters:

listener - the listern to add

isScapeListener

public boolean isScapeListener(ScapeListener listener)

Returns true if and only if the argument is an observer of this scape.

removeScapeListener

public void removeScapeListener(ScapeListener listener)

Removes the observer from this scape. This observer will be notified when the scape has finished iterating, and is expected to notify this scape when it has updated itself.

getScapeListeners

public java.util.ArrayList getScapeListeners()

Returns all listeners for this scape.

notifyViews

public void notifyViews(int id)

Notifies all scape listeners that this scapes state has changed. The root scape thread then waits until all listeners have been updated.

notifyViews

public void notifyViews(ScapeEvent event)

Notifies all scape listeners that this scapes state has changed. The root scape thread then waits until all listeners have been updated.

isAllViewsUpdated

public final boolean isAllViewsUpdated()

Have all views and views of memebers of this scape been updated? [The grammer is terrible, but it fits the text pattern!]

Returns:

boolean true if no views are still updating, false if not

listenerOrMemberUpdated

protected void listenerOrMemberUpdated()

Called whenever a listener or member scape of this scape has been updated. If all listeners and members have been updated, informs parent scape.

listenerUpdated

public void listenerUpdated(ScapeListener listener)

Called whenever a listener has been updated.

Parameters:

listener - the listener tha has been updated

memberUpdated

public void memberUpdated(Scape member)

Called whenever a member has been updated.

Parameters:

member - the member that has been updated

respondControl

public void respondControl(ControlEvent control)

Responds to any control events fired at this scape. Currently reacts to start, stop, pause, resume, step, quit, and restart events, as well as listener update report events. All control events except listener updates are passed up to the root. Any other events trigger an untrapped exception.

Specified by:

respondControl in interface ControlListener

Parameters:

control - the event

respondDrawFeature

public void respondDrawFeature(DrawFeatureEvent event)

This is for grid communication of changes in draw feature.

Parameters:

event -

setRunning

public void setRunning(boolean running)

Sets the running state for all scapes. Safe to call on any scape in the model; the request is propogated to the parent scape. If true, starts the parent scape's thread, which causes scape to iterate. If set false, the scape will be stopped when the current iteration is complete.

Parameters:

running - if true, starts the thread, if false, stops it.

isRunning

public boolean isRunning()

Has the scape been requested to run? Note: if false, indicates that a stop has been requested, not neccesarily that it has occured, as the simulation continues the current iteration. If you need to know when a scape has actually stopped, listen for the scapeStopped event.

Returns:

the current requested running state

setPaused

public void setPaused(boolean pause)

Sets the paused state for all parent and member scapes. Safe to call on any scape in the model; the request is propogated up to the parent scape. If set true, a pause will occur when the current iteration is complete.

Parameters:

pause - if true, pauses, otherwise resumes iterations

isPaused

public boolean isPaused()

Has the scape been requested to pause? Note: indicates that a pause has been requested, not neccesarily that the simulation is paused; it may be completing its current iteration.

Returns:

true if pause requested, false if resume requested or running normally

setEarliestPeriod

public void setEarliestPeriod(int earliestPeriod)

Sets the earliest period this scape is expected to be run at. 0 by default.

Parameters:

earliestPeriod - the lowest period value this scape can have

setLatestPeriod

public void setLatestPeriod(int latestPeriod)

Sets the latest period this scape is expected to be run at. Max of integer (effectively unlimited) by default.

Parameters:

latestPeriod - the highest period value this scape can have

isValidPeriod

public boolean isValidPeriod(int period)

Is the supplied period a valid period for this scape?

Parameters:

period - the period to test

Returns:

true if within earliest and latest periods, false otherwise

getStartPeriod

public int getStartPeriod()

Returns the period this scape begins running at. By default, the greater of earliest period and 0.

setStartPeriod

public void setStartPeriod(int startPeriod)
                    throws SpatialTemporalException

Sets the start period for this scape. The start period is the period this scape is given when a model run is started.

Parameters:

startPeriod - the period to begin runs at

Throws:

SpatialTemporalException

getStopPeriod

public int getStopPeriod()

Returns the period this scape stops running at. By default, the lesser of latest period and integer maximum value (effectively unlimited.)

setStopPeriod

public void setStopPeriod(int stopPeriod)
                   throws SpatialTemporalException

Sets the stop period for this scape. The stop period is the period that the scape is automatically stopped at. The scape may be automatically set to start agina at start value is the scape is set to restart.

Parameters:

stopPeriod - the period the scape will stop at upon reaching

Throws:

SpatialTemporalException

See Also:

setAutoRestart(boolean)

getPausePeriod

public int getPausePeriod()

Returns the period to pause on.

setPausePeriod

public void setPausePeriod(int pausePeriod)

Causes the model to pause at the specified period.

Parameters:

pausePeriod - when to pause

isStartOnOpen

public boolean isStartOnOpen()

Does the scape automatically start upon opening? True by default.

setStartOnOpen

public void setStartOnOpen(boolean startOnOpen)

Should the scape be automatically started upon opening? True by default.

Parameters:

startOnOpen - true to start the scape upon opening a model

setAutoRestart

public void setAutoRestart(boolean autoRestart)

Should the scape be automatically restarted upon stopping at its stop period? Setting this value to true allows easy cycling of models for demonstrations, model explorations, etc. See DataOutputView for an example of more sophisticated handling of multiple runs.

Parameters:

autoRestart - true to restart the scape upon reaching stop period, false to simple stop

See Also:

setStopPeriod(int)

getModel

public Runner getModel()

Deprecated. please use #getRunner().

Returns the root of this scape, which may be this scape. This was an older usage and is retained for backward compatability only. It is now not a all good name as it confuses model for a view / control component, and may be removed in the future.

getRunner

public Runner getRunner()

Returns the runtime model environment, which manages model-wide state such as run status.

Returns:

the model environment for entire model

setRunner

public void setRunner(Runner _runner)

getHome

public java.lang.String getHome()

Returns the path in which all files should by default be stored to and retrieved from. Nonstatic, so that parameter can automatically be set from command line, but backing variable is static. Default is "./", can be modified by calling setHome or providing an ascape.home java property. (This may change now since it is no longer neccesary.)

setHome

public void setHome(java.lang.String home)

Sets the path in which to store all scape related files. Nonstatic, so that parameter can automatically be set from command line, but backing variable is static.

Parameters:

home - the fully qualified path name for this scape

isMembersActive

public boolean isMembersActive()

Are members of this active scape model participants, that is, do they have rules executed upon them? Default is true.

Returns:

true if members actively execute rules, false otherwise

setMembersActive

public void setMembersActive(boolean membersActive)

Sets whether members of this scape actively execute rules upon members.

Parameters:

membersActive - true if members actively execute rules, false otherwise

isCellsRequestUpdates

public boolean isCellsRequestUpdates()

Do cells request view updates manually or are all cells automatically updated every view cycle? While requiring cells to request updates manually adds a little to complication to model design and maintenance, manual requests allow a significant boost in view performance, as all cells do not have to be drawn every cycle. False by default.

Returns:

true if cells must request updates, false if cell updates handled automatically

setCellsRequestUpdates

public void setCellsRequestUpdates(boolean cellsRequestUpdates)

Should cells request view updates manually or are all cells automatically updated every view cycle? See above. Important: If you set this value to be true, you are responsible for ensuring that the requestUpdate method is called anytime a cell's state changes such that a view may be affected. Some of these calls will be handled for you automatically, for instance, it is not neccesary to call requestUpdate when a cell moves, since the HostCell calls requestUpdates for you. Typically, you will need to request updates when the internal state of a cell changes and that is reflected in how a cell is represeneted in a view, for example, if you color an agent for wealth, you will need to call requestUpdate anytime the agent wealth changes.

Parameters:

cellsRequestUpdates - if cells should request updates, false if cell updates should be handled automatically

See Also:

LocatedAgent.requestUpdate()

execute

public void execute(java.util.List rules,
                    java.util.List agents)

Executes the provided rules on the supplied agentArray.

execute

public void execute(Rule rule,
                    java.util.List agents)

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

executeOnMembers

public void executeOnMembers()

Executes all of this scapes selected rules on its members.

executeOnMembers

public void executeOnMembers(VectorSelection ruleSelection)

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

executeOnMembers

public void executeOnMembers(Rule rule)

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

executeOnMembers

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

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

iterator

public java.util.Iterator iterator()

Returns an iterator across all agents in this scape. Note that this is simply an iterator of the backing collections members. It will have different behavior than is typically desried when iterating behavior across a scape*; so for instance, this method is not used by the internal rule mechanism. It should be perfectly adequete for tight iterations across agents when there are no additions or deletions during the iteration; for instance, when calcualting some value across a number of agents. *The iterator will not be aware of an agents deletion from the scape after its creation; this is because the scape caches these removals to improve performance. It may include agents that are added to the scape after its creation, and this is typically not desirable behavior when touring a collection of current agents.

Specified by:

iterator in interface java.lang.Iterable

Specified by:

iterator in interface java.util.Collection

Returns:

an iterator over the agents in scape order

executeOnRoot

public void executeOnRoot(Rule[] rules)

Propogates the rule for execution up to the root of the scape tree, then propogates down to all nodes.

executeOnRoot

public void executeOnRoot(Rule rule)

Propogates the rule for execution up to the root of the scape tree, then propogates down to all nodes.

search

public Agent search(java.util.Comparator comparator,
                    java.lang.Object key)

Searches through the scape for an object (agent) that matches the supplied key and comparator. Typically will return the first agent found, but this behavior is not guranteed. For now, this is implemented as a simple linear search, so search time is O(n). Future versions may allow use of a binary search where the scape is allready appropriatly sorted, or may allow a cached comparator map to be used. For now if the scape is sorted in an order matching the comparators order, you can use "getAsList" and Collections.binarySearch to get an O(log(n)) search. This code is not thread safe, but can easily be made so.

Parameters:

comparator - the Comparator to use to perfrom the search

key - the key that an agent must match in order to be returned.

searchMin

public Agent searchMin(java.util.Comparator comparator)

Searches through the scape for an object (agent) that has the minimum value as defined by the comparator.

Parameters:

comparator - the Comparator to use to determin the minimum

searchMax

public Agent searchMax(java.util.Comparator comparator)

Searches through the scape for an object (agent) that has the minimum value as defined by the comparator.

Parameters:

comparator - the Comparator to use to determin the minimum

setCollectStats

public void setCollectStats(boolean collect)

If true, turns on value (typically for statistics) collection, else turns off stat collection.

getCollectStats

public CollectStats getCollectStats()

Returns the value collection rule in effect; null if no value collection.

setCollectStats

public void setCollectStats(CollectStats collectStats)

Sets the value collection rule to the one supplied. Allows use of custom value collection rules. Please let me know if you use this..considering removal.

isAutoCreate

public boolean isAutoCreate()

Is the scape responsible for creating itself and its members, or are other classes responsible for creating the scape? If true (default) calls the createScape method on model construction, typically causing the scape to be populated with clones of prototype agent. If false, scape must be populated manually.

setAutoCreate

public void setAutoCreate(boolean autoCreate)

Sets wether the scape is responsible for creating itself and its members, or other model components handle this.

Parameters:

autoCreate - if true calls createScape at construction, otherwise model is built manually

isPopulateOnCreate

public boolean isPopulateOnCreate()

Is the scape populated when the scape is created? That is, is the populate scape method called when create scape is executed? (Typically, the populate scape method will fill each cell with clones of the prototype cell, but of course this behavior can be overidden.) True by default.

Returns:

true if the scape will be populated when scape create is called, false otherwise

setPopulateOnCreate

public void setPopulateOnCreate(boolean populateOnCreate)

Sets wether the scape is responsible for populating itself.

Parameters:

populateOnCreate - if true calls createScape at construction, otherwise model is built manually

addStatCollectors

public void addStatCollectors(StatCollector[] stats)

Adds the specified stat collectors to this scape for automatic collection by the scape. If this scape is not allready collecting stats, implicitly sets collect stats to true. Adds the stats to the stat collection rule.

Parameters:

stats - the stat collectors to add to this scape.

addStatCollectorIfNew

public StatCollector addStatCollectorIfNew(StatCollector stat)

Adds the specified stat collector iff and only if it hasn't allready been added.

Parameters:

stat - the stat collector to add to this scape. todo allow replacement (cuurent version only adds if a stat does not already exist.) possibly get rid of this once issue with multiple stat collectors is resolved.

addStatCollector

public void addStatCollector(StatCollector stat)

Adds the specified stat collector to this scape for automatic collection by the scape. If this scape is not allready collecting stats, implicitly sets collect stats to true. Adds the stat to the stat collection rule.

Parameters:

stat - the stat collector to add to this scape.

getStatCollectors

public StatCollector[] getStatCollectors()

Returns the stat collectors currently calcualting stats for this scape.

addDrawFeature

public void addDrawFeature(PlatformDrawFeature feature)

Adds the provided draw feature to this scape.

See Also:

org.ascape.util.vis.awt.DrawFeature

removeDrawFeature

public boolean removeDrawFeature(PlatformDrawFeature feature)

Removes the provided draw feature.

Parameters:

feature - the draw feature to be removed

Returns:

returns true if successful. False, otherwise.

getDrawFeaturesObservable

public java.util.Observable getDrawFeaturesObservable()

Returns an observable delegate that notifies users of draw features that a change has occurred. If you need to know when a change in draw features occur, implement observer in the appropriate class and add it to the Observerable this method returns.

getDrawFeatures

public java.util.Vector getDrawFeatures()

Returns, as a vector, the draw features available for interpretation of members of this scape.

See Also:

org.ascape.util.vis.awt.DrawFeature

getUIEnvironment

public AbstractUIEnvironment getUIEnvironment()

Returns the user environment for this scape. Returns null if no user environmnet exists; that is if we are running in a non graphic context. Otherwise, returns the same environmnet as getRuntimeEnvironment, except cast apprpriatly.

getEnvironment

public RuntimeEnvironment getEnvironment()

Returns the runtime environment, if any, for this scape.

retrieveAllAccessors

public java.util.List retrieveAllAccessors()

Returns all property accessors for this scape and recursivly for all member scapes of this scape.

retrieveAllAccessorsOrdered

public java.util.List retrieveAllAccessorsOrdered()

Returns all property accessors for this scape and recursivly for all member scapes of this scape.

retrieveModelAccessorsOrdered

public java.util.List retrieveModelAccessorsOrdered()

Returns all property accessors for this scape (excluding inappropriate/disabled accessors such as size) and recursivly for all member scapes of this scape. Can be overriden to only include those accessors that should be included in model definitions.

getAllScapes

public java.util.List getAllScapes()

Returns all scapes that are composed with this scape. All subscapes, parent scapes, and subscapes of parent scapes (more simply, the root scape and all of its subscapes) are returned.

isViewSelf

public boolean isViewSelf()

Does the scape view itself? True by default for root scape when createViews is used, false otherwise.

setViewSelf

public void setViewSelf(boolean viewSelf)

Sets wether the scape is a view of itself. True by default for root scape whn createViews is used, false otherwise. Not extensively tested yet.

Parameters:

viewSelf - should the scape view itself.

createSelfView

public void createSelfView()

Makes the scape a view of itself.

createViews

public void createViews()

Constructs the views for this scape. If display graphics is set to true, calls create graphic views. Calls create nongraphic views in either case. Override to create views for the scape. Alternativly, override the createGraphicsViews and createNonGraphicViews methods to create views appropriate for the current operating mode. This method does NOT get called when a model is deserialized, but createGraphicViews does.

createGraphicViews

public void createGraphicViews()

Override to create any graphical views for the scape. This method will not be called when display graphics is set to false, and so is a good place to put any user interface only views. If root, will setup the user interface environment and add an auto customizer.

createNonGraphicViews

public void createNonGraphicViews()

Overide to create and non-graphical views for the scape. If root, will automatically create control and counter views, create a self view, add a standand output view.

scapeInitialized

public void scapeInitialized(ScapeEvent scapeEvent)

If the scape has delegated a view to itself, called each time a scape sends a "initialize" event, indicating it has been initialized. Normally wouldn't use in this context.

Specified by:

scapeInitialized in interface ScapeListener

Parameters:

scapeEvent - the scape event

scapeSetup

public void scapeSetup(ScapeEvent scapeEvent)

If the scape has delegated a view to itself, called each time a scape sends a "setup" method, indicating it needs to be setup for a run. Possible uses include setting initial vector extents, responding to changes in user settings, and changing parameters systematically. (A view delegate to the scape is automatically created for root scapes when the standard model implementation is used.)

Specified by:

scapeSetup in interface ScapeListener

Parameters:

scapeEvent - the associated scape event

scapeIterated

public void scapeIterated(ScapeEvent scapeEvent)

If the scape has delegated a view to itself, called each time the scape is iterated. (A view delegate to the scape is automatically created for root scapes when the standard model implementation is used.)

Specified by:

scapeIterated in interface ScapeListener

Parameters:

scapeEvent - the associated scape event

scapeStarted

public void scapeStarted(ScapeEvent scapeEvent)

If the scape has delegated a view to itself, called each time the scape is started. (A view delegate to the scape is automatically created for root scapes when the standard model implementation is used.)

Specified by:

scapeStarted in interface ScapeListener

Parameters:

scapeEvent - the associated scape event

scapeStopped

public void scapeStopped(ScapeEvent scapeEvent)

If the scape has delegated a view to itself, called each time the scape is stopped. (A view delegate to the scape is automatically created for root scapes when the standard model implementation is used.)

Specified by:

scapeStopped in interface ScapeListener

Parameters:

scapeEvent - the associated scape event

scapeNotification

public void scapeNotification(ScapeEvent scapeEvent)

If the scape has delegated a view to itself, called each time the scape is updated. (A view delegate to the scape is automatically created for root scapes when the standard model implementation is used.)

Specified by:

scapeNotification in interface ScapeListener

Parameters:

scapeEvent - the associated scape event

scapeClosing

public void scapeClosing(ScapeEvent scapeEvent)

If the scape has delegated a view to itself, called each time a scape sends a "closing" event. Normally wouldn't use in this context.

Specified by:

scapeClosing in interface ScapeListener

Parameters:

scapeEvent - the associated scape event

environmentQuiting

public void environmentQuiting(ScapeEvent scapeEvent)

Method called as the entire envornmnet is about to be exited.

Specified by:

environmentQuiting in interface ScapeListener

Parameters:

scapeEvent - the associated scape event

scapeDeserialized

public void scapeDeserialized(ScapeEvent scapeEvent)

If the scape has delegated a view to itself, called each time a scape sends a "deserialized" event.

Specified by:

scapeDeserialized in interface ScapeListener

Parameters:

scapeEvent - the associated scape event

scapeAdded

public void scapeAdded(ScapeEvent scapeEvent)
                throws java.util.TooManyListenersException

Add a scape to this listener. Just here to fulfill the scape listener contract.

Specified by:

scapeAdded in interface ScapeListener

Parameters:

scapeEvent - the associated scape event

Throws:

java.util.TooManyListenersException - the too many listeners exception

scapeRemoved

public void scapeRemoved(ScapeEvent scapeEvent)

Notifies the listener that the scape has removed it. Just here to fulfill the scape listener contract.

Specified by:

scapeRemoved in interface ScapeListener

Parameters:

scapeEvent - the associated scape event

See Also:

scapeAdded

isGraphic

public boolean isGraphic()

Returns false the scape is not a graphical user interface component.

Specified by:

isGraphic in interface ScapeListener

Returns:

true, if is graphic

isLifeOfScape

public boolean isLifeOfScape()

Returns true (default) if the listener is intended to be used only for the current scape; certainly true in this case.

Specified by:

isLifeOfScape in interface ScapeListener

Returns:

true, if is life of scape

save

public void save(java.io.File file)
          throws java.io.IOException

Save the state of the scape to a file.

Throws:

java.io.IOException

save

public void save(java.io.OutputStream os)
          throws java.io.IOException

Save the state of the scape to an output stream.

Throws:

java.io.IOException

assignParameters

public void assignParameters(java.lang.String[] args,
                             boolean reportNotFound)

Sets values for the models paramters based on supplied array of key value pairs. Paramters and values are expected to be seperated with an "=", for example: "MyParameter=12".

Parameters:

args - an array of strings with paramter-value paris in the form "{paramter-name}={paramter-value}"

reportNotFound - if paramters not found should result in a console notification and if errors in invocation should be reported, false otherwise

createViews

public void createViews(java.lang.String[] args)

assignParameters

public void assignParameters(java.lang.String[] args)

Sets values for the models paramters based on supplied array of key value pairs, reporting if any of the keys (parameter names) are not found. Paramters and values are expected to be seperated with an "=", for example: "MyParameter=12".

Parameters:

args - an array of strings with paramter-value paris in the form "{paramter-name}={paramter-value}"

moveAway

public final void moveAway(LocatedAgent origin,
                           Coordinate target,
                           double distance)

Moves an agent toward the specified agent.

Parameters:

origin - the agent moving

target - the agent's target

distance - the distance to move

moveToward

public final void moveToward(LocatedAgent origin,
                             Coordinate target,
                             double distance)

Moves an agent toward the specified agent. It is an error to call this method on collections (and discrete discrete scapes not composed of HostCells.

Parameters:

origin - the agent moving

target - the agent's target

distance - the distance to move

calculateDistance

public double calculateDistance(LocatedAgent origin,
                                LocatedAgent target)

Returns the shortest distance between one agent and another.

Parameters:

origin - the starting agent

target - the ending agent

calculateDistance

public final double calculateDistance(Coordinate origin,
                                      Coordinate target)

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

Parameters:

origin - one LocatedAgent

target - another LocatedAgent

find

public final java.util.List find(Conditional condition)

Find the maximum cell of some data point. If multiple points have the same value, returns a random instance at that value.

Parameters:

condition -

Returns:

findMaximum

public final LocatedAgent findMaximum(java.util.Iterator iter,
                                      DataPoint dataPoint)

Find the maximum cell of some data point. If multiple points have the same value, returns a random instance at that value.

Parameters:

iter -

dataPoint -

Returns:

findMinimumWithin

public final LocatedAgent findMinimumWithin(Coordinate coordinate,
                                            DataPoint dataPoint,
                                            Conditional condition,
                                            boolean includeSelf,
                                            double distance)

findMaximumWithin

public final LocatedAgent findMaximumWithin(Coordinate coordinate,
                                            DataPoint dataPoint,
                                            Conditional condition,
                                            boolean includeSelf,
                                            double distance)

findMinimum

public final LocatedAgent findMinimum(java.util.Iterator iter,
                                      DataPoint dataPoint)

withinIterator

public final java.util.Iterator withinIterator(Coordinate origin,
                                               Conditional condition,
                                               boolean includeSelf,
                                               double distance)

Returns an iteration across all agents the specified distance from the origin.

Parameters:

origin - the starting cell

includeSelf - should the origin be included

distance - the distance agents must be within to be included

findMinimum

public LocatedAgent findMinimum(DataPoint point)

Returns the agent with the minimum value.

Parameters:

point - the data point to use to make the comparison for minimum

findMaximum

public LocatedAgent findMaximum(DataPoint point)

Returns the agent with the maximum value.

Parameters:

point - the data point to use to make the comparison for maximum

findNearest

public final LocatedAgent findNearest(Coordinate origin,
                                      Conditional condition,
                                      boolean includeOrigin,
                                      double distance)

Finds the nearest agent that meets some condition. Scapes 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

findRandomCoordinate

public final Coordinate findRandomCoordinate()

Returns a coordinate randomly selected from the collection's space.

findWithin

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

Returns all agents within the specified distance of the agent.

Parameters:

origin - the coordinate at the center of the search

includeSelf - whether or not the starting agent should be included in the search

distance - the distance agents must be within to be included

countWithin

public final int countWithin(Coordinate origin,
                             Conditional condition,
                             boolean includeSelf,
                             double distance)

Returns the number of agents within the specified distance of the agent that meet some condition.

Parameters:

origin - the coordinate at the center of the search

condition - the condition the agent must meet to be included

distance - the distance agents must be within to be included

hasWithin

public final boolean hasWithin(Coordinate origin,
                               Conditional condition,
                               boolean includeSelf,
                               double distance)

Returns if there are agents within the specified distance of the origin that meet some Condition.

Parameters:

origin - the coordinate at the center of the search

condition - the condition the agent must meet to be included

distance - the distance agents must be within to be included

isMutable

public final boolean isMutable()

contentsToString

public java.lang.String contentsToString()

Returns a string composed of descriptions of the contents.

toString

public java.lang.String toString()

Returns a string representation of this scape.

Overrides:

toString in class Cell

isSerializable

public boolean isSerializable()

setSerializable

public void setSerializable(boolean serializable)

clone

public java.lang.Object clone()

Overides the clone method to do a deep clone of member state so that such state will not be shared between scapes.

Specified by:

clone in interface ScapeListener

Specified by:

clone in interface Location

Overrides:

clone in class CellOccupant

Returns:

the object

findRandom

public final LocatedAgent findRandom()

Returns an agent randomly selected from the collection. If no agents exist, returns null.

findRandom

public Agent findRandom(Location excludeAgent)

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

Parameters:

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

findRandom

public final Agent findRandom(Conditional condition)

Returns an agent randomly that matches a condition. Note: If there are no agents in the collection that meet the condition, the method returns null.

Parameters:

condition - the condition that must be matched

newAgent

public Agent newAgent()

Creates a new agent in this collection by cloning the prototype agent, adding it in an arbitrary place (typically at the end of a list), and initializing it.

newAgent

public Agent newAgent(boolean randomLocation)

Creates a new agent in this collection by cloning the prototype agent, adding it to a random or arbitrary (last in most cases) place in the collection, and initializing it.

Parameters:

randomLocation - should the agent be placed in a random location, or in an arbitrary location?

size

public int size()

Returns the number of agents in the scape.

Specified by:

size in interface java.util.Collection

Returns:

the number of agents in the scape

isEmpty

public final boolean isEmpty()

Are there no agents in this scape?

Specified by:

isEmpty in interface java.util.Collection

Returns:

true if the scape is empty

contains

public final boolean contains(java.lang.Object o)

Returns true if the scape collection contains the object (agent.)

Specified by:

contains in interface java.util.Collection

Parameters:

o - the agent to search for

Returns:

true if the scape contains the agent

toArray

public final java.lang.Object[] toArray()

Returns an array containing all of the elements in this collection in proper sequence. Obeys the general contract of the Collection.toArray method.

Specified by:

toArray in interface java.util.Collection

Returns:

an array containing all of the elements in this collection in proper sequence.

See Also:

Arrays.asList(java.lang.Object[])

toArray

public final java.lang.Object[] toArray(java.lang.Object[] a)

Returns an array containing the current agents in this scape; the runtime type is specified by the passed array.

Specified by:

toArray in interface java.util.Collection

Parameters:

a - the array to copy the agents to

Returns:

an array containing the agents

Throws:

java.lang.ArrayStoreException - if the runtime type of the specified array doesn't match all agents

containsAll

public final boolean containsAll(java.util.Collection c)

Returns true if this collection contains all of agents in the specified collection.

Specified by:

containsAll in interface java.util.Collection

Parameters:

c - collection of agents to be found in the scape

Returns:

true if this scape contains all of the agents in the collection

addAll

public final boolean addAll(java.util.Collection c)

Adds all of the agent in the specified collection to the end of the scape. Assumes (but does not check) that all of the elements are instances of agent.

Specified by:

addAll in interface java.util.Collection

Parameters:

c - collection whose agents are to be added to the scape

Returns:

true if the scape had new agents added

removeAll

public final boolean removeAll(java.util.Collection c)

Removes all of the agnets contained in the collection. No attempt is made to cache the removal; the agents are all removed at once.

Specified by:

removeAll in interface java.util.Collection

Parameters:

c - collection whose agents are to be added to the scape

Returns:

true if the scape had agents (but not neccessarily all?) removed

retainAll

public final boolean retainAll(java.util.Collection c)

Retains only the elements in the scape that are in the specified collection.

Specified by:

retainAll in interface java.util.Collection

Parameters:

c - collection whose agents are to be retained in the scape

Returns:

true if this scape had agents removed

clear

public final void clear()

Removes all agents from the scape.

Specified by:

clear in interface java.util.Collection

add

public boolean add(java.lang.Object a)

Adds the supplied object (agent) to this collection.

Specified by:

add in interface java.util.Collection

add

public final boolean add(java.lang.Object agent,
                         boolean isParent)

Adds the supplied object (assumed to be an agent) to this collection. The object is assumed to be an agent, though that behavior may be loosened at some point.

Parameters:

agent - the agent to add

isParent - should this scape be made the parent scape of the agent?

Throws:

java.lang.UnsupportedOperationException - if this scape's space is not a list.

add

public final void add(int index,
                      java.lang.Object a)

Adds the supplied object (agent) to this collection.

Throws:

java.lang.UnsupportedOperationException - if this scape's space is not a list.

add

public final void add(int index,
                      java.lang.Object o,
                      boolean isParent)

Adds the supplied object (assumed to be an agent) to this collection. The object is assumed to be an agent, though that behavior may be loosened at some point.

Parameters:

o - the agent to add

isParent - should this scape be made the parent scape of the agent?

Throws:

java.lang.UnsupportedOperationException - if this scape's space is not a list.

remove

public boolean remove(java.lang.Object o)

Removes the supplied object (agent) from this collection.

Specified by:

remove in interface java.util.Collection

Parameters:

o - the agent to be removed

Returns:

true if the agent was deleted, false otherwise

remove

public final java.lang.Object remove(int index)

Removes the object at the index from this collection.

Parameters:

index - the index for the agent to remove

Throws:

java.lang.UnsupportedOperationException - if this scape's space is not a list.

get

public final LocatedAgent get(Coordinate coordinate)

Returns the cell existing at the specified coordinate.

set

public final void set(Coordinate coordinate,
                      LocatedAgent agent,
                      boolean isParent)

Sets the agent at the specified coordinate to the supplied agent.

Parameters:

coordinate - the coordinate to add the agent at

agent - the agent to add

set

public void set(Coordinate coordinate,
                LocatedAgent agent)

Sets the agent at the specified coordinate to the supplied agent.

Parameters:

coordinate - the coordinate to add the agent at

agent - the agent to add

get

public final java.lang.Object get(int index)

Returns the cell existing at the specified location. Convenience method.

Throws:

java.lang.UnsupportedOperationException - if this scape's space is not a list.

set

public void set(int index,
                java.lang.Object agent)

Sets the specified location to the provided agent. Convenience method.

Throws:

java.lang.UnsupportedOperationException - if this scape's space is not a list.

set

public void set(int index,
                java.lang.Object agent,
                boolean isParent)

Sets the specified location to the provided agent. Convenience method.

Throws:

java.lang.UnsupportedOperationException - if this scape's space is not a list.

scapeIterator

public final ResetableIterator scapeIterator()

scapeRandomIterator

public final RandomIterator scapeRandomIterator()

scapeIterator

protected final ResetableIterator scapeIterator(int start,
                                                int limit)

isPeriodic

public boolean isPeriodic()

setPeriodic

public void setPeriodic(boolean periodic)

getSuperScape

public Scape getSuperScape()

setSuperScape

public void setSuperScape(Scape superScape)

scapeIterators

public final ResetableIterator[] scapeIterators(int count)

Returns multiple independently thread safe scape iterators across all agents in this scape.

Returns:

an iterator over the agents in scape order

isListenersAndMembersCurrent

public boolean isListenersAndMembersCurrent()

getSpace

public final Space getSpace()

setSpace

public void setSpace(Space space)

setSize

public void setSize(int size)

Sets the size of the collection, filling with clones of prototype agent. It is an error to set size while a scape is running.

Parameters:

size - a coordinate describing the size of this scape

getThreadCount

public int getThreadCount()

setThreadCount

public void setThreadCount(int threadCount)

getPrototype

public Location getPrototype()

Description copied from interface: SpaceContext

Gets the prototype.

Specified by:

getPrototype in interface SpaceContext

Returns:

the prototype

isHome

public boolean isHome(Location a)

Description copied from interface: SpaceContext

Checks if is home.

Specified by:

isHome in interface SpaceContext

Parameters:

a - the a

Returns:

true, if is home

getData

public DataGroup getData()

Convenience method for obtaining sata for current run.

Returns:

the Runner's Data Group.

getUserEnvironment

public AbstractUIEnvironment getUserEnvironment()

Deprecated. retained for backward compatability, please use #getUIEnvironment instead.

Returns the UI Environment.

Returns:

a UI environment appropriate for given UI.