The most simple form of a request is the name of a property of interest.
polymake first looks for this property in the file.
If it's already there, the job is easy: just extract and print it.
If not, or the property is not persistent
(temporary or pseudo-target),
polymake selects all rules which promise to create this
property and determines whether they are applicable: the input
properties required for these rules must be already existing or obtainable in their turn from another rules.
This process terminates either gaining one or more sequences of applicable rules (called rule
chains), or stating that the request is infeasible due to lacking initial data.
In the latter case polymake exits without performing any computations.
From all rule chains found this way, the cheapest one (that is, having
minimal sum weight of rules) is chosen and the rules are executed
consecutively. If some rule terminates with an error message, the rest of
the rule chain is discarded, and the planning process is unrolled
again. The failed rules are disclosed from the future planning. A rule
terminated due to a keyboard signal (usually by pressing Control-C) or
alarm clock is treated as failed too.
Requesting for a pseudo-target has a side effect: the rule providing it
is allowed to rewrite all other properties it creates. While it never
plays any role by visualization pseudo-targets (since they don't create
any properties at all), it has consequences for pseudo-targets connected
to computational algorithms, especially convex-hull computations. For
more details, see the discussion about
rewriting of properties.
If you have specified several requests, they will be considered as if tied
with AND operator, that is, polymake will try to find a rule chain
supplying all of them. If it fails, no partial resolving will be
considered. To change this behaviour, you can use alternative and weak requests.
Complex requests
'property1 | property2 ...'
Make an alternative request. Only one of the properties will be looked for.
The more preferred property should be specified first.
Several alternatives can happen to get created during the execution of the rule chain,
but only one (the leftmost) will be printed.
'?property'
Make a weak request. It tells polymake that it won't be a fatal error
if the property can't be created nor found in the file.
Obviously, it makes sense only in an AND combination with other requests.
You can make an alternative request weak by placing the question mark in front of the last property.
'filter(request [, ...])'
Apply a printing filter function to the obtained data
in order to change their printed representation. Filter expressions can be nested.
Note that the original data stored in the file are not influenced.
By default, polymake prints the requested properties exactly in the same
format they are stored in the file.
Be sure to quote the complex requests as shown in the examples above,
since some characters like vertical bar or parentheses have special meaning to the shell.
Specifies an alternative rule file.
You can repeat this option several times, in which case all rules will be merged together.
You will need this option if you choose to perform the convex hull
computation using floating-point artihmetics, if the exact computation
takes too much time or the coordinates cannot be expressed by
rational numbers without distortion of the structure of
the polytope (e.g. the regular dodecahedron). Just specify
-f float.rules.
But you should be aware that the combinatorial description computed on the base of floating-point rules
can be completely invalid in unfortunate cases.
In the absense of -f options, polymake looks for the
file poly.rules. The standard set of rules distributed
with polymake uses the exact rational arithmetic for the convex hull computation.
Thus if you want to extend the set of rules and not to replace the standard one,
you must specify both your own rule file(s) and poly.rules.
-I path
Specifies a directory where polymake should seek for the rule files;
may be repeated several times. The path will be prepended to the
default search path, which usually consists of the current working directory
and the standard rules installation directories.
-A application
Tells polymake that the data file belongs to the given application. Effectively it
changes the default rule search directory to apps/application/rules.
Since the application name is stored in the data file, you will need to specify this option only
if you have manually created it and now call polymake for the first time.
The default application is polytope, for historical reasons.
You can also use this option later, forcing polymake to ignore the original application. But this is dangerous,
since different applications are allowed to have properties with identical names and specific semantics.
Debugging options
These options make polymake more chatty. All debugging information goes to standard error stream.
-n
polymake only displays the rule chain it would execute to resolve the request.
No rule is actually executed and no data printed.
-v
Each occurence of this option increases the verbosity level.
polymake will report about some internal events which are normally transparent to the user.
Display the version number. Tell when a property is deleted due to the dependence on another one having
been overwritten, or some expected property is negated.
List all rule files as they are being parsed, as well as all rules being executed.
Illustrate the selection process of applicable rules.
-d
Increases the debugging output level. This might be of interest primarily for polymake developers.
Dump the data flow between polymake server and the client programs.
Dump the rule chains under construction in a terse form.
The same but in an exhaustive form (very voluminous!)
-T sec
Sets the limit for the execution time of a single rule (in seconds).
A rule exceeding this limit will be interrupted and treated
as failed. Default policy is to let all rules run as long
as necessary.
Some rules are made insensitive to
the alarm clock, in particular those involving interactive visualization tools.
If you permanently need to specify some options (such as -f
or -I), you can conveniently store them in the environment variable
POLYMAKE_SWITCHES. They will be then active by each call of
polymake or client programs. Options specified via the
environment variable are treated as if they were standing at the
beginning of the command line arguments.
Hide the requested properties temporarily, find the rule chain producing them and run it, then compare the
hidden and new data. The data file remains unchanged. This mode allows to check the correctness of a new
rule by means of the existing alternatives.
--touch
Read the file, convert obsolete properties if necessary, and write it back. No requests are possible in this mode.
--write
Read data from standard input and store it in the file in the sections specified as command line arguments.
Multiple sections are to be separated by empty lines.
--help
Print all HELP sections
found in the rule base and exit. No data file or requests can be specified.
This mode is kept mostly for historical reasons, since the description of the rules
is integrated into the HTML documentation you are reading just now.
--server fd
Read the commands from the pipe opened at the file descriptor fd, execute them, and send the results
back into this pipe. This mode is designed only for communication with client programs.