====== HMR language quickstart ====== ===== Use case ===== Imagine you need to model a rule-based system that will automatically turn on and off parking meter with your mobile phone. The system for paying for parking with mobile phone exist, so the only thing you need to do is to determine if someone parked the car in a pay zone, and send request to the system to trigger the payment. For the purpose of this tutorial we focus only on very (very) basic aspects of such model. Several factors may have an impact on whether we should pay for parking or not. It depends on our localization: when you are not in a pay zone you will not have to pay for parking for sure. However, you may also not be charged a parking fee in a pay zone if you park during a weekend, or after business hours (this is how it is in Krakow, Poland). So, the informal specification of the model should look as follows If you are in free zone, then you do not pay If you are in pay zone and it is weekend, then you do not pay. If you are in pay zone and the hour is between 10 and 20 (not inclusive) and it is a workday, then you pay Otherwise you do not pay. The XTT2 model build upon this specification could look as presented in Figure below. {{:pub:software:heartdroid:tutorials:parking-zones-1.png|}} The next sections will discuss in more details the stages which knowledge engineer has to follow in order to create such a model in HMR+ notation. The full model can be downloaded here: {{:pub:software:heartdroid:tutorials:urban-helper-easy.hmr|Parking Model}} You can try running the inference by providing manually values of these attributes with [[pub:software:heartdroid:tutorials:haquna|HaQuNa]] commandline shell. The comman for running the inference can look as follows: java -cp haquna.jar:. haquna.HaqunaMain --model urban-helper-easy.hmr \ --tables ['parkingReminder'] --inference gdi \ --initial-state [day=mon,hour=14,location=pay_zone] For more information on how to configure the inference process, see [[pub:software:heartdroid:tutorials:inference_config|Configuring inference process]] tutorial. ===== Attributes and Types ===== Looking at the informal specification presented in previous section one can think on several attributes that should be used to build a model. These are: * hour (0 to 23) * day type (weekend/workday) * day (Monday to Sunday) which will be used to determine day type * location or zone (pay zone / free zone) * tariff (pay / free) There is also one additional attribute that can be considered as a final attribute that determines the action for the system: * notification (free to park / pay for parking) The attributes listed above were given possible values in round brackets. This possible values are called domains in HMR+ and are determined by **types**. Determining attributes and types, together with their domains should be the first phase of modelling process. Taking all of the above we can distinguish six types, each assign to separate attribute (this is not always like that -- attributes may share types). We create a type in HMR+ using **xtype** keyword. For instance to create type for hour we would put the following code in our ''*.hmr'' file: xtype [ name: hour_type, domain: [0.000 to 23.000], base: numeric ]. It says that the name of he type is ''hour_type'', it is a numeric type (so the values should be treated as numbers, not strings) and the domain is from 0 up until 23 (these are the allowed values for the attribute that will have this type assigned). Numeric types are by default floating point numbers. We can do the same for the remaining types. Take for instance type for attribute **day**: xtype [ name: day_type, domain: [mon/1,tue/2,wed/3,thu/4,fri/5,sat/6,sun/7], ordered: yes, base: symbolic ]. The above definition says that this is the symbolic type, so its domain consists of nominal values. However, it also provides an information that the type is **ordered**. It means that we can refer to the elements of the domain providing their ordering numbers. For instance instead of typing **mon** for Monday, you can use ordering number assigned to it. This also allows you to define ranges of nominal values, for instance ''[mon to fri]'' or ''[1 to 5]''. Once all the types are defined one can start defining **attributes**. This is done in HMR+ with **xattr** keyword. For instance a definition of a hour attribute should look as follows: xattr [ name: hour, abbrev: h, type: hour_type, class: simple, comm: in ]. The ''name'' and ''abbrev'' entries are self-explanatory. The ''type'' entry defines the type of the attribute (in this case it is a ''hour_type'' defined by us previously). The ''class'' entry says if the attribute can take a single value at a time (''simple'') or is it allowed to take set values (''generalised''). Finally, the ''comm'' entry defines the type of the attribute. The attribute can be ''in'',''out'' or ''inter'', which plays a role when using [[.:callbacks| callbacks mechanism]]. Similarly, the definition of a day attribute should look as follows: xattr [ name: day, abbrev: d, type: day_type, class: simple, comm: in ]. ===== Schemas ===== Schemas define dependencies between attributes that provide skeletons for rules. In other words schemas define headers of XTT2 tables. Looking at the informal specification presented at the beginning of the tutorial, we would like to have rules that will determine whether current tariff is ''pay'' or ''free'' The ''tariff'' depends on the current ''hour'' and ''daytype'', therefore the schema describing this relation will look as follows: xschm tariff: [hour, daytype] ==> [tariff] The schema is defined with **xschm** keyword, followed by the name of the schema. After that the two sets are given in square brackets: first denotes the attributes that will be later used as rules' conditions, the second denotes attributes that will be used in rules' conclusions in this particular schema. Similarly, the schema that will determine the value of a ''notification'' attribute that depends on the ''tariff'' and ''location'' will look as follows: xschm parkingReminder: [location,tariff] ==> [notification]. ===== Rules ===== Rules in HMR+ notation encodes knowledge. Every rule has to be assigned to exact one schema and cannot use other attributes in its conditional and decision parts other than specified by the particular schema. Rules are created with **xrule** keyword. For instance one of the rules that determine the ''tariff'' (therefore is part of ''tariff'' schema) could look as follows (the complete and more formal definition of rule can be found in [[pub:software:heartdroid:documentation:hmr#rules|HMR grammar]] page): xrule tariff/1: [ hour in [10 to 19], daytype eq workday ] ==> [ tariff set pay ].#1 The ''tariff/1'' is a name of the rule that specifies the schema to which the rule is assigned and its position in the XTT2 table. Later the list of conditions is given. Every condition is of the form of ''attribute operator value''. There exist two separate lists of operators for ''simple'' and ''generalised'' attributes. The list can be found in [[pub:software:heartdroid:documentation:hmr#rules|HMR grammar]] page. Furthermore, the operators can be time-parametrised to allow capture dynamics of the procesess. For more details on the time-based operators see [[pub:software:heartdroid:tutorials:tbo|Time-based operators]] and[[pub:software:heartdroid:tutorials:statistics|Statistical operators]] tutorials. After the list of conditions followed by ''==>'' (then) operator, there goes the list of conclusions of the form '' attribute set value/expression''. The expression should be a value from the attribute's domain, or more complex expression involving mathematical and statistical operators and functions. The list of admissible expressions for the conclusion can be found in [[pub:software:heartdroid:documentation:hmr#rules|HMR grammar]] page. Finally, at the end there is a certainty factor value assigned to the rule. It denotes the confidence of the rule. The certainty factor is proceeded with ''#'' sign. More about the certainty factors can be found in [[.:uncertainty_cf|Managing uncertainty]] with certainty factors algebra tutorial.