edu.brook.ascape.model
Class Scape

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

Direct Known Subclasses:

AgentScape, ScapeGraph

public abstract class Scape

extends CellOccupant

implements java.lang.Runnable, ControlListener

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

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

 ScapeGraph lattice = new ScapeArray2DVonNeumann();
 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 ScapeVector, is created, and other scapes are added to it:

 root = new ScapeVector();
 root.addAgent(lattice);
 

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

 public class MyModel extends ScapeVector {
     ...
     public MyModel() {
         addAgent(lattice);
         ...
     }
 }
 

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

 lattice.addRule(new MyRule());
 

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

To observe a scape, you attach views to it:

 lattice.addView(new Overhead2DView()); 
 

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

 lattice.addView(new ControlBarView()); 
 

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

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

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

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

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

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

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

 lattice.start();
 

or send it

 lattice.respondControl(ControlEvent.REQUEST_START);
 

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

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

Examples:

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

Application:

java edu.brook.ascape.model.Scape mypath.MyModel

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:

1.9

See Also:

Rule, edu.brook.ascape.view.ScapeListener, StatCollector, CanvasView, ControlEvent, ControlBarView, Serialized Form

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.
protected boolean	autoCreate Should members of the scape be automatically created at startup?
protected boolean	cellsRequestUpdates Should cells indicate that they need to be updated manually (imroving performance significantly) or should all cells be updated every iteration.
static Rule	COLLECT_STATS_RULE A rule causing all children and members that are scapes to iterate.
protected CollectStats	collectStats The value collection rule for this scape.
static int	COMPLETE_TOUR Symbol for complete tour excution style.
static java.lang.String	copyrightAndCredits Copyright and credits information for ascape.
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.
protected static DataGroup	dataGroup Data group for all scapes.
static java.lang.String[]	demoModelClasses Common demo model class specifications.
static java.lang.String[]	demoModelNames Common demo model names.
protected java.lang.String	description A brief descripiton (including credits) of the scape or of the model, if this is root scape.
protected edu.brook.ascape.model.Scape.DrawFeatureObservable	drawFeatureObservable A delegate keeping track of observers of draw features.
protected java.util.Vector	drawFeatures A vector of features available to draw memebers of this scape.
protected static int	earliestPeriod The earliest period this scape is expected to be run at.
protected int	executionOrder Order in which rules should be executed.
protected int	executionStyle 'Stlye' of rule execution.
protected Geometry	geometry The basic geometric structure of this collection.
protected static java.lang.String	home The system path in which all files are by default stored to and retrieved from.
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 static Rule	INTERNAL_START_RULE A rule causing the target scape to set its internal state to running.
static Rule	ITERATE_SCAPE_RULE A rule causing all children and members that are scapes to iterate.
protected int	iteration The number of iterations since the scape began iterating.
protected static int	latestPeriod The latest period this scape is expected to be run at.
protected boolean	membersActive Should members of the scape be iterated against?
static Rule	PAUSE_RULE An rule causing the target scape to be paused.
protected boolean	paused Is the scape currently paused?
protected int	period The current period.
protected static java.lang.String	periodName The unit of time each iteration or period represents.
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.
protected boolean	restartAfterAutoStop Should the scape be restarted automatically after being stopped?
static Rule	RESUME_RULE An rule causing the target scape to resume execution.
static int	RULE_ORDER Symbol for by rule execution order.
protected VectorSelection	rules The rules that this scape will execute on its memebers.
protected boolean	running Is the scape currently running?
protected ScapeListener[]	scapeListeners The observers of this scape.
protected ScapeListener	selfView A view of the scape that delegates back to the scape, often null.
protected static StandardOutView	standardOutView A view that can report results to the console.
static Rule	START_RULE A rule causing the target scape to resume execution.
protected static boolean	startOnOpen Should the scape be started automatically upoin openning it? Default true.
protected static int	startPeriod Iteration to start on when restarting, creating new model, etc...
protected boolean	step Has a step been requested?
static Rule	STOP_RULE A rule causing the target scape to cease execution.
protected static int	stopPeriod Iteration to stop on.
protected int	updatedListeners Count of the number of listeners that have been updated.
protected int	updatedMembers Count of the number of members that have been updated.
static java.lang.String	version The current version of the Ascape framework as a whole.

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

