specification.md

-# Specificiation 
+# Specification 
 
 NDL is a strongly-typed declarative language describing both constraint programming problem structure and neighbor operators.
 
@@ -77,10 +77,10 @@ NDL query is a Prolog like program, containing rules, with bodies consisting of
   * if `Condition` fails and `Else` query is provided, then `Else` is evaluated
   * if `Condition` fails and `Else` query is not provided, then nothing happens and expression succeeds (non-standard in the Prolog world)
 * operation operating on the current solution:
-  * `get_value(+Index:variable_index, -Value:integer)` - gets the variable's current value
-  * `set_value(+Index:variable_index, +Value:integer)` - set the variable's value to `Value`
-  * `swap_values(+Index1:variable_index, +Index2:variable_index)` - swap values of two variables
-  * `flip_variable(+Index:variable_index, +HeadsValue:integer, +TailsValue:integer)` - if variable has value `HeadsValue` or `TailsValue`, sets the value to the other one. Otherwise fails.
+  * `get_value(+Index:variable_index, -Value:integer)` - gets the variable's current value. Supports only normal and fixed variables.
+  * `set_value(+Index:variable_index, +Value:integer)` - set the variable's value to `Value`. Supports only normal variables.
+  * `swap_values(+Index1:variable_index, +Index2:variable_index)` - swap values of two variables. Supports only normal variables.
+  * `flip_variable(+Index:variable_index, +HeadsValue:integer, +TailsValue:integer)` - if variable has value `HeadsValue` or `TailsValue`, sets the value to the other one. Otherwise fails. Supports only normal variables.
 
 ## Extensions
 
@@ -112,4 +112,28 @@ This extension adds three additional constructs:
 * `top(+Type:type, -Arg:Type)` - gets the last added element of `Type` from the stack, but doesn't remove it from the stack
 * `while(pop(+Type:type, -Arg:Type), Query:query)` - new loop that loops while the stack contains value of a type `Type`. It can be used to simulate recursion, there is no guarantee it finishes.
 
+## Semantics
+
+Motivation: user can define constraint and auxiliary variables semantics in the model. Exploiting semantic part of the model often simplifies the operator.
+This extension adds additional constructs:
+
+* `get_value/2` support reified and auxiliary variables.
+* `is_satisfied(+Name:name, +Arg1:arg1(Name), +Arg2:arg2(Name))` - succeeds if the constraint named `Name` is satisfied for arguments `Arg1` and `Arg2`
+* `is_violated(+Name:name, +Arg1:arg1(Name), +Arg2:arg2(Name))` - succeeds if the constraint named `Name` is not satisfied for arguments `Arg1` and `Arg2`
+
+## Generative semantics
+
+Motivation: the common strategy when implementing a neighborhood operator is to make a move and then fix constraints that got violated by the move. 
+
+The biggest difference between the **normal** and *generative* semantics is that in the latter case one can query the violated constraints in a generative manner.
+This extension adds additional constructs:
+
+* all from the weak semantics
+* `violated(+Name:name, ?Arg1:arg1(Name), ?Arg2:arg2(Name)) is nondet` - finds a violated constraint named `Name` if there is any. Otherwise it fails.
+* loops `for_each(violated(+Name:name, ?Arg1:arg1(Name), ?Arg2:arg2(Name)), +Query:query)` 
+* loop `while(violated(+Name:name, ?Arg1:arg1(Name), ?Arg2:arg2(Name)), +Query:query)` - a common patter used in the neighborhood operators.
+
+**Warning** using generative semantics adds an overhead to all operations modifying the solution.
+ 
+