--- hekate:heart_howto [2011/09/29 11:26]
kkr
+++ hekate:heart_howto [2019/06/27 15:49]
@@ Line 1: / Line 1: @@
-====== HeaRT How To Documentation ======
-===== Working with HeaRT =====
-==== Running inference process ====
-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.
-=== Running Heart from a console ===
-To run heart from a Linus console run a bash script //heart// located in heart directory. The script can take 4 parameters:
-  - HML file to consult. Usage:<code>heart somefile.pl</code> After that, SWI-Prolog will be run, and file given as a parameter will be consulted.
-  - Tables to be fired. Usage:<code>heart somefile.pl [table1,table2,table3]</code>. 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.
-  - Inference mode. Usage: <code> heart somefile.pl [table3] gdi</code> After that SWI-Prolog will consult somefile.pl file, and run GDI inference, treating table3 as a goal table.
-  - Initial state. Usage:<code>heart somefile.pl [table3] gdi state1</code> After that SWI-Prolog will run inference in GDI mode treating table3 as a goal table and taking attributes values from state1.
-=== Commands ===
-==gox(+State, +Tables, +Mode)==
-    * **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 <code>xschm table1 : [A] ==> [B].
-xschm table2 : [B] ==> [C].</code>
-      * 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 <code>xschm table1 : [A] ==> [B].
-xschm table2 : [B] ==> [C].</code>
-      * 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
-==goxio(+Tables, +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.
-==== Tracking system's work ====
-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.
-=== Commands ===
-==debug_set_flag(+Number)==
-Sets the debug level
-  * **Number** is an positive integer number.
-==heart_debug(+Level, +MessagesList)==
-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(+Number)|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(+Number)|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.
-==trajectory_set_mode(+Mode)==
-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.
-==trajectory_projection(+Name, +Mode)==
-Saves Current system's state if the **Mode** parameter equals trajectory mode set by the [[trajectory_set_mode(+Mode)|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(+Mode)|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 <code> xtraj %STRING% : %LIST%.</code>
-  * %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.
-==== Verifying models ====
-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.
-===Commands===
-==check_grammar(+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.
-==vsubsume(+Schema)==
-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.
-==vcomplete(+Schema)==
-Works exactly the same way as [[vsubsume/1]], but checks the model for completeness.
-==vcontrdict(+Schema)==
-Works exactly the same way as [[vsubsume/1]], but checks the model for contradictions within the given table.
-==vreduce(+Schema)==
-Works exactly the same way as [[vsubsume/1]], but checks if there are rules that can be reduced to one rule.
-==io_export_TEX(+Filename)==
-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.
-==== Running HeaRT in server mode ====
-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.
-===Commands===
-==create_server(+Port)==
-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]].
-===== TCP Protocol How To =====
-==== Protocol commands ====
-  - **[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 <code>[true,[heart,hello,1.0,5,[]]]</code>
-  - **[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 <code>[true, [[modelname1,username1],[modelname2,username1], [ modelname3,username2]]]</code> If there is no models in the storage area following answer is returned: <code>[true,[]]</code>. If there are errors during reading a model list, following message is returned: <code>[false,]</code>[false,'Error occured while reading a model list']</code>
-  - **[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:<code>[model, get, hml, +modelname, +username, [[atrs], [tpes], [tbl,t]]].</code>get the all the attributes and types and one table with id ''t'' in HML format. The Heart accepts only:<code>[model, get, hmr, +modelname, +username, [[all]]]</code>\\ As a result client gets following answer: <code>[true,'MODEL']</code> where MODEL is the requested model or part of it. \\ If there is no requested model or user, follwing answer is sent: <code>[false, 'Model or username does not exist.']</code>
-  - **[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: <code>[true,true]</code> If there is no such file <code>[true,false]</code> is sent back. If there is an error during this procedure, following error message is sent to the client: <code>[false,'Error while checking file existence']</code>
-  - **[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, <code>[true]</code> is returned. In case of an error following error message is sent to the client:<code>[false,'Error message.']</code>
-  - **[model,remove, +modelname, +username].** - removes a model specified by modelname and username. After successful deletion fo the model <code>[true]</code> is returned. In case of an error, following error message is sent back to the client<code>[false,'Error while deleting model.']</code>
-  - **[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: <code>[[attribute_name1, value],[attribute_name2, value] ... ]</code> If the inference process succeed, the following answer is sent back to the client:<code>[true,system_state, system_trajectory]</code> 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 <code>[schema_name,rule_id,schema_name, rule_id, ...]</code> If there is an error during this procedure, the following error message will be sent back to the user: <code>[false,'Error occurred while running model']</code>
-  - **[state, add ,+modelname, +username, +statename, +statedef ].** - adds new state to specified model. The statedef is full state definition in a form of: <code>[[attribute_name1, value],[attribute_name2, value] ... ]</code> The statename is a Prolog string.
-  - **[state, remove, +modelname, +username, +statename ].** - remove a state from specified model. If the operation succeeds following message is sent back to the client: <code>[true]</code>. In case of an error, the following message is sent back: <code>[false,'Error while deleting model.']</code>
-  - **[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: <code> [ [report],[report], ... ]</code> 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: <code>[false,'Error while verifying']</code>
-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:<code>[false,'Timeout. Bad or incomplete command.']</code>
-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:<code>[false, 'Command not supported.']</code>
-==== Protocol examples ====
-  - Adding a model in hmr format <code> [model,add,hml'MyName','Username','xtype [ name: week_days, base: symbolic, ordered: yes, domain: [moday,tuesday], desc: \'This is only one definition\'].']. </code>
-  - Getting a whole model in hmr format <code> [model,get,hmr, 'MyName','Username', [[all]]].</code>As a result following message should be returned:<code>[true, [xtype[name:week_days, base:symbolic, ordered:yes, domain:[moday, tuesday], desc:'This is only one definition'].]]</code>
-  - Getting all the atrributes and types in hml format <code>[model,get,hml, 'MyName','Username', [[atrs], [tpes]]]</code>
-  - Getting a two attribute with IDs ''att_1'', ''att_2'' and all the callbacks in the hmr format: <code>[model,get,hmr, 'MyName','Username', [[clbs], [atr, atr_1], [atr, atr_2]]]</code>
-  - Getting a list of all models stored by the server: <code> [model,getlist].</code> Folling answer can be returned:<code>[true, [[hqedmodel0, PHP], [temostat, PHP], [Termostat2, PHP], [therm-rt, PHP], [MyName, Username], [Termostat1, XTTd]]]</code>
-  - Deleting a model: <code> [model,remove, 'MyName','Username'].</code>
-  - Running a model <code> [model,run,'temostat','PHP',ddi, [ms,dt], s1].</code>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:<code>[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]]</code> Instead of state name, clinet can send a full state definition over the protocol:<code> [model,run,'MyName','Username',ddi, [ms,dt,th,os], [ [day,monday], [hour,13], [month, january] ] ].</code>
-  - Verifying a model <code> [model,verify, vreduce, temostat,'PHP',os].</code>  Following answer was sent by the server: <code>[true, [[4, 'In os rule: 4 can be joined with rule 8'], [8, 'In os rule: 8 can be joined with rule 4']]]</code>
-==== Libraries ====
-Here you can downloads source code of all integration libraries and read how to use them in you project.
-=== JHeroic ===
-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
-<code>
-javac *.java
-</code>
-Create JHeroic folder and move all class files to it
-<code>
-mkdir JHeroic
-mv *.class JHeroic
-</code>
-Create jar from class files stored in JHeroic folder and MainClass
-<code>
-jar cfm JHeroic.jar MainClass JHeroic/
-</code>
-Now you can remove all class files and use jar instead
-<code>
-rm -r JHeroic
-</code>
-=== YHeroic ===
-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
-<code>
-import string, sys, YHeroic
-</code>
-Then you can create a new instance of YHeroic object and call evey methods from library
-<code>
-myLib = YHeroic.YHeroic('localhost',20044)
-</code>
-An example of Python script using YHeroic you can download here: {{yheroic-main.zip|}}
-=== PHeroic ===
-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
-<code>
-include_once('PHeroic.php');
-</code>
-Now you can create PHeroic object
-<code>
-$pheroic = new PHeroic("localhost",20044);
-</code>
-and run any method from library
-<code>
-$modelsList = $pheroic->getModelList();
-</code>
-===== Callbacks How To =====
-Download {{:hekate:callbackslibrary.zip|}}. It is a NetBeans project that contains a set of default components for acquiring data from a user. The components are:
-  - silder \\ {{:hekate:cases:hekate_case_cardio:hekate_case_cardio-1-clb.png|}}
-  - combo box \\ {{:hekate:hekatecases:hekate_case_thermostat:hekate_case_thermostat-1-clb.png|}}
-  - list \\ {{:hekate:hekatecases:hekate_case_cardio:hekate_case_cardio-2-clb.png|}}
-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:<code>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)).</code>
-where
-  * CALLBACK_NAME - is either ComboBoxFetcher, SliderFetcher, TwoListFetcher
-  * PARAMETERS - is properly formated string with parameters.
-===Examples===
-  - For SliderFetcher. Domain should be defined as Min to Max:<code>
-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)).</code>
-  - For ComboBoxFetcher and TwoListsFetcher. <code>
-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)).</code>
-===== Miscellaneous =====

hekate/heart_howto.txt · Last modified: 2019/06/27 15:49 (external edit)

Show page Old revisions

Media Manager Back to top

AIwiki

Menu

Dla Studentów

Old specialized AI courses

SMaDA/SMaIDA/AIDA

Informatyka (EAIiIB)

Studia Dr

Inne materialy dydaktyczne

Archiwum

Dyplomanci

Geist Season of Code

HeKatE

Public

HeKatE

Differences