====== Hekate Markup Language ======

The //Hekate Markup Language (HML)// is provided for the machine readable XML serialization of the HeKatE rule base described in a human-readable [[HMR]] format.

The rules are formalized with the use of the [[hekate:ALSVFD]] logic 
and [[hekate:XTT2]] rules 
prototyped with the [[hekate:ARDplus]] method.

There are the following subsets of the HeKatE Markup Language defined: 
  * ''attml'' -- Attribute Markup Language for describing rule [[hekate:attributes]]
  * ''ardml'' -- Attribute Relationship Markup Language for the [[hekate:ARDplus]] prototype
  * ''xttml'' -- XTT2 Rule Markup Language for the [[hekate:XTT2]] structured rule representation

The sublanguages can be used according to the following scenarios:
  - ''attml'' -- only attribute definition, the minimalistic case
  - ''attml'' + ''ardml'' -- attributes and ARD dependencies
  - ''attml'' + ''ardml'' + ''xttml'' -- attributes, dependencies and XTT2 rules
  - ''attml'' + ''xttml'' -- attributes and rules, (without the ARD prototype)

A HML application using all sublanguages is as follows:

<code xml>
<hml>
  <!-- attml starts here -->
  <types>
    ...
  </types>

  <attributes>
    ...
  </attributes>
  <!-- attml ends here -->

  <!-- ardml starts here -->
  <properties>
    ...
  </properties>

  <tph>
    ...
  </tph>

  <ard>
    ...
  </ard>
  <!-- ardml ends here -->

  <!-- xttml starts here -->
  <xtt>
    ...
  </xtt>
  <!-- xttml ends here -->

  <!-- extra system state specification -->
  <states>
  </states>
</hml>
</code>

The current version is referred to as //HML2//
(the first one is [[HML1]], see below).

===== HeKatE markup history=====

The markup for the various knowledge representations now present in HeKatE has been evolving.
  * 2004 - first markup for XTT in GJN PhD -> XTTML0
  * 2007 - first markup for ARD+ in VARDA
  * 2007 - second version of markup for XTT in early versions of HQEd -> XTTML
  * 2007 - third version of  markup for XTT in HQEd M5_* -> XTTML2
  * 2008 - first version markup proposal for HeKatE, ARD+, XTT+ -> [[HML1]]: ATTML1, ARDML1, XTTML3 (proposal for XTT+, partially supported by design tools)
  * 2009 - second version of HML, ARD+ XTT2 -> HML2: ATTML2, ARDML2, XTTML4 (supported by HQEd M6_* from 05.2009)


===== HML syntax =====

HeKatE markup language DTD:  (for HML2).

For syntax test purposes there is an example XML file:{{:hekate:hml-test-hekate_case_thermostat.xml|}} 
A minimalistic file is: {{:hekate:hml-test-min.xml}}

//(Note: the above files are versioned in the HaDEs CVS repo in the [[HatHoR]] module.)//

Important elements are indexed with an attribute ''id''.
''id'' value has to be unique (enforced by DTD) and should start with (depending on particular element):
  * types: ''id="tpe_..."''
  * attributes: ''id="att_..."''
  * properties: ''id="prp_..."''
  * type groups: ''id="tgr_..."''
  * attribute groups: ''id="agr_..."''
  * dependencies: ''id="dep_..."''
  * ARD history (TPH): ''id="hst_..."''
//All id numbers start with 1//

An additional attribute (''id'') is introduced to guarantee that types, attributes, properties and groups can be uniquely referenced.
It can be forced, using DTD, that an attribute has a unique value within an XML document, it becomes a unique identifier.
Similarly, it can be forced that an attribute references an element by its unique identifier.
Making attribute names unique identifiers prevents naming a group, or type, with the same name as the attribute, since unique identifiers are unique within entire document regardless of the element they regard to.

It is possible to validate a HML file using a validator i.e. ''xmlstarlet'':

  xmlstarlet val -e -d hml.dtd hml-test.xml

