Ascape 1.9.1

Contents

Introduction

Important Information

Installation

Getting Started

User

java edu.brook.ascape.model.Scape

java edu.brook.ascape.model.Scape edu.brook.pd.PD2D

Developer

Known Issues

Acknowledgements

Contact Inforamtion

Miles Parker
The Brookings Institution
1775 Massachusettes Ave. NW
Washington, DC  20036
mparker@brook.edu
[Please send technical questions, bug reports, etc.. to the mailing list only.]

Home Page:

http://www.brook.edu/es/dynamics/models/ascape

Mailing List:

http://www.brook.edu/scripts/lyris.pl?enter=ascape&text_mode

Version History

[1.9.1]

Maintenance release:


Began work on clarifying role of euclidian space within Scape2D structure.
 

Distance code finished.
 

Get info now reflects correct version.
 

Minor agent/cell inspector bug fixes.
 


[1.9]

Extensive user-interface and functionality enhancements, including:


Added ability to dynamically view individual cell properties through a runtime cell and agent customizer. [This facility
is very similar to Swarm and RePast agent 'probes'.] To try this feature out, simply meta [option on mac, alt on PC] click on an cell
in a view. You can also drag around a view to scan the properties of different cells. If the view supports agents, agents hosted on a
praticular cell will also have their characteristics displayed. To cause the customizer to 'track' agents, shift-meta/opt/alt-click in a view.



Added sophisticated paramater sweeping support. See aa.LHVRMS for an example.



Added support for direct capture of views to quicktime movies.



Support for debug and release runtime modes, providing support for debugging or a more 'graceful' user experience on error.



Created multiple view functionality.



Improved support for data output, e.g. writing data from runnning models out to a file stream. This was allready supported, but the implementation
was confusing and spread across multiple classes.



Seperated out the run control functionality from the previously mentioned data output view, creating a new "SweepControlView" that is responsible
for managaing runs and setting paramaters. Other paramater exploration controls could easily be created using the same technique.



Added new tabbed multi-view mode. This allows you to add multiple views and have them automatically displayed within a tabbed panel.



Added 'Speed' control to control bar. This allows you to slow a model down by delaying the contol bar's reporting of its view
update. Drag the slider to the left to slow the model.



Added support for easy use of two-phase and calculated statistics.



Added navigation popup to control bar. This allows you to easily select a particualr view frame by selecting it from the popup.



Enhanced and cleaned up view functionality in Scapes, and improved general scape updating and response code.



Improvements to scape run control code.



Suport for debug and release modes, providing clean user level handling of bugs, while allowing bugs to remain unfiltered in DEBUG_RUNTIME_MODE.



All scape control events, except for the TICK event, intended for views must now be responded to, beofre the Scape is unblocked. This is a change in
the implicit Scape/View contract, and ensures that all views have a chance to respond properly to setup and close events.



Some minor performance related changes.



Fixed a bug in ScapeVector that occured when rules execute nested multiple iterations.



[1.6]

Interim version. (No official release.)

[1.5.1]

Mostly small fixes and refactoring.

Added ability to easily create calculated statistics. These statisitics can be used for summary or derivitive stat calculations.

Fixed problem with inital stat calculation.

Cleaned up stat calculation, initialization and running code and rules.

Many changes to ViewFrameBridge and related code to clarify and better support creation of web deployment package.

[1.5]

Many important and minor changes, including, but not limited to:

Ascape is no longer a 'technical release' and can be considered a full release. While there are many important
features to add, it is now essentially feature complete.

Created standard 'open' dialog functionality with easily accessible standard models..can now invoke Scape directly from command-line.

Many important model behaviors, including rules selection and execution order and style, are now accessible
at run time and can be modified through the model 'settings' customizer. Click on the globe button in the toolbar to
check this feature out.

Implemented rule execution through an iterator pattern, so that new scape topologies can be created simply
by providing an iterator, and the execution order can be safely and consistently maintained in one place (ScapeGraph.)

Changed the names for execution order from the confusing (because of association with parallel processing)
"Parallel/Serial" to "Rule Order/Agent Order". Added repeated draw functionality, and moved it from execution order
to a new property, 'execution style.'

Now deploying though InstallAnywhere installer.