MOVE_RANDOM_LOCATION_RULE, PLAY_HOST_RULE, PLAY_NEIGHBORS_RULE, PLAY_OTHER, RANDOM_WALK_AVAILABLE_RULE, RANDOM_WALK_RULE

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

cellsNear, coordinate, neighbors, thisUpdate

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

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

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

ARBITRARY_SEED, count, name, scape

Constructor Summary

Scape()
Constructs a scape.

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

Method Summary

void	addDrawFeature(DrawFeature 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	addStatCollector(StatCollector stat) Adds the specified stat collector to this scape for automatic collection by the scape.
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 createWindow) Adds a view to this scape.
void	addView(ScapeListener view, boolean createWindow, boolean showControlBar) Adds a view to this scape.
void	addViews(ScapeListener[] views) Adds a view to this scape.
void	addViews(ScapeListener[] views, boolean createWindow) Adds a view to this scape.
void	addViews(ScapeListener[] views, boolean createWindow, boolean showControlBar) Adds a view to this scape.
java.lang.Object	clone() Clones the host cell, performing deep copy of prototype agent and geometry so that they may be modified independent of the original.
void	close()
void	closeAndOpenNew() Requests the scape to open another model, closing the existing one.
static void	closeAndOpenNewFinally(Scape oldScape) Requests the scape to open another model, closing the existing one.
void	closeFinally() Closes the application; allowing views to close themseleves gracefully.
java.lang.String	contentsToString() Returns a string composed of descriptions of the contents.
static int[]	createOrder(int length) Creates a new array of ints for use as indexes for an ordered iteration.
void	createScape() Create this scape; populate it, add rules, create statistic collectors, etc..
void	createSelfView() Makes the scape a view of itself.
void	createViews() Override to create views for your agent scapes.
void	execute(java.lang.Object[] rules, Agent[] agents) Executes the provided rules on the supplied agents.
void	execute(Rule rule, Agent[] 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.
protected void	executeOnMembers(java.lang.Object[] rules) Executes the provided rules on every member of the scape, according to the rule settings and the execution order of this 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.
static void	exit() Final kill.
abstract Agent[]	getAgents() Returns all agents in the scape as an array.
Agent[]	getAgentsNear(Agent centralAgent, int distance, boolean includeSelf) Returns all agents within the specified distance from the supplied agents.
int	getAgentsPerIteration() Returns the number of agents to iterate through each iteration cycle.
java.util.Vector	getAllScapes() Returns all scapes that are composed with this scape.
CollectStats	getCollectStats() Returns the value collection rule in effect; null if no value collection.
ModelCustomizer	getCustomizer() Returns the customizer responsible for scape paramaters.
DataGroup	getData() Returns the group of all data series for the current model.
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.
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.
Geometry	getGeometry() Return the geometry of this scape.
java.lang.String	getHome() Returns the path in which all files should by default be stored to and retrieved from.
VectorSelection	getInitialRules() Returns all the rules executed following scape initialization.
int	getIteration() Returns current count of iterations.
java.lang.String	getName() Returns the name of this scape, the model name if this is root and there is no name set.
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.
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.
abstract int	getSize() Returns the number of members of this scape.
StandardOutView	getStandardOutView() Returns the customizer responsible for scape paramaters.
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.
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	isMembersActive() Are members of this active scape model participants, that is, do they have rules executed upon them? Default is true.
boolean	isMutable() Is the scape mutable, that is, can it change its structure at runtime? Returns false for base class.
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	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	isStartOnOpen(boolean startOnOpen) Does the scape automatically start upon opening? True by default.
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.
void	iterateScape() Called when each iteration completes.
abstract ScapeIterator	iterator()
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.
static void	main(java.lang.String[] args) Creates, initializes and runs the model specified in the argument.
void	memberUpdated(Scape member) Called whenever a member has been updated.
void	notifyViews(int id) Notifies all scape listeners that this scapes state has changed.
void	onSetup() 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	onStart() If the scape has delegated a view to itself, called each time the scape is started.
void	onStop() If the scape has delegated a view to itself, called each time the scape is stopped.
void	onUpdate() If the scape has delegated a view to itself, called each time the scape is updated.
static void	open() Requests the scape to open a model, providing UI for this purpose.
static Scape	open(java.lang.String modelName) Constructs, creates and runs the supplied model.
static Scape	open(java.lang.String modelName, ModelApplet applet) Constructs, creates and runs the supplied model.
static Scape	open(java.lang.String modelName, ModelApplet applet, java.lang.String[] args) Constructs and creates the supplied model.
static Scape	open(java.lang.String modelName, java.lang.String[] args) Constructs, creates and runs the supplied model.
protected void	parseSettingArgs(java.lang.String[] args)
void	pause() Requests the scape to pause.
void	quit() Exits the application; calling stop if running and allowing views to close themseleves gracefully.
void	quitFinally() Exits the application; allowing views to close themseleves gracefully.
abstract ScapeIterator	randomIterator()
int[]	randomizeOrder(int[] order) Randomizes order of the supplied int.
void	removeScapeListener(ScapeListener listener) Removes the observer from this scape.
void	requestRestart() Requests the scape to restart.
void	respondControl(ControlEvent control) Responds to any control events fired at this scape.
void	restart() Stops the scape and requests the scape to restart.
void	resume() Requests the scape to resume.
PropertyAccessor[]	retrieveAllAccessors() Returns all property accessors for this scape and recursivly for all member scapes of this scape.
PropertyAccessor[]	retrieveAllAccessorsOrdered() Returns all property accessors for this scape and recursivly for all member scapes of this scape.
void	run() The basic execution cycle of a running scape.
void	save() Requests the scape to save itself, providing UI for this purpose.
static void	save(Scape scape) To be done.
static void	save(Scape scape, java.io.File file) To be done (perhaps.) Save the state of the scape to a file.
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 memebers, or other model components handle this.
void	setAutoRestart(boolean restartAfterAutoStop) 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	setCustomizer(ModelCustomizer customizer) Sets the chart view being edited.
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	setGeometry(Geometry geometry) Sets the geometry or basic structure of this scape.
void	setHome(java.lang.String _home) Sets the path in which to store all scape related files.
void	setInternalPaused(boolean paused) Sets the paused state for all parent and memberren scapes.
void	setInternalRunning(boolean running) Sets this scape's running property.
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 paused) Sets the paused state for all parent and memberren scapes.
void	setPeriodName(java.lang.String name) Sets the name that periods are referred to by.
void	setPrototypeAgent(Agent prototypeAgent) Sets the prototype agent, the agent that, in default implementations, will be cloned to populate this scape.
void	setRunning(boolean running) Sets the running state for all scapes.
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	setViewSelf(boolean viewSelf) Sets wether the scape is a view of itself.
void	start() Requests the scape to start.
void	stop() Requests the scape to stop.
java.lang.String	toString() Returns a string representation of this scape.
void	waitForViewsUpdate() Blocks until all views of this scape and this scape's members have been updated.

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

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

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

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

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

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

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

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