===== ATTML =====

For information on attributes [[hekate:attributes|see here]].

<code xml>

  <types>
    <type id="tpe_1" name="Temperature" base="numeric" length="5" scale="0">
      <desc>represents a temperature</desc>
      <domain>
        <value from="1" to="5"/>
        <value is="7" />
        <value from="20" to="22"/>
        <value is="26" />
        <value is="27" />
      </domain>
    </type>
    <type id="tpe_2" name="Integer" base="numeric" length="5" scale="0">
      <desc>represents an integer number</desc>
      <domain>
        <value from="-10000" to="10000"/>
      </domain>
    </type>
  </types>
 
  <attributes>
    <attr id="att_1" type="tpe_1" name="temp" abbrev="t1" class="simple" comm="in">
      <desc>input temperature from sensor number 1</desc>
    </attr>
    <attr id="att_2" type="tpe_1" name="temp-aux" abbrev="t1a" class="general" comm="in">
      <desc>input temperature from sensor number 1, aux reading, including historic data</desc>
    </attr>
 
    <agroup id="grp_1" name="sensors" abbrev="sns">
      <desc>temperatures from sensors</desc>
      <attref ref="att_1"/>
      <attref ref="att_2"/>
    </agroup>

  </attributes>
</code>

Both in the case of //types// and //attributes// groups can be specified.
Example: types day, hour, month can form a type group //date//.
The same could apply to specific attributes.
In the example above there is set of attributes describing sensor readings formed out of values of temp and corresponding temp-aux.
Attributes in groups and types are //ordered//.


