HeaRT How To Documentation

It i possible to run inference process in one of four modes:

• Fixed order
• Data driven
• Goal driven
• Token driven

All of these modes can be run:

• from a given state, (gox/3 predicate)
• with assumption that all in attributes have callbacks written that will be fired before inference process to collect all required data (goxio/2 predicate)

All information about the inference process, and states are displayed on the console.

To run heart from a Linus console run a bash script heart located in heart directory. The script can take 4 parameters:

1. HML file to consult. Usage:

   heart somefile.pl

   After that, SWI-Prolog will be run, and file given as a parameter will be consulted.

2. Tables to be fired. Usage:

   heart somefile.pl [table1,table2,table3]

   . After that swi prolog will consult somefile.pl file, and then fire table1, table2 and table3 in DDI mode. If there were callbacks written they also will be fired.

3. Inference mode. Usage:

    heart somefile.pl [table3] gdi

   After that SWI-Prolog will consult somefile.pl file, and run GDI inference, treating table3 as a goal table.

4. Initial state. Usage:

   heart somefile.pl [table3] gdi state1

   After that SWI-Prolog will run inference in GDI mode treating table3 as a goal table and taking attributes values from state1.

• State is a state name that was defined in HMR file from which the inference suppose to start.
• Tables is a list of tables names (schemas). A meaning of this parameter depends on th inference mode selected.
  • For foi the list denotes tables that have to be processed. The order of the tables is relevant.
  • For ddi the list denotes start tables from which the inference should begin. Based on this tables, a stack of successor tables is created, and then processed. The orderer of the tables in the list is not relevant. Successor table is designated as the one that requires attribute's value that the other table (the predecessor table) produces. For instance if table2 will be successor for table1 if

    xschm table1 : [A] ==> [B].
    xschm table2 : [B] ==> [C].

  • For gdi the list denotes goal tables. Based on these tables a stack of predecessor tables is created and the processed. The order of the tables in the list is not relevant. Predecessor table is designated as the one that produces attribute's value that the other table (the successor table) requires. For instance if table1 will be predecessor for table2 if

    xschm table1 : [A] ==> [B].
    xschm table2 : [B] ==> [C].

  • For tdi the list denotes goal tables. Based on these tables a stack of predecessor tables is created, required numbers of tokens calculated and the stack of tables is processed. The order of the tables in the list is not relevant. Predecessor table is designation is based on the links between tables.
• Mode can take one of the following values:
  • foi - for Fixed ordered mode
  • ddi - for Data driven mode
  • gdi - for Goal driven mode
  • tdi - for Token driven mode

Works exactly like a gox/3, but instead of taking values of attributes from a given state, callbacks for in attributes are fired and data is acquired form the user.

There are two ways of tracking system;s work:

• Debugging the whole system's work
• Tracking a trajectory of an inference process

Debugging is a simple mechanism that writes information about current interpreter's activity to the Prolog console. A level of debugging process (a level of details and amount of information that will be displayed) can be dynamically changed from the Prolog console.

Tracking a trajectory of an inference process allows to see which rules, or tables were fired during inference process, and how did that affect system's state.

Sets the debug level

• Number is an positive integer number.

Displays message on the Prolog's console if the level given as a parameter is less or equal the level set by the debug_set_flag/1 predicate. This predicate is a development one, not used by an end-user.

• Level - a positive integer. If the Level number is less or equal the debug level set by the debug_set_flag/1 predicate, the message stored in the MessageList will be displayed; if not - nothing happens.
• MessageList - is a list of Prolog terms that have to be displayed as a message.

Sets the trajectory mode.

• Mode - a parameter that can take one of the following values:
  • simple - system's state is projected only at the beginning of the inference process and at the end.
  • table - system's state is projected at the beginning, and then after every processed table
  • full - system's state is projected at the beginning, and after every fired rule.

Saves Current system's state if the Mode parameter equals trajectory mode set by the trajectory_set_mode/1 parameter. This predicate is a development one, not used by an end-user.

• Name - is a name of an entity (table, rule) after which the projection was made (depends on the trajectory mode).
• Mode - is a name of a trajectory mode. If the name equals to the mode set by the trajectory_set_mode/1 projection is performed.

All information about an inference trajectory can be found in xtraj/1 predicate, that is automatically added to the knowledge base after inference process. xtraj/1 predicate is build as follows

 xtraj %STRING% : %LIST%.

