| Both sides previous revision Previous revision Next revision | Previous revisionLast revisionBoth sides next revision |
| general [2012/03/06 07:48] – [Custom variables] gawrilow | general [2019/01/29 21:46] – external edit 127.0.0.1 |
|---|
| Here you can find instructions and tips concerning general use practice rather than specific mathematical questions. | 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 "unavailable to broad public". We apologize for this inconvenience and kindly ask you to have patience till the next polymake release, should you really miss the feature in question. | > 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 [[perpetualbeta|perpetual beta]] should you really urgently need the feature in question. |
| |
| ===== Interactive Shell ===== | ===== Interactive Shell ===== |
| ===== Most Important Commands ===== | ===== Most Important Commands ===== |
| |
| Precisely speaking, polymake commands are quite normal perl functions, either built-in 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: | 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: |
| |
| <code> | <code> |
| help 'custom/$history_size';</code> | help 'custom/$history_size';</code> |
| -- 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). | -- 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). |
| .. For partial matches, please use regular expressions like ''%%help "POINT.*"%%''; -- right, it is a perl regular expression and not a unix shell wildcard, therefore this example reads as "word starting with ''POINT''". Only topic names are matched, no full-text search is performed. | |
| -- 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. | -- 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. |
| | -- 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. | Finally, you can just enter a bare ''help;'' command and get a //very// brief summary of the page you are currently reading. |
| |
| There is also another command searching for the help topics matching the given substring: ''%%apropos "TEXT FRAGMENT";%%'' | |
| It does not involve any sophisticated interaction, but simply dumps all the matching headlines to the screen. | |
| You can then paste one of them with your mouse into a ''help'' command. | |
| |
| ==== Handling "big" objects ==== | ==== Handling "big" objects ==== |
| The complete list of commands related to polymake "big" objects can be found in the [[scripting:start#Object|reference part]]. | The complete list of commands related to polymake "big" objects can be found in the [[scripting:start#Object|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 ==== | ==== Switching between applications ==== |
| |
| ? ''%%reset_custom $name{key};%%'' | ? ''%%reset_custom $name{key};%%'' |
| :: restore the default value | :: 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 a ''local'' keyword in front of the assignment. (It's not polymake's black magic, just normal perl operator.) | .. 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 ==== |
| - 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. | - 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. |
| -- Calling interactive commands: | -- Calling interactive commands: |
| ** ''%%prefer "labels";%%''\\ It may be used in two flavors. Firstly, you may declare some tool to be the preferred one for any tasks it may perform. For example, saying ''%%prefer "javaview";%%'' instructs polymake to call javaview 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 javaview be responsible for all the rest. | ? ''%%prefer "label";%%'' |
| .. Secondly, you may establish a specific order of applying 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 as last resort. | :: 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. |
| ** ''%%reset_preference "label";%%''\\ restores 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". | ? ''%%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. | .. 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'' (since perl does not allow to apply ''local'' to anything but variable assignments). | ? ''%%prefer_now "labels";%%'' |
| * ''show_preferences;''\\ displays 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' . | :: 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 configuration files can be changed from its default value ''~/.polymake'' by setting an environment variable ''POLYMAKE_USER_DIR=///other/location//'' . | **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 ===== | ===== Configuration ===== |
| polymake comes with a lot of interfaces to [[external_software|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: | polymake comes with a lot of interfaces to [[external_software|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;''\\ displays 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. | ? ''show_unconfigured;'' |
| ** ''%%reconfigure("rulefile");%%''\\ re-runs 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. | :: 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. | .. You can also run this command for an already enabled interface, for example, when some paths to programs have been changed. |
| * ''%%unconfigure("rulefile");%%''\\ forgets the configured settings and disables 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 be re-configured later if needed again. | ? ''%%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 <nowiki>--</nowiki>reconfigure'' is equivalent to applying the ''reconfigure'' commands to each rulefile containing any auto-configuration routines, but without asking questions in the failed cases. | 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. |