christian512 / randa

Recursive AdjaceNcy Decomposition Algorithm

RANDA

RANDA is an extension of PANDA, which implements AdjaceNcy Decomposition Algorithm for enumerating facets of convex polyhedra using parallel computing. This README describes the installation process of RANDA and all tools needed to execute it. The instructions will be focussed on Ubuntu as operating system, but it is also possible to set things up on other systems.

The extension adds the following features to the original functionality:

• Enumeration of faces up to automorphism symmetries
  • Communication with GAP for group calculations
• Recursive calls of the Adjacency Decomposition Method (optional)
• A heuristic version of the Adjacency Decomposition Method (optional)

PANDA was written by Stefan Lörwald, Universität Heidelberg, and released under the CC BY-NC 4.0 license. Accordingly, RANDA is released under CC BY-NC 4.0: http://creativecommons.org/licenses/by-nc/4.0/legalcode

Important Note

RANDA makes use of the computer algebra system GAP, which is used for computational group theory operations. A running instance of a specific script in GAP, which compares and stores facets, is needed in order to execute RANDA properly. If no such script is running in GAP, the enumeration using RANDA will not progress. Furthermore (as the name suggests), the changes applied here to PANDA remove the parallel functionality. Thus RANDA can only run on a single-core.

Installation

It is recommended to install RANDA using CMake. On Ubuntu, you can install CMake using the command:

sudo apt-get install build-essential cmake

If you are on another platform take a look at the CMake website to find installation instructions.

After the CMake installation proceed with the following steps:

1. create a build-folder in the randa directory
2. change directory into the build-folder
3. call cmake .. and then make
4. optionally run tests that the installation was successful using ctest
5. make install to make randa accessible from any directory

This is the complete list of commands to run in Ubuntu for the above actions:

mkdir build
cd build
cmake ..
make
ctest
sudo make install

Install GAP

A detailed instruction on installing GAP can be found here.

GAP requires external library GMP, which needs to be installed beforehand. On Ubuntu you can install it using the following command.

sudo apt-get install libgmp-dev

Next download GAP from their Download webpage and follow these steps to install GAP:

1. unpack the GAP archive and change into the new directory
2. configure the installation using ./configure
3. make the installation

On Ubuntu you can do this by the following commands:

tar -xf gap-4.11.1.tar.gz cd gap-4.11.1
./configure
make

GAP can now be executed by running ./bin/gap.sh.

For executing the scripts to communicate with RANDA, you have to install the packages for GAP.

cd gap-4.11.1/pkg
../bin/BuildPackages.sh

In order to call GAP from any location, you have to add it to the PATH variable. Edit your bashrc-file using nano:

nano ~/.bashrc

Add the following lines to the end of the file.

PATH=~/gap-4.11.1/bin:$PATH
alias gap="gap.sh"

To finish the setup, source the .bashrc file.

source ~/.bashrc

Now you should be able to call gap from any directory.

Example

In the /example/ directory I provide example input files for running RANDA and GAP. To run this examples change the directory:

cd example

For the communication between RANDA and GAP you need to create a communication pipe between the two programs. This is done by the mkfifo command:

mkfifo fromgap.pipe
mkfifo togap.pipe

You can start the GAP program by running the following in one Terminal:

gap --quitonbreak example_stabilizer_program.g 

Now you can start RANDA which communicates to GAP and enumerates all facet-classes of the polytope given by the vertices in example_vertices.ext. Note that you have to execute this in a second Terminal as the GAP program need to be running while RANDA is executed:

randa example_vertices.ext

You can give any options to RANDA such as: -r : Recursion level to use (integer) -p : Flag for enabling the sampling method (1 for activating sampling method, 0 for not)

Enumerate different Polyhedra

To enumerate any other polyhedron, you have to give a description of its vertices/rays and its combinatorial symmetry group.

The vertices need to be provided in a format as shown in example/example_vertices.ext. This format is also described here. The symmetry group, for the particular polyhedron, needs to be given in the GAP program. You can use the example_stabilizer_program.g as a template. Note that for recursive calls, this program calculates the stabilizer as symmetry group for intermediate polyhedra. The symmetry group is defined in line 4 of the file:

GRP_RED := ();

You have to give the symmetry group in disjoint cycles for the indices of the vertices (as given in the vertices file). For example, if the exchange of the first vertex with the second vertex is a valid symmetry of the polyhedron, this is denoted by (1,2). It is best to provide here only a minimal generating set of the symmetry group, as the calculations will make use of it.

randa's Issues

Remove VertexMaps code

The VertexMaps are outdated, since GAP is used to check symmetries.

Create Dockerfile for Environment

For easier setup a Dockerfile should be provided.
The installation procedure can then also be reduced to the installation of the container.

Read Symmetries from Input File

RANDA should read the symmetries directly from the input file, which also gives the H- or V-representation of the polyhedron.

Recursion Depth - Number of vertices

Currently there recursion depth is set explicitly when calling randa by the flag -r.
Another option for the recursion depth should be the number polyhedron's vertices.
If the number is lower than some threshold the recursive calls should be stopped.

Additionally, RANDA should read the recursion depth parameters from the input file, so we don't need the flags anymore.
The Flag for which method to use (e.g. -s for sampling) should remain.

Script for Bell Polytope

Port your scripts from the polybell repository for creating input files for a Bell polytope.

Include GAP program execution directly

Currently it is required to run an external GAP program for the symmetry calculations. We can also start this program from inside the C++ program. This way the usage of RANDA gets a little more user-friendly.