Viewing, Editing, and Storing Configurations

This page consists of design notes for a GUI and persistent storage for configurations. The design should integrate with the overall UrbanSim GUI.

Goals

  • Initially avoid changing the internal representation of configurations as used in models, unless necessary. Instead, have an alternate format used for viewing, editing, and storing, which is then converted to the internal representation. We can refactor the code that uses the internal representation later, after the GUI is working and in use.
  • Provide tree-structured graphical viewing and editing of configurations, using QT widgets, to fit into an overall QT-based GUI (along with QGIS and other packages).
  • Provide an inheritance mechanism, so that one configuration can inherit from another. Use standard object-oriented notions of inheritance.
  • Provide persistent storage for configurations.
  • Support a scheme for keeping configurations and code in sync with respect to updates. For example, if a user has a set of configurations, and we subsequently update the Opus/UrbanSim code to require an additional field in a configuration, or change a field name, we'd like to provide a straightforward way to update the existing stored configurations. Similarly, we'd like to detect that a configuration is out-of-date with respect to the code or vice versa.

Storage Format for Configurations

Several options for this are listed on a separate wiki page XmlConfigurations.

Versioning

We need a scheme for keeping configurations and code in sync with respect to updates. Examples of changes would be adding a required field to configurations, renaming or deleting a field, changing the semantics, etc. Initially we should punt on this issue, and in the release notes give directions for updating existing configurations by hand (or with the GUI if the changes lend themselves to that) to match the new spec.

Later, we could check version numbers to make sure the configuration was up-to-date, and also start providing automated updating scripts for updating configurations. This interacts with Opus version numbers -- ticket:65 is a task to re-implement these. Opus version numbers could be something like '4.1.0', or '4.1.0-dev1345'.

The xml would include a version number as an attribute of the top-level element. The code would check that the version number matched what was expected, and raise an exception if it wasn't. The update script would update the version number on xml configurations in addition to making any other needed changes. There are a couple of options for the version numbers:

  • Configuration version numbers could be completely separate from the Opus version number.
  • The xml configuration version number could be the same as the Opus version number. In this case we should introduce minor release numbers and increment whenever there was a change to the configuration format, but not necessarily make an official new stable release for each of those. (Note that we don't want to force users who are tracking the svn repository to run an update script every time they get a new revision, e.g. we don't want to be checking the dev version for development releases.)

Removing Traits Dependency

After we've replaced the existing traits-based GUI functionality, change over the traits-based configuration classes to be simple Python classes. At that point we could remove traits dependencies from the system, and remove it from the installer and installation instructions.