Methods inherited from class java.lang.Object

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

Field Detail

version

public static final java.lang.String version

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

copyrightAndCredits

public static final java.lang.String copyrightAndCredits

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

demoModelNames

public static final java.lang.String[] demoModelNames

Common demo model names.

demoModelClasses

public static final java.lang.String[] demoModelClasses

Common demo model class specifications.

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. Creates views for the resulting scapes.

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.

ITERATE_SCAPE_RULE

public static final Rule ITERATE_SCAPE_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.

START_RULE

public static final Rule START_RULE

A rule causing the target scape to resume execution.

INTERNAL_START_RULE

protected static final Rule INTERNAL_START_RULE

A rule causing the target scape to set its internal state to running.

STOP_RULE

public static final Rule STOP_RULE

A rule causing the target scape to cease execution.

PAUSE_RULE

public static final Rule PAUSE_RULE

An rule causing the target scape to be paused.

RESUME_RULE

public static final Rule RESUME_RULE

An rule causing the target scape to resume execution.

ALL_AGENTS

public static final int ALL_AGENTS

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

AGENT_ORDER

public static final int AGENT_ORDER

Symbol for by agent execution order.

RULE_ORDER

public static final int RULE_ORDER

Symbol for by rule execution order.

COMPLETE_TOUR

