General Introduction

Here you can find instructions and tips concerning general use practice rather than specific mathematical questions.

Please be aware that in rare cases this introduction and other Wiki pages might describe features implemented very recently without explicitly marking them as “new” or “available since that and that date”. We apologize for this inconvenience and kindly ask you to download the latest perpetual beta should you really urgently need the feature in question.

Interactive Shell

The default running mode of polymake is an interactive shell-like interpreter. To start it, just type polymake in your command line. The interactive polymake shell executes an endless loop, in which it waits for you to type in some commands, then executes these commands, optionally displaying some results or error messages, and so on. To be precise, what you type in are perl expressions, as perl is the language polymake speaks (and is partially written in. This distinguishes polymake, by the way, from the majority of computer algebra systems coming each with an own proprietary programming language.) How these commands and expressions may look like is explained later in the following sections; at first let's become acquainted with the interactive facility as such.

polymake shell is based on the famous GNU readline library. This means, if you have worked with bash, gdb, gnuplot, or other one of thousands GNU programs, you will feel comfortable with polymake from the very beginning. This also means, if you have tackled the copious documentation for readline and defined your favorite key bindings in ~/.inputrc, they will be active in polymake shell too.

polymake excessively uses the TAB completion feature. It tries to guess the proper context for the partially typed word (as far as the entangled perl syntax allows) and presents the possible continuations. The guessing is, however, conservative: if the context can't be recognized with certainty, you will see no choices at all. We believe it to be a better solution than offering eventually invalid expressions.

History and replaying

Naturally, polymake shell uses the history facility to store all your input. Besides the standard readline functions for incremental and non-incremental search of single input lines (usually bound to keys Ctrl-S/R and PageUp/PageDown), there are three special commands allowing for manipulate and recall larger input sequences:

history;

starts an editor with complete collected history copied to a temporary file. You can pick an arbitrary sequence of commands, reorder and/or modify them if needed, and paste them at the very beginning of the file. After you exit from the editor, these pasted commands are executed.

replay_history;

rewinds the current history pointer to the very beginning, from where you can re-execute the commands line by line or skip some of them using the usual arrow-key navigation or search functions. During the replay mode the sequential number of the line in the history is displayed in the prompt in square brackets. As soon as you move past the last history line, the replay mode is switched off and the input prompt becomes empty again.

load_commands "file";

appends the commands stored in the given file to the history, rewinds back to the first of them, and turns on the replay mode. This command is especially useful for making live demos with polymake, as you can prepare and test your input in advance and don't have to waste your time for typing during the presentation.

Please note a semicolon at the end of each command – it is a universal syntax rule. Each input in the shell must be concluded with a semicolon. Should you once forget it, polymake supposes that your expression is going to be continued on the next line; you will see this on the changed input prompt, which will contain the continuation number in parentheses. This mishap can be easily remedied: just type in the semicolon and press ENTER.

The continuation mode may be used for more sensible things too: you may type in conditional blocks or loops, distributing the commands over several lines as you please. Another situation where continuation mode comes in handy is the input of multi-line constants (e.g. for matrices).

Unfortunately, you can't change previous lines which are already committed with ENTER. Should you change your mind or discover an error in your input, just press Ctrl-C to escape from the continuation mode. The lines typed in so far are not lost, however: they are kept in the history like everything else.

Finally, let's mention two custom variables related to the history handling.

$history_size

specifies a maximal size (in lines) of the file ~/.polymake/history keeping your input history between the sessions. If you want to let it grow unlimitedly, set this variable to undef.

$history_editor

contains the command starting the editor when you call history. The default value is extracted from the environment variables VISUAL or EDITOR.

Most Important Commands

Precisely speaking, polymake commands are quite normal perl functions, either built-in ones like print or exit, or specially written for polymake. As long as you are not concerned about implementation details, you won't feel any difference. All commands taking arguments may be written in two fashions: with argument list enclosed in parentheses or separated by a blank from the command keyword. For example:

print "dim=", $p->DIM, "\n";
print("dim=", $p->DIM, "\n");

