## 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:
  BasicModel, BasicMovementModel, City, DemographicPrisonersDilemma, Epidemic, Epidemic, Epidemic, GAS_Base, Heatbugs, Markets, Region, SpatialModel, StupidModel1, StupidModel2, StupidModel3, StupidModel5, WikiExample

    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. 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();
     lattice = newScape();
     lattice.setSpace(new Array2D());
     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. Normally you don't need to worry about controls as they are managed automatically by the framework. 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 the default list space 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.]
            }
            createGraphicViews() {
                [and graphic views to the model. Ignored when displayGraphics=false]
            }
            ...
         }
     </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:
  5.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, PLATFORM_DEFAULT_COLOR, 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, getPlatformColor, 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.