HMR Language

HeKaTe Meta Representation (HMR) is an algebraic notation, created to be human-readable language for XTT2 model representation. File written in HMR language is in fact a legal Prolog code, therefore it can be interpreted directly by ISO-compliant Prolog environments (for example SWI-Prolog). In case of usage outside the Prolog environment, HMR syntax is formally specified using Parsing expression grammar (PEG) — parser for the desired executing technology can be directly derived from grammar by means of a parser generator.

HMR file can be written by hand or it can be generated from different representations by HQEd XTT2 editor.

This section will present the semi-formal definition of HMR along with link to the full grammar used in actual parser generation process (using Mouse parser generator). Firstly, there will be defined primitive types used in HMR. Subsequent subsections will concern more and more complex elements of a HMR model.

As for the notation, double-quotes “ are put around the literals, brackets ( and ) are used to group tokens, and question sign ? is used in some places to mark that the preceding token is optional.

• Comment: HMR supports multi line (/* COMMENT */) and single line comments (% COMMENT)
• Number: HMR supports both Floats (with dot as separator) and Integers
• String: every string used in HMR file. Defined the same way as an atom in Prolog, which can be expressed with following grammar rules:

| String grammar rules

// two variants
String = 
    QuotedString / 
    NormalString;
// everything in single quotes; does not support escape characters
QuotedString = "'" ^["'"]* "'"; 
// starts with lowercase letter, then letter or digit or underscore
NormalString = [a-z] ([a-z]/[A-Z]/[0-9]/"_")*;

• Foreign Identifier: identifies action or callback implemented in foreign language (for example in Java). Syntax is similar to Java class name rules (except lack of support for '$' character). It also supports dots in order to designate the Java package structure. It can be defined by following grammar rules:

| Foreign Identifier grammar rules

ForeignIdentifier =
    NormalString /
    "'" ([a-z]/[A-Z]/"_") ([a-z]/[A-Z]/"_"/[0-9]/'.')* "'";  

• Symbol: string treated as value of an attribute, it can be associated with numeric weight:

| Weighted Symbol grammar rules

Symbol =
    String "/" UnsignedInteger /
    String;  

• Range: represents a range between two values (Numbers or Strings, whenever there is defined order over elements). It has fairly straightforward syntax:

| Range grammar rules

// both values should be of the same type (Number or String)
Range = Value "to" Value; 

• Set: represents a collection of Values (Number, String, Range).

| List grammar rules

// both values should be of the same type (Number / String / Range)
// you can mix Range elements with simple Values, when Range represents values
// of the same type (Number and range of Numbers) 
List = "[" Value ("," Value)* "]"

• Boolean: represents logical value (in two-valued logic).

| Boolean grammar rules

Boolean = "yes" / "no";

• Time index: a non-positive number designating a specified moment in the history of the program execution. It can be written with time unit ('ms', 's', 'min', 'h'), or without it e.g.

| Time index grammar rules

TimeIndex = '0' TimeUnit? | '-' Integer TimeUnit?
TimeUnit = 'ms' | 's' | 'min' | 'h' 

• Time period: represents some past period of time. There are two ways to define a period. First uses colon as a separator. This way user can define also a step of quantization (what should be time difference between following samples) e.g. -5s : 1s : 0 will contain 6 samples measured at moments: -5s, -4s, -3s, -2s, -1s, 0.

| Time period grammar rules

TimePeriod = TimeIndex (Colon TimeIndex)? Colon TimeIndex  

The other way uses the old range notation and doesn't allow defining step value:

| Time Period grammar rules

TimePeriod = TimeIndex "to" TimeIndex.

In both definitions of period, user can't mix TimeIndexes with and without time units, e.g. -5 : 1s : 0 is not allowed, for details, please refer to the original grammar file.

Types in HMR language are used to define kind, structure and domain for further attributes definitions. Type grammar rules could look as follows:

| Type grammar rules

Type = "xtype" "[" "name" ":" String ","
                   "base" ":" ("numeric" / "symbolic") ","
	           "domain" ":" List ","
	           "desc" ":" String ","
                   "ordered" ":" Boolean "]" "."

• name — mandatory — a field that contains type's name.
• base — mandatory — a field describing base of the type. It can be either numeric, or symbolic.
• domain — mandatory — a field that contains a list of all acceptable values for this type. For ordered symbolic domains, it is possible to use. For instance in the example below, every day has it's own number assigned, that allows referring to the values using this number instead of symbolic name. If a symbolic domain is marked as ordered, and there are no weights assigned explicitly to the domain's values, default numbering is assumed that starts from 1 and ends on n, where n is the number of elements in the domain. This behavior is very similar to C enum construct.
• ordered - optional — a field indicating whether domain is ordered or not. Every numeric type has ordered domain by default. It's required to create Range with values of this type.
• desc — optional — a field containing longer description of the type.

The order of fields does not matter, so type definition may look as follows:

Type example

xtype [ domain: [mon/1,tue/3,wed/5,thu/7,fri/9,sat/10,sun/20],
	ordered: yes, 
	desc: 'Days of the week', 
        name: day].

Attributes in HMR language denotes instances of defined types. Every attribute in the HMR language must have a type assigned. Only one type can be assigned to one attribute. Type definitions looks as follows:

| Attribute grammar rules

Attribute = "xattr" "[" "name" ":" String ","
   	                "class" ":" ("simple" / "general") ","
 		        "type" ":" String ","
		        "comm" ":" ("in" / "out" / "inter" / "comm") ","
		        "callback" ":" ForeignIdentifier ","
		        "abbrev" ":" String ","
		        "desc" ":" String "]" "."

