core functionality

Core functionality available in all applications.

Objects

  •  

    This is the common base class of all `big' objects in polymake. It does not have any properties, but provides several useful methods for scripting and interactive use.

    User Methods of Core::Object

    •  
      apply_rule (pattern)

      Executes the specified production rule. If the object does not possess enough initial properties to provide all required rule sources, or any of its preconditions are not satisfied, an exception is raised.

      Parameters
      Stringpattern
      : 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 the given pattern matches headers of several rules, or the given label is associated with several rules, the rule chain with smallest total weight (including the rules supplying the source properties) is chosen.
    •  
      attach (name, data, constructor_args)

      Attach an arbitrary data item to a `big' object. Attachments are saved in the same data file as the `big' object itself. They can be retrieved by calling get_attachment.

      Parameters
      Stringname
      : attachment name, can be an arbitrary string. If an attachment with the given name already exists, it is silently replaced with new data.
      Anydata
      : attachment data, can be a simple numeric scalar, a string, or a complex data type, e.g. a Matrix or Polynomial. `Big' objects, anonymous arrays or hashes are not allowed.
      Stringconstructor_args
      : optional list of property names of the owning `big' object which should be passed to the attached data constructor when it will be restored from a data file. Properties of subobjects are specified in dotted path notation. For example, for an attachment of type NodeMap you must specify the "ADJACENCY" property containing the graph the map is referring to.
    •  
      disable_rules (pattern)

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

      Works much like the user function disable_rules but only affecting the given object.

      Parameters
      Stringpattern
      : 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 the given pattern matches headers of several rules, or the given label is associated with several rules, they all will be disabled regardless their precoditions, weights, or other attributes.
    •  
      dont_save ()

      Clears the `changed' flag in the object, so that it won't be saved in the XML file it stems from. This method is primarily designed for unit tests, but could be also useful in interactive mode if you want to revert all recent changes and reload the object from the data file.

    •  
      get_attachment (name)

      Retrieve data stored in the given attachment.

      Parameters
      Stringname
      : attachment name
    •  
      get_schedule (request) → Core::RuleChain

      Compose an optimal chain of production rules providing all requested properties. The returned RuleChain object can be applied to the original object as well as to any other object with the same initial set of properties. If no feasible rule chain exists, `undef' is returned.

      To watch the rule scheduler at work, e.g. to see announcements about tried preconditions, you may temporarily increase the verbosity levels $Verbose::rules and $Verbose::scheduler.

      Parameters
      Stringrequest
      : name of a property with optional alternatives or a property path in dotted notation. Several requests may be listed.
      Returns
      Core::RuleChain

      Example:
      • generate an optimal rule chain for a parameterized family of polytopes:> @p=map { new Polytope("POINTS" => my_matrix($_) ) } 1..10;> $s=$p[0]->get_schedule("FACETS", "TRIANGULATION.FACETS");> $s->apply($_) for @p;
    •  
      list_attachments ()

      Return names of all attachments as a list of strings.

    •  
      list_names ()

      Returns the list of names of multiple subobject instances. This method can be applied to any instance of a multiple subobject. For a normal (non-multiple) subobject or a top-level object just returns its name.


      Example:
      • List all names of linear programs associated with a polytope:> print join(" ", $p->LP->list_names);
    •  
      list_properties (deep)

      Returns the list of names of all properties kept in the object.

      Parameters
      Booldeep
      : recursively descend in all subobjects and list their properties in dotted notation.
    •  
      properties ()

      Returns or prints a string with all properties (names and values) and subobjects.

      Options
      Intmaxdepth
      descend into subobjects up to given depth, default 0
    •  
      remove (prop)

      Remove the property prop from the object. The property must be mutable, multiple, or unambiguously reconstructible from the remaining properties.

      Parameters
      Stringprop
      : property name or a path to a property in a subobject in dotted notation, Several properties may be removed at once.
    •  
      remove (subobj)

      Remove the multiple subobject instance(s) from the object.

      Parameters
      Objectsubobj
      : multiple subobject instance. Several subobjects may be removed at once.
    •  
      remove_attachment (name) → Any

      Remove the given attachment from the `big' object.

      Parameters
      Stringname
      : attachment name
      Returns
      Any
      attachment data
    •  
      set_as_default ()

      Makes the multiple subobject instance the default one. Physically this means moving it at the 0-th position in the instance list.

      The instance can be selected by give() or PROPERTY_NAME access method.


      Examples:
      • by current position:> $p->TRIANGULATION->[$i]->set_as_default;
      • by subobject name:> $p->TRIANGULATION("placing")->set_as_default;
      • by checking for a specific property:> $p->TRIANGULATION(sub { defined($_->lookup("WEIGHTS")) })->set_as_default;
      • by analyzing all instances and picking the best one:> for (@{$p->TRIANGULATION}) { assign_min($min_facets, $_->N_FACETS) and $t=$_ } $t->set_as_default;
    •  
      set_as_default_now ()

      Temporarily make the multiple subobject instance the default one. The change is automatically reverted at the end of the current user cycle. Usage as set_as_default.

  •  

    A rule chain to compute properties of a `big' object. It can be obtained by calling the method get_schedule.

    User Methods of Core::RuleChain

    •  
      apply (o)

      Apply the rule chain to an object.

      Parameters
      Objecto
    •  
      list ()

      Return the headers of rules in the chain.

    •  
      list_new_properties ()

      Return the names of properties computed by the rule chain.