It's completely up to your taste which fashion to use. But never forget the trailing semicolon!

The first command to learn is exit; It gets you out from the interactive shell and ends the session, saving all changed objects (those having associated data files) and settings.

Getting help

The online help facility enables a systematic and user-friendly access to a plenty of comments and help texts scattered over polymake source code. There are three ways of getting help.

  1. Hierarchical browsing. All help topics are organized in a tree-like hierarchy. You can just start typing help ' and then press the TAB key to see all the branches available at this level. Having chosen one branch, you type it in (or at least few first letters to make your choice unambiguous). Now you can close the quote – and don't forget the semicolon! – to get the general description of this level (if any) and the complete list of subtopics available beneath. Alternatively you type the trailing / and press TAB, directly descending to the next sublevel. Here are some examples of help topics you might find useful for your first reconnaissance mission in polymake:

    help 'functions/Basic/help';
    help 'functions/Producing from scratch/rand_sphere';
    help 'objects/Polytope/properties/Basic properties/VERTICES';
    help 'custom/$history_size';
  2. Keyword search. You enter help "WORD"; and get a list of all help topics matching the given word. If there are only few topics matching your input, they will be displayed immediately; if there are many of them, they will be loaded in the history buffer of the interactive shell, so that you can choose the topic of your interest using the regular history navigation (ArrowUp/ArrowDown keys).

  3. Context-sensitive help. Having typed in a part of an expression, you press the F1 key. If the cursor stands within or immediately after a name of a function, method, or property, the corresponding help topic is shown. For functions and methods, only a brief description listing the order of parameters and options is displayed; to get the full explanation, you must press F1 once again.

  4. Partial word search. You enter apropos "SUBSTRING"; and get all matching headlines. Paste one of them with your mouse into a help command. You can use regular expressions in the search string, e.g. .* for an arbitrary substring in the middle of your pattern. The search is case-insensitive and only involves the item names, no full-text search is performed.

Finally, you can just enter a bare help; command and get a very brief summary of the page you are currently reading.

Handling "big" objects

Two commands related to “big” objects are used probably more often than all the rest:

$var=load("filename");

read the XML file with an object (polytope, matroid, etc).

save($var, "filename");

store the object in the given XML file.

save($var);

store the object in the XML file it's originating from or in a new file with the same name as the object itself.

If the given filename does not contain a period, a type-specific suffix is appended.

load can also read files in plain ASCII format which may occasionally have been left behind after the legacy polymake installations. They are automatically converted to the new XML format. In rare occasions load will require interaction, namely if the legacy file contains an unknown section (they were allowed formerly). Then you'll have a choice between renaming it to a known property, storing it as an attachment, or just dropping it forever.

save in the second form may ask for your attention too, if the filename constructed from the object's name and the application-specific suffix already exists. You can choose between overwriting the file and taking a different filename. The first form with an explicit filename always silently overwrites existing files.

Normally you'll be using save only for new objects constructed by hand, since all objects loaded from existing files and changed thereafter are automatically saved as soon as they are disposed of or, at the latest, at the end of the interactive session.

A new object can be created either using one of the construction functions or explicitly specifying its initial properties:

$a=rand_sphere(4,20);
$b=new Polytope<Rational>(POINTS => (a lengthy matrix expression));

Asking for properties or drawing pictures is simply calling a suitable method of an object:

print $b->VERTICES;
$a->VISUAL;

The complete list of commands related to polymake “big” objects can be found in the reference part.

Loading and saving arbitrary data

Apart from the full objects, you can also persistently store arbitrary data structures like matrices or graphs. There are two commands working with data pieces:

$x=load_data("filename");
save_data($x, "filename", "description");

The description is optional; it can be an arbitrary text, even stretching over several lines.

Switching between applications

Applications are, roughly speaking, collections of object types, functions, and other stuff related to some distinct mathematical subject. At all times during the interactive session in the polymake shell, there is one current application, while other applications are modestly standing on the backstage. The name of the current application is permanently displayed in the shell prompt.