Added an 'about' dialog feature that makes it possbile to easily create custom about dialogs for your models. You can
now provide about information for your model by simply creating a MyModel.html file and placing it in the appropriate
place in your model hierarchy. You can include html tags and references in this file. 

Added modest user exception alerting.

Went back to original contruction naming scheme; populate is know called createScape. Note that I did not go back
to using a seperate createRules method..seems unneccesary, esp. since rule 'availibility' and selection are now
seperate issues.


[1.3]

No public release..all changes became part of 1.5.

[1.2.5a]

Just a couple of deployment related fixes, and a minor fix for a problem that was causing models to stop
when swtiching between chart types in the chart customizer.

[1.2.5]

A number of relatively minor changes, bug fixes, and enhancements, as well as new models. The most significant change
is the addition of support for using images (GIFs) to represent cells in views. This feature will be used more in future
release. This release also includes an implementation of heatbugs that should be familiar to Swarm users.

[1.2]

I've finally made a change that I wanted to make at almost the moment I designed the initial framework. I've changed the names of
engine and observe to model and view to more explicitly reflect the overall design pattern behind them, and also because I think
they are more appropriate names.

Many rules classes have become anonymous inner class instance members of Agent or Scape.

Changed the implementation of a number of "feature" type classes so that they can be implemented
as inner and anonymous classes more easily. These include DrawFeature@, ColorFeature@, UnitIntervaldataSource@, and StatCollector@.

Changed stat collection mechanism to allow for non-automatic collection of stats. (Partially
implmented earlier.) Made StatCollector.getValue non-abstract, neccessitated by non auto collection.
Again, added support for name and auto collect member variables so that it it no longer neccesary to override these methods.

Added support for custom sliders and live model changes.

Copied many random functions to Ascape objects, using random seed, so that common random functions are
accessible to all objects without having to go through Utility.

Provided access to the random seed used for the running model, even if the seed was set arbitraily (using system time.)

Added an abstraction for data series that provides a way of customizing any aspect of a data series view.
In the initial case, it allows one to set wheteher data should be represeneted as continuous (a curve) or discrete (points.)

Implemented all the 'settings' style frames as customizer panels.

I'm considering removing the nested drawing feature from DrawFeature, since I haven't really found a use
for it. Let me know if you find it useful.

Created jar files and changed the distribution's directory structure to better conform to standard practice.

