Automatic Rule Generator

How does the Automatic rule generator work?

The automatic rule generator takes 2 inputs: a template file and a parameter file.

The template file shoudl like very much like a rule set file, using either of the allowed syntaxes (with position-based or property-based atoms; mix and match allowed). The only unusual thing is that in its rule lines you can use "special variables" (identifiers starting with an X) anywhere where an identifier (such as Red or T) or a number (such as 2) is allowed.

The parameter files contains some information that will help the automatic rule generator to replace special variables with some identifiers or numbers, as will be explained in details below.

The automatic rule generator parses the template file using exactly the same mechanism that is used to parse "normal" rule set files, but with an additional "hook" which replaces each special variable with an identifier or a number.

How special variables are replaced

All occurrences of special variables are completely indendent of each other. For example, in the rule template

(*,X,X,[0,X],[X,X,p+X])

When the automatic rule generator subsitutes a particular occurence of a variable, it randomly draws its value from a set which is defined according to the following rules:

1. If the parameter file explicitly gives the set of values for a named variable, this set is used. For example, if the parameter file has the line

   Xpos,"[1..5]"

   , each occurrence of the variable Xpos is replaced by an integer drawn from the set {1,2,3,4,5}.
2. If the parameter file does not mention the specific special variable name, but has a line that defines the default value set for special variables encountered in a particualr "domain" (particular section of atoms, such as count, shape, color, pos, bucket), then this range is used. For example, suppose the parameter file, in its entirety, looks as follows:

   pos,"[2..4]"
   shape,"(Triangle,Square)"
   color,"(Red,Pink,Orange)"

   Then in the atom template

   (X,X,[X,X]*,[pc,ps])

   or

   (pos:X, shape:X, color:X, bucket:[pc,ps])

   the first X will be replaced with an integer from the range 2 thru 4, the second X, with Triangle or Square, and the third X and fourth X, will be replaced (independly from each other) with Red, Pink, or Orange.
3. If the parameter file has no values provided for either the specific special variable name or the domain, the automatic rule generator uses its default value set for the domain in question. Presently, such sets defined for the following domains:
   • shape: the 4 legacy shapes
   • color: the 4 legacy colors
   • pos: the built-in orders
   • bucket: [0..3]
   Note that there is no default value set for the pos domain. This means that if you put a special variable in the pos field of an atom, you must make sure that your parameter file contains a value set either for this specific variable or for the pos domain.

The syntax of the paramter file

The parameter file is a CSV file with 2 columns. The first column contains the variable name or the domain name; the second, the value set. The value set can consist of any of the following:

• a single number or identifier, e.g. 5 or Triangle
• a set of values, e.g. "(Square,Triangle,Star)" or "(1,3,5,7)"
• a range of integer values, e.g. "[2..6]" (which is equivaluent to the set "(2,3,4,5,6)").

The allowed domain names are the same as those used in the property-based rule syntax, i.e. count, shape, color, pos, bucket. If you use image-and-property-based objects in your rule template, you can also use the names of your custom properties.

Command-line interface

There is a script on sapir that you can use to run the automatic rule set generator. The syntax is as follows

/home/vmenkov/w2020/game/scripts/auto-rule-generator.sh [options] param-file.csv template-file.txt n

• -seed s : an integer seed for the random number generator. You can use this for repeatable runs.
• -out directory_name : the name of the output directory. By default, tmp.

Examples (with the input files from /home/vmenkov/w2020/game/templates):

  /home/vmenkov/w2020/game/scripts/auto-rule-generator.sh  /home/vmenkov/w2020/game/templates/param-4.csv  /home/vmenkov/w2020/game/templates/template-4.txt 10

Web interface, with examples

Example 1

Example 2

For each shape, there are two randomly chosen permanent designated buckets (sometimes just one, if both random choices are identical). For each shape, there is a specific randomly chosen order (e.g. T, B, L1) in which they can be picked from the board. For each shape, a certain number of pieces (Xcnt, ranging from 1 to 4, as per the param file) can be picked before the control falls to the next line.

This will have a very high stalemate rate.

Example 3

For each shape, there are two randomly chosen permanent designated buckets (sometimes just one, if both random choices are identical). For each shape, there are 2 specific randomly chosen orders (such as T, B, L1) in which they can be picked from the board. For each shape, a certain number of pieces (Xcnt, ranging from 1 to 4, as per the param file) can be picked before the control falls to the next line.

This template will have many rule sets rejected for stalemating rate, but at a lower rate than Example 2 (template-2.txt)

Example 4

The first rule line allows you to pick 1 piece from anywhere, and put it into a randomly chosen bucket

The second rule allows picking pieces from the top, to be put into one bucket, and from the bottom, to be put into another bucket. Each of those buckets will be chosen randomly, to be either pc or ps

This is an example of a rule with disappearing (or, more precicely, possibly-never-appearing) atoms; while they may often stalemate, the stalemate tester does not detect this possibility.