ReaK Library Overview

Current Version: 0.2.0-00

Main contributor and founder: Sven Mikael Persson, M.Sc.(Tech.) mikael.s.persson@gmail.com

ReaK is a C++ software platform, library and algorithms for multi-body dynamics simulation, control, estimation, and path-planning. Intended for robotics software development and testing. This library is published as open-source under the terms of the GNU General Public License v3 (GPLv3). The library is entirely written in C++, practically no external dependencies, and utilizes three main paradigms, i.e., object-oriented programming, generic programming and template meta-programming, whichever works best in a given situation.

##What the ReaK library is

ReaK (pronounced as the 'reac' in 'reaction' or 'reactor') is a software platform which is the result of many years of accumulation of C++ code used by the original author (Sven Mikael Persson) for various project in the fields of multibody dynamics and control. At the core of the ReaK platform are several general-purpose utilities which facilitate serialization / deserialization of objects, memory sharing between distributed software modules, run-time type identification, and data input / output.

The core math libraries included in ReaK handle basic linear algebra methods (fixed and variable size vectors, variable size matrices of various structures and alignments, and matrix composition, views and slices), 2D and 3D geometric calculations (rotations and kinetostatic frame transformations), matrix numerical methods (LU, Cholesky, QR, Jacobi, SVD, PadeSAS matrix exponentials, Redheffer star-product, and matrix norms), numerical integration methods (fixed-step, variable-step, and multi-step predictor-correctors, both closed-form and iterative), and a set of optimization routines (although out-dated and seldom used). Performance optimization of these libraries is limited to good coding style, but do not expect these math libraries to be the fastest available, they were designed to be easy to use and interoperable, not for performance-critical applications.

The multibody dynamics elements of this library were developed according to the Kinetostatic Transmission Elements (KTEs) framework, as originally developed by Prof. Andres Kesckemethy at Graz University (now at the University of Duisburg-Essen), this is not, however, developed from other existing code that use KTEs, this is an original implementation which was done during the course of a Master's degree, by the original author, in Space Robotics and Automation at Aalto University, School of Science and Technology in Helsinki, Finland. This framework allows serial kinematic chains to be modeled in a modular and flexible fashion, to be used for model-based control of a robotic system and high-fidelity dynamics simulations. The construction of a dynamics model is done via a serial chain of KTEs which model simple (or complex) transmission of motion and forces (hence the 'kineto' and 'static' in Kinetostatic Transmission Elements). Available KTEs include, but not limited to, the following: inertial elements, (torsional) springs, (torsional) dampers, revolute joints, prismatic joints, free joints, rigid links, flexible Euler-Bernoulli beams, force actuators, driving actuators, geometric constraints (point-on-line and point-on-plane), dry and viscous friction, virtual-to-real model interfaces (for Virtual Model Control (VMC)), and state measurements and direct controls (no motor/controller model). Additionally, some utility classes are available, which are not KTEs but work in parallel to KTEs to extract higher-level information about the KTE chain. The main utility class is the mass_matrix_calc class which can, once given a list of degrees-of-freedom, joint motion jacobians and inertial elements, be used to compute the system's mass-matrix as well as its composing elements (twist-shaping matrix and aggregate, constant mass matrix), and their derivatives (and thus, also the time-derivative of the system mass matrix, which is useful in model-based control and estimation).