Added a standard out view which manages printing model information to the console. (You can disable this
by calling getRoot().removeScapeListener(getStandardOutView());.

Fixed many bugs, and added may minor features.

[1.1.2]

Abstracted frames and created view manager, providing simpler support for different viewing
environments, and for deploying simple applets. (See appletsupport folder.)

Fixed a bug in ScapeArray2D causing incorrect execution of random rules in parallel.

[1.1.1]

Truly random rule execution for 2D lattices (previously only supported for occupants.)

Expanded api for finding cells, etc..

Standard methods for view updates.

Many fixes to find cells etc..

Limited support for internal frames. (Broken in Win95.)

Many other minor improvements.

[1.1]

There are significant enhancements this time, including:

The ability to assign set period values (from a historical record, for example) to agents.

Data collection methods and views.

"Pluggable" drawing features, including the ability to change them at runtime from a user dialog.

Automatic discovery of model paramaters at runtime, allowing their modifcation in a running model
through user customizers, or using command line paramaters.

New models.

Updating from Previous Versions

[1.9/1.6]

Replace ...
Change any calls to view.getRunsPer() to view.getSweep().getRunsPer()
Any references to REQUEST_QUIT wwith REQUEST_CLOSE (these pprobably would not be used directly by developers.)
Any reference to ScapeEvent.REQUEST_UPDATE with ScapeEvent.RREPORT_ITERATE

No changes are neccesary to take advantage of new user interface feautures, excpet that you may want to
add more getters and setters to your Cell and Agent objects. Adding these getters and setters will allow
the customizer to automatically display and allow updating for cell values. Of course, to allow read only
access to a variable simply provide a getter but no setter.

Any Code that uses Data..View's classes will have to be modifed to use the modifed classes. This should
be straightforward, lete us know if you have any problems.

When using any of the Data..View's, the following changes should be made:


Change writeCurrentData to writeIterationData

Change writeOnStop to writeRunData

[1.5]

Replace all occurences of clearRules() with getRules().clear() or get getRules().clearSelection()
Replace        ""         SERIAL with AGENT_ORDER
Replace        ""         PARALLEL with RULE_ORDER
Replace        ""         IterationsPerCycle with AgentsPerIteration
Replace        ""         ITERATE_ALL with ALL_AGENTS
Replace        ""         AutoPopulate with AutoCreate
Replace        ""         populate with createScape


[1.2.5]

No changes should be neccesary.

[1.2]

Replace engine with model and observe with view

Replace *PopulateOnInitialization with *AutoPopulate

Replace any ViewManager with FrameManager

[Optional] You may want to replace calls to any constructors of "feature" like classes to a newer, simpler
pattern. (See above for list of classes affected.) As an example, you could change:
	new StatCollectorCondition() {
        public boolean meetsCondition(Object object) {
            return (((Player) object).strategy == PD2D.DEFECT);
        }
        public String getName() {
            return "Defect";
        }
    }
to:
	new StatCollectorCondition("Defect") {
        public boolean meetsCondition(Object object) {
            return (((Player) object).strategy == PD2D.DEFECT);
        }
    }
In general this change should apply to any classes were you were previosly required to provide an implementation
of get name. You can now provide a name in the constructor or using a setter. If you want to do this with ColorFeature,
implement ConcreteColorFeature _not_ ColorFeature, which remains an interface.

Reverse the order of a contructor's paramaters for ColorFeatureFixed to ColorFeatureFixed(String, Color)

Reverse the order of a contructor's paramaters for ColorFeatureGradiated to ColorFeatureGradiated(Color, UnitIntervalValueSource) and ColorFeatureGradiated(String, Color, UnitIntervalValueSource)

Replace any calls to [ScapeVector].newElement() with [ScapeVector].newAgent().

[Optional] From within any AscapeObject, you can replace any calls having the pattern:

    Utility.random*(getRandom(), ..);
    
with

    random*(..);

[1.1.2]

None

[1.1.1]

Just one change for exisiting models this time. A lot of method calls of the form get...() have been
changed to find...(). My future guideline will be that if a call typically returns the same result, then I'll
use get, but if it can return an arbitrary result, like findRandom, and/or can involve a lot of
calculation, like findCell or findAvailable, I'll use the find. I'd reccomend just doing a compile and
replacing anything that comes up.

get*() -> find*() for many cases in ScapeGraph and ScapeArray2D

[1.1]

In this release, I've tried to streamline things and clean things up a bit. I have made some significant
name changes once again, sorry! I felt it would be best to make these changes now, while there are just
a few users; I really think that they'll help make things more clear for later users.

You should be safe just doing a global replace for these. Many of them are new features, so you probably
haven't used them much, with the exception of ValueSeriesSource -> Stat. If your code is small, the
simplest thing to do would be to rebuild your entire project, and then just replace anything the compiler
chokes on.

If you have trouble, drop me a note and I'll try to help you fix things up.

Classes:

ScapeLatticeDiscrete -> ScapeGraph
ScapeLatticeDiscrete1D -> ScapeGraph
ScapeArray -> ScapeArray1D
CollectValues -> CollectStats

ValueSeriesSource -> StatCollector
Stat -> StatCollector
StatCount -> StatCollector
StatConditionCount -> StatCollectorCondition
Stat* -> StatCollector* (but ~CollectStat -> CollectStatCollector!)
StatCondition* -> StatCollectorCondition*

ValueSource -> DataPoint
ValueSeries -> DataSeries
SeriesGroupSelection -> DataSelection
SeriesGroupViewSelection -> DataViewSelection
SeriesGroup -> DataGroup

ColorSource -> ColorFeature
FixedColorSource -> ColorFeatureFixed
GradiatedColorSource -> ColorFeatureGradiated
DrawColorSource -> DrawColorFeature
DrawSource -> DrawFeature
GraphicsSymbol -> DrawSymbol

Methods:

getSeriesGroup -> getData
getValueName -> getName

Others:

selectGroup -> dataSelection
SelectGroup -> DataSelection