public static final int COMPLETE_TOUR

Symbol for complete tour excution style.

REPEATED_DRAW

public static final int REPEATED_DRAW

Symbol for repeated random draw execution style.

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 memebrs are initialized with clones of this agent.

geometry

protected Geometry geometry

The basic geometric structure of this collection.

iteration

protected int iteration

The number of iterations since the scape began iterating.

period

protected int period

The current period.

earliestPeriod

protected static int earliestPeriod

The earliest period this scape is expected to be run at.

latestPeriod

protected static int latestPeriod

The latest period this scape is expected to be run at.

periodName

protected static java.lang.String periodName

The unit of time each iteration or period represents.

description

protected java.lang.String description

A brief descripiton (including credits) of the scape or of the model, if this is root scape.

startPeriod

protected static int startPeriod

Iteration to start on when restarting, creating new model, etc...

home

protected static java.lang.String home

The system path in which all files are by default stored to and retrieved from. The value of the system varaible ascape home.

startOnOpen

protected static boolean startOnOpen

Should the scape be started automatically upoin openning it? Default true.

standardOutView

protected static StandardOutView standardOutView

A view that can report results to the console. Every model has one by default.

stopPeriod

protected static int stopPeriod

Iteration to stop on.

restartAfterAutoStop

protected boolean restartAfterAutoStop

Should the scape be restarted automatically after being stopped?

rules

protected VectorSelection rules

The rules that this scape will execute on its memebers.

initialRules

protected VectorSelection initialRules

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

scapeListeners

protected ScapeListener[] scapeListeners

The observers of this scape. All listeners are notified when the scape is updated and given a chance to update themselves.

agentsPerIteration

protected int agentsPerIteration

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

executionOrder

protected int executionOrder

Order in which rules should be executed.

See Also:

setExecutionOrder

executionStyle

protected int executionStyle

'Stlye' of rule execution.

See Also:

setExecutionOrder

membersActive

protected boolean membersActive

Should members of the scape be iterated against?

autoCreate

protected boolean autoCreate

Should members of the scape be automatically created at startup?

cellsRequestUpdates

protected boolean cellsRequestUpdates

Should cells indicate that they need to be updated manually (imroving performance significantly) or should all cells be updated every iteration.

collectStats

protected CollectStats collectStats

The value collection rule for this scape. Null if no values should be collected.

dataGroup

protected static DataGroup dataGroup

Data group for all scapes. At some point this may be made non-static.

selfView

protected ScapeListener selfView

A view of the scape that delegates back to the scape, often null. Automatically created for root when standard model is used.

drawFeatures

protected java.util.Vector drawFeatures

A vector of features available to draw memebers of this scape.

paused

protected boolean paused

Is the scape currently paused?

running

protected boolean running

Is the scape currently running?

step

protected boolean step

Has a step been requested?

updatedListeners

protected int updatedListeners

