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.1) the command syntax depends on the task to complete. There are two major cases:

  1. 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:
    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.
  2. 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
    PREFERENCE_LABEL.SUBLEVEL ...
    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 topics "Preferences" in the applications' navigation subtrees.
    '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 top subdirectory scripts.
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_FILE
If the only command argument is a file name, polymake assumes that it contains a perl script and executes it. The SCRIPT_FILE can reside in the current directory, in the scripts subdirectory of the polymake installation, or at one of the user's preferred locations for rulefiles as stored in the @Poly::User::lookup_rules array in the preference file.
polymake --script SCRIPT_FILE arguments...
The script can take arguments from @ARGV. The option --script is necessary to distinguish this case from the compatibility mode call (as decribed above).
Another way to pass arguments to a script is to define a subroutine there and use the perl function require:
polymake 'require "my_script.pl"; my_sub(arg, ...)';

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:

polymake 'load("myfile"); ...'
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 '$p1=load("myfile1"); $p2=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.

Interactive mode

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.

The current version 2.1 is already 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.