As a matter of fact, the only difference between the current application and the rest is that you can call the functions and object constructors of the former without having to qualify them with the application name as a prefix; however, this is a quite comfortable feature. When you want to make other application current, you must enter this command: application "NAME";

There are two custom variables related to applications. The list @start_applications contains names of all applications to be loaded at the very beginning of the interactive session (although the process of loading applications is totally transparent to you, having loaded your favorites in advance avoids annoying delays during the session). The variable $default_application names the application to be made current at the beginning of the session. Until you change this, it will be polytope for its undisputed merits as the oldest and most prominent application in polymake.

Customizing

Here we won't speak about really mighty features like defining own rules or object types; they are described elsewhere. Instead we'll start with tiny, easy to use tools of fine-tuning.

Custom variables

You can tune many aspects of polymake behavior by changing values of numerous variables which are dedicated for keeping user-visible settings. In the following these variables are called with their polymake nickname custom variable (which actually has been borrowed from the xemacs terminology). The definitions of custom variables are scattered over dozens of rule files; fortunately, polymake offers two ways of accessing them in a more systematic and comfortable manner.

  1. All definitions are repeated in a text file residing in your home directory: ~/.polymake/customize.pl . You are invited to load it in your favorite text editor and study its contents. The variables are sorted there first by applications, then by package names. Most of them will appear as deactivated (that is, the lines start with '' which is the perl fashion of making comments to programs). This means, the default values assigned to them somewhere in the polymake source code are in effect. If you want to change them, simply remove the '' sign and fill in your desired value. By the way, the color values don't need to be entered in numerical RGB notation; any color name listed in the system color list addressed in $Visual::Color::RGBtxt_path can be used instead.

    Some variable definitions appear accompanied by a preceding line of the form ARCH('xyz') . These are special in that they are dynamically set by auto-configuration routines lurking in some rule files, and therefore potentially dependent on the computer architecture. (Recall that you may use polymake on alternating computer platforms having different paths to programs etc.) The preferred way of changing these variables is to use the reconfigure command as described below, because with some of them additional consistency checks may be associated. But in many cases they can be easily edited as well.

    A few variables are stored in a different file: ~/.polymake/prefer.pl . They are separated from the rest because they don't belong to any application but rather control the universal facilities like history editing in the interactive shell or locating extensions. When specifying various search paths, you may use ~ as an abbreviation for your home directory; other environment variables can be referred as $ENV{name}

    Please remember that you shouldn't edit any of these files as long as a polymake process is running anywhere under your account. Sometimes polymake needs to store some changes there on its own behalf, but this happens immediately before the exit; so either your or polymake's changes will definitely be lost.

  2. There are two interactive commands manipulating custom variables:

    set_custom $name=value;
    set_custom @name=(value, ...);
    set_custom %name=(key => value, ...);
    set_custom $name{key}=value;

    set a new value of a scalar, an array, a hash map, or a single value therein

    reset_custom $name;
    reset_custom @name;
    reset_custom %name;
    reset_custom $name{key};

    restore the default value

    Both commands come into effect immediately, but also mark the variable as changed, so that the new value will also appear in your personal customization file after the session end. You can also change the custom variables for the rest of current session only, without updating the file – by a plain assignment. If you want to change some value temporarily, just to influence the evaluation of the next expression, write the local keyword instead of set_custom. (It's not polymake's black magic, just normal perl operator.)

Preferences

Preferences are lists of choice of different tools capable of performing the same task. When polymake can't make a choice based on objective criteria, it consults the preference lists and takes the tool listed as first. For example, there are several programs capable of drawing a 3-d polytope: javaview, povray, geomview, etc. Another example is the convex hull computation for which up to five different algorithms (depending on the coordinate type) come into consideration. The sensible choice between them can't be made based on some quantitative estimates; instead, your intuition and, sometimes, personal taste must take over the leadership.

