Using the Code for AIMA

Starting Up

Ask whoever performed the installation procedure which of the following applies to your installation:

You have a specialized Common Lisp system that contains all the code for the book pre-loaded. In that case, you just type the name (or click on the icon) of that program to get started.
You have a Common Lisp system without the code loaded. Start up the Common Lisp and enter the following two forms:
```
 (load "aima.lisp")
 (aima-load 'name)
```
Where name is the name of a system you want to work with. The systems that are currently defined are:
```
 utilities (Automatically loaded when you load aima.lisp)
 agents (Part I: Agents and Environments)
 search (Part II: Problem Solving and Search)
 logic (Part III: Logic, Inference, and Knowledge Rep.)
 planning (Part IV: Planning and Acting)
 uncertainty (PART V: Uncertain Knowledge and Reasoning)
 learning (Part VI: Learning)
 language (Part VII, Chapters 22-23: Natural Language)
 all (All the above, except utilities)
```
Not all Lisps are clever enough to figure out when to load binary (compiled) files, and when to load lisp (source) files. If your Lisp has trouble with this, and you want to load the binary files, then instead of (aima-load 'name) you can do (aima-load-binary 'name)

Exploring the Code

Here are some suggestions for how you can get familiar with the code, experiment with it, and extend it to do more things.

