User Functions

•  

  Basic

  These functions are part of the core user interface. They are available in both scripting and interactive modes.

  •  

    application (name)

    
    

    Called in void context sets the current application to the one given by name (loading its rules if necessary) or by an object of type Polymake::Core::Application.

    Called in non-void context loads the application if necessary and returns the Application object representing it, but does not make it the current application.

    Finally, if called without arguments, just returns the current Application object, which is also always available in the variable $application. Say print $application->name; to see its name.

    Parameters

    String

    name

    | Application app_obj

  •  

    disable_rules (pattern, object_type)

    
    

    Temporarily disable production rules matching given pattern. Rules are re-enabled after the complete execution of the current script or input expression in interactive mode.

    Parameters

    String	pattern	: either a label (see prefer) or a rule header. The rule header must exactly match the definition in the rulefile, up to white spaces around property names. If several rules have headers matching the pattern, they all will be disabled even if they differ in precoditions, weights, or other attributes.
    String	object_type	: optionally constrain the search of matching rules to those applicable to the given object type. Instead of a type name you can also pass an ObjectType instance, e.g. as $obj->type.

  •  

    include (rulefile)

    
    

    Read additional rule files, interpret them in the context of the current application. The rule files may reside in the application's standard subdirectory rules or in any of the known extensions.

    Parameters

    String

    rulefile

    : one or more filenames.

  •  

    load (filename) → Object

    
    

    Read the object data file. If the data file is in old plain ASCII format and does not contain a type declaration, the default type of the current application is assumed.

    Parameters

    String

    filename

    Returns

    Object

  •  

    load_data (filename) → any

    
    

    Read the data file created earlier by save_data and return the data object stored there.

    Parameters

    String

    filename

    Returns

    any	data object; in list context additionally returns the optional description read from in the file.

  •  

    prefer (label_expression)

    
    

    Make the production rules, user functions, or methods (further called items) matching the given label_expression be preferred over competing rules (functions, methods).

    The new preference list is also saved in your personal file ~/.polymake/prefer.pl It remains active in all forthcoming sessions until you revoke it with another prefer or reset_preference command.

    For the sake of symmetry you can call this function by its alias name set_preference.

    Parameters

    String

    label_expression

    : may have one of the following forms: "top_label" or "top_label.sublevels" selects all items whose labels start with the given path, e.g. "javaview" or "cdd.convex_hull". "*.sublevels top_label_1, top_label_2 ... " selects all items with matching labels and establishes a ranking between them. For example, "*.convex_hull cdd,lrs" makes rules labeled with cdd.convex_hull and lrs.convex_hull preferred over all other convex hull rules, with cdd rules having the topmost rank.

  •  

    prefer_now (label_expression)

    
    

    The same as prefer, but does not store the changes persistently. The lifespan of the new preference order lasts up to the end of the current user cycle (that is, end of user script or interpretation of the current input line in interactive mode).

    Parameters

    String

    label_expression

  •  

    reset_custom (Variable)

    
    

    Reset the custom variable, array, hash, or hash element to the default value(s) as defined in the rule base and store it perpetually in your personal settings file ~/.polymake/customize.pl

    Parameters

    any

    Variable

    : following expressions are allowed: $var; @array; %hash; $hash{key};

  •  

    reset_preference (label_expression)

    
    

    Reset the matching preference lists to the default state. If there are matching preference lists declared in the rule files, they come back into effect; otherwise the preferences are neutralized, i.e. all competing items (rules/methods/etc.) get equal ranks.

    This change is permanent, the former settings are wiped out from your preference file ~/.polymake/prefer.pl

    Parameters

    String

    label_expression

    : "label" or "label.sublevels" or "*.sublevels" or "*" or "all" Two last forms match all preference lists visible from the current application.

  •  

    save (object, filename)

    
    

    Store the given object in a data file.

    If filename is specified, create the file with this name (or overwrite an existing one) and store the object there.

    If filename is omitted, write the object back to the file it was loaded from. If the object is not yet associated with a file (e.g. it was created with a new constructor) a new file is created, with the name consisting of the object name and the application-specific suffix. If the object name is empty, you will be asked for it. In non-interactive mode an artificial name of the form ObjectType_NNN will be generated, where NNN is an ordinal number.

    The save operation is only performed if the boolean attribute object->changed has the true value.

    Parameters

    Object	object
    String	filename

  •  

    save_data (data, filename, description)

    
    

    Create an XML data file and store the given data object there, together with an optional description. Only objects of complex types declared as property_type can be stored this way.

    Parameters

    any	data	object
    String	filename
    String	description

  •  

    script (filename, Arguments)

    
    

    Run the polymake script, passing the arguments in @ARGV. The scripts specified without path are first looked for in the current application's scripts subdirectory, then in the user's script directories (custom array @lookup_scripts), and finally in the top-level scripts subdirectory.

    Parameters

    String	filename	: script code
    any	Arguments	: arbitrary many arguments passed to the script

  •  

    set_custom (assignment)

    
    

    Set the custom variable, array, hash, or hash element to a new value and store it perpetually in your personal settings file ~/.polymake/customize.pl

    Parameters

    any

    assignment

    : following expressions are allowed: $var=value; @array=(values); %hash=( key => value, ... ); $hash{key}=value;