Count of the number of listeners that have been updated. Used to determine when all listeners have been updated.

updatedMembers

protected int updatedMembers

Count of the number of members that have been updated. Used to determine when all members have been updated.

drawFeatureObservable

protected edu.brook.ascape.model.Scape.DrawFeatureObservable drawFeatureObservable

A delegate keeping track of observers of draw features.

Constructor Detail

Scape

public Scape()

Constructs a scape.

Scape

public Scape(java.lang.String name,
             Geometry geometry,
             Cell prototypeAgent)

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

Parameters:

name - a descriptive name for the scape

geometry - the strucutre of the graph

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

Method Detail

getSize

public abstract int getSize()

Returns the number of members 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. Typically, this method isn't called directly, but is used with a factory method in Geometry. (Or is it?) It is an error to call while the scape is running.

Parameters:

prototypeAgent - the agent whose clones will populate this scape

See Also:

Geometry.newScape()

getPrototypeAgent

public Agent getPrototypeAgent()

Returns the agent that is cloned to populate this scape.

setGeometry

public void setGeometry(Geometry geometry)

Sets the geometry or basic structure of this scape. Typically, this method isn't called directly, but is assigned by an implementing class or used with a factory method in Geometry.

Parameters:

geometry - the structure of this scape

See Also:

Geometry.newScape()

getGeometry

public Geometry getGeometry()

Return the geometry of this scape.

getCustomizer

public ModelCustomizer getCustomizer()

Returns the customizer responsible for scape paramaters. By default, this is the auto model customizer.

getStandardOutView

public StandardOutView getStandardOutView()

Returns the customizer responsible for scape paramaters. By default, this is the auto model customizer.

setCustomizer

public void setCustomizer(ModelCustomizer customizer)

Sets the chart view being edited.

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

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

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.

Overrides:

getName in class AscapeObject

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. If no description is provided, return the standar toString() 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.

getRoot

public 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?

createScape

public void createScape()

Create this scape; 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.

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.

Overrides:

initialize in class Cell

getIteration

public int getIteration()

Returns current count of iterations.

Overrides:

getIteration in class Agent

getPeriod

public 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 chagned, rules are executed in the order they are added.

Parameters:

rule - the rule to add

true - 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

true - 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.

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 createWindow)

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. If createWindow is false, doesn't create a window.

Parameters:

view - ComponentView to display in window

addView

public void addView(ScapeListener view,
                    boolean createWindow,
                    boolean showControlBar)

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

showControlBar - IGNORED -- this feature not currently supported...should a control bar appear in the view window?

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:

view - ComponentView to display in window

addViews

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

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. If createWindow is false, doesn't create a window.

Parameters:

view - ComponentView to display in window

addViews

public void addViews(ScapeListener[] views,
                     boolean createWindow,
                     boolean showControlBar)

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

showControlBar - IGNORED -- this feature not currently supported...should a control bar appear in the view window?

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.

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.

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.

waitForViewsUpdate

public void waitForViewsUpdate()

Blocks until all views of this scape and this scape's members 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!]

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.

See Also:

listenerOrMemberUpdated

memberUpdated

public void memberUpdated(Scape member)

Called whenever a member has been updated.

See Also:

listenerOrMemberUpdated

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

run

public void run()

The basic execution cycle of a running scape. In normal usage this methos is not called directly; use start() instead. In the current implementation, only the root scape is a running thread; all child scapes are iterated through the root thread. Synchronous, determined, reproducible behavior is expected, let us know if you encounter anything different! The cycle always begins by notifying any observers, giving them a chance to observe initial state. Then, the scape waits for the observers to update. When updated, the simulation iterates the root scape and all child scapes with their rules. Again, the scape waits for the observers to update, and the cycle of iteration and update continues until it is paused or stopped. While paused, tick events will be sent to observers, which typically chose to ignore them.

Specified by:

run in interface java.lang.Runnable

setInternalRunning

