Production Rules

Production rules are the crucial information source for polymake. They bring in the semantics to the properties.

Header

TARGET [ , ... ] : SOURCE [ ,  ... ]

(Whitespaces are not mandatory.)

Sources are properties the rule algorithm needs as its input. The rule can expect all its input properties to already exist at the moment the rule is starting to run. It is the job of the polymake server to provide it. If for some reason a source property will be nevertheless lacking, the rule will most probably fail.

A source can be also given as a list of alternatives:

property₁ | property₂ ...

It means that it will be sufficient to provide any one of these properties. If several are available, the leftmost will be used.

Another variation has the form ?property, which means that the property should be created by other rules if possible, but this rule can cope without it too. Such source is called weak.

Targets are properties produced by the rule algorithm. More exactly, these are the properties the rule is expected to produce. If some property is "forgotten", it will be automatically created as negated after the rule finishes.

The rule header states also an access restriction: only those properties can be read or created by the rule that are declared as its sources rsp. targets. Violation of this restriction leads to the abnormal termination of the rule.

The source access list of the rule can be expanded with following clause:

may read(property [ , ... ])

The polymake server will make no efforts to create the properties listed there, but will allow the rule to check their existence and read them.

Body

It contains optional rule characteristics and a piece of perl code which actually makes the whole job. Characteristics are placed on separate lines at the beginning of the body.

WEIGHT x.y

Specifies the cost of applying this rule. It should reflect the computational complexity of the algorithm. Assigning weights to the rules is entirely up to their developer.

The weight value is interpreted as a monome y M^x, so the sum weight of a rule chain is a polynome of M with degree max(x) over all involved rules. When choosing which rule chain to execute, the weights are compared first by degree, and then lexicographically.

The current convention supposes the following mapping between the expected rule complexity and its weight category x:

0	constant time, trivial operation
1	linear time
2	quadratic time
3	polynomial time of degree > 2
4	exponential time
>= 5	artificial weights for rules that should be applied only when explicitly called for, and pseudo-targets

The default weight of a producing rule is 2.10 if it reads and produces some data sections (not pseudo-targets,) otherwise 0.

NOTIMEOUT

Makes the rule insensitive to the alarm clock. Such a rule can only be terminated by the INT signal (if it refuses to finish by itself, of course). Usually this characteristic is assigned to interactive visualization tools.

CLASS classname [ , ... ]

Rules can be bundled into logical classes based on some of their properties, such as a common algorithm or the same precondition that must hold in order to be able to apply the rule. When a rule belonging to some class can anticipate the failure of other rules from this class, it can dynamically inhibit their execution. This speeds up the search of an alternative rule chain a little.

Most probably, this feature will disappear in future versions of polymake, as its functionality can be now modeled by negated sections. The rule classes have been introduced much earlier, are are kept for historical reasons.

The rest of the body is interpreted as an usual perl code, but with following restrictions:

Each rule is a separate subroutine; however, the keyword sub and the enclosing braces are added automatically during rule file parsing, so they must be omitted. Empty lines must not occur in the code, since they would be treated as rule delimiters. Perl comments (starting with a #) can be inserted at will.
The compilation environment of the rule subroutine is

package Rules; use strict;

The subroutine may not refer to any objects from the package main except for the standard perl library routines.
Rules should exchange data only with the server via the public interface, but not via global variables with each other: it can't be predicted which rules are going to be actually executed and in which order (polymake may even become multithreaded in the future). my variables should be used whenever possible.
The rule subroutine is called with an empty argument list. It should return a scalar value indicating the successful completion. Any non-zero value means OK and allows polymake to accept the created target properties (and eventually store them in the file).
Zero or undef return value means failure and forces polymake to revert the data to the state they had before the execution of the rule. Then it seeks for an alternative rule chain or gives up to build the targets.
The rule subroutine may abort with die instead of returning a zero value. The message specified in die will be printed on stderr.

An error-handling routine can be supplied for the rule. Similarly to the catch clauses in C++, it is called if the rule terminates prematurely with die or a signal. The perl code of the error handler is separated from the rule body by ON ERROR on a separate line. Such a handler might delete temporary files created by the rule and do some other clean-up.

A little theory: the object oriented aspects of the system

If we treat a polyhedron as an object in the sense of object-oriented programming languages, then the production rules will correspond to const access methods.

Why const? Let's consider the life cycle of a polyhedral object in polymake. Once created with an initial set of known properties, it doesn't change them during his whole lifetime. Though the main and only purpose of the production rules is to compute new properties, they aren't allowed to change the already known ones, and this means, that the polyhedron remains the same. More precisely, the object in polymake always models the same well-defined equivalence class of geometric objects, such as all polytopes with the same f-vector, with the same combinatorial structure, or with the same vertex coordinates in Q^d. (The notion of equivalence classes will be mapped more directly in the future versions of polymake. Currently it is given only implicitly by the initially known properties.)

Thus, applying production rules to the polyhedral object only reveals some of its properties having been "invisible" so far. This way the rules implement the well-known principle of lazy evaluation: creation of new properties is delayed until they are really needed. But with respect to a geometric object being modeled it is the same as if all properties were computed at once by its birth and never touched since then.

There is an important consequence from this design scheme: the properties are considered invariant to the rules they are created by. Therefore, if some property is created repeatedly by several rules, the second and following "versions" of it are in the most cases simply discarded. (By the way, it differs from the treatment in previous polymake versions, where all properties were always updated). But sometimes the property rewriting can be forced by the user (via pseudo-targets). If the property concerned doesn't have a natural canonical (invariant) representation, there arises a problem how to maintain the consistency between the rewritten version and other properties computed from the old version. It is solved by the synchronization mechanism.

Probably we'll introduce in the future a concept for non-const methods too, and we are going to decrease the granularity of polyhedral objects in order to allow to change some parts of an object. But now you have to submit to the fact that there are only const methods in polymake.