• %STRING% is an automatically generated unique ID that can be obtained by the traj_id/1 predicate.
• %LIST% is a system's inference process trajectory. The list contains two-elements list that are built as follows:
  • [%STRING1%, %STRING2%] - where %STRING1% is a name of table or rule after which the projection were made (depends on the trajectory mode). %STRING2% is an ID of a xstat/1 element that contains information about system's state. If the trajectory mode is set to simple, the %STRING1% is start and end - at the beginning of the inference process and at the end. For other modes, the first pair [%STRING1%, %STRING2%] is always [start, %STRING2%], where %STRING2% is the state before inference started.

Therea are three ways of verifying models in HEaRT:

• Syntactic verification of the HMR files with DCG plugin
• Logical verification of a model stored in HeaRT memeory
• Verification by the user, after exporting the model to TEX

DCG is located in DCG.pl file, and it is not loaded by default by HeaRT interpreter. To use it, DCG.pl file has to be consulted by the Prolog interpreter.

Logical Verification is included in HeaRT, and all predicates offered by this plugin is available immediately after consulting main interpreter file. All information about verification process are stored in xhalv/1 predicates.

Export to TEX is included in HeaRT and is available immediately after consulting main interpreter file.

Checks if a File is a valid HMR file. As a result user gets information if the File is valid printed on the Prolog console.

• File - is a path to the HMR file to check.

Checks currently loaded model for subsumtions. Versification's reports are printed out to the Prolog's console respectively to the vreport flag that can be set by the set_vreport_flag/1. The higher the flag, the more detailed information are printed out.

All information about verification process are saved in the xhalv/1 predicate not matter what is a value of the vreport flag. Last performed verification report can be obtained by the get_current_vreport/1 predicate. ID (or name) of the xhlav/1 record can be retrieved using vid/1 fact.

• Schema - is a name of a table (schema) for which the verification is supposed to be performed.

Works exactly the same way as vsubsume/1, but checks the model for completeness.

Works exactly the same way as vsubsume/1, but checks the model for contradictions within the given table.

Works exactly the same way as vsubsume/1, but checks if there are rules that can be reduced to one rule.

Exports currently loaded model to TEX file given as a parameter. Generated file is a complete TEX file, that can be directly compile by any TEX compiler.

• Filename is a full path to the file where TEX representation of the model will be stored.

HeaRT can be run in a server mode. This mode disables a console (only information about the server work is displayed), and enables remote access to the server via TCP/IP Protocol.

Before using server mode a storage folder has to be set up. To set the folder where all models will be stored, a modification of storage_dir/1 fact is required. The fact is located in heart-io.pl file. The fact stores full path to the storage area, where all models should be stored.

Runs a server.

• Port - positive integer number that denotes a port on which the server will listen.

The protocol HOWTO is located in Protocol HOWTO.

1. [hello, +client_name]. - welcome message that client sends to HeaRT in order to obtain information about version of the protocol implemented on the server, and functionality offered by the protocol.
   As a result the client gets

   [true,[heart,hello,1.0,5,[]]]

