polymake is an object-oriented system for experimental mathematics. The typical working cycle of a polymake user is to
construct an object of interest (polytope, simplicial complex, graph, etc.), ask for some of its properties or make some pictures,
then change the construction parameters or build something more complex using existing objects, and start from the beginning.
If you don't have any experience in polymake, we recommend you to look first at the list of
available applications and study the corresponding tutorials.
This will give you the first idea what the whole system is good for.
What follows is a more systematic description of the tools usage, not related to any specific application.
Basic concepts
The polymake objects are similar to those used in the well-known object-oriented programming languages like C++ or Java: they have
properties (known elsewhere as data members, attributes, fields, etc.) and methods; the object types can build inheritance
hierarchies, adding own properties and methods to those inherited from the parent types. However, polymake objects have two
distinctive features: they are open and immutable.
Openness means that the set of properties and methods can be arbitrarily extended as often as needed, unlike the classes in C++ or
Java which are always defined by a monolithic piece of code. The ability to add new properties without deriving a new
object type allows you to interchange your objects with other researchers, even when they don't have access to your extension
code. Alternatively, you can distribute your add-ons and merge them with extensions created by other polymake users, without
introducing artificial object types with multiple inheritance.
Immutability means that each object once created does not change any more. This idea stands much closer to the tradition of the
mathematical literature: "Let G be a graph ..., then G' is a subgraph of G induced by ..." than to the usual design of the imperative
language programs where variables are "recycled" over and over again. Note that "does not change" relates to the
equivalence class of the mathematical object represented by the polymake object. The latter gets more and more properties "revealed" as soon as you ask
for them, and these properties are stored in the object with the purpose to save the computation time if they will be needed in
the future again. polymake implements here the well-known principle of lazy evaluation.
This way all object methods can be seen as const methods, even if they add new properties to the object like the
production rules.
Running modes
There are two-and-half possible modes how to use polymake. The first one is traditional, command-line oriented, mimicking the earlier
versions of polymake, therefore also called compatibility mode. The new scripting mode allows to perform much more
interesting constructions than the command-line mode, but is aimed at users with at least basic programming skills. Finally, the
interactive mode is currently half-implemented.
Command-line mode
Currently (as of release 2.3) the command syntax depends on the task to complete. There are two major cases:
Constructing a new object
The constructions are implemented as independent programs, which for historical reasons are called clients in polymake
jargon. You can find the full lists of the construction clients under the "Constructions" topics in the navigation subtrees of
corresponding application. Each client has its own command line syntax; there are, however, some common features:
called without arguments, they print a short usage message and exit
the first argument is always the file name where to store the created object
the following arguments are input objects (= file names), then obligatory parameters, and finally, options
each optional argument starts with a dash and a keyword
So each construction step is concluded by creation of a new data file. You might sometimes
take a look in this file, it's just plain printable ASCII. However, you should refrain from changing the properties
stored there, except for properties of purely descriptional nature like VERTEX_LABELS. Tampering with the
essential object properties will almost surely render its description inconsistent, causing all consequent computations with
the object to yield wrong results.
You can also create the data file by yourself, manually in a text editor or using some software, provided the syntax rules are
not violated.
Asking for object properties or calling methods
As soon as an object is stored in a data file you can ask for any properties defined for this object type and call user methods
and functions, e.g. for visualization. This is done using a uniform syntax:
polymake DATAFILE EXPRESSION ...
where each EXPRESSION can be one of the following:
PROPERTY_NAME
The complete lists of properties can be found on the "Object Types" overview pages (as alphabetically sorted lists) as
well as on the individual object's "Properties" pages (accompanied by detailed descriptions).
METHOD_NAME
'METHOD_NAME(arguments...)'
'METHOD_NAME->SUPPLEMENT_METHOD_NAME ...'
The visualization methods were formerly called pseudo-targets. Now they are implemented as real object methods which
can take arguments and be involved in complex expressions. Don't forget to quote the expression if it contains characters
having special meaning for the shell, like parentheses or the "greater" sign in the arrow.
The complete lists of methods can be found under the topics "Methods" in the object's individual navigation subtrees.
Please pay attention to the mouse-sensitive argument lists offset in green and the supplementary
method lists.
PREFERENCE_LABEL
Choose temporarily a computational algorithm or visualization engine different from the default (preferred) one.
Be aware that the changed preference can only effect the processing of arguments following it on the command line,
since the arguments are evaluated one by one.
The complete lists of preference labels can be found under the topic "Preferences" of the chosen application.
'USER_FUNCTION(arguments...)'
There are several kinds of user functions. Formatting functions convert the printable representation of object properties.
The visualization functions allow to compose pictures of several objects.
The complete lists of user functions can be found under the topics "User Functions" in the applications' navigation
subtrees.
Some functions like isomorphy check work with entire objects; they can be called using a slightly different syntax:
polymake USER_FUNCTION DATAFILE DATAFILE ...
polymake has also several command line options described here.
Scripting mode
The core part of polymake is implemented in perl, and it is the user's programming
language too. polymake defines a rich API which allows to work with the objects and their properties, to call user methods and
functions, as well to access the metadata, such as object and property descriptions. At the same time you have still the full
power of the well-known programming language with its countless extension libraries.
Unfortunately, the documentation of the polymake interface for scripting is not 100% complete. Under the "Scripting" navigation
topic you can find a short introduction as well as the reference material about the most important
functions. We have also included few sample scripts in the distribution, you can find them in the subdirectories scripts at
the distribution top and in some applications.
Please feel free to ask for individual support per email. We'll very much appreciate any constructive feedback to these brand new
features.
polymake interprets the command line arguments as perl scripts in the following cases:
polymake 'some perl code'
A very short script can be specified directly as the only command argument.
polymake [--script] SCRIPT_FILE
If the only command argument is a file name, polymake assumes that it contains a perl script and executes it.
If the script file name is not an absolute path and does not reside in the current directory, it is searched for
at the number of locations, starting with your individual search path, then in the scripts subdirectory of the default
application, and finally in the top scripts subdirectory of the polymake installation.
Your individual script search path is kept in the array @lookup_scripts, stored in the
preference file~/.polymake/prefer.pl .
The default application can be changed by prepending the script file name with the application name:
APP_NAME::SCRIPT_FILE, or by the -A option.
polymake --script SCRIPT_FILE arguments...
The script can take arguments from @ARGV. The option --script is obligatory here to distinguish this case from the
compatibility mode call (as decribed above).
Using standard constructions in scripting mode
In this polymake version you can't directly call the construction algorithms as perl functions in your scripts.
Enabling this stays one of the primary goals for the next release; in the meanwhile you must use one of the workarounds explained
below. We apologize for this incovenience.
The first, obvious way is to call the construction client from the command line separately. Then your script can load the created data
file and work with it:
The load function loads the object and assigns this to the variable $this. If you have to work with several objects,
you can assign them to the variables of your choice:
polymake 'my $p=load("myfile1"); my $q=load("myfile2"); ...'
This simple way is however unacceptable if the construction parameters are first to be computed in your script.
For this case there is a special function Modules::client allowing to run client programs from within the script.
It is, however, not very convenient; in particular, it requires additional operations before and, sometimes, after the client call.
Please refer to the example in the scripting tutorial.
The is is one of the main goals for the next polymake version. The next paragraph is a brief "letter of intents" to give
you a taste of the upcoming features.
polymake enters the interactive mode when called without any arguments. Then it starts an internal shell with its own command
line, offering automatic keyword completion, online help, and other goodies. Each line is interpreted, depending on the syntax,
either as a perl expression or like a command line in the compatibility mode.
Since version 2.2 polymake is capable of reading and interpreting perl expressions from the input, but only from a pipe
or TCP/IP socket. To run polymake in this "semi-interactive" mode, you must start it as follows:
polymake -
Read the perl expressions from STDIN line by line and interpret them. The output (everything produced by print
... operators) goes as usual to STDOUT.
polymake SOCKET_FILE
polymake HOSTNAME:PORT
If the only argument is a named unix-domain socket (ls -l marks such files with a little s) or an internet
address, polymake connects to it and reads the lines with perl expressions. The output goes back to the socket.