Install Eugene Tutorial

From ExternalWiki

Version

Please use the most recent version of this tutorial at Nightly:Install Eugene Tutorial, unless you must use the code from the Tuesday, November 21, 2006 build.

The version below is for the code and data produced on Tuesday, November 21, 2006.

Introduction

An easy way to get started with UrbanSim is to follow a simple tutorial based on the Eugene-Springfield area of Oregon, USA. The following instructions will help you install the necessary components and open up the tutorial itself. Note that these instructions are for installing on a Windows operating system. Separate instructions for Linux and MacOS are forthcoming.

You will need to download and install a consistent set of the Opus and UrbanSim code, documentation, and baseyear cache. It is important to use concurrent versions of all of these, since we continue to change all three of them. If you have installed a different version of the code and it doesn’t work with the Eugene baseyear data, please install the version of code associated with the version of the database you are using.

Uninstall matplotlib

If the matplotlib Python package is already installed on your computer, uninstall it before you install the Enthought Python Edition (below). Otherwise, your maps will fail with odd error messages. The Enthought Python Edition (below) will install the appropriate matplotlib version (0.87).

To uninstall matplotlib, open the Add or Remove Programs from your Windows Control Panel. Search for "matplotlib" or "Python matplotlib" and remove it if you find it.

Uninstall Python

If you have Python installed, uninstall it.

Install Python

Note: you must install the following version of Python. It comes with some packages needed for this UrbanSim tutorial. It would be complicated to just install the additional parts. Trust us.

First, if you haven't done this already, download and install the Python Enthought Edition – Python 2.4.3 for Windows Enhanced Python Distribution from http://code.enthought.com/enthon/. This installer will install both Python and the Python packages needed by UrbanSim. In particular, it installs the Enthought Traits/TraitsUI package required by the graphical user interfaces used in this tutorial. It also installs the correct version of matplotlib.

Install Opus and UrbanSim

Install Opus and UrbanSim 4 via the Windows installer located here. Simply open the program and run the installer. This will install the Opus and UrbanSim packages into Python's site-packages directory.

Download the Cached Eugene Database

Download and unzip the Eugene 1980 baseyear cache into a "cache" directory of your own choice, such as C:\urbansim_cache. This example Eugene-Springfield database contains all of the data that UrbanSim needs to run a simulation.

Download the Eugene Model Files

Download and unzip the Eugene Opus package into a directory of your choice, such as C:\myworkspace. This Opus package contains extra Python code that specializes UrbanSim to run on the Eugene data. We recommend keeping these files in a separate location from the installed Opus packages, so that there is less risk of accidentally modifying the core Opus code.

Set Environment Variables

You now need to define the PYTHONPATH environment variable to include the path to your "workspace" directory, such as C:\myworkspace:

Open the control panel by going to Start > Control Panel.
Double click the icon labeled System. If you can’t see the System icon double click on the link labeled Switch to Classic View under the menu labeled Control Panel on the left pane, and then double click on the icon labeled System.
Choose the Advanced tab, and press the button at the bottom of the panel labeled Environment Variables.
Add or edit the variable called PYTHONPATH in the list labeled User Variables. Add the directory you chose, such as C:\myworkspace, to the beginning of the variable. If there already is an entry in the path, put a semicolon between the directories in the path.
Select OK to accept the changes to the variable.

You now have everything you need to run UrbanSim on the Eugene data, view indicators, examine the data, write new variables, and so on. Your workspace directory structure should look something like:

And your urbansim cache directory should look something like this:

Install Documentation

The last piece to install is the collection of documentation files for Opus and UrbanSim, including the Eugene tutorial. Download the documents file here and extract the files to a directory of your choice, e.g. C:\opusdocs.

Open the Tutorial

Please use the most recent version of this tutorial at Nightly:Install Eugene Tutorial, unless you must use the code from the Tuesday, November 21, 2006 build.

You are now ready to begin the tutorial. Open either the pdf version or html version of the tutorial and follow the steps; the content is the same, so simply choose the format that suits you best.

You'll find this tutorial either in the opusdocs directory you chose in the previous step or on the web at the links below:

HTML version: on the web C:\opusdocs\html\run-eugene-model\index.html
PDF version: on the web C:\opusdocs\run-eugene-model.pdf

If you have any questions, please send email to bugs at urbansim dot org, or post a message to users at urbansim dot org.

Working with MySQL

This tutorial did not use MySQL. If you need to use MySQL, please install the MySQLdb Python package, as noted in these instructions.

Problems

If you try to run a simulation and encounter an error like this:

...
 File "C:\Python24\lib\site-packages\wx-2.6-msw-unicode-enthought\wx\_windows.py", line 645, in __init__
   newobj = _windows_.new_Dialog(*args, **kwargs)
wx._core.PyNoAppError: The wx.App object must be created first!

it probably is because you do not have the right versions of Python and Python libraries installed. Uninstall Python and all Python libraries, re-install them as noted above, and try again.