2. [model, getlist]. - returns list of all models (with users' names that own them) that are store in HeaRT storage area.
   As a result of the the client gets following answer

   [true, [[modelname1,username1],[modelname2,username1], [ modelname3,username2]]]

   If there is no models in the storage area following answer is returned:

   [true,[]]

   . If there are errors during reading a model list, following message is returned:

   [false,]

   [false,'Error occured while reading a model list']</code>

3. [model, get, +format, +modelname, +username, +[+parts]]. - returns a model in the given format specified by modelname and username. The parts is a list defining which parts of model should be send in the responce. The following values are permitted: [all] - all parts, [atrs] all attributes, [tpes] - all types, [tbls] - all tables, [clbs] - all callbacks, [atr,id] - attribute with given id, [tpe,id] - type with given id, [tbl,id] - table with given id, [clb,id] - callback with given id.
   In example, command:

   [model, get, hml, +modelname, +username, [[atrs], [tpes], [tbl,t]]].

   get the all the attributes and types and one table with id t in HML format. The Heart accepts only:

   [model, get, hmr, +modelname, +username, [[all]]]

   
   As a result client gets following answer:

   [true,'MODEL']

   where MODEL is the requested model or part of it.
   If there is no requested model or user, follwing answer is sent:

   [false, 'Model or username does not exist.']

4. [model,exists,+modelname, +username]. - checks if a given modelname that belongs to username is present in HeaRT storage area. If it is stored by the interpreter, following answer is sent to the client:

   [true,true]

   If there is no such file

   [true,false]

   is sent back. If there is an error during this procedure, following error message is sent to the client:

   [false,'Error while checking file existence']

5. [model, add, +format, +modelname, +username, +'CONTENT_OF_THE_MODEL_IN_SPECIFIED_FORMAT' ]. - adds new model to the server storage area, overriding any existing models of the sam ename.
   If adding succeed,

   [true]

   is returned. In case of an error following error message is sent to the client:

   [false,'Error message.']

6. [model,remove, +modelname, +username]. - removes a model specified by modelname and username. After successful deletion fo the model

   [true]

   is returned. In case of an error, following error message is sent back to the client

   [false,'Error while deleting model.']

7. [model,run, +modelname, +username, +{ddi | gdi | tdi | foi}, +tables, +{statename | statedef} ]. - runs inference process for the specified by specified model in one of the four modes, ddi, gdi, tdi or foi for given tables (schemas) - (see gox/3 for details). State from which the inference should start can be either a name of the state that is located in HMR file, or a full definition of the state. The full definition of the state (statedef) should look as follows:

   [[attribute_name1, value],[attribute_name2, value] ... ]

   If the inference process succeed, the following answer is sent back to the client:

   [true,system_state, system_trajectory]

   The system_state is final state of the system defined as statedef. The system trajectory is a list of rules that were fired in the form of

   [schema_name,rule_id,schema_name, rule_id, ...]

   If there is an error during this procedure, the following error message will be sent back to the user:

   [false,'Error occurred while running model']

8. [scheme, get, +modelname, +username, +schemeName]. - returns scheme of a given name in aform of:

   [true,[[INPUT_ATTRIBUTES],[OUTPUT_ATTRIBUTES]]]

9. [state, add ,+modelname, +username, +statename, +statedef ]. - adds new state to specified model. The statedef is full state definition in a form of:

   [[attribute_name1, value],[attribute_name2, value] ... ]

   The statename is a Prolog string.

10. [state, remove, +modelname, +username, +statename ]. - remove a state from specified model. If the operation succeeds following message is sent back to the client:

    [true]

    . In case of an error, the following message is sent back:

    [false,'Error while deleting model.']

11. [model, verify, +{vcomplete | vcontradict | vsubsume | vreduce}, +modelname, +username, +schema]. - runs verification process in one of four modes, complete, contradict, subsume and reduce. If the verification succeeds the following message is sent back to the client:

     [ [report],[report], ... ]

    Where report is one xhalv/1 record. The list contains all reports generated by the verification process.
    In case of an error, following message is sent back to the client:

    [false,'Error while verifying']

Character + means, that this parameter is obligatory. Format like this +{ddi | gdi | tdi | foi} means, that you must specify one of these parameters.

All protocol's commands have to be valid Prolog's lists followed by a dot. If the command that is is sent to the server, is not a list followed by a dot, following command will be sent back to the client:

[false,'Timeout. Bad or incomplete command.']

If a valid Prolog's list is sent to the server, but it's not recognized by it, following message will be sent back to the user:

[false, 'Command not supported.']

1. Adding a model in hmr format

    [model,add,hml,'MyName','Username','xtype [ name: week_days, base: symbolic, ordered: yes, domain: [moday,tuesday], desc: \'This is only one definition\'].']. 

2. Getting a whole model in hmr format

    [model,get,hmr, 'MyName','Username', [[all]]].

   As a result following message should be returned:

   [true, [xtype[name:week_days, base:symbolic, ordered:yes, domain:[moday, tuesday], desc:'This is only one definition'].]]

3. Getting all the atrributes and types in hml format

   [model,get,hml, 'MyName','Username', [[atrs], [tpes]]]

4. Getting a two attribute with IDs att_1, att_2 and all the callbacks in the hmr format:

   [model,get,hmr, 'MyName','Username', [[clbs], [atr, atr_1], [atr, atr_2]]]

5. Getting a list of all models stored by the server:

    [model,getlist].

   Folling answer can be returned:

   [true, [[hqedmodel0, PHP], [temostat, PHP], [Termostat2, PHP], [therm-rt, PHP], [MyName, Username], [Termostat1, XTTd]]]

6. Deleting a model:

    [model,remove, 'MyName','Username'].

7. Running a model

    [model,run,'temostat','PHP',ddi, [ms,dt], s1].

   This command will run a Data-Driven inference from state s1 on the model temostat belonging to PHP user. Following return message can be sent by the server:

   [true, [[day, 3.0], [hour, 3.0], [month, [2.0]], [season, 3.0], [today, 1.0], [operation, 2.0], [thermostat_settings, 16.0]], [ms, 4, dt, 1, th, 3, os, 7]]

   Instead of state name, clinet can send a full state definition over the protocol:

    [model,run,'MyName','Username',ddi, [ms,dt,th,os], [ [day,monday], [hour,13], [month, january] ] ].

8. Verifying a model

    [model,verify, vreduce, temostat,'PHP',os].

   Following answer was sent by the server:

   [true, [[4, 'In os rule: 4 can be joined with rule 8'], [8, 'In os rule: 8 can be joined with rule 4']]]

Here you can downloads source code of all integration libraries and read how to use them in you project.

Download JHeroic (version 1.0.1): jheroic.zip

When you download file with JHeroic library there will be file called “make”. Using it you can build jar archive and then you can add it to your project. If you would like to compile this library manualy you have to:

Compile all source java files

javac *.java

Create JHeroic folder and move all class files to it

mkdir JHeroic
mv *.class JHeroic

Create jar from class files stored in JHeroic folder and MainClass

jar cfm JHeroic.jar MainClass JHeroic/

Now you can remove all class files and use jar instead

rm -r JHeroic

Download YHeroic (version 1.0.1): yheroic.zip

After downloading YHeroic library you can compy YHeroic.py file to you Python project. To include this library to it you must import it

import string, sys, YHeroic

Then you can create a new instance of YHeroic object and call evey methods from library

myLib = YHeroic.YHeroic('localhost',20044)

An example of Python script using YHeroic you can download here: yheroic-main.zip

Download PHeroic (version 1.0.1): pheroic.zip

After download library you can copy it to your web page and include to other php script

include_once('PHeroic.php');

Now you can create PHeroic object

$pheroic = new PHeroic("localhost",20044);

and run any method from library

$modelsList = $pheroic->getModelList();

Download callbackslibrary.zip. It is a NetBeans project that contains a set of default components for acquiring data from a user. The components are:

1. silder
   
2. combo box
   
3. list
   

Code is organized in following packages:

• skeleteon
  • DataFetcher.java - an abstract class that other callbcks classes have to extend
  • RequestInterface.java - the controler
  • Response.java
• callbacks
  • input
    • ComboBoxFetcher.java
    • SliderFetcher.java
    • TwoListsFetcher.java
    • ComboGUI.java
    • SliderGUI.java
    • TwoListsGUI.java

To fire one of the following GUI callbacks from Prolog, you have to copy the catalog structure to the folder where your HMR file is located, and then add xcall definition in your HMR file:

xcall callback_name: [AttName] >>> (jpl_new('skeleton.RequestInterface',[],T),
	 jpl_call(T,request,['callbacks.input.CALLBAC_NAME',PARAMETERS],Answer),
	 atom_to_term(Answer,Answer2,_),
	 alsv_new_val(AttName,Answer2)).

where

• CALLBACK_NAME - is either ComboBoxFetcher, SliderFetcher, TwoListFetcher
• PARAMETERS - is properly formated string with parameters.

1. For SliderFetcher. Domain should be defined as Min to Max:

   xcall ask_numeric_GUI : [AttName] >>> (jpl_new('skeleton.RequestInterface',[],T),
   	 alsv_domain(AttName,[Min to Max],numeric),
   	 concat_atom(['[',AttName,',',Min,',',Max,']'],Parameters),
   	 jpl_call(T,request,['callbacks.input.SliderFetcher',Parameters],Answer),
   	 atom_to_term(Answer,Answer2,_),
   	 alsv_new_val(AttName,Answer2)).

2. For ComboBoxFetcher and TwoListsFetcher.

   xcall ask_GUI : [AttName] >>> (jpl_new('skeleton.RequestInterface',[],T),
   	 alsv_domain(AttName,Domain,_),
   	 Params = [AttName|Domain],
   	 term_to_atom(Params, AtomParams),
   	 jpl_call(T,request,['callbacks.input.ComboBoxFetcher',AtomParams],Answer),
   	 atom_to_term(Answer,Answer2,_),
   	 alsv_new_val(AttName,Answer2)).