===== ARDML =====
For ARD see [[hekate:ardplus]]
and
[[hekate:bib:hekate_bibliography#gjn2008flairs-ardformal]]
[[hekate:bib:hekate_bibliography#gjn2008flairs-ardprolog]]

<code xml>

<hml>
  <types>
    ...
  </types>

  <attributes>
    <attr name="Thermostat" id="att_0"/>
    <attr name="Time" ... />
  </attributes>

  <properties>
    <property id="prp_1">
      <attref ref="att_0"/>
    </property>
    <property id="prp_2">
      <attref ref="att_0"/>
      <attref ref="att_1"/>
    </property>
    <property id="prp_3">
      <attref ref="att_0"/>
    </property>
    <property id="prp_4">
      <attref ref="att_1"/>
    </property>
    <property id="prp_5">
      <attref ref="att_0"/>
    </property>
  </properties>
 
  <tph>
    <hist id="hst_01" src="prp_1" dst="prp_2"/>
    <hist id="hst_02" src="prp_2" dst="prp_3"/>
    <hist id="hst_03" src="prp_2" dst="prp_4"/>
    <hist id="hst_04" src="prp_4" dst="prp_5"/>
  </tph>
 
  <ard>
    <dep id="dep_01" independent="prp_1" dependent="prp_2"/>
    <dep id="dep_02" independent="prp_2" dependent="prp_3"/>
    <dep id="dep_03" independent="prp_3" dependent="prp_4"/>
    <dep id="dep_04" independent="prp_2" dependent="prp_4"/>
  </ard>

  ...
  ...
</hml>
</code>

==== Defining ARD+ Properties ====

Basic syntax:
<code xml>
<properties>
          <property id="prp_1">
               <attref ref="att_0"/>
               ...
               <attref ref="att_ad003"/>
          </property>
		...
		<property id="prp_2">
               <attref ref="att_44"/>
               ...
               <attref ref="att_2"/>
          </property>
</properties>
</code>

  * Properties are defined in ''<properties>...</properties>'' section. This section must contain all properties which are being used in an ARD diagram.
  * Single property is defined by ''<property>'' tag
  * Single property contains any number of attributes. A list of attributes is defined by ''<attref>''

==== Defining TPH Diagram  ====
Basic syntax:

<code xml>
     <tph>
          <hist src="prp_1" dst="prp_2"/>
          <hist src="prp_2" dst="prp_3"/>
          <hist src="prp_2" dst="prp_4"/>
		...
          <hist src="prp_n" dst="prp_m"/>
     </tph>
</code>

  * TPH diagram is definied in ''<tph>...</tph>'' section. TPH diagram contains relationships called transformations.
  * A transformation is defined with the ''<hist>'' tags and it describes the development between a source (''src'') and destination (''dst'') properties.


==== Defining Dependencies ====
Basic syntax:

<code xml>
<ard>
     <dep independent="prp_1" dependent="prp_2"/>
     <dep independent="prp_2" dependent="prp_3"/>
     ...
     <dep independent="prp_x" dependent="prp_y"/>
     ...
     <dep independent="prp_x" dependent="prp_z"/>
</ard>
</code>

  * ARD dependencies begin with the  ''<ard>'' tag. The tag does not have attributes. Each dependence is defined with a a pair of properties: an ''independent'' and a ''dependent'' one.



===== XTTML =====

For information on the XTT itself [[hekate:xtt2|see here]].

<code xml>
  <xtt>
    <table id="tab_1" name="first">
      <schm>
       <precondition>
         <attref ref="att_1"/>
       </precondition>
       <conclusion>
         <attref ref="att_0"/>
       </conclusion>
      </schm>
      <rule id="rul_1">
       <condition>
         <relation name="in">
           <attref ref="att_0"/>
           <set>
             <value from="1" to="5"/>
             <value is="8"/>
           </set>
         </relation>
       </condition>
       <decision>
          <trans>
           <attref ref="att_1"/>
            <expr name="add">
             <attref ref="att_1"/>
            <value is="1"/>
           </expr>
          </trans>
          <trans>
           <attref ref="att_1"/>
            <expr name="add">
              <value is="5"/>
              <expr name="sin">
                <attref ref="att_0"/>
             </expr>
           </expr>
          </trans>
       </decision>
       <link>
         <tabref ref="tab_1"/>
       </link>
      </rule>
    </table>
  </xtt>
</code>

An XTT diagram (''xtt'' element) consists of some number of XTT tables (the ''table'' element).
The above example can be read as:

<code>
xtt_1:
rule_1: if att_0 in <1,5>u{8} then att_1 = att_0 + 1 and att_1 = 5 + sin(att_0)
</code>

==== Schema ====

Element ''schem'' describes precondition and conclusion attributes that are allowed to be used in a particular XTT table.
The schema is generated by the ARD->XTT transition algorithm directly from ARD.

==== Rule ====

A rule (''rule'') consists of a condition (''condition'') part and a decision part (''decision'').
The condition is composed of the [[hekate:ALSVFD]] formulas, that specify certain''relation''s between attribute values and given set of values.

The decision part is decomposed into two parts:
  * state ''trans''istion that can specify new state (attribute values), and
  * external ''action'' to be executed; it is assumed it does //not// infulences the state in any way.

Each rule can explicitly transef the inference to a next table (possibly also a rule).

===== State specification =====

Number of named system states can also be specified.
A single state is a vector of attribute values.

<code xml>
<states>
  <state id="sta_1" name="start">
    <attref ref="att_0"/>
    <set>
      <value from="1" to="5"/>
      <value is="8"/>
    </set>
    <attref ref="att_1"/>
    <set>
      <value from="1" to="5"/>
    </set>
  </state>
</states>
</code>

===== HML implementation and support =====
HML is used to serialize the knowledge in the HeKatE project in a machne redable format.
It is used to interchange knowledge between the tools forming the [[HaDEs]] framework.

HML syntax has been designed to:
  * correspond to the logical system formulation with [[hekate:XTT2]] based on the [[hekate:ALSVfd]] logics, and
  * match the syntax of //HMR// (the HeKatE Meta Representation) as supported by //[[hekate:HeART]]// - the HeKatE runTime environment.