The CuikSuite Documentation

[Introduction] [Installation] [Applications] [Scripts] [Examples] [FAQ] [Disclaimer]

For a more recent version of the CuikSuite please go to here

Introduction

The CuikSuite is a set of applications to solve position analysis and path planning problems with applications mainly to robotics but also to molecular biology.

The CuikSuite algorithms are specially adequate for systems with one of more kinematic loops and with a dimensionality of the configuration space much below the cardinality of the problem (i.e., the number of degrees of freedom of the system is much below the number of variables in the problem). This type of system is specially hard to deal with other position analysis/path planning systems.

As described in our recent papers, our approach provides a formulation and a resolution technique that fit particularly well together. The adopted formulation yields a system of simple equations (only containing linear and bilinear terms) whose special structure is exploited by a branch-and-prune method based on a mix of constraint propagation, linear relaxations, and Taylor forms. The method is general, as it can be applied to kinematic problems with single or multiple loops with arbitrary topology and complete, as all possible solutions get accurately bounded, irrespectively of whether the system is rigid or mobile.

Be aware that the code you can download from our web pages include only part of the CuikSuite (basically the main solver cuik). This documentation might refer to other applications not included in the current distribution.

The CuikSuite has been developed in the context of a series of projects mainly founded by the Spanish Goverment. For more information about this project, including publications that introduce the algorihtms implemented in the CuikSuite, see the project webpage.

Installation

Download

You can download the CuikSuite from here.

License

CuikSuite by KRD group at IRI is licensed under a GPL License.

Pre-Requisites

The CuikSuite package requires of the following libraries and packages

• A Simplex library: Three possible options are
  • CLP: This is the recommended option. It is almost as fast as glpk, but much more stable and more gentle with the user.
  • GLPK This implementation is quite efficient but it tends to have numerical problems and, what is worst, in many cases of numerical inestability is simply aborts the execution instead of returning an error code to the caller. If this happens the execution of the corresponding CuikSuite application will be aborted too and this is quite anoying.
  • LP_SOLVE The inteface to lp_solve is defined but we hardly use it.
• A MPI library. The recomended option is to use OpenMPI. This is only necessary if you want to execute cuik in a multiprocessors environment.
• flex and bison
• cmake, a cross-platform build system.
• doxygen and graphviz to generate the documentation.

Under linux all of these utilities are available in ready-to-use packages, but for CLP that need to be compiled and installed manually.

Under MacOS most of the packages are available via Mac ports.

Configuration

Unpack the CuikSuite project and edit the CMakeList.txt file in the main directory. The variables to set are

• SIMPLEX_ENGINE: The simplex library to use.

• USE_MPI: Set to 1 if cuik is to be executed in a multiple processor environment. In this case cuik should be executed through the rmpicuik script in the scripts directory. You should edit this script to adapt the execution to your particular multiprocessor system.
  The parallel execution of cuik follows a simple master-slave schema, where a central scheduler takes care of sending boxes to the slaves and the slaves try to reduce the boxes as much as possible before returning them to the master. The implementation we have is robust to the failure of some of the slaves.
  Up to now the only CuikSuite application that takes advantage of parallelism is cuik.
  

• DEBUG This parameter controles the amount of verbosity of the CuikSuite applications. Set it to 0 to avoid any output while applications are running. Moreover, setting it to 0 activates the optimization flags for the compiler producing a slightly faster code. In general, however, setting it to 1 is better to get some information about how the solving process evolves.

Compilation

Once your system is ready, type

• cmake .
• make

in a console to compile all the executable mentioned below. Cmake will complain if some of the pre-requisites are still missing.

In default operation cmake generates makefiles. See the instructions on the cmake manual to generate other types of project files (Kdevelop, Xcode, Visual Studio,...).
To generate this documentation type

• make doc

When the process finishes you can browse the documentation from the index.

Applications

The CuikSuite includes different applications. Follow the links below to get information about the functionality of each one of them and the way to use them. The main applications are:

• cuik

But the suite also includes many auxiliary applications:

• cuiksort

• cuikanimate

• cuikplay

• cuikplot3d

• cuikplot

• cuikequations

• cuiksimplify

• cuikunsimplify

• cuikatan2

• cuiktransform

From the main functions of each application you can get into the details of the implementation.

Below you have a graph with the relations between the different applications (green ellipses) and file types (pink rectangles). Blue ellipses are external applications. Almost all applications read the file with the parameters, but, for clarity, the relations are not shown in the graph below.

Here you can find a chart briefly describing the syntax and grammar for cuik and the world files. This description is a bit outdated so check the examples directory to learn about the current syntax.

Disclaimer

The CuikSuite is distributed in the hope that it will be useful, but without any warranty. it is provided "as is" without warranty of any kind, either expressed or implied, including, but not limited to, the implied warranties of merchantability and fitness for a particular purpose. The entire risk as to the quality and performance of the program is with you. should the program prove defective, the KRD group does not assume the cost of any necessary servicing, repair or correction.

In no event unless required by applicable law the author will be liable to you for damages, including any general, special, incidental or consequential damages arising out of the use or inability to use the program (including but not limited to loss of data or data being rendered inaccurate or losses sustained by you or third parties or a failure of the program to operate with any other programs), even if the author has been advised of the possibility of such damages.