`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.2) 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:
   - 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.
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
   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:

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 '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.

### 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.2 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.