User Functions

  •  

    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
      Stringname
      | Application app_obj

      Example:
      • To set the graph application as current, type this:> application "graph";
    •  
      disable_rules (pattern)

      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.

      This ban applies to all production rules defined in the current application. If you need more fine-granular control on object type level or even for individual objects, please use user methods of the same name: $obj->type->disable_rules(...) $obj->disable_rules(...)

      Parameters
      Stringpattern
      : 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 the given pattern matches headers of several rules, or the given label is associated with several rules, they all will be disabled regardless their precoditions, weights, or other attributes.
    •  
      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
      Stringrulefile
      : one or more filenames.
    •  
      load (filename) → Object

      Read the object data file created earlier by save and return the object.

      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
      Stringfilename
      Returns
      Object
    •  
      load_data (filename) → any

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

      Parameters
      Stringfilename
      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
      Stringlabel_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
      Stringlabel_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
      anyVariable
      : 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
      Stringlabel_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. The filename may have the suffix ".gz" in which case the contents are compressed with gzip.

      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
      Objectobject
      Stringfilename
    •  
      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. The filename may have the suffix ".gz" in which case the contents are compressed with gzip.

      Parameters
      anydata
      object
      Stringfilename
      Stringdescription
    •  
      save_schema (object ..., filename)

      Generate a Relax-NG schema describing one or more `big' or `small' object types in the form as they would appear when saved with commands save resp. save_data.

      Parameters
      anyobject ...
      an object whose type should be described, may be specified as a type expression as well. Multiple objects or type expressions may be passed as a list. Mixing `big' and `small' object types is not allowed.
      Stringfilename
      a suffix .rng is appended automatically if no suffix is given

      Examples:
      • create a schema for a Polytope<Rational> and save it in the file poly_rat.rng> save_schema(typeof Polytope<Rational>, "poly_rat"); the same, specifying a type via a representative object> $c=cube(3);> save_schema($c, "poly_rat");
      • create a schema for graphs and save it in the file graphs.rng> save_schema(typeof props::Graph<Undirected>, typeof props::Graph<Directed>, "graph");
    •  
      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
      Stringfilename
      : script code
      AnyArguments
      : 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
      anyassignment
      : following expressions are allowed: $var=value; @array=(values); %hash=( key => value, ... ); $hash{key}=value;
  •  

    These functions are available in the interactive shell only.

    •  
      apropos (pattern)

      List all help topics matching the given pattern.

      Parameters
      Stringpattern
      (part of) an item name to be looked for, may contain regular expression elements.

      Example:
      • To get all help topics that include the word "simplicial", type this:> apropos("simplicial"); /objects/Visual::SimplicialComplexLattice /objects/Visual::SimplicialComplex /objects/GeometricSimplicialComplex /objects/SimplicialComplex /functions/Producing a new simplicial complex from others/simplicial_product In order to view a help entry, you can use the help() funtion.> help("/functions/Producing a new simplicial complex from others/simplicial_product");
    •  
      exit ()

      use this command only if you want to restart polymake.

    •  
      export_configured (filename)

      Saves all custom variables having non-defalt values in a file. This includes all results of automatic 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
      Stringfilename
      where to store the settings
      Options
      Boolmerge_with_global
      if TRUE, the settings inherited from *your* global configuration will be included in the resulting file as well.
      Boolonly_configured
      if TRUE, configuration status of unconfigured or only partially configured rulefiles is not exported
      Stringsuppress
      regular expression matching fully qualified names of custom variables that should not be exported
    •  
      extend_application (extension, app_name)

      Create a directory tree for rules, scripts, clients, etc. in the given extension pertaining to the given application.

      Parameters
      Stringextension
      : URI or top-level directory of a registered extension.
      Stringapp_name
      : name of the application to be extended; by default, the current application is assumed.
    •  
      found_application (extension, app_name)

      Create a directory tree for a new application, rooted at the given extension.

      The new application is neither loaded at this moment (just because it's quite empty at its birth), 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 extension argument. This action is only allowed in developer's mode, i.e. when polymake is invoked from the git copy of the source tree.

      Parameters
      Stringextension
      : URI or top-level directory of a registered extension, or special string "core".
      Stringapp_name
      : name of the new application
    •  
      found_extension (path)

      Found a new extension at the given path. The specified directory may be absent, then it will be created; if it already exists, it should be empty or at least not contain any files and subdirectories with names having special meaning for polymake, like polymake.ext or apps.

      A new bundled extension can be created by entering a name of the form "bundled:NAME" instead of the path argument. This action is only allowed in developer's mode, i.e. when polymake is invoked from the git copy of the source tree.

      Please note that this command only creates an empty skeleton of top-level directories. In order to be able to populate the extension with new rules, scripts, clients, etc. you must execute the command extend_application for every application you want to to extend.

      Parameters
      Stringpath
      : top-level directory of the extension, or "bundled:NAME" for a bundled extension.
    •  
      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
      Stringitem
      : "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, options)

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

      If the extension requires some third-party libraries, which can't automatically be found by its configuration script, you can pass options to it as trailing arguments of this command. Usually, the error message displayed after the failed attempt to configure the extension will tell you which options you should specify. To obtain the complete list of configuration options supported by the extension, you can pass a single option "--help", examine its script configure.pl, or just make use of the TAB completion when typing this command.

      Parameters
      Stringpath
      top-level directory of the extension.
      Listoptions
      options passed to the extension script configure.pl
    •  
      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
      Stringfilename
    •  
      obliterate_extension (path)

      Removes all references to the specified extension from your settings, 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. The files comprising the extension itself are not deleted, however, so that you can re-import the extension later once you need it again.

      Parameters
      Stringpath
      URI or top-level directory of the extension.
    •  
      reconfigure (rulename)

      Repeats the auto-configuration routines stored in the given rulefile, possibly asking for program paths, options, etc. If the configuration succeeds, and the rulefile hasn't been configured until now, it will be loaded, as well as all other known rulefiles depending on it.

      Parameters
      Stringrulename
      name of the rulefile with optional prefix and suffix: "[APPNAME::]rulefile[@URI]". APPNAME is to be specified when the rulefile does not belong to the current application; URI specifies an extension the rulefile comes from.
    •  
      reconfigure_extension (path, options)

      Re-run the configuration script of the extension, passing some options to it. The extension must already have been imported; if not, please use the command import_extension, which supports passing configuration options too.

      Parameters
      Stringpath
      : URI or top-level directory of the extension.
      Listoptions
      options passed to the extension script configure.pl
    •  
      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
      Stringfilename
      : 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
      Boolbrief
      : list the product names only, no descriptive text
    •  
      show_extensions ()

      Prints the list of active extensions including their URIs and credit notes.

    •  
      show_preferences ()

      Prints the currently active preference lists. Please be aware that the output only reflects the persistent preferences; temporary changes made by prefer_now are not displayed even if they might be in effect when this command is executed.

    •  
      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 out other configuration troubles.

    •  
      unconfigure (rulename)

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

      Parameters
      Stringrulename
      name of the rulefile with optional prefix and suffix: "[APPNAME::]rulefile[@URI]". APPNAME is to be specified when the rulefile does not belong to the current application; URI specifies an extension the rulefile comes from.