Documentation: Programming guide

Handling knowledgebases

This chapter will provide you with the most basic concepts to use SPIRIT knowledgebases.

Using the SPIRIT Package

The SPIRIT library is a collection of classes to manage knowledge bases. These classes can be used by an arbitrary application that shall be supplied with probabilistic knowledge. Such an application has to create and manage an instance of the class KBase. The other public classes of SPIRIT are of less importance now. To make use of any SPIRIT class, add the following line to the relevant modules of your code: 

import spirit.*;

Make sure that compiler and runtime machine are able to find the SPIRIT library. If necessary, add a link to the SPIRIT library file to your local CLASSPATH variable.

Error Handling

The class KBase provides some dozens of methods to manage variables and rules, to learn those rules into an internal structure of probabilistic tables and to respond to more or less complex queries according to the actual state of knowledge. The methods of the KBase class could be called in any order, but some might not behave as originally supposed to do. There are certain situations in which calling some methods will not be of success, i.e. an error will be reported. Therefore nearly each class of KBase is able to throw an exception. Exceptions in SPIRIT are of the class KBE. When a KBE is thrown by a KBase method, it includes some valuable information on the cause of the error (an error code). You do not need to worry on making an illegal method call, but you should ensure a correct error handling. Here is an example of a typical error handling sequence: 

try {
  kb.deleteRule(-1);    »An illegal method call«
  }
catch(KBE kbe) {
  System.out.println("SPIRIT call error! (" + kbe + ")");
  }

Here the deleteRule method is called with an illegal parameter (-1) and will throw an exception. This is caught in the catch block and treated in a suitable way. As usual, the compiler will report an error when you call any KBE-throwing SPIRIT method without a matching catch block.
In most of the following code segments, we will ignore error handling.

Creating, and Deleting Knowledge Bases

To create a knowledge base, just make a declaration such as 

KBase kb = new KBase(); »Create a new instance of KBase»

This newly created knowledge base will not contain any variables and rules and should by supplied by some knowledge soon.
If you want to get rid of a knowlegde base, just ensure that your program does not contain any references to the KBase instance. The runtime system's garbage collection will clean up the memory used for it. For example use the sequence 

kb = null;    »Remove the only reference to the KBase instance«
System.gc();  »Call the system's garbage collection to clean up«

to remove a KBase from memory.

Loading, Merging, and Saving Knowlegde Bases

It is possible to write a KBase into an arbitrary OutputStream and restore it later. Writing means, that the whole KBase is stored as a text file including all variables and rules, each supplied with additonal state information. Reading means that the variables and rules from an InputStream are added to the actual KBase. Thus it is possible to merge several knowledge bases.

The following example saves a KBase to a new file 

OutputStream os = new FileOutputStream("aldi.kb");
kb.exportFile(os);

This file can be reloaded using 

KBase kb = new KBase();
InputStream is = new FileInputStream("aldi.kb");
kb.importFile(is);

Loading does not include an exact restoration of the KBase's state when saved. You might have to rebuild and reinit the LEG structure for that. Each file contains information on the LEG structure (i.e. the enumeration of the variables) and the actual knowlegde (stored in the compact form of the rules' alphas). To restore the state of knowlegde provided by the file, use the following calls after the import operation 

kb.rebuild();  »Rebuild using the enumeration from the file«
kb.reinit();   »Reinit using the alphas from the file«

If you want to reject the actual knowlegde from the file, you should call the KBase.reset method to ensure that the rule's alphas are reset and the LEGs set to uniform distribution.

Adding User Information to a Knowledge Base

It is possible to add arbitrary "user" information to a KBase. You are able to add arbitrary Objects which could be interpreted as comments, some important values or options or whatsoever to an instance of the KBase class. Those informations will be written to the SPIRIT file and restored later. Even though it is possible to add any Object to a KBase, they are imported from a file as Strings only.

Each application importing a file enriched by such information might ignore or use the values. The user infos are addressed using a "tag" word (an arbitrary String). The following example adds some comments to the KBase. 

kb.setUserInfo("comment", "This KBase explains the sense of life.");
kb.setUserInfo("author", "Douglas Adams");
kb.setUserInfo("answer", new Double(42));

Those informations can be read by a call like the following: 

String author = kb.getUserInfo("author").toString();