The CuikSuite Documentation
[Introduction] [Installation] [Tutorial] [Support] [Applications] [Benchmarks] [Disclaimer]



Introduction

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

The CuikSuite algorithms are specially adequate for systems with one of more kinematic loops and with a dimension of the configuration space (much) below the cardinality of the problem (i.e., when the number of independent degrees of freedom of the system is lower than the number of variables describing the problem). Such systems are quite common in practice and specially hard to deal with other position analysis/path planning systems.

Some of the applications where the CuikSuite can be useful are:

  • Kinodynamic motion planning with holonomic and dynamic constraints. See the new examples for more details.
  • Path planning for systems with arbitrary kinematic constraints.
  • Assymptotically optimal path planning for kinematically constrained problems.
  • Grasp synthesis and optimization for general hands and objects.
  • Motion analysis for tensegrity structures.
  • Motion analysis for molecular systems.
  • Position analysis (including direct/inverse kinematics) of arbitrary systems.
  • Singularity analysis of arbitrary robotic systems.

Some of the key features of the CuikSuite are::

  • Parallel implementation (multi-core) of branch-and-bound techniques.
  • Implementation of higher-dimensional continuation techniques.
  • Generation of kinematic and dynamic equations from high-level robot, molecular, and tensegrity descriptions.
  • Import models from ROS (URDF files).
  • Comprehensive set of tools to manipulate robot models and to visualize solution sets and trajectories.

This RAM-14 paper gives a general description to the basic tools included in the CuikSuite. Further details on the techniques and application implemented in the CuikSuite can be found in our publications:

Works using branch-and-prune techniques:

Works using higher-dimensional continuation techniques:

  • Planning with graph-based techniques: WAFR-10, IJRR-12.
  • Grasp optimization: RSS-11.
  • Atlas-RRT: ISRR-11, TRO-13a.
  • Asymptotically-optimal planning: RSS-12, RAS-13.
  • Singularity-free plath planning: ICRA-12.
  • Computation of singularity-free, force-feasible paths: ARK-12.
  • Wrench-feasible path planning: ICCPR-12.
  • Testing molecular conjectures: CK-13.
  • Exploring molecular energy-landscapes: JCC-13.
  • Path planning for tensegrity structures: IJSS-16.
  • Path planning for cable-suspended robots: ICCPR-17.
  • Kinodynamic planning avoiding forward singularities: ARK-18.
  • Singularity-robust control: IROS-18.
  • Kinodynamic planing with holonomic constraints: ICRA-18, TRO-20.

Please, note that there is a previous version of the CuikSuite that only included the branch-and-prune methods based on linear relaxations and was basically oriented to position analysis. This former version was used to obtain the results of our TRO-09 paper. This version can be downloaded from here.

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

License

The CuikSuite has been developed by the KRD group at IRI and is licensed under GPLv3 License.

For the impatient

If you are only interested in testing whether or not the CuikSuite is adequate for your needs, you can use Docker.

You can install the CuikSuite docker image executing

docker pull jmporta/cuiksuite

Then, you can run the image executing

xhost + 127.0.0.1
docker run –rm -it -e DISPLAY=host.docker.internal:0 cuiksuite:3.1

The Dockerfile used to generate the image is included in the source code (in the doc folder). It essentially replictes the steps detailed in the following section.

For the Ubuntu-addicted

For convenience, we offer pre-compiled Ubuntu pacakges to install the CuikSuite via apt. Only packages for 64 bits Ubuntu 20.04 LTS (Focal Fossa) are provided. We are sorry but we do not provide 32 bit packages.

IMPORTANT: This binary distribution have been tested on a clean Ubuntu install. If you already installed some optional packages or you changed the installation, then the installation may generate conflicts.

To use the pre-compile packages execute the folowing commands in a terminal.

First, get the key used to sign the packages:

gpg --keyserver keyserver.ubuntu.com --recv 17325767
gpg --export --armor 17325767 | sudo apt-key add -

Then, add the address of the CuikSuite package repository to your system:

sudo add-apt-repository 'deb [arch=amd64] http://www.iri.upc.edu/cuik/ubuntu focal main'

Now, you can install the CuikSuite executing:

sudo apt update
sudo apt install cuiksuite geomview xfig tcsh

