This page holds some answers to frequently asked questions about QSIM and its extensions.

This list is undoubtedly incomplete. Please send any additional  information we should
include to qsim-maintainers@cs.utexas.edu.

Questions and answers are organized in following categories:

1.  General
2.  Installation
3.  Simulation

Q1.1:    On what platforms has QSIM been tested ?
A:    The latest version of QSIM has been tested on the following platforms

• Allegro Common Lisp on a Unix workstation running X-windows
• Allegro Common Lisp on a PC running Linux (available for free from Allegro)
• Lucid Common Lisp on a Unix workstation running X-windows
• MCL 3.9 on a MacIntosh PowerPC
• Allegro Common Lisp on a PC running Windows 95

The following components are included in release 4.0_alpha :
• QSIM (qualitative simulator)
• Q2 (semi-quantitative simulator)
• NSIM (dynamic envelope simulation)
• NUMSIM (numerical simulation of a QDE)
• TeQSIM (trajectory constraints for QSIM)
• CC (building qualitative models using component-connection models)
• C-CODE (a C-implementation of the basic QSIM algorithm)

 
Packages for maintaining separate binary directories and displaying results of a QSIM simulation:
• CMU common lisp defsystem
• POS display facility

There are also a lot of examples and extensions as well as a draft documentation included in the distribution package. The standard distribution of QSIM does NOT include QPC.  This must be obtained separately from our web site.
 

There are a lot of examples included in the distribution package. These examples require just a basic experience in Lisp. You can easily expand these examples or develop new simulation models using these examples as templates.

However, if you wish to explore the source code or even extend it, programming experience is obviously required.

The Lisp FAQ is a good starting point to learn more about Lisp.
 

The following QSIM-related mailing lists are available:
• qsim@cs.utexas.edu

A general mailing list used to announce new releases of QSIM or significant advances.
• qsim-users@cs.utexas.edu

A mailing list intended to be a discussion forum for QSIM users

To subscribe or unsubcribe from either mailing list please send your request to qsim-maintainers@cs.utexas.edu.

While there have been a number of applications using QSIM developed within industrial research labs, to our knowledge there is not an industrial application of QSIM that is in use today.  We are very interested in any potential applications.  If you are familiar with an industrial application or interested in developing one, please contact us.

There are some industrial applications which use qualitative reasoning techniques.
The European Network of Excellence MONET is a good starting point to find out more about such applications.
 

You can get a lot of information about QSIM from our web server.  There are also a lot of papers are available.
A definitely excellent source is the Qualitative Reasoning book by Ben Kuipers.
An overview of the various users of QSIM and their work can be found at our user's page.

Q2.2:    I want to use QSIM on platform on a different platform or I am using a different Lisp.  Can I do it?
A:

In general, QSIM should run on any CLTL compatible common lisp.  In practice, there are usually a few issues that must be addressed  when installing QSIM on a new lisp, but in general these issues are quite manageable.  The biggest issue is the mechanism used to display the results.  The current QSIM distribution uses the X windows system to display the results of the simulation.  Thus, if you are installing QSIM under Unix running X windows, you should be able to get QSIM to run without any real problem.  If, however, you are not using X-windows, then getting the results to display can be a little tricky.  This problem, however, can be solved by using ghostview to display the results of a simulation.  This is the technique that is used when running QSIM under ACL on Windows 95.  Basically, you need to save the display results of a simulation to a postscript file and then you need to view the file using ghostscript.

QSIM displays the results of a simulation by writing the information for a requested display to a file and then invoking an X-windows program that reads the file and displays the results.  One of the issues that must be addressed when installing QSIM on a new Lisp is that the installer must find out how to make a foreign function call from within Lisp and must add the appropriate call to the X-windows program.  The function that must be modified is called QPLOT-END-DISPLAY and it is in the file xpos/qplot-primitives.lisp.  At the end of the file, you will see a bunch of statements preceeded by the symbols "#+".  This symbol is a read-time conditional.  It causes the form that follows to be executed if and only if the string that follows the "#+" string is contained within a list maintained on the special variable *features*.  Execute *features* from the main package and you will see the contents of this list.  You must add the command for your Lisp version and then find the string in  *features* that is unique to your version of Lisp.  Currently, we have already included the command for most of the publicly available Lisp implementations.
More information is contained in the installation manual.

 If you do install QSIM on a new version of LISP, please contact us with information about your experiences.

Q2.3:    Can I install and run QSIM on my PC ?
A:

Yes, QSIM can be installed and executed on a PC. The two most common possibilities are:
1. Install Allegro Common Lisp on a PC running Windows 95
2. Install Allegro Common Lisp on a PC running Linux (ACL is free for Linux)

For the QSIM installation, please refer to the installation instructions.
 
 

There are two measures you can use to determine whether the installation is successful.  First, you can try to run an example model using the function Q.  Execute the following Lisp commands once you have completed the installation:

(in-package :qsim)
(q)

You will receive a menu.  Select the EXAMPLES option and try to run an example.
If you receive an error at this point, you may still be able to use QSIM.  The problem may just be in the mechanism used to load the example files from the menu since this can be a little flaky.

Alternatively, you can manually load a model and try to run it.  Load the file nq/source/examples/bathtub.lisp and then execute the function  (fill-a-bathtub) while in the QSIM package.
After executing a model, you will receive a menu that you can use to display the results.  Use this menu and see whether the results are displayed on your machine.
 

The core of QSIM has been implemented in various languages by various students and researchers around the world.
A rather old C implementation of the basic QSIM functionality is included in the distribution package, i.e., in the
directory source/c-code.

If you know of available ports of QSIM or parts of it, please contact us.
 

Q2.7:    Does QSIM run under ACL5.0?
A:

QSIM can be installed under Allegro Common Lisp (ACL) version 5.0.
Extract the latest QSIM distribution and extend the read-time conditional in the files nq/start-nq.lisp and c-code/defsystem-patches.lisp by "#+:allegro-v5.0" or simply replace these files by

• start-nq.lisp
• defsystem-patches.lisp.

Follow the instructions in the installation manual.
 

Q3.1:     How can I start a simulation ?
A:    To perform a simulation you must perform the following steps:

1.  Generate a model using the define-qde form.
2.  Generate a function that calls
• make-new-state (or one of the other functions use to create an initial state) to create an initial state
• qsim to perform the simulation, and
• qsim-display to display the results

Q3.2:     How can I view the results of a simulation ?
A:

The results of a simulation are displayed using the qsim-display function.  This function provides a menu that you can use to look at the behavior tree as well as individual behaviors.  The menu also provides a number of other options that can be very useful when evaluating the results of the simulation.  Some of these additions are explained in the qsim-extensions manual.

Q3.3:     QSIM predicts (too) many behaviors. What can I do to reduce the number of behaviors ?
A:    The number of behaviors generated by QSIM can be quite large and may be due to a number of reasons.
 

1. The model is too ambiguous

In general, the initial version of a model that you are developing will be too ambiguous and will often be missing a number of     constraints that you had not considered.  To refine the model, you need to analyze the results of the simulation and identify behaviors that are inconsistent with your understanding of the device being modeled.  Then you must identify the structural constraints that you expect would eliminate these models.  Some common problems include forgetting monotonic function constraints and not including corresponding values within the constraints specified.  For example, for most monotonic function constraints you will want to include (0 0) as a corresponding value.
 
2. See the papers on tractable simulation by Clancy and Kuipers.