{{ :pub:software:heartdroid:heart-logo-no-borders.png?150|}}
====== HeaRTDroid ======
HeaRTDroid is a rule-based inference engine both for **Android mobile devices, and desktop solutions** that is based on [[http://ai.ia.agh.edu.pl/wiki/hekate:heart|HeaRT]] inference engine. It is distributed under the GNU General Public License.
Modelling is supported with  [[http://heartdroid.re/hwed/|HWEd web editor]]. \\
HeaRTDroid can be downloaded from [[https://github.com/sbobek/heartdroid|Github]]

Key features are:
  * Inference support for **XTT2 rule representation** that is based on the **Attributive Logic with Set Values** and its textual representation called **[[pub:software:heartdroid:tutorials:hmr_quickstart|HMR+]]**
  * Pure Java implementation that allows for **integration with any Java code**, including **[[pub:software:heartdroid:tutorials:android_quickstart|Android applications]]**
  * Integration with [[http://awareframework.com|AWARE framework]] in a form of **[[pub:software:heartdroid:tutorials:aware_quickstart|HeaRTDroid Plug-In]]**
  * **[[pub:software:heartdroid:tutorials:callbacks|Callbacks mechanism]]** based on Java reflection, that allows for easy integration with other systems
  * **[[pub:software:heartdroid:tutorials:uncertainty_cf|Uncertainty]]** management mechanism based on modified certainty factors algebra and probabilistic approach
  * Capturing dynamics with **[[pub:software:heartdroid:tutorials:statistics|statistical functions]]** and **[[pub:software:heartdroid:tutorials:tbo|time parametrised operators]]**
  * **[[pub:software:heartdroid:tutorials:inference_config|Different inference modes]]** and real time **reasoning triggers**
  * Interactive commandline shell **[[.:pub:software:heartdroid:tutorials:haquna|HaQuNa]]**
  * Under development: **Server mode** with TCP/IP protocol and REST API.


===== QuickStart =====

==== Running the inference ====
The example below is available in the ''StandardReasoningDemo.java'' in the examples package: {{:pub:software:heartdroid:examples.zip|}}.
To run the examples you have to have the latest version of [[pub:software:heartdroid:downloads:start|HeaRTDroid library]].
It shows how to perform reasoning using Java API.
For interactive commandline shell tutorial see [[pub:software:heartdroid:tutorials:haquna|HaQuNa]].

=== Creating the model ===
The HeaRTDroid inference engine uses [[http://ai.ia.agh.edu.pl/wiki/hekate:hmr|HMR]] models. These can be created with the visual editor called HWEd. Please refer to [[.:#creating_your_own_model|Creating your own model]] for details how to create the [[http://ai.ia.agh.edu.pl/wiki/hekate:xtt2|XTT2]] model.

For the purpose of the tutorial you can use the XTT2 model given here: {{:pub:software:heartdroid:threat-monitor.hmr|}}
The model was used for context-aware filtering threats from the Social Threat Monitor system created as a part of the [[http://www.indect-project.eu/|Indect]] project. You can find more about the model and the system in the paper: [[http://link.springer.com/article/10.1007%2Fs11042-014-2060-9|Mobile Context-based Framework for Threat Monitoring in Urban Environment with Social Threat Monitor.]]

The visualisation of the ''threat-monitor.hmr'' model is presented below:

{{:pub:software:heartdroid:threat-monitor.png?700|}}

=== Loading a model to HeaRTDroid===
First, you need to get the HeaRTDroid inference engine. 
  - You can download the latest version in a form of JAR file, that can be added to your Java project from: or [[.:downloads:start|Download section]] or from [[https://bitbucket.org/sbobek/heartdroid/downloads|Bitbucket]]
  - You can download the source code with a command line: <code bash>hg clone https://bitbucket.org/sbobek/heartdroid/</code>

After that you can create an ''XTT2Model'' object and load the ''HMR'' file to it:
<code java>
try {
    //Loading a file with a model
    XTTModel model = null;
    SourceFile hmr_threat_monitor = 
        new SourceFile("./heartdroid/src/main/resources/threat-monitor.pl");
    HMRParser parser = new HMRParser();

    //Parsing the file with the model
    parser.parse(hmr_threat_monitor);
    model = parser.getModel();
    
    //Printing all the types within the model
    LinkedList<Type> types = model.getTypes();
    for(Type t : types){
        System.out.println("Type id: "+t.getId());
        System.out.println("Type name: "+t.getName());
        System.out.println("Type base: "+t.getBase());
        System.out.println("Type length: "+t.getLength());
        System.out.println("Type scale: "+t.getPrecision());
        System.out.println("desc: "+t.getDescription());
        
        for(Value v: t.getDomain().getValues()){
            System.out.println("Value: "+v);
        }
        System.out.println("==========================");
    }
    
    //Printing all the attributes within the model
    LinkedList<Attribute> atts = model.getAttributes();
    for(Attribute att: atts){
        System.out.println("Att Id: "+att.getId());
        System.out.println("Att name: "+att.getName());
        System.out.println("Att typeName: "+att.getTypeId());
        System.out.println("Att abbrev: "+att.getAbbreviation());
        System.out.println("Att comm: "+att.getComm());
        System.out.println("Att desc: "+att.getDescription());
        System.out.println("Att class: "+att.getXTTClass());
        System.out.println("==========================");
    }
    
    //Printing all the tables and rules within the model
    LinkedList<Table> tables = model.getTables();
    for(Table t : tables){
      System.out.println("Table id:"+t.getId());
      System.out.println("Table name:"+t.getName());
      LinkedList<heart.xtt.Attribute> cond = t.getPrecondition();
      for(heart.xtt.Attribute a : cond){
          System.out.println("schm Cond: "+a.getName());
      }
      LinkedList<heart.xtt.Attribute> concl = t.getConclusion();
      for(heart.xtt.Attribute a : concl){
          System.out.println("schm Conclusion: "+a.getName());
      }
      
      System.out.println("RULES FOR TABLE "+t.getName());
      
      for(Rule r : t.getRules()){
          System.out.print("Rule id: "+r.getId()+ ":\n\tIF ");
          for(Formulae f : r.getConditions()){
              System.out.print(f.getAttribute().getName()+" "+f.getOp()+" "+f.getValue()+", ");
          }
          
          System.out.println("THEN ");
          
          for(Decision d: r.getDecisions()){
              System.out.print("\t"+d.getAttribute().getName()+"is set to ");
              
              ExpressionInterface e = d.getDecision();
              System.out.print(e);
          }
          System.out.println();
          
      }
      System.out.println();
      System.out.println("=============================");
      
      
    }      
      
} catch (Exception allExceptions){
  // Simplified for the purpose of the example
}   
</code>
=== Creating a new state ===

Once the model is loaded, you can set the initial state for the system. 
The state is a set of initial values for the selected attributes. 
The state usually will be dynamically set by the context-aware application.

<code java>

// Creating StateElements objects, one for each attribute
StateElement hourE = new StateElement();
StateElement dayE = new StateElement();
StateElement locationE = new StateElement();
StateElement activityE = new StateElement();
      
// Setting the values of the state elements  
hourE.setAttributeName("hour");
hourE.setValue(new SimpleNumeric(16d));
      
dayE.setAttributeName("day");
dayE.setValue(new SimpleSymbolic("mon",1));
      
locationE.setAttributeName("location");
locationE.setValue(new SimpleSymbolic("work"));
      
activityE.setAttributeName("activity");
activityE.setValue(new SimpleSymbolic("walking"));
      
    
//Creating a XTTState object that agregates all the StateElements  
State XTTstate = new State();
XTTstate.addStateElement(hourE);
XTTstate.addStateElement(dayE);
XTTstate.addStateElement(locationE);
XTTstate.addStateElement(activityE);
   
// Printing current state (it should be null for all attributes, 
// the state will be set later). The state can be set before inference
// by calling HeaRT.getWm().setCurrentState(...)      
System.out.println("Printing current state");
State current = HeaRT.getWm().getCurrentState(model);
for(StateElement se : current){
    System.out.println("Attribute "+se.getAttributeName()+" = "+se.getValue());
}
</code>

=== Running the inference ===

After the initial state is set, the inference can be run.


<code java>
try{
// Fixed order inference -- we give all tables names 
// in an order in which they should be fired
HeaRT.fixedOrderInference(model, 
    new String[]{"DayTime","Today","Actions","Threats"},
    new Configuration.Builder()
        .setInitialState(XTTstate)
        .build());
        
// Data driven inference -- we give only the starting tables names. 
// The algorithm crawls the table network and fires only the necessary tables. 
HeaRT.dataDrivenInference(model, 
    new String[]{"DayTime","Today"},
    new Configuration.Builder()
        .setInitialState(XTTstate)
        .build());
        
// Goal inference -- we only give the table which produces the attribute value
// that we are interested in. 
// The algorithm crawls the table network and fires only the necessary tables.
HeaRT.goalDrivenInference(model, 
    new String[]{"Threats"},
    new Configuration.Builder()
        .setInitialState(XTTstate)
        .build());

}catch(UnsupportedOperationException e){
   e.printStackTrace();
} catch (AttributeNotRegisteredException e) {
   e.printStackTrace();
}


System.out.println("Printing current state (after inference");
current = HeaRT.getWm().getCurrentState(model);
for(StateElement se : current){
   System.out.println("Attribute "+se.getAttributeName()+" = "+se.getValue());
}
</code>
==== Creating your own model ====
The model is created with HMR+ notation.
To learn more about this, go to the [[pub:software:heartdroid:tutorials:hmr_quickstart|HMR language quickstart]] tutorial.
You can use HWEd online web editor for this purpose: [[http://heartdroid.re/hwed/|HWEd web editor]]
If you want to use it on your server, please visit [[https://bitbucket.org/sbobek/hwed|HWEd website]] for more details on how to do this.