Finally, for the purpose of estimation and path-planning, the ReaK platform includes several generic algorithms and concepts for state representation and estimation, and probabilistic path-planning methods. Note that this part of ReaK is under active development (as part of the author's Ph.D. research), so it should be considered as very experimental at this stage and incomplete parts are to be expected. First, the state estimation algorithms and concepts include several variations of the Kalman filtering method, including the (Extended-)Kalman Filter ([E]KF), the (Extended-)Kalman-Bucy Filter ([E]KBF), the Hybrid Kalman Filter (HKF), the Unscented Kalman Filter (UKF), the Aggregate Kalman Filter (AKF), the Symplectic Kalman Filter (SKF), and Invariant versions of most of the filters (IKF, IKBF, IAKF, and ISKF). The implementations are all generic, based on a certain number of concepts (using the Boost.Concept-Check library) that define fundamental constructs such as a continuous-time state-space system, a continuous-time linear state-space system (including linear-time-invariant (LTI), linear-time-varying (LTV), and linearized at the current time, state and input), discrete-time versions of those state-space system concepts, an invariant state-space system, a covariance matrix representation, and a belief-state representation. Additionally, a Gaussian belief-state class is also provided for convenience. Second, the path-planning algorithms include several basic implementations and concepts related to classic probabilistic path-planning methods and other related utilities. Most algorithms build upon the framework of the Boost.Graph library, in the same programming style. Algorithms include the Anytime Dynamic A* (AD*), the Rapidly-exploring Random Tree (RRT), the Probabilistic Roadmap (PRM), and the Flexible Anytime Dynamic Probabilistic Roadmap (FADPRM). Several concepts are defined such as a metric space, a temporal space, a reachability space, as well as spatial paths and trajectories. Additionally, some of the utilities provided include linear-search through topological point-sets (for nearest-neighbor queries, through extensive search), a Dynamic Vantage-Point Tree (DVP-tree) implementation for fast nearest-neighbor queries via the partitioning of a general metric space, and a multi-index sorting of points of a reachability space for fast nearest-reachable-neighbor queries. This part of ReaK will be under heavy development during the summer of 2011, contributers are welcomed!

##What the ReaK library is NOT

• A hardware abstraction layer (HAL). ReaK does not include drivers for sensors, motors, cameras, or anything of the sort. This is a conscious design decision. The diversity of peripherals used in robotics, whether it be real hardware or a simulated environment, is vast and hence, most attempts to write one-size-fits-all hardware abstractions suffer from one or more of the following problems: excessively large, heavy-weight code-base; deep levels of indirection; maintainability nightmares; awkward mix of different programming languages; and a large number of external dependencies, and thus, lack of portability, maintainability and scalability. For all these reasons, the hardware abstraction is left to the user to implement or select his or her preferred library. The generic nature of most of the ReaK library allows for minimal requirements for use, much in the style of the C++ STL.

• A virtual environment for robot emulation. ReaK does include an entire multibody dynamics library with several features and elements. However, ReaK is designed as an open-architecture library, its target end-user is a programmer. Several software packages exist, open-source or commercial, to do low-fidelity simulations (mostly using the Open Dynamics Engine (ODE)) with the intent and purpose of creating a virtual environment where a robotic system's dynamics can be emulated in real-time and with visualization, such that high-level controllers can be tested. However, these platforms are often closed-architecture and of too low fidelity to be used to test low-level controllers, or even to compute model-based control laws numerically. On the other hand, ReaK does not include any visualization (e.g. 3D rendering) and is not meant to run simulations in real-time, but is able to compute medium to high fidelity multibody systems efficiently such that it can be used for model-based control, virtual model control, estimation and model prediction.

• A comprehensive multibody dynamics simulation software. Although ReaK does include a decent amount of multibody dynamics code, it would be highly pretentious to paint it as being a serious rival to professional, high-fidelity multibody dynamics software packages such as MSC.Adams and others. The elements of multibody dynamics simulation which are available in ReaK are the most commonly used ones (joints, links, springs/dampers, masses, etc.) and several numerical integrators are provided as well, but, still, it should not be mistaken for a professional engineering tool. The KTE framework which is used for multibody dynamics calculation in ReaK does offer enormous potential for expansion and a very simple framework to develop custom components as needed, and, in that sense, can serve as the basis for the development of multibody dynamics software (e.g. for custom dynamics elements or for research in MBD).

##License

Copyright 2011 Sven Mikael Persson

THIS SOFTWARE IS DISTRIBUTED UNDER THE TERMS OF THE GNU GENERAL PUBLIC LICENSE v3 (GPLv3).

This program is free software: you can redistribute it and/or modify
it under the terms of the GNU General Public License as published by
the Free Software Foundation, either version 3 of the License, or
(at your option) any later version.

This program is distributed in the hope that it will be useful,
but WITHOUT ANY WARRANTY; without even the implied warranty of
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
GNU General Public License for more details.

You should have received a copy of the GNU General Public License
along with this program (as LICENSE in the root folder).  
If not, see <http://www.gnu.org/licenses/>.

##Dependencies

Supported compilers and platforms:

• Tested on GCC 4.4.x, 4.5.x and 4.6.0.
• Compatible with all platforms that support the Boost libraries and the C++ standard libraries, at least in theory.
• Tested on Linux Ubuntu/Kubuntu 9.10, 10.04, 10.10, and 11.04.
• Should be mostly compilable in Windows, although not officially maintained.

External Dependencies:

• CMake build system.
• The Boost Library (www.boost.org), version 1.42.0 or later.

Optional External Dependencies (for test-programs):

• OpenCV
• FreeImage
• Qt 4.6 or later

#Detailed Description

##History

The author's earliest work has involved amateur 3D computer game programming (roughly 12 years ago). Back then, the author developed, amongst other things, a comprehensive math library for geometry and linear algebra calculations. These were used for 3D rendering and low-fidelity real-time physics engines, and were mostly written in Delphi (Object Pascal). The author's interest in programming shifted more and more towards dynamics simulations, as he was starting his bachelor's degree in mechanical engineering. The project that gave birth to the first design iteration of the ReaK platform was a two-year bachelor's thesis with the goal of developing a general-purpose multibody dynamics simulator for the purpose of integrating a new closed-form continuous contact dynamics formulation which could not be easily implemented using customization facilities of existing, commercial multibody dynamics packages (MSC.Adams, SimMechanics, etc.). The author, not being entirely comfortable with C++, wrote the graphical user interface in Delphi (VCL), but decided to write all the multibody dynamics software in C++, and so, ReaK was born. The name comes from the fact that this software was originally made for the purpose of resolving contact forces ("reaction" forces) in closed kinematic chains formed by continuously contacting rigid bodies. However, since then, the multibody dynamics calculation framework has been completely changed to be based on Kinetostatic Transmission Elements, which are more appropriate for serial kinematic chains and are just more scalable.

The main outcome of the first design iteration was the amount of lessons learned about managing memory, interfacing modules, creating a plugin system, binary compatibility, and just learning to work effectively with C++. Obviously, since the first iteration involved a GUI written in Delphi, it implied that the C++ code was wrapped in DLLs (back then, ReaK was Windows-only), in fact various sections of the code were bundled in different individual DLLs. Objects which were created from different DLLs would be shared between them, based on standard ABIs. A plugin system was created to allow an extensible amount of new classes to be loaded into the GUI application, with published properties and visual artifacts (OpenGL) for the GUI application to use. This implementation was very tedious to complete successfully and led to hours, days, and months of frustration over difficult bugs, across the different modules, but was eventually finished to a working level (although still buggy). Immediately following it, plans and ideas were starting to form the basis of the next design iteration, which could now be referred to as ReaK 0.1 (thus, explaining the 0.2 minor version number today).

After much thought and planning, the second iteration of the ReaK platform was started in late 2009 and used during a Master's degree in Space Robotics and Automation at Aalto University, School of Science and Technology, in Helsinki, Finland. In this version of ReaK, most of the core code, as it is now, was developed, including the base classes for the platform, the distributed shared-memory model, the custom, cross-module, cross-platform run-time type identification system (RTTI), the serialization library, and data recorders. The math libraries for linear algebra, matrix numerical methods, geometry, and numerical integration were mostly taken from the previous version, with some refactoring, and, eventually, further refactoring led to the current version of those library. Most importantly, the KTE framework was adopted to create a fairly complete suit of multibody dynamics code, which has since remained largely the same in the current version, with some additional elements. This second iteration of ReaK also included a signals-and-systems implementation which allowed a multi-threaded approach to designing behavior-based controllers via systems running on independent threads and a mix of synchronous and asynchronous signals to communicate between and trigger different control loops (or sub-systems of the overall controller). However, this latter part of ReaK 0.1 tended to be somewhat unstable due to certain rare, but possible, occurrences of data races and dead-locks. Nevertheless, ReaK 0.1 was used, in conjunction with the Machine Control Interface (MaCI) (a hardware abstraction layer developed and maintained by the department of Automation and Systems Technology, at Aalto University), to develop controllers for a humanoid torso (on a centaur-like robot, the WorkPartner) to achieve physical human-robot interactions (e.g. cooperative manipulation of large objects). The multibody dynamics library was used to compute Virtual Model Control laws (VMC) and to implement a non-linear disturbance observer which would be able to measure the human operator's force without force-sensing capabilities of any kind on the robot (i.e. no force cells or motor-current sensing). The project was largely successful and the ReaK platform was mature, stable, effective and efficient. However, the library still had some problems which led to the development of the current version of ReaK, version 0.2, making it the third design iteration.