• name — mandatory — a field contains attribute's name
• class — mandatory – a field that denotes weather the attribute is simple (represents simple values) or general (represents set values).
• type — mandatory – a field that contains a name of a type defined as xtype. This field denotes the attribute's type.
• comm — optional — a field that describes attribute's relation to the world. If the attribute is in it means that a value of it is supposed to be given by the user; if the attribute is out it means that the value of it should be presented to the user; if attribute is inter it means that its value is set by the system as a result of inference process, but it's not relevant to the user; if the attribute is comm, it means that it's both in and out.
• callback — optional — a field that contains an information about which callback is supposed to be fired for the attribute.
• abbrev — optional — a field that contains short name of the attribute.
• desc — optional — a field that contains longer description of the attribute.

As with Type definition, order of fields does not matter. Attribute definition may look as follows:

Attribute example

xattr [name: day,
       abbrev: d,
       class: simple,
       type: days,
       comm: in,
       callback: ask_console.

Schemas represents XTT tables in HMR language. However, they cannot be considered as entities filled with rows containing rules. Schema is only a representation of relation between attributes that rules falling into this schema realizes. Definitions of schema looks as follows:

| Scheme grammar rules

Schema = "xschm" SchemaName "/" SchemaDesc ":" AttributesIn "==>" AttributesOut "."
SchemaName = String;
SchemaDesc = String;

• SchemaName — mandatory — a field containing obligatory schema name,
• SchemaDesc — optional — a field containing an optional schema description,
• atts_in — mandatory — list of attribute names (or abbreviations); attributes in this list are required to be known by the rules that falls in this schema.
• atts_out — mandatory — list of attribute names (or abbreviations); attributes in this list are going to change their value as a result of the rule falling within this schema.

An example of schema definitions may look as follows:

Schema example

xschm current_season/"Scheme calculating current season": 
      [month, day] ==> [season].

Rules in HMR language are defined as follows:

| Rule grammar rules

Rule = "xrule" RuleName ":" Conditions "==>" Decisions "**>" Actions ":" Links "." "#" CertaintyFactor
RuleName = SchemeName "/" String;

• RuleName — mandatory — a field composed from owning Schema's name and string identifying this particular rule.
• Conditions — mandatory — list of conditions; every condition can only used Attributes declared in Schema's conditional part. Every condition has a form:

| Condition grammar rules

Condition = AttributeExpression ALSV_OPERATOR Value TemporalParameter?

• AttributeExpression may be on of following:

| Rule grammar rules

AttributeExpression = AttributeName 
AttributeExpression = "valat" "(" AttributeName "," TimeIndex ")"
AttributeExpression = StatisticalOperator "(" AttributeName "," TimePeriod ")"

In the first case we use the attribute's name to check it's current value. In the second case we use “valat” operator to get historical value of the attribute at the specified moment of time. In the last case we use a statistical operator to get a statistical characteristics of the attribute. All availavle statistical operators are described below.

• ALSV_OPERATOR is one of the unary operators. Following table contains every allowed combination. “any” and “null” are considered as special values allowed only in “neq” and “eq” contexts.

• Additionally, in recent versions there were introduced optional Temporal Parameters, which check if a specified condition was satisfied in a period of time.

| Condition grammar rules

TemporalParameter = "{" "min"/"exact"/"max" Number "%" "in" TimePeriod "}"

• Decisions - contains a list of Decisions, that have to fired when the all conditions are satisfied. Each Decisions has to assign value to Attribute already listed in owning Schema. It can be expressed as:

| Decisional grammar rules

Decision = AttributeName "set" DecisionalExpression;

• DecisionalExpression has a form of algebraic expression using a set of left-associative binary operators and unary operators. There exist three types of allowed operands:
  1. Value (Symbol, Number, List, “null”)
  2. AttributeExpression
     • Symbols and Attribute names share the same namespace; name clash is solved in favour of Attribute
  3. another Expression with higher precedence (can be obtained using brackets as in common algebra).
  • unary operators have precedence higher than binary operators and are written using functional notation. Following table contains all unary operators:

Also, all the

• binary operators with functional notation can be found in next table

• binary operators with algebraic notations (all of them are left associative) are listed in next table (smaller number means higher precedence):

• Actions is a list of Foreign Identifiers. Every identifiers indicates action, which should be performed after firing the rule. Actions can't change system state.
• Links is a list of rules or schemes which receive control after firing the rule; every element of the list has a form:

| Link grammar rules

Link = RuleName / SchemeName;

• Certainty Factor is an optional number from range ←1.0, 1.0>. If present, has to be preceded with # symbol. This number is used to handle uncertain knowledge in the reasoning phase.

• Example of rule:

Rule example

xrule handle_wind/medium:
  [wind in [5.0 to 7.0], engine lt 10]
    ==>
  [engine set log(wind) * (inertia + current_zero), detector_states set except(detector_states, [off])]
    * *>
  [update_engine]
    :
  [handle_pressure, update_engine/wind].

which can be read as:

if value of wind attribute is between 5.0 and 7.0 AND value of engine attribute is less than 10 THEN set to attribute engine value equal log(wind attribute's value) * sum of inertia and current_zero values AND set detector_states to detector_states except element off PERFORM action update_engine MOVE CONTROL to schema handle_pressure AND rule update_engine/wind.

Having all elements already defined, HMR file is simply list of Types, Attributes, Schemas and Rules. The HMR example can be found here.

All the definitions written in earlier sections are strongly simplified. PEG grammars do not support polymorphic rules like List. Furthermore all the rules above hadn't coped with white characters. The grammar used in project is much richer — many subproblems of parsing the HMR file had to be moved into separate contextual analysis phase. Nonetheless following link contains the full HMR grammar at this moment of time. Grammar should be read according to Mouse parser generator manual.