public void setInternalRunning(boolean running)

Sets this scape's running property.

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.

start

public void start()

Requests the scape to start. Note that the scape may not start immeadiatly.

See Also:

setRunning

stop

public void stop()

Requests the scape to stop. Note that the scape will not actually stop until the current iteration is complete.

See Also:

setRunning

save

public void save()

Requests the scape to save itself, providing UI for this purpose. Will not occur until the current iteration is complete. Always called on root.

requestRestart

public void requestRestart()

Requests the scape to restart.

restart

public void restart()

Stops the scape and requests the scape to restart. (Convenience method).

See Also:

setRunning

close

public void close()

closeFinally

public void closeFinally()

Closes the application; allowing views to close themseleves gracefully. Do not call this method directly unless you want to force close; call close() instead, allowing a running scape to stop gracefully. Override this method if you want to provide any scape related pre-quit finalization or clean-up.

See Also:

quit()

quit

public void quit()

Exits the application; calling stop if running and allowing views to close themseleves gracefully. Override quitFinally if you want to provide any pre-quit finalization or clean-up.

See Also:

quitFinally()

quitFinally

public void quitFinally()

Exits the application; allowing views to close themseleves gracefully. Do not call this method directly unless you want to force quit; call quit() instead, allowing a running scape to stop gracefully. Override this method if you want to provide any scape related pre-quit finalization or clean-up.

See Also:

quit()

exit

public static void exit()

Final kill. Calls System exit, which appears neccessary for vm even when code has finished.

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.

Returns:

the current requested running state

setInternalPaused

public void setInternalPaused(boolean paused)

Sets the paused state for all parent and memberren 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:

paused - If true, pauses, otherwise resumes iterations

setPaused

public void setPaused(boolean paused)

Sets the paused state for all parent and memberren 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:

paused - If true, pauses, otherwise resumes iterations

pause

public void pause()

Requests the scape to pause. (Convenience method).

See Also:

setPaused

resume

public void resume()

Requests the scape to resume. (Convenience method).

See Also:

setPaused

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

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

See Also:

setAutoRestart

isStartOnOpen

public boolean isStartOnOpen(boolean startOnOpen)

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 restartAfterAutoStop)

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:

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

See Also:

setStopPeriod

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

isMutable

public boolean isMutable()

Is the scape mutable, that is, can it change its structure at runtime? Returns false for base class.

setMembersActive

public void setMembersActive(boolean membersActive)

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

Parameters:

memebersActive - 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:

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

See Also:

Cell.requestUpdate()

createOrder

public static int[] createOrder(int length)

Creates a new array of ints for use as indexes for an ordered iteration. Initially sequential.

randomizeOrder

public int[] randomizeOrder(int[] order)

Randomizes order of the supplied int.

execute

public void execute(java.lang.Object[] rules,
                    Agent[] agents)

Executes the provided rules on the supplied agents.

execute

public void execute(Rule rule,
                    Agent[] 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

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

Executes the provided rules on every member of the scape, according to the rule settings and the execution order of this scape. This method now takes Object[] typpe which makes it easier to sue with collecitons, but less typesafe.

iterator

public abstract ScapeIterator iterator()

randomIterator

public abstract ScapeIterator randomIterator()

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.

iterateScape

public void iterateScape()

Called when each iteration completes. Increments the iteration counter, and collects statistics, if requested.

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 memebers, or other model components handle this.

Parameters:

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

getData

public DataGroup getData()

Returns the group of all data series for the current model. Guaranteed to return non-null; if a data data group does not exist, one will be created. For now, data group is static. If you need this to change (for instance, to support multiple models in the same vm), let me know.

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.

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(DrawFeature feature)

Adds the provided draw feature to this scape.

See Also:

DrawFeature

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:

DrawFeature

retrieveAllAccessors

public PropertyAccessor[] retrieveAllAccessors()

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

retrieveAllAccessorsOrdered

public PropertyAccessor[] retrieveAllAccessorsOrdered()

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

getAllScapes

public java.util.Vector 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.

getAgents

public abstract Agent[] getAgents()

Returns all agents in the scape as an array.

getAgentsNear

public Agent[] getAgentsNear(Agent centralAgent,
                             int distance,
                             boolean includeSelf)

Returns all agents within the specified distance from the supplied agents.

Parameters:

centralAgent - the agent at the search origin location.

distance - the maximimum distance that another location can be from the centralAgent to be included

includeSelf - should the centralAgent itself be included in the results of this method

isViewSelf

public boolean isViewSelf()

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

Parameters:

viewSelf - if a scape self view exists

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()

Override to create views for your agent scapes. If root, will automatically create control and counter views, create a self view, add a standand output cview, and add an auto customizer.

onSetup

public void onSetup()

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.)

