Perkun2 is a strict form programming language. A program in Perkun2 consists of three sections and any number of commands:
• values section
• agents section
• interfaces section
• commands
The simplest Perkun2 program is:
# begin of the program
values {}
agents {}
interfaces {}
# end of the program
When you place the above text in a file (for example test.perkun2) and run:
$ perkun2 test.perkun2
it will do nothing. That is correct. But if you remove any of the sections you will get an error.
Also correct.
Below is the list of all Perkun2 keywords:
• actions
• agent
• agents
• beliefs
• cout
• eol
• generator
• haskell
• hidden
• illegal
• impossible
• input
• interface
• interfaces
• loop
• model
• output
• payoff
• prolog
• set
• state
• states
• value
• values
• variable
• variables
• visible
• xml
A valid identifier is any sequence of letters/digits beginning with a letter that is not a keyword.
The values section of the Perkun2 code contains the keyword "value" followed by the valid identifiers,
separated by commas.
The values are used to denote the possible values of the variables.
You can print out all the values with the command
cout << values << eol;
For example:
values
{
value false, true, do_nothing, switch;
}
agents{}
interfaces{}
cout << values << eol;
There are many other commands apart from "cout << values << eol;". They can all be placed directly after the interfaces section.
One-line comments begin in Perkun2 with a hashtag "#".
The agents section looks as follows:
agents
{
agent a {}
agent b {}
...
}
Each agent has the following syntax:
agent <identifier>
{
variables
{
}
payoff
{
}
model
{
}
}
Perkun2 allows three kinds of variables:
• input variables
• hidden variables
• output variables
The hidden variables are essential for the machine learning.
They represent the state variables of the world that are not directly visible to the agent.
Yet they do affect the state of the world.
The payoff section contains the commands "set" with two arguments:
• input state query
• payoff value (a real number)
The query contains all input variables followed by "=>" and the corresponding value, separated by commas,
enclosed in curly brackets. In short it is an expression:
{INPUT_VARIABLE1=>VALUE,INPUT_VARIABLE2=>VALUE,...}
Note that the query must contain all the input variables.
What does the payoff value mean? It is a value representing "how good" the payoff function is
(for the respective combination of the input variable values). The higher the payoff value the "better" it is.
In the example above the agent "likes" to see the value "true" on its input (variable what_I_can_see),
while it dislikes the value "false", because for "true" the payoff value equals 1.0, while for "false"
it equals 0.0.
Perkun2 hidden variables
We do not perceive directly everything that is happening in the world. Or to say it otherwise - in order to understand the world it is useful to imagine that some facts about it remain hidden. Likewise - in Perkun2 it is assumed that the world has a state described by the visible variables (so called input variables) and by the invisible variables (so called hidden variables). How to declare them in Perkun2?
values { value false, true; }
agents
{
agent a1
{
variables
{
input variable a:{false, true}, b:{false, true};
hidden variable c:{false, true}, d:{false, true};
}
payoff {}
model {}
}
}
interfaces
{
interface a1=>a1 {}
}
The above Perkun code defines an agent a1 with two input variables (a and b) and two hidden variables (c and d). All of them may have either value false or true.
But how can we use the hidden variables? What is it good for, to take into account the variables we do not perceive? Well, in order to understand this we need to learn how to use the model section of the Perkun2 program.
Perkun2 model
We know already how to declare the variables (input,output or hidden ones) and how to define the payoff, i.e. tell Perkun2 which input variable values are good and which are not so good. In order to do its job Perkun2 needs to know how its decisions will affect the world, i.e. how the world state in the future depends on its state now and the Perkun2's choices.
Imagine a world where we have only one variable - input variable alpha. Its value can be either false or true. Let us introduce an output variable beta which can control two actions:
• do_nothing - alpha remains as it is now
• switch - alpha switches to not alpha
Let us further assume that Perkun2 "likes" alpha=true, and "dislikes" alpha=false. For this simple world our Perkun2 program will look as follows:
values
{
value false, true, do_nothing, switch;
}
agents
{
agent a1
{
variables
{
input variable alpha:{false, true};
output variable beta:{do_nothing, switch};
}
payoff
{
set({alpha=>false},0.0);
set({alpha=>true},100.0);
}
model
{
set({alpha=>false},{beta=>do_nothing},{alpha=>false},1.0);
set({alpha=>false},{beta=>do_nothing},{alpha=>true},0.0);
set({alpha=>true},{beta=>do_nothing},{alpha=>false},0.0);
set({alpha=>true},{beta=>do_nothing},{alpha=>true},1.0);
set({alpha=>false},{beta=>switch},{alpha=>false},0.0);
set({alpha=>false},{beta=>switch},{alpha=>true},1.0);
set({alpha=>true},{beta=>switch},{alpha=>false},1.0);
set({alpha=>true},{beta=>switch},{alpha=>true},0.0);
}
}
}
interfaces
{
interface a1=>a1 {}
}
The model section is filled with the set instructions, but they have slightly different syntax than the set
instructions we know from the payoff section. Each set instruction in the model section has syntax:
set(INITIAL_STATE_QUERY,ACTION_QUERY,TERMINAL_STATE_QUERY,VALUE);
The INITIAL_STATE_QUERY and TERMINAL_STATE_QUERY are regular queries containing all input and hidden variables.
The ACTION_QUERY is a regular query containing all output variables.
The VALUE is a probability value.
In short set(A,B,C,D) means "if A and you do B then the probability to jump to C is D".
Perkun2 interfaces
interfaces
{
interface agent1 => agent2 {}
interface agent2 => agent3 {}
...
interface agentn => agent1 {}
}
A single interface defines how agents "think" about each other. Imagine section agents consisting of two agents - p and q.
values { value false, true; }
agents
{
agent p
{
variables
{
input variable a:{false, true};
hidden variable b:{false, true};
output variable c:{false, true};
}
payoff {}
model {}
}
agent q
{
variables
{
hidden variable a:{false, true};
input variable b:{false, true};
output variable c:{false, true};
}
payoff {}
model {}
}
}
interfaces
{
interface p=>q { p.a => q.a, p.b => q.b }
interface q=>p { q.a => p.a, q.b => p.b }
}
In the above example interfaces determine agents p and q to act interchangeably. The agent p "thinks" what would agent q do, and the agent q "thinks" what would agent p do. The "body" of the interface determine how the input/hidden variables of one agent are tranformed into the input/hidden variables of another agent. Note that one variable can be an input variable for one agent and a hidden variable for another agent. Of course some variables can be hidden for both agents. The variable names can be different (in the above example they are identical for both agents).
The output variables are ignored by the interfaces.
Illegal actions
You may be wondering how to prevent some actions to be chosen by Perkun2 in some situations. There is a special instruction for that used in the model section. It is called "illegal".
The syntax is:
illegal(VISIBLE_STATE_QUERY,ACTION_QUERY);
The VISIBLE_STATE_QUERY contains the input variable values, while the ACTION_QUERY contains the output variable values. That is it, Perkun2 won't try to use these actions when these situations occur!
Example:
illegal({where_is_Dorban=>place_Wyzima, do_I_see_vampire=>false},
{action=>goto_Wyzima});
illegal({where_is_Dorban=>place_Wyzima, do_I_see_vampire=>true},
{action=>goto_Wyzima});
illegal({where_is_Dorban=>place_Shadizar, do_I_see_vampire=>false},
{action=>goto_Shadizar});
illegal({where_is_Dorban=>place_Shadizar, do_I_see_vampire=>true},
{action=>goto_Shadizar});
illegal({where_is_Dorban=>place_Novigrad, do_I_see_vampire=>false},
{action=>goto_Novigrad});
illegal({where_is_Dorban=>place_Novigrad, do_I_see_vampire=>true},
{action=>goto_Novigrad});
Impossible states
If we have a deterministic model then it can be represented as a collection of directed graphs, each graph for one action (fixed values of the output variables). It may happen that in these graphs certain states cannot be achieved.
There is an instruction for the model section that denotes that. It is called "impossible".
Its syntax is:
impossible(STATE_QUERY);
The STATE_QUERY contains values of the input and hidden variables.
Example:
impossible({where_is_Dorban=>place_Wyzima, do_I_see_vampire=>false,
where_is_vampire=>place_Wyzima});
The actual way to use Perkun2 is an interactive mode - after the interfaces section type:
loop(3);
This instruction makes Perkun2 to enter the interactive mode. The parameter is the recursion depth used to select the optimal action. Don't make it too large or the computation may take very long!
In the interactive mode it first prompts what variables values are expected to be entered and waits for your input. In the above example it will expect values of the variables x and y (all input variables in the declaration order).
After the prompt type for example: perkun2> v1 v2
The Perkun2 will calculate its belief and the optimal action, then it will print both. The optimal action will be chosen so that according to the model it will maximize the payoff function. The maximization will concern the expected value of the payoff functions within the next n steps, with n being the parameter passed to the loop instruction.
What is the belief?
Belief is a probability distribution over all combinations of the hidden variable values. In the beginning Perkun2 chooses a uniform belief, but after each input the belief will be updated to reflect the interpretation of the input given the model.
Prolog generators
The following instruction prints out a Prolog code that will help you to create the payoff and the model:
cout << prolog generator << eol;
Once created - it is a boilerplate code to be extended with your own facts/rules. Read it (find the comments PLEASE INSERT YOUR CODE HERE).