polymake offers an alternative interface for integration with other software, a C++ callable library.
This page describes only those parts of the interface which are specific to the callable library. Software collaborating with polymake may (and in most cases even have to) use the Object and Function interfaces too; they are described on the Client Development page.
Benjamin Lorenz gave a presentation on the callable library with examples.
The polymake as a library must be initialized by creating an instance of class polymake::Main. This class is declared in the header polymake/Main.h . Special precaution prevents including this header in the polymake clients, it's designed exclusively for standalone programs.
An instance of the class polymake::Main is an empty placeholder, whose sole purpose is to pull the whole polymake machine into memory and make it ready to serve your requests. You can create as many instances as you please; important is only the chronologically first one. If you have linked your application with libpolymake, polymake will stay loaded until the very termination of your program; hence if you want to be able to completely unload the polymake library from memory during the runtime, you should use explicit dynamic loader functions dlopen and dlclose (under Linux; MacOS equivalents exist as well but have substantially longer names).
polymake::Main has one constructor:
Main(user-settings = "user") "user", which causes the standard settings for the interactive mode to come into effect (usually stored under ~/.polymake). Other possible values are "none" for “no configuration at all” or a configuration path allowing to combine several configuration sources with user's individual settings.
Further methods:
set_application("APPNAME") loads the given application, if necessary, and makes it the current one
set_application_of(Object) sets the current application to that one where the type of the given object is defined
add_extension("DIRECTORY") loads the extension rooted in the given directory. Repeated calls with the same path have no effect.
newScope() create an instance of polymake::perl::Scope .
include("RULE_FILE") parses one additional rule file in the context of the current application. See the corresponding interactive command include() .
set_preference("label") reset_preference("label") correspond to the interactive commands of the same names.
set_custom("name", value) reset_custom("name") allow to change values of custom variables. The variable names must be specified fully qualified (unless they reside in the current application package) and with appropriate leading symbol designating its perl type, that is, $ for scalars, @ for arrays, and % for hash maps. Note that get_custom() is now a free function available for clients too.
greeting(int verbose = 2) return the polymake greeting as std::string with different verbosity levels (0-2): just name + version, with copyright added and including the GPL notice.
An instance of class polymake::perl::Scope represents (by its mere lifespan) one execution cycle within the polymake session. At the end of the cycle (when an instance of polymake::perl::Scope gets destroyed), some cleanup actions may occur; most important ones are discarding temporary properties from the Objects and restoring the preferences temporarily modified by prefer_now.
In the interactive running mode, one execution cycle comprises the evaluation of one complete input line. In the callable library mode, however, there are no natural cyclic events which can be used to perform the cleanup. Therefore, if you expect your program to run for longer time and work with many polymake Objects, you should consider regular creation of polymake::perl::Scope instances with limited lifespan.
The only available way to create a polymake::perl::Scope instance is the method Main::newScope(); the instances are not copyable nor assignable. If you create several polymake::perl::Scope instances, their lifespans must be properly nested, that is, the one born last has to die first. Violation of this rule leads to immediate program termination.
Methods:
prefer_now("label") corresponds to the interactive command of the same name.
set_custom("name", value) temporarily changes the value of the given custom variable, until the Scope object is destroyed. Custom variables are specified in the same manner as in corresponding Main::set_custom methods.
You can use polymake callable library for building your programs only after having installed it at the final destination, that is, after ninja install . To facilitate the build process, polymake comes with a small utility polymake-config which resides side by side with the main script polymake in the binary installation directory. Calling this utility with various options you can obtain the compiler and linker options needed for successful build of your program. You can even insert the calls in your Makefile directly, using the GNU make $(shell) function or `backtick` shell substitution.
Following configuration parameters can be requested from polymake-config:
--cc --cflags --includes -I options)
--ldflags --libs -l options)
--version
Please note that the options displayed by --cflags are more kind of a suggestion, you are free to change or omit most of them. Two options are mandatory, however: -DPOLYMAKE_DEBUG={0,1} (which controls a plenty of consistency checks in polymake library data structures) and -fPIC (or similar option, depending on your compiler, which provides for emitting a position-independent binary code). If you omit the latter one, data transfer between C++ and perl worlds, in particular all give() and take() methods, will not work properly in your program.
You can add an option --debug before --cflags, --ldflags, or --libs if you are going to debug your program together with polymake. Compiler options displayed without --debug provide for a build optimized for execution speed.