See Also:

edu.brook.pd.PD2D#onSetup

onStart

public void onStart()

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.)

See Also:

edu.brook.pd.PD2D#onSetup

onStop

public void onStop()

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.)

See Also:

edu.brook.pd.PD2D#onSetup

onUpdate

public void onUpdate()

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.)

save

public static void save(Scape scape,
                        java.io.File file)
                 throws java.io.IOException

To be done (perhaps.) Save the state of the scape to a file. We may decide that simply supporting model opening (and not state) is suffecient, ( given that all models are determined anyway. Feedback is welcome.

closeAndOpenNew

public void closeAndOpenNew()

Requests the scape to open another model, closing the existing one. Will not occur until the current iteration is complete; use static forms to open concurrently. Always called on root.

closeAndOpenNewFinally

public static void closeAndOpenNewFinally(Scape oldScape)

Requests the scape to open another model, closing the existing one. Will not occur until the current iteration is complete; use static forms to open concurrently. Always called on root.

open

public static Scape open(java.lang.String modelName,
                         ModelApplet applet,
                         java.lang.String[] args)

Constructs and creates the supplied model. The supplied model name is expected to be valid; this method throws a runtime exception if the class can not be found.

Parameters:

modelName - the fully qualified name of the Java class for the model's root scape

applet - are we in an applet vm context

args - paramter arguments for the scape

open

public static Scape open(java.lang.String modelName,
                         java.lang.String[] args)

Constructs, creates and runs the supplied model.

Parameters:

modelName - the fully qualified name of the Java class for the model's root scape

args - paramter arguments for the scape

open

public static Scape open(java.lang.String modelName,
                         ModelApplet applet)

Constructs, creates and runs the supplied model.

Parameters:

modelName - the fully qualified name of the Java class for the model's root scape

applet - are we in an applet vm context

open

public static Scape open(java.lang.String modelName)

Constructs, creates and runs the supplied model.

Parameters:

modelName - the fully qualified name of the Java class for the model's root scape

open

public static void open()

Requests the scape to open a model, providing UI for this purpose.

save

public static void save(Scape scape)

To be done. Save the state of the scape to a file.

parseSettingArgs

protected void parseSettingArgs(java.lang.String[] args)

main

public static void main(java.lang.String[] args)

Creates, initializes and runs the model specified in the argument. To allow the running of a model directly from the command line, you should subclass this method as shown below:

     public MyModel extends Model {
         public static void main(String[] args) {
             (open("mypath.MyModel")).start();
         }
     }

 

Otherwise, assuming your classpath is set up correctly, to invoke a model from the command line type:

     java edu.brook.ascape.model.Scape mypath.myModel
 

Parameters:

args - at index 0; the name of the subclass of this class to run

clone

public java.lang.Object clone()

Clones the host cell, performing deep copy of prototype agent and geometry so that they may be modified independent of the original. To do: support the deep cloning of entire scapes including member cells. This is not trivial, since referred scapes and cells must be handled. Let us know if this capibility is important to you.

Overrides:

clone in class CellOccupant

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