Heart Documentation

HeaRT (HeKatE RunTime) is an inference engine created for HeKatE Project. It provides inference mechanism, model verification, model administration and integration. To start inference process, HMR file must be created. It can be write by user in any text editor or can be generate as an output from HQEd visual editor. Result of inference process, verification or model administration can be shown to user by Prolog console message, callback mechanism or TCP/IP protocol. For more information about HMR files, inference and communication with HeaRT read HeaRT HowTo.

One of the main requirement for HeaRT interpreter was to perform full support for the HMR language specification. This format allows to represent the XTT knowledge representation as a text file format. HeaRT allows to:

• store in memory models read from HMR files
• export models to HMR files
• verify HMR syntax and logic

• HeaRT supports four types of inference process, Data Driven, Goal Driven, Fixed Order, and Token Driven
• Inference is based on assumption, that every system is deterministic, which means that there are no conflicts in it. Conflicts should now be handled during design of expert system process.
• Inference engine provides full support for ALSV(FD) attribute formulas syntax

• HeaRT supports Java integration based on callback mechanism and JPL library
• Allows direct interaction via Prolog console based on callback mechanism
• HeaRT can operate in two modes, stand-alone and as TCP/IP server
• Offering TCP/IP integration mechanism with other applications

HeaRT is not only stand - alone application. In spite of this fact models administration feature was extended.

• HeaRT allows to store and make access to one or more models
• Provides user's namespaces, that allows implementation of model access control feature
• It is possible to add, remove and modify all models stored in HeaRT's memory
• Allows to run inference process begin from any state in the model
• HeaRT has interactive inference mode, where informations about system states are taking from user in real time
• It is possible to run inference process in DDI, GDI and TDI mode

• HMR syntax and logic check based on DCG
• Model verification in complete, subsume, reduce and other modes
• Export rules to TeX file format
• Debug mode for inference process analization

The Inference module implemented in heart-infer.pl file is responsible for running models in three offered by the system modes:

• Data-Driven (forward chaining),
• Goal-Driven (backward chaining)
• Token driven which allows controlling inference by exchanging tokens between XTT tables. The Token-Driven solution is based on the idea of data flow in Petri nets - only those tables that have required number of tokens can be processed.

ALSV(FD) logic module that is implemented in heart-alsv.pl file is responsible for evaluating rules conditions.

Rules processing module implemented in heart-rules.pl file is responsible for selecting rules that firing conditions are true, and then firing them.

Communication and integration module implemented in heart-io.pl file is responsible for providing TCP/IP communication mechanism and callbacks system.

States management module implemented in heart-state.pl file provides mechaninsm for printing, adding and removing system's states; it also implements mechanism for tracking states of the system during inference process.

Verification and analysis module implements:

• simple debugging mechanism that allows tracking system's work
• export to TEX mechanism which provides functionality of exporting entire model to TEX file, providing more convinirent way of analyzing model to the user.
• logical verification of models
• syntactic analysis of HMR files

HeaRT is an inference engine. Also it provides two mechanism for integration with other applications and programming languages. HeaRT can communicate by callback mechanism and TCP/IP protocol.

• It is possible to create console or graphical user interface build on Model - View - Controler design pattern
• It is possible to share data with HeaRT from other libraries like NXT library
• It is possible to perform remote model administration by TCP protocol

Callback is a type of function that is called in certain points of application runtime. In HeaRT, callback are connected to attributes in HMR files. There are two types of callbacks in HeaRT

• in - this type of callback is used to get attribute value from user. This can be done by console or graphical user interface based on callback implementation
• out - this type of callback is used to present attribute value to user.

Callback can be use to create GUI with JPL and SWING library in Java. To make that process easier you can download JHNormal interface with example. This can be done in HeaRT HowTo documentation.

interface JHNormal
{
 public String getAttributeValue();
 public void setAttributeValue(String attributeValue);
 public String request(JHNormal t, String attribute);
}

TCP/IP protocol for HeaRT provides some useful commands

1. [hello,+client_name]. - welcome message
2. [model, getlist]. - returns list of all models that are store in HeaRT memory.
3. [model, get, +modelname, +username,]. - returns a model specified by modelname and username
4. [model,add, +modelname, +username, +'model' ]. - adds new model to HeaRT memory
5. [model,remove, +modelname, +username]. - removes a model specified by modelname and username
6. [model,run, +modelname, +username, +{ddi | gdi | tdi | foi}, +tables, +{statename | statedef} ]. - runs inference process in one of the three modes, ddi, gdi or tdi and with specified state
7. [state, add ,+modelname, +username, +statename, +statedef ]. - adds new state to specified model
8. [state, remove, +modelname, +username, +statename ]. - remove a state from specified model
9. [model,exists,+modelname, +username]. - checks if a given modelname that belongs to username is present in HeaRT storage area.
10. [model, verify, +{vcomplete | vcontradict | vsubsume | vreduce}, +modelname, +username, +schema]. - runs verification process in one of four modes, complete, contradict, subsume and reduce