That should be it!

If you follow this procedure to install the CuikSuite, you will not have the examples included in the source distribution. You can directly download them from here: examples

For the rest of the world

The CuikSuite requires of the following libraries and packages:

  • g++ a C and C++ compiler. If using a mac, please install gcc via brew and avoid clang.
  • glib, the core library for applications written in C.
  • cmake a cross-platform build system to generate the makefiles.
  • flex, a lexical analyzer generator.
  • bison, a general purpose parser generator.
  • The CBLAS and CLAPACK (or LAPACKE) numerical libraries.
  • The expokit library to compute matrix exponentials. This requires a fortran compiler.
  • CLP, a linear programming library.
  • A least one of the following collision detection libraries:
  • The CBLAS and CLAPACK (or LAPACKE) numerical libraries.
  • The expokit library to compute matrix exponentials. This requires a fortran compiler.
  • A MPI library. The recomended option is to use OpenMPI. This is only necessary if you want to execute cuik in a multi-core environment. If the library is not available the sources will be automatically compiled in single CPU mode.
  • The assimp library to read mesh files (tested with version 3.0.1270). If not available, only OFF and binary STL files will be accepted.
  • A kd-tree nearest neighbour library. This is optional, but recommended. Two possible options are
    • The Cuik-KDtree library.
    • Our modified version of the MPNN nearest-neighbour search.
  • OpenBabel for the bio-chemistry applications. If not installed, the interface for molecular problems will not be compiled.
  • The RigidCLL collision detection library for molecular structures. Only necessary if the interface for molecular problems is required.
  • tinyxml2, a library to parse xml files
  • gtk, a library to create graphical user interfaces. In particular, we use the following libraries: libatk, libgtk, and libgdk-pixbuf.
  • Optional: (but recommended)
    • xfig to visualize some 2D output plots.
    • Geomview to visualize 3D output plots.
    • tcsh for the scripts.
    • A MPI library. The recomended option is to use OpenMPI. This is only necessary if you want to execute cuik in a multi-core environment. If the library is not available the sources will be automatically compiled in single CPU mode.
    • The assimp library to read mesh files (tested with version 3.0.1270). If not available, only OFF and binary STL files will be accepted.
    • A kd-tree nearest neighbour library. This is optional, but recommended. Two possible options are
      • The Cuik-KDtree library.
      • Our modified version of the MPNN nearest-neighbour search.
    • OpenBabel for the bio-chemistry applications. If not installed, the interface for molecular problems will not be compiled.
    • The RigidCLL collision detection library for molecular structures. Only necessary if the interface for molecular problems is required.
    • tinyxml2, a library to parse xml files. Mainly used to import URDF files.
    • doxygen and graphviz. Only required to generate the documentation.

Most of these dependencies can be easily installed in linux ubuntu and mac using the corresponding packages managers (apt or brew, respectively), without any need to download and compile them from source.

After installing the dependencies, we can install the CuikSuite. Download the package:

wget http://www.iri.upc.edu/cuik/CuikSuite3.tar.gz
tar xzf CuikSuite3.tar.gz

Instead of wget in Mac you can use curl -O.

Generate the makefiles

cd CuikSuite3/build
cmake ..

cmake will complain if some of the pre-requisites are still missing. If everything is found, you can compile the package executing

make

At this point the CuikSuite executables are available localy in the bin folder. If necessary, you can install them into the system executing

make install

In this documentation we assume this last step is not executed and, thus, all executables are assumed to be in the bin folder.


Finally, to generate this documentation type

make doc

The html documentation can be browsed from doc/html/index.html

Support

The CuikSuite is in continuous development and thus, we can offer a limited support to external users.

Please, send us an e-mail at porta at iri.upc.edu if you have any troubles installing or using the suite.

For general questions about this software, please check the CuikSuite FAQ

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:

But the suite also includes many auxiliary applications:

Beside the main applications, the CuikSuite also includes several scripts to automate different tasks.

Here you can find a brief description of the syntax used to describe problems, i.e., the world files and the cuik files. This description is quite obsolete and its better if you check the examples.

The parameters that can be set for each problem (in the corresponding .param file) are described here.

To get an overview of the different files used in the CuikSuite have a look at this.

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.