As with custom variables, polymake offers two ways of handling the preferences:

  1. Manually editing the file ~/.polymake/prefer.pl . The preferences are stored in the last section of this file, grouped by applications. What you see there are exact copies of prefer commands as they appear in the polymake rules. Modify them at your taste. They have the same syntax as the interactive commands described below.
  2. Calling interactive commands:

    prefer "label";

    declare some tool to be the preferred one for any tasks it may perform. For example, saying prefer "jreality"; instructs polymake to call jReality to display any kind of 2-d, 3-d, and 4-d drawings related to polytopes, as well as graphs visualized with spring embedding model. You can specify your wishes more precisely, though: saying prefer "graphviz.graph"; makes the neato program from the graphviz package the default tool for visualizing graphs, letting jReality be responsible for all the rest.

    prefer "*.task label1, label2 ...";

    establish a specific order of preferred tools for special task. For example, a command prefer "*.convex_hull cdd, lrs, beneath_beyond"; directs polymake to always try the cdd convex hull computation first; if it fails, the lrs algorithm will be applied; if both fail, then beneath_beyond, and as the last resort anything else without specific order.

    reset_preference "label";

    restore the settings to the pristine state. It accepts a tool name or a wildcard expression as its argument and restores the effect of any matching prefer command encountered in the rule files. The most radical form reset_preference "*"; forgets any preferences you've ever changed and restores the “factory settings”.

    Both commands come immediately into effect; before exiting the interactive session the changes will be stored in your preference file.

    prefer_now "labels";

    does the same as prefer, but restores the previous setting as soon as the current input is completely evaluated. No persistent changes are made. This command can be seen as the local modification of prefer (standard perl does not allow to apply local to anything but variable assignments).

    show_preferences;

    display all active preferences in the current application. If you want to find out all tools involved into the preference mechanics, including inactive ones, use the TAB completion in prefer command or browse the help system starting at the topic '/preferences' .

Remark: the location of the configuration files can be changed from its default value ~/.polymake by setting an environment variable POLYMAKE_USER_DIR=/other/location, or overridden temporarily just for one session with a command-line option --config-path.

Configuration

polymake comes with a lot of interfaces to third-party software. Each interface must be configured before the first use; in the most cases this involves investigations where the required programs and/or configuration files are installed on your machine. Up to version 2.9.8 polymake used to ask annoying questions about each and every software package regardless of your real interest in it. Now the automatic configuration is performed silently, and it only tries to find the programs at some standard locations (e.g. by examining your PATH setting). If this heuristic search fails, the interface is disabled until you intentionally take care of it. For this purpose, polymake got three new interactive commands dealing with configuration:

show_unconfigured;

display the list of currently disabled interfaces; more precisely, for each interface it prints the name of the rulefile where the interface is defined, together with an optional credit note. The latter usually contains a brief description of the third-party software and includes a URL to the website where you can download it. After you have installed the software, you should call reconfigure with the appropriate rulefile name, to enable the interface.

reconfigure("rulefile");

re-run the auto-configuration routines defined in the rulefile. This time polymake will ask you questions if the search heuristics fail to find the required programs or a version discrepancy is detected. Should you change your mind at the last moment, you can response with an empty input, which will effectively disable the interface again.

You can also run this command for an already enabled interface, for example, when some paths to programs have been changed.

unconfigure("rulefile");

forget the configured settings and disable the interface. The effect of this command is partially deferred until you quit the interactive session, because the functions loaded from the disabled rulefile can't be deleted in a running process. You might find this command useful if you, for example, decide to stop using some third-party software and to deinstall it from your computer. On the other hand, the interface can always be re-configured later on demand.

The old bulk configuration mode is still available: starting polymake --reconfigure is equivalent to applying the reconfigure commands to each rulefile containing any auto-configuration routines, but without asking questions in the failed cases.

general.txt · Last modified: 2014/11/05 11:15 by gawrilow
Except where otherwise noted, content on this wiki is licensed under the following license: CC Attribution-Noncommercial-Share Alike 4.0 International
Recent changes RSS feed Donate Powered by PHP Valid XHTML 1.0 Valid CSS Driven by DokuWiki