How to use zubr

zubr is a Java code generator. In order to use it we need a specification written in a Zubr language. Take a look at perkun-0.1.8/examples to see example zubr specifications.

The most simple zubr specification is example11_simple.zubr. It looks as follows:


// This is an example zubr specification.

%%

// here we put the Perkun code (values and variables)

values {}
variables {}

%%

// here we put Java code to be included in the result class

You can run it typing:


zubr example11_simple.zubr > Optimizer.java 

The result will be a new file Optimizer.java containing some Java code. This code needs to be compiled then by your Java compiler (javac). You can put it into some larger project. Take a look at more complex examples - like example12_with_frame.zubr. It generates a standalone Java application that opens a Swing frame.

Zubr can be used if you need the Perkun algorithm in your Java project and for some reason do not want to use JPerkun. You can freely use the zubr created code even in your commercial projects without any license fees.

Zubr is a strict form programming language. A program in Zubr consists of three sections:

  • declaration section
  • perkun section
  • definition section

This is an example Zubr code:


       // This is a Zubr example code
       %%
       values
       {
            value FALSE, TRUE, DO_NOTHING, MOVE;
       }
       variables
       {
            input variable alpha:{FALSE, TRUE};
            output variable beta:{DO_NOTHING, MOVE};
       }
       %%
       // end of example

The values section of the Perkun code within Zubr specification contains the keyword "value" followed by the valid identifiers, separated by commas.

The values are used to denote the possible values of the variables. The Perkun variables is a complex topic and will be discussed later. One-line comments begin in Zubr with a hashtag "#" or with "//". Zubr 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. Let us forget for now the hidden variables though, and introduce a simple Zubr code with one input variable and one output variable:


       %%
       values
       {
            value FALSE, TRUE;
            value MOVE, DO_NOTHING;
       }
       variables
       {
            input variable what_I_can_see:{FALSE, TRUE};
            output variable action:{MOVE, DO_NOTHING};
       }
       %%

As you can see the variables section contains now two variables:

  • what_I_can_see
  • action

Each variable declaration is followed by a colon and a list of possible values in curly brackets, separated by commas. For example what_I_can_see may have value FALSE or TRUE.

We know already how to declare Zubr values and variables. We know that the agent i.e. Zubr optimizer can see the input variables and can control the output variables. The question is how to control the output variables. What do we want to achieve? What is "good" for the agent and what is not?

In order to define it we use the getPayoff method in the Zubr program. Try the following code:


       %option getpayoff own // method getPayoff
       %%
       values
       {
            value FALSE, TRUE;
            value MOVE, DO_NOTHING;
       }
       variables
       {
            input variable what_I_can_see:{FALSE, TRUE};
            output variable action:{MOVE, DO_NOTHING};
       }
       %%
       protected float getPayoff(VisibleState vs) {
            switch (vs.getVariableValue("what_I_can_see"))
            {
                 case FALSE:
                      return 0.0f;
                 case TRUE:
                      return 100.0f; // TRUE is "better" than FALSE
            }
            return 0.0f;
       }

In the declaration section we used the Zubr option:
%option getpayoff own

It will create an optimizer that "prefers" TRUE rather than FALSE as input.

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 100.0, while for "FALSE" it equals 0.0.