There is an overview of every file, and every definition in every file. This is a good place to start browsing.
There is an alphabetical index of every definition in the code (with links to the overview), and every pre-defined Common Lisp symbol (with links to the official documentation).
You can browse the source code directly.
You can run the test cases that we have defined for each of the systems. For example, try this:
```
 (test 'agents)
```
This will print a transcript of various operations from the agent code. Besides printing the transcript, it also counts up the number of unexpected answers, and returns the total at the end. If this is not 0, it means something is wrong. The most recent run of (test 'all) on a Sparc-10 took about a minute total. But it may take longer if you have a slower machine, if you have not compiled the files first, or if you just have bad luck: many of the tests involve generating random environments, and there is a chance that a particularly difficult environment will be generated, and the agents will perform slowly on it. If you have to wait more than a minute or two for any one environment, you might want to abort out of the test and try again.
Once you see what is in the tests, you will get an idea of what functions you can run on your own.

Organization of the Code

To write new code, you need a good understanding of the code that is there, and how it is organized. Note that most of the systems are divided into four subdirectories:

algorithms Here you will find general-purpose algorithms such as the A*-search algorithm in search/algorithms/repeated.lisp This code is similar to the code you will find associated with other AI textbooks.
domains Here you will find implementations of specific problem areas or domains, such as the travelling salesperson problem. Again, this is similar to other AI code.
environments In this directory we define simulated environments in which agents can execute (via the run-environment function). The difference between the domains and environments directories is that domains is about what an agent does in analyzing a problem, while environments is about actually running a simulation. (Of course there may be some overlap, in the sense that, say, knowing the legal moves in the wumpus world is useful both for deciding what to do and for running the simulation.)
agents Here we define the agents that will run in the simulated environments. This is where we show one of the major points of the book: that AI can be seen as the science of agent design.

Each system contains a README.html file that explains what is in the system, and a test-system.lisp file. You can just browse through this file to get an idea of what the system offers, or you can evaluate the expression (test 'name) to see some actual output (and get a report if your Lisp gives an answer that we did not expect).

Extending the Code

Here are some types of programming projects you might want to take on, with advice on how to do them:

Optimize or otherwise modify existing algorithms. For example, in chart-parse.lisp, there are some comments suggesting how to speed up the algorithm. This is just like any other programming task: use your knowledge of data structures and algorithms, and make sure you meter or profile the code to know what to change.
Define a new agent for an existing environment.
Define a new environment. Create a structure type which inherits from environment (or from one of its subtypes). Then define methods for the generic functions mentioned in basic-env.lisp. An example of defining a new environment is shown in agents/environments/vacuum.lisp.

Problems?

Have fun with the code. If you find bugs or have suggestions, write to peter@norvig.com. Include a transcript of what you have loaded and executed, a backtrace of the calling stack if there is an error, and the value of the variable *aima-version*.

Version History

0.99 AIMA Code, Appomattox Version, 09-Apr-2002: Updated Franz-specific conditional code to work with newest version.
0.98 AIMA Code, Thelonious Monk Birthday Version, 10-Oct-2001: Line 190 of agents/environments/grid-env.lisp changed to
((xy-p where) (parse-whats env where whats))
Previously it had the parameter order confused. Thanks to Yoshihiro Ota.
0.97 AIMA Code, Shot Heard 'Round the World Day Version, 03-Oct-2001: Removed support of Lispworks from the documentation. Lispworks appears to have a bug with the treatment of special variables (it shows up in logic/algorithims/tell-ask.lisp). If someone sends me a workaround I'll add it. For now, I'll just limit official support to Allegro and MCL (although you certainly can get the code to work in other Lisps).
0.96 AIMA Code, Palindrome Day Version, 10-02-2001: Replaced get-setf-method with get-setf-expansion, as per the ANSI standard. Updated documentation. The biggest error was that I didn't mention that you need to do a aima-load before the aima-compile. Tested code with Allegro, Lispworks, and MCL. It loads, compiles, and tests out ok in all three Lisps.
0.95 AIMA Code, Patriots Day Version, 21-Apr-1997: Four main changes: First, modified much of the code to use an object-oriented approach using defmethod. We limited this to single-inheritance, and single dispatch (on the first argument). This is both because we wanted it to work even in old Lisps that don't have a CLOS (Common Lisp Object System) implementation, and because we wanted it to be familiar to programmers who are used to object-oriented approaches in other languages such as Java or Smalltalk. Second, added extensive machine-generated HTML documentation, of which this mpage is part. Third, the directory structure was re-organized. Fourth, completed the code for a chart parser and grammar in the language directory. There were also some minor bug fixes, e.g. David Palmer pointed out that the wumpus agent can pick up the wumpus when it is trying to pick up the gold.
0.94 AIMA Code, Ground Hog Day Version, 2-Feb-1995: Ray Liere and David Palmer pointed out that non-square grid-environments were incorrectly initialized in grid-env.lisp. Roger Kirchner pointed out that the precedence of the | operator in infix.lisp was wrong. John Sterling discovered some files where we still referenced the USER package, and suggested removing the (declare (ignore contained?)) from DEFSETF GRID-CONTENTS to avoid a warning in MCL. The infix reader was enhanced to turn lowercase symbols into variables, i.e. "F(x,C)" turns into (F ?X C). Some code that answers exercises from the book was moved out of the code repository and into the soon-to-be-released instructor's manual. Added file "index.txt", which lists all functions, types, and variables, the page they appear on in the book, and the file they appear in.
0.93 AIMA Code, Oral Roberts' Birthday Version, 24-Jan-1995: There were problems with older Common Lisps stemming from the difference between the USER and CL-USER packages, so I just decided to eliminate all code that deals with packages. There were a few other changes to fix problems in Clisp. When compiling under Clisp, if you get an error message that says a macro is being redefined, just type "continue". After you've compiled once, you won't get the message again when you load. The code has now been tested in Harlequin, Lucid, Franz, AKCL and Clisp.
0.92 AIMA Code, Martin Luther King Day Version, 16-Jan-1995: Added new game-playing and logic code, and new systems for learning and uncertainty. Added some documentation and minor changes to agents and search code.
0.91 AIMA Code, Newer Years Version, 5-Jan-1995: Fixed a few minor bugs that resulted from too-quickly merging two versions of the code, and added some (declare (ignore variable))s. Tested in several implementations of Common Lisp: Harlequin, Lucid, Franz, and AKCL.
0.9 AIMA Code, New Years Version, 4-Jan-1995: A preliminary version, released because several instructors were starting courses this week. Only the AGENTS and SEARCH systems are supported, although unsupported code for other systems is included.

AIMA Home Contact Russell & Norvig What's new Changed 10/02/2001