Character + means, that this parameter is obligatory. Format like this +{ddi | gdi | tdi | foi} means, that you must specify one of these parameters. For more information about protocol commands, examples and return values format please read HeaRT HowTo documentation.

To make HeaRT integration easier, you can download one of three integration libraries, JHeroic, PHeroic or YHeroic.

This library was write in Java. It is one of the most popular programming language. Based on JHeroic you can build applets, desktop application or even JSP services. It is also possible to integrate HeaRT with database using ODBC, Hibernate. This library works under Microsoft Windows or Linux

public interface JHeroicInterface
{
    public static String protocolVersion = "1.0";
 
    public ArrayList<JHModel> getModelList() throws Exception;
    public String getUserModel(String userName, String modelName) throws Exception;
    public String addUserModel(String userName, String modelName, String model) throws Exception;
    public String removeUserModel(String userName, String modelName) throws Exception;
    public String runInference(String userName, String modelName, String infType, ArrayList<String> tables, String state) throws Exception;
    public String addStateToModel(String userName, String modelName, String stateName, String stateDef) throws Exception;
    public String removeStateFromModel(String userName, String modelName, String stateName) throws Exception;
    public String getProtocolVersion();
    public String verifyModel(String userName, String modelName, int mode) throws Exception;
}

YHeroic is a library created in Python script language. It has the same functionality as JHeroic but is easier to use because of Python language nature. It can be used in any Python application under Microsoft Windows or Linux.

class YHeroic:
	def __init__(self, hostname, port):
	def getModelList(self):
	def getUserModel(self, userName, modelName):
	def addUserModel(self, userName, modelName, model):
	def removeUserModel(self, userName, modelName):
	def runInference(self, userName, modelName, infType, tables, state):
	def addStateToModel(self, userName, modelName, stateName, stateDef):
	def removeStateFromModel(self, userName, modelName, stateName):
	def getProtocolVersion(self):
	def verifyModel(self, userName, modelName, mode):

PHeroic is the same library as both mentioned above but it is crated in PHP5. It can be used in any dynamic web page based on PHP scripts. This allows for easy integration with databases like MySQL, CMS systems like Wikipedia or any other language where inference engine is needed.

class PHeroic 
{
	public function __construct($hostname, $port)
	public function getModelList()
	public function getUserModel($userName,  $modelName)
	public function addUserModel($userName, $modelName, $model)
	public function removeUserModel($userName, $modelName)
	public function runInference($userName, $modelName, $infType, $tables, $state)
	public function addStateToModel($userName, $modelName, $stateName, $stateDef)
	public function removeStateFromModel($userName, $modelName, $stateName)
	public function getProtocolVersion()
	public function verifyModel($userName, $modelName, $mode)
}

To download or check examples of using these libraries check HeaRT HowTo.

A simple mechanism for testing HeaRT was implemented. It is a bash script called test.sh located in tests directory. (It can be downloaded also from here: test.sh) The script takes as a parameter a name of the file with testing data, and produces information about errors on the screen. More detailed information are stored in log.txt file automatically created by the script.

Example use of the script looks as follow:

./test.sh thermostat_test.pl

Example output with no errors:

Testing thermostat_test.pl
0
OK

Example output with errors:

Testting thermostat_test.pl
1
There was errors!
ERROR: Produced state is different that expected, for states init4 and eval4 
ERROR: Produced: [[day, wed], [hour, 3], [month, 7], [today, workday], [season, summer], [operation, nbizhrs], [thermostat_settings, 27]] 
ERROR: Expected: [[day, mon], [hour, 3], [month, 7], [season, summer], [operation, nbizhrs], [today, workday], [thermostat_settings, 27]]

The log file contains the full trajectory of the system (see example logfile).

1. A test file is a HMR file prepared for testing script.
2. A HMR file that should be a test file has to have two following lines at the begining of the file:

   :- ensure_loaded('../heart.pl').
   :- ensure_loaded('test-predicates.pl').

   The test-predicates file can be downloaded from here: test-predicates.pl

3. Special sets of states have to be added to the file. The state that is an input file have to be called initX, where X is some number. The state that describes the expected output should be called evalX, where X is a number that binds init state with eval state. Example of the testing states are shown below:

xstat init2: [day, 1].
xstat init2: [hour, 12].
xstat init2: [month, 4].

xstat eval2: [day, 1].
xstat eval2: [hour, 12].
xstat eval2: [month, 4].
xstat eval2: [season, spring].
xstat eval2: [operation, bizhrs].
xstat eval2: [today,workday].
xstat eval2: [thermostat_settings, 20].

It means that for the input state init2, we expect output state eval2.