•  

  Interactive

  These functions are available in the interactive shell only.

  •  

    apropos (pattern)

    
    

    List all help topics matching the given pattern. bash-like syntax for wildcards is supported.

    Parameters

    String

    pattern

  •  

    export_configured (filename, merge_with_global)

    
    

    Saves all custom variables having non-defalt values in a file. This includes all results of automatical or manual rule configuration. The obtained file can be edited manually, if needed, and used as a global configuration source (see also How to configure polymake for a group of users).

    Parameters

    String	filename	: where to store the settings
    Bool	merge_with_global	if TRUE, the settings inherited from *your* global configuration will be included in the resulting file as well.

  •  

    forget_extension (path)

    
    

    Removes all references to the specified extension, so that the following polymake session won't load anything from it. Beware that in the current session all the rules and functions defined in the extension remain active! Therefore it's strongly recommended to quit the current session right after executing this command.

    Parameters

    String

    path

    : URI or top-level directory of the extension.

  •  

    found_application (name, path)

    
    

    Create a directory tree for a new application, rooted at the given extension. The apps and build subtrees are created unterneath if necessary. If it's the first application being created or extended there, the path will be inserted in the custom list @lookup_applications.

    The new application is neither loaded at this moment, nor it is inserted in the @start_applications list. Both must be done manually at the appropriate time.

    A new core application can be created by entering the string "core" instead of the path argument. This option is only available in developer's mode, i.e. when polymake is invoked from the SVN copy of the source tree.

    Parameters

    String	name	: new application's name
    String	path	: top-level directory of the new or existing extension. By default, the first writeable directory listed in @lookup_applications will be taken.

  •  

    found_extension (path)

    
    

    Found the extension for the current application rooted at the given directory. The apps and build subtrees are created unterneath if necessary. If it's the first application being created or extended there, the path will be inserted in the custom list @lookup_applications.

    Parameters

    String

    path

    : top-level directory of the extension. By default, the first writeable directory listed in @lookup_applications will be taken.

  •  

    help (item)

    
    

    Display the help information or comments associated with a given item.

    If a single word without path separators / is given, it is looked for in the entire help hierarchy. If there are more than 5 matches, the corresponding help commands with full paths are generated and placed into the shell history buffer, so you can choose the themes of interest using the standard history navigation (arrow up/down keys).

    You may use TAB completion to navigate thru the category tree. Start with '/' to see the description of the current application. Descend via 'functions', 'objects', 'types', or 'preferences' to the topics of interest. If you stop in an intermediate category level, both the comment specific to this category and the list of subtopics will be displayed.

    Parameters

    String

    item

    : "word" | "category/subcategory/.../item"

  •  

    history ()

    
    

    Let you choose and edit the commands typed earlier in the interactive shell. The complete history list is written in a temporary file, which is opened with a text editor. Until you store your favorite editor in the custom variable $history_editor, the values of environment variables VISUAL and EDITOR are consulted.
  •  

    import_extension (path)

    
    

    Load the extension installed in the given directory. The path is also included in the custom list @lookup_applications for future sessions.

    Parameters

    String

    path

    : top-level directory of the extension.

  •  

    load_commands (filename)

    
    

    Read the lines from the given file, filter out comments and empty lines, append them to the history list of the interactive shell, and enter the replay mode (see replay_history) starting at the first inserted line.

    Parameters

    String

    filename

  •  

    reconfigure (rulefile)

    
    

    Repeats the auto-configuration routines stored in the given rulefile, possibly asking for program paths, options, etc. If the configuration succeeds, and the rulefile wasn't configured until now, it will be loaded.

    Parameters

    String

    rulefile

    : name of the rulefile, optionally prefixed with "application::" if it does not belong to the current application.

  •  

    replay_history ()

    
    

    Bring the interactive shell in the replay mode. In this mode you can revisit, edit and execute the commands stored in the history. Simply press RETURN if you want to execute the command as is; alternatively you can edit it or jump over it using the usual history navigation keystrokes. The replay mode is switched off when the last history line has been executed or navigated over. You can leave it prematurely by entering Control-C as well. The replay mode is visually signaled by the history line number in square brackets displayed in the shell prompt.
  •  

    save_history (filename)

    
    

    Saves the commands entered in the current and recent sessions in the file. Polymake does it automatically at the end of each interactive session; this command is provided for the case that you might want to store the commands in an alternative file and/or don't want to exit the session. Commands can be loaded using load_commands.

    Parameters

    String

    filename

    : defaults to ~/.polymake/history

  •  

    show_credits (brief)

    
    

    Prints the short descriptions of third-party software packages available from within polymake, including the copyright holders and project site URLs. Please note that here you will see only packages for which the polymake interface has been successfully configured; try show_unconfigured command to see what's you currently missing.

    Parameters

    Bool

    brief

    : list the product names only, no descriptive text

  •  

    show_preferences ()

    
    

    Prints the currently active preference lists.
  •  

    show_unconfigured ()

    
    

    Prints the names of all rulefiles visible from the current application, which could not be loaded because of configuration failures (in most cases, due to some lacking external software). You may use the command reconfigure to load some of them if you have installed the required software and/or cleared other configuration questions.
  •  

    unconfigure (rulefile)

    
    

    Forgets the configuration made for the given rulefile and disables it for the following polymake sessions.

    Parameters

    String

    rulefile

    : name of the rulefile, optionally prefixed with